[Un] Restuffing the documentation

**Bandobras** · March 1, 2008, 20:22

Wow, thanks a lot. I'm just looking at the files and double-checking using my insider knowledge. I will not start modifying the files, until I let you know about my comments and hear back from you. Here I begin:

> The following options are missing descriptions:

You mean in neither the V nor the Un files?

> These are also missing descriptions
> (if descriptions are indeed planned for them:
> Load a user pref file
> Append options to a file
> Reset all options to defaults
> Interact with macros (advanced)
> Interact with visuals (advanced)
> Interact with colours (advanced)

A word about each would be nice. The last three are, or should be, described in details in other files.

>For <disturb_detect> the description from the old <verify_safe> option was copied in.

Great.

>Both <room_names> and <room_description> specifies that the effect works when variant_room_info is enabled. That option no longer appears on the options screen, so I've removed that part from the description on the assumption that it's probably now built into the game or at least is no longer a factor.

Seems to be the case.

>Changed "Disturbance options" category to "Warning and disturbance options" since that's the way it now appears onscreen.

OK.

>On <disturb_near> I've removed 'See also the "view_reduce_view" option.' from the description since we no longer have that option.

I think the V docs editors would benefit from your work...

>Changed "Window Settings" category to "Subwindow display settings" as that's how it now appears onscreen.

OK.

>Changed "Display map view" to "Display dungeon map" - I'm assuming that's the current name for the same option, but I may be mistaken.

I don't use subwindows, but a quick look confirms your version.

>Under the "Subwindow" options, I removed the ones that do not currently appear, but I have the feeling that some of those descriptions might apply under new names. I've included those that were removed below, for that reason.

I have no clue, but they seem out of date, anyway, so let's leave writing a new version for somebody else, perhaps when the subwindows menu at last has a context sensitive help, so assigning help to subwindows will be permanent. Better no than misleading documentation...

>Note: Other than the above, I fixed a few typos. Also, for everything else that appears on the options screen beneath the "other info", I added a line to indicate its title, since I don't know whether you plan to include a description for those at some point.

Great.

>The following are the options that I removed from the option help file because they no longer appear. I include them here on the chance that some of those options may still exist in the current game, but under a new name that I don't recognize.

Nope. All are dead.

Edit:
>The following options are missing descriptions:
> pickup_always - under Interface options

I think this is described jointly with <pickup_inven>
in Vanilla (mentioned in consecutive lines)
and I guess this is a good idea.

> birth_haggle - under Birth options

I've found a description in an old version of V

***** <auto_haggle>
Auto-haggle in stores [auto_haggle]
Disable "haggling" in stores, resulting in a ten percent sales tax
on items which you would have otherwise been forced to haggle for.
When this option is on, all prices listed in stores will be the
actual price that you pay for an item, as opposed to the price
that the shop-keeper will suggest.

Here are also the S and the O descriptions,
but the V one is probably what actually happens
in Un (though not necessarily the best written,
in particular I don't like quote marks in "haggling".

Never haggle in stores [never_haggle] (off) :
You never haggle in stores, regardless of the markup the shopkeeper asks
(which is very little or nothing on inexpensive stuff, but can be as great as
33% on extremely valuable items).

Auto-haggle in stores [auto_haggle]
Disable haggling in stores, resulting in a ten percent sales tax on items
which you would have otherwise been forced to haggle for. When this option
is on, all prices listed in stores will be the actual price that you pay
for an item, as opposed to shop-keeper's initial offer.

**Anne** · March 1, 2008, 22:33

Originally posted by Bandobras

> The following options are missing descriptions:

You mean in neither the V nor the Un files?

Yup. I checked both and if I didn't find the description in either file, I listed them as missing descriptions. But there again, it's possible that that the name of a current option used to be something else, and I might not recognize it.

Originally posted by Bandobras

> These are also missing descriptions
> (if descriptions are indeed planned for them:
> Load a user pref file
> Append options to a file
> Reset all options to defaults
> Interact with macros (advanced)
> Interact with visuals (advanced)
> Interact with colours (advanced)

A word about each would be nice. The last three are, or should be, described in details in other files.

I went ahead and looked that up. Actually, the macro.txt covers all of the above rather than just the last three, so I went ahead and altered the Options file that I posted earlier to reflect that. I'll post it here again with an updated modifications file.

Originally posted by Bandobras

>The following options are missing descriptions:
> pickup_always - under Interface options

I think this is described jointly with <pickup_inven>
in Vanilla (mentioned in consecutive lines)
and I guess this is a good idea.

Aha, you're right! I altered this in the version I'm about to upload as well - I simply removed the blank line between the two options so that they're more visually connected.

That's all I fiddled with in this batch, to give you a little more head start. Modify however you like.

Attached Files

RevisedOptionsHelp 030107.2.zip (10.3 KB, 280 views)

**Bandobras** · March 1, 2008, 22:35

OK, thanks a lot. I'll take another look, modify and upload so that it'll by published in beta2 soon to come.

**Anne** · March 1, 2008, 22:39

Anytime, Bandobras. You know I'm glad to help.

**Bandobras** · March 2, 2008, 00:04

Committed the help file to SVN. We are good.

BTW, did you know the 'R' command, which description you wanted to remove, was the "reset options to defaults" command requested by you? ;D

**andrewdoull** · March 2, 2008, 02:59

*I suggest 3 listings & descriptions for commands; a list common to V, and a "new / different commands list", as well as an "all commands" listing, for new players (like Anne, as it turns out) who are trying to play Unangband without having ever played V. Creating the third is as simple as merging the first two. I appreciate that this seems to have been the point, but I don't think the present state is complete or totally accurate. There is also the question of how to work the roguelike keyset into that framework, without too many redundant text files adding to the navigation problems.
{ EDIT - I don't think my ideas here are correct after more thought, TBH. }

My suggestion here is to write the Unangband file including everything, then drop the non-Angband specific stuff for the differences file, which is what I originally did.

Quote:
Originally Posted by Anne View Post
Wand of Spark - "When aimed, it electrifys at up to range 3 a beam. When set in a trap, it electrifys one target."
Misspelled and awkward wording. Should be something like:
"When aimed, it sends a beam to electrify up to range 3. When set in a trap, it electrifies one target."
Tricky. Teaching computer "y"+"s"="ies". Filed a bug report.

I'd like to include a more generic singular vs plural string handling code. e.g. replace ~ with s when plural or nothing when singular plus |he|she|it| type string handling. Not sure the best approach for this yet.

Discolored Spot trap - recall says it can be disarmed to get a flask of oil. I got a flask of acid when I did this.

That's because you only see the description of the 'mimiced' feature at the moment... I haven't figured quite how to expand this out yet.

Quote:
Potion of Slime Mold Juice - Description gives throwing information but not quaffing. On Nethack and such, that item did at least give some nutrition, but maybe it doesn't here.
Yes, it's quite nutritious and flavourful.

We should include the nutrition information for potions when it applies. This should of course be automatically generated.

Quote:
Wooden Torches and Flask of Oil - neither says in the description that they can also be used to fuel a torch/lantern. Should that be there, or is it left out intentionally?
I guess half-intentionally. This is not a property of an object, but something hard-coded in the refuelling code, so this should be described manually in docs, I guess.

Modify the item description code to include this information.

I think this is only true about the birth options. They only affect the next game (not 100% sure if even that).

Yes, that is correct. The birth options get turned into adult options when you are born. Outside of birth.c, you should only ever check the setting of the adult option, not the birth option.

**andrewdoull** · March 2, 2008, 03:19

Hi,

Thanks for everyone's input on this always complex issue. I just want to give you a quick overview of my thinking around the documentation side of things.

As much as humanly possible, I wanted to make the documentation automatically generated. This was driven by the fact I was a one man band trying to get a whole lot of work done and very rapidly increasing the number of items/monsters etc.

I still think this applies to spoiler files and a lot of the in game information about items and monsters and so on. Where we want to add manual information, this should probably be done by adding or amending the description field in the lib\edit file so that you can amend small details about the particular item.

Angband variants like T.o.M.E. and Sangband have nice item description information already that we could probably borrow. Note that I think T.o.M.E. goes overboard on the artifact descriptions - I'd just prefer a brief history of the object (who owned it, etc.), as opposed to necessarily a physical description and hint of the item powers.

For stuff that is manually written, I want to get as much of it in the game via the lib/info files interface where possible. e.g. the 'You find a note' style. This enables the information to be given in a hopefully time sensitive fashion. There is a good file describing how to populate this information: http://svn.berlios.de/svnroot/repos/...nfo/readme.txt

The biggest problem we face with the in-game help system is that it just uses dumb text display. As I've mentioned elsewhere, I'd like to get an online wiki up and running with the help files so that we can edit these as easily as possible and then import those files into the game. The help browser also makes bad assumptions about the screen size that we may want to avoid. I'd also like to be able to create Windows help versions of the documentation if possible.

Berlios supports adding in a wiki, but uses the ODFL license which is incompatible with the GPL and uses Open Facts, which is fairly ugly. Instead, I think we can just safely agree that the license is instead GPL/Angband/ODFL dual licensed and as long as only people that do so update the wiki we should be fine. I'd much rather have someone set up a MediaWiki wiki if possible, as we can then control licensing and it's a much nicer interface.

Link to the Berlios wiki is here: http://openfacts.berlios.de/index-en.phtml?title=Unnamed%20Angband%20%28Unangband%29

I'll populate this with the existing documentation if you don't have any objections.

Finally, my documentation contribution will be to update the lib/edit files with a readme.txt that contains much more information about what each value/entry and so on is in the files. In fact, I may just create a lib/docs folder which contains this information for each corresponding lib/edit file. This should enable you guys to get a little more insight into how the game works...

Andrew

**Anne** · March 2, 2008, 04:48

Originally posted by Bandobras

BTW, did you know the 'R' command, which description you wanted to remove, was the "reset options to defaults" command requested by you? ;D

Oh I meant to mention that! Thank you! Originally, I figured it would help newbies who'd made a mess of their options. But it's going to be very handy for me too, now that I'm testing things with different options on. Much quicker than having to do it manually. And it means I won't need to keep a separate list of all the defaults in case I garble things, which I'm prone to do at 3am.