[Un] Restuffing the documentation

[Bandobras]

Daven_26d1 suggested UnAngband docs should be brought back to health (and even offered his help) at

http://angband.oook.cz/forum/showthread.php?p=5334#post5334

which is great idea, but too great for one-time effort of any single person. Therefore I've opened this thread for collaboration. If you have any question about the game mechanics, ask here and somebody will code-dive and answer. If you have pieces of docs ready, publish here for discussion (and please append your license statement --- GNU GPL + old Angband license, preferably).

AFAIK, but Andrew knows best, there are no secret game notes game notes kept by the maintainer. Everything is either in the in-game notes or in the raw code. Or in the current documentation or comments to the script files, which are both very inaccurate and outdated sources of information.

I think the (already seen) in-game notes should be available from a menu, but they should not supplant a (basic, at least) proper documentation (and/or manual). I wonder, if we should base the documentation on the current files (mostly taken from an ancient V release), current V documentation or something else (e.g. something totally original)? I suppose the current ASCII + menus with links format of documentation is enough?

So, since this is the place for Q&A:
1. what text should be base our efforts on?
2. could we put together a list of all files needed, first, and then work file by file?
3. does it make sense, Andrew?

[Daven_26d1]

A collaborative thread sounds like a really good idea.

I've just read your post twice, and I'm finding it hard to understand the sentences. Not your fault, I got <4 hours sleep last night, and I've been working on cryptography analysis code & scripts for the last four or five hours. Its now after 5am, and my head hurts.

So my plan right now is to wait till my son wakes up, then feed him, then wake up his mother, then sleep (probably for a while!), then drink coffee, then spend an hour "playing" Unangband, then make some kind of notes based on my observations, and try to come up with some sort of vague plan, and try to remember what it was like to try to figure the game out when I first tried it, then log back into oook and share what I have. Depending on how much sleep I get, it may be 12-36 hours before I'm online again, but I'll see you then. I've just added another desktop to my linux, for the express purpose of this endeavour, and I'm quite looking forward to covering it with KNotes.

I think the most useful initial plan would be to review and list all the current documentation, and to add notes to that based on what each contains (info, errors, ommissions, inconsistencies). If you could make some headway with that Bandobras, then perhaps you could simply edit in everyones observations to the list as we review it. Of particular use would be for (especially) new players to comment on the things they found difficult to understand or find, and what they feel is missing. As documentation is most useful to newcomers, its only sensible that we use their fresh perspectives to guide us.

The main problem is I think the docs need to be more unified; kind of like Un itself things have sort of been stuffed in here and there as time has gone on; but the structure of the online help probably needs a total overhaul, I don't feel its just a case of reworking the outdated information. The in game tips are pretty good though, probably little if anything needs to be rewritten, but perhaps some additional pages need to be introduced.

Regarding everything else, I figure what seems like a large volume of work now, and a very difficult problem of how to go about it, will look a lot less daunting once what exists has been properly itemised and once some clear goals have been identified.

Anyway, see you in about a day...

[Anne]

I've noticed some items have either no descriptions at all, or they need redone. Much of that, I could easily correct and give you myself, but I can only do that by getting lucky and coming across them on the game. I get the impression that all that info is written in the .raw files, but I have no idea how to open those to see. No programming knowledge here at all. Of course, if it's all written in indecipherable computerese, I may not be able to figure out what I was looking at anyway.

Is it possible to put that type of thing up where we can see them? Or is there some simple way for someone with no programming knowledge whatsoever to open up those files? I don't mind downloading software if necessary, but I don't want to have to learn programming in order to do it either. If not, I'll just have to catch what I can through playing.

[Daven_26d1]

Yawn *bump*, morning! Although actually I've been up for a while, my brain only joined me about a half hour ago.

Okay, some musings.

*Pete Mack appears to have put in an commendable amount of work modernising the Angband documentation, only moron's wouldn't at least start there as a base for the new help files.

*The largest problem I had with Unangband was the apparent uselessness of the "differences from Angband" section; I'm starting to think that it's because Unangband was changing so quickly and important documentation simply fell by the wayside. Some system needs to be in place to ensure the help files aren't allowed to fall into this trap again once they have been restored to full health; it's probably just a question of diligence.

*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. }

*"Too many cooks spoil the broth". Collaboration seems the best idea, but I would like (unless anyone violently objects) to be left to get on with what I'm currently thinking of the 'core' manual. I mean by this those parts which introduce the player to roguelikes, Angband, Unangband and how to play the game; what the symbols mean, how to explore etc. My reason for this is that I have a worry that some information while be reduntantly echoed in different files, other things overlooked because someone thought it was supposed to go in someone else's file and simply that the information won't end up feeling unified and accessible, because nobody had anything but a disjointed view of how it would all snap together. I'm looking to work up a first draft within the week (I have plans to party hard this weekend, as I rarely get a chance any more, but as of Monday I'm game for getting my teeth into this).

Basically, once I have a good idea of what needs adding, and what needs removing or shuffling about, I can sit on the floor and work out a good structure for everything old-skool biro and A4 pad style. After that, I can pretty much zombie through the typing overnight, because the flow and ordering should be good enough to do so (like writing pseudocode and doing "top-down stepwise refinement" really) and present my work for review and critical scrutiny.
{ EDIT- after preliminary review, I think a broad structural design and some draft files for sampling purposes is a more likely goal. }

*There will be placeholders. I won't be able to describe all the races and classes (something that needs doing!) for instance, but the structure obviously wouldn't be affected by simply putting "DESCRIPTION HERE" in the appropriate place. I haven't really read Tolkien much for over a decade, though I still have most of the books; I don't mind expanding on terse descriptions, or making ugly descriptions more evocative, but I just don't understand Andrew's world the way he does, nor am I intimately familiar with the mechanics of all the classes. Mistakes in what is available need identifying, in this thread preferably, because they will end up being the basis of what is to be done. For example, I remember reading in the description for bards that they are penalised for wearing gloves as mages are; this is either wrong, a bug or simply not clear enough (I never did find an instrument, so I wondered if it only applied when one was wielded.)

*Prioritisation & Delegation - surely the most important thing is to get together the sections that help new players and keep them interested into as clearly presented a manner as possible, more players means more responses and more fresh perspectives, but much of this is covered in the core segment I wish to attack shortly. Some feedback over the weekend to help me with getting that started would be fantastic. With a review of the current docs, some files will be flagged up that can be easily worked on separately from the rest, particular command references, maybe even a FAQ / hints page; flavour descriptions for the locales from any Tolkien buffs reading this. ToME has some dungeon spoiler pages which have short descriptions, something like this for Unangband (perhaps with a little more flavour and a little less spoiling might be nice, to go with that lovely map that was so lovingly crafted in glorious ASCII. This is another one of those pages that would need to be kept on top of as the state of the game altered, however.
{ EDIT- to clarify, some files will need working up that require no knowledge of the (yet unknown) grand scheme; this work can be begun by anyone who has the motivation to do so. }

*Am I fine collating from the sources, scripts and .txts in the latest offical release, or should I grab the latest SVN from berlios?

*Lastly, you mentioned licensing; I'd presumed that documentation would just come under the same license as the game itself, I don't intend to claim any copyright over anything I do towards this. I will expect some credit in the final draft, of course, but that's about it. I'm not too up on the whole GPL vs Angband license debate, but I think it would be best if anyone who wants to help with this just leaves it up to to maintainers and saves further complicating matters.
{ EDIT- which basically means it would be nice if contributors simply agreed that GPL + Angband license was fine with them. I can't see there being a problem here =) }

*Lastly, again I appeal to all the players watching this thread to either message me your gripes and observations or drop them into a reply in the thread, because many hands make light work.

[Bandobras]

I've just read your post twice

Sorry about that. I'm not a native speaker and even in my native savage language I sound funny. One more reason I desperately need help.

I think the most useful initial plan would be to review and list all the current documentation, and to add notes to that based on what each contains (info, errors, ommissions, inconsistencies). If you could make some headway with that Bandobras, then perhaps you could simply edit in everyones observations to the list as we review it. Of particular use would be for (especially) new players to comment on the things they found difficult to understand or find, and what they feel is missing. As documentation is most useful to newcomers, its only sensible that we use their fresh perspectives to guide us.

Great. I'll make a start and then I'll be incorporating everybody's contributions. But go on with your own ideas --- I doubt any work will be wasted, because there is lots to do and only a few people, so significant overlap is not very probable.

I've noticed some items have either no descriptions at all, or they need redone.

I think, in Un, items don't have hand-made descriptions at all. Only names. The rest is generated on the basis of item's properties.

Much of that, I could easily correct and give you myself

That would be welcome, because it probably indicates problems in the auto-description routines.

but I can only do that by getting lucky and coming across them on the game. I get the impression that all that info is written in the .raw files

Nope. Not in the lib/data/*.raw files (these are already compiled binary formats), but in lib/edit/*.txt files, e.g. object.txt. Open them in ordinary text editor. The comments at the start explain some of the magic, but it still seems very misterious at first sight.

[Daven_26d1]

Sorry about that. I'm not a native speaker and even in my native savage language I sound funny. One more reason I desperately need help.

Don't worry I can understand your post today. I literally couldn't concentrate on reading and comprehending the words on the screen. I was _really_ tired, and my brain just kept wondering where the syntax highlighting had gone.

Regarding your points, you seem to have a similar idea to me in that a framework needs to be sketched out so that work can be encapsulated into files or groups of files that can be handled independently of the rest; its this framework, or at least a working version of the framework, that I'm hoping to get laid out through this week. As soon as I have anything good, I'll drop it here.

[Bandobras]

Regarding your points, you seem to have a similar idea to me in that a framework needs to be sketched out so that work can be encapsulated into files or groups of files that can be handled independently of the rest; its this framework, or at least a working version of the framework, that I'm hoping to get laid out through this week.

Great, so I'll just comment on your earlier points. Take your time.

*Pete Mack appears to have put in an commendable amount of work modernising the Angband documentation, only moron's wouldn't at least start there as a base for the new help files.

If Andrew has nothing against, I'm all for it. (I know Pete from his excellent work on the Un knowledge screens, without which Un would be overwhelming even for myself.) We will salvage manually what is valuable from the current Un documentation. I'm fond of where V is currently going, so the more we have common with V, the better (merging with future V changes, taking advantage of player and codes already knowing V, etc.).

*The largest problem I had with Unangband was the apparent uselessness of the "differences from Angband" section; I'm starting to think that it's because Unangband was changing so quickly and important documentation simply fell by the wayside.

True. This is ancient.

Some system needs to be in place to ensure the help files aren't allowed to fall into this trap again once they have been restored to full health; it's probably just a question of diligence.

Some things in Un will not change so rapidly any more, I guess. Of course there will be lots of extensions, bit only a few major changes (such as semi-persistent levels and probably dungeons scaled from 100 to 50 levels max depth). Moreover, we are writing docs for 0.6.2, which will probably branch off and be maintained (only but fixes and small improvements) for a long time.

*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

OK. BTW, if comparison with current V shows there are different keys for the same command, we may want to upgrade to V. The latter, regardless if 3 listings is a good idea or not. Perhaps instead mention the new keys (and their roguelike counterparts) in the chapter about new Un commands vs V? The chapters about commands are big enough that splitting them into 2 sections seems quite reasonable, especially that the Un-specific commands are usually less essential.

*There will be placeholders. I won't be able to describe all the races and classes (something that needs doing!) for instance, but the structure obviously wouldn't be affected by simply putting "DESCRIPTION HERE" in the appropriate place.

Sure thing. The 'game content' is actually a totally different work that also needs to be done. So, races, classes, wilderness locations' descriptions, dungeon levels' descriptions, in-game notes (still many write), quests (this one post 0.6.2), etc. These are less introductory material nor game-mechanics explanations, but rather the flavour of the game and sometimes, with a bit of scripting, plot and game structure material.

I haven't really read Tolkien much for over a decade, though I still have most of the books; I don't mind expanding on terse descriptions, or making ugly descriptions more evocative, but I just don't understand Andrew's world the way he does, nor am I intimately familiar with the mechanics of all the classes.

So, here is the place to ask. But from what I know, this is all just as true to Tolkien (especially the general high fantasy mood, with fairy-tale, but not teenage humor) as we can get without sacrificing game-play or ripping off the existing game engine. Actually, if you write an interesting (over)interpretation of a Tolkien concept that induces a nice game-play variety, you can expect that the scripting for a class or dungeon will be changed to fit your description. Of course, knowing what the physics of the Un world allows helps...

Mistakes in what is available need identifying, in this thread preferably, because they will end up being the basis of what is to be done. For example, I remember reading in the description for bards that they are penalised for wearing gloves as mages are

Generally, yes. As for bards, this was only true when specialized in instruments. But it's irregular, no other class gets icky hands for anything else than magic books use, so I now remove the penalty. Instruments are underused anyway. I guess sometimes the rules may get simplified when we write the documentation and they turn out to be hard to describe due to irregularity.

*Prioritisation & Delegation - surely the most important thing is to get together the sections that help new players and keep them interested into as clearly presented a manner as possible

Agreed.

ToME has some dungeon spoiler pages which have short descriptions

May be worth a look. But I'd propose to put the 'content', the 'flavour', texts off to a later stage. BTW, you are aware of the '~7' knowledge screen (accessible also with 'L' from the travel menu) when the dungeon descriptions are gathered? Also, at the start of the lib/edit/dungeons.txt file there are some remarks about the style of dungeon descriptions and their relation to dungeon definitions (changing the description often should lead to the change of the level generator and/or guardians).

{ EDIT- to clarify, some files will need working up that require no knowledge of the (yet unknown) grand scheme; this work can be begun by anyone who has the motivation to do so. }

You mean the grand scheme of documentation or of the game? For 0.6.2 the game grand scheme is already in place --- LOTR + the Hobbit, the races + the classes, fairy open-ended wilderness unlocking structure, a few battles and rewards, Mr S, Mr M, the West.

*Am I fine collating from the sources, scripts and .txts in the latest offical release, or should I grab the latest SVN from berlios?

For now you are fine. Anything I do I'll be announcing on the forum (as I do e.g. in this post for bards).

*Lastly, you mentioned licensing; I'd presumed that documentation would just come under the same license as the game itself

Which is just the set of two licenses I mentioned.

I don't intend to claim any copyright over anything I do towards this.

Of course you can go Public Domain. But you have to say so. By default you have copyright, sorry, and by default copyright does not allow nearly anything.

*Lastly, again I appeal to all the players watching this thread to either message me your gripes and observations or drop them into a reply in the thread, because many hands make light work.

Concurred. Come on lazy orcs/trolls crawl out from under your rocks, Morgoth's ducks curse you! We need comments about what you can't find in documentation and what should be written there!

[Pete Mack]

*Pete Mack appears to have put in an commendable amount of work modernising the Angband documentation, only moron's wouldn't at least start there as a base for the new help files.

I can't take credit for this; I did a tiny bit of work on the FAQ & such about a year ago, but the recent work has all been done by others. Most of what I did was coding, first to modernize the OSX interface (no more Quickdraw), and then to do a big cleanup of the menu & character knowledge (cmd4.c) code. All of that is included in UnAngband.

[Anne]

Okey-doke, here's more.

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."

Wand of Lightning Beams - "When set in a trap, it electrifys one target."
Mispelled. Should be:
"When set in a trap, it electrifies one target."
(Picky, picky, picky. lol)

Rod of Haste Monsters - gives only throwing info, not zapping.

Light Crossbow of Health Regeneration - "When thrown, it does 1d2+6 blunt damage. When shooting or set in a trap, it multiplies the base damage of bolts by 3. It is a useful ego item."
Shouldn't that mention something about the regeneration since it's already identified in a shop?

Service of Rest until Dawn and Service of Rest until Dusk - no description. Of course, this should be obvious to even a kiddo with or without a description, but I thought I'd mention it.

Mushrooms of Mana - description says "When eaten, it provides nourishment and cures you of mana mites and adds mana to you." This needs some clarification. 'Adds mana' could mean that it replenishes mana up to your max, or it could mean it raises your max. Or maybe it would replenish if low and raise the max if not. Can't tell from this description.

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. It could be the same situation as Slow Poison where it really has no purpose at all.

Rod of Slow Monsters - Only gives throwing info, not using.

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?

And here's some little problems in the notes:

From birth5.txt -
"If auto-haggle is on, the price listed is the price you pay: if you are haggling manually, the price listed is his starting offer, which you can haggle downwards."

Haggling is disabled by default, and the auto_haggle option has been removed (at least from the options screen). The first time I entered a store, I thought I was supposed to haggle and couldn't figure out how. So I think that section should be removed from the note entirely. Those interested in extra options will look into the appropriate file to find out what's available, and trying to cover them in notes meant for raw newbies would be throwing too much information to them at once. It's generally better to stick to what they really need to know at the time.

On Food and Related Victuals (tval80.txt)
From tval80.txt -
Last sentence...
"Many a noble adventurer has succumb to the oversight of not carrying enough food to allow them to journey safely through the wilderness."
Should be 'succumbed' rather than 'succumb'.

It took me a bit to realize that I could put ammo in my quiver by 'wearing' it. Maybe that could be in a starting note, since we start with a sling.

Now, here are some that are pretty vague to raw newbies who haven't played Angband types before:

Service of Recharge Item I - "When purchased, it recharges one staff or wand for 40 power." What do you mean by power? It gives it 40 charges?

Service of Detect Magic - "When purchased, it detects all powerful objects, and senses their power within 40 grids and will sense the general power level on all unknown items in your pack." What do you mean by power level? Would that give a message like "excellent"?

Ring of Feather Falling - "It gives its wielder feather falling." What is feather falling? You don't get hurt if you fall through a trap or something?

Potion of Boldness - "When quaffed, it blasts you with holy magic. When applied to coat an arrow, bolt, sword or polearm, it hits to blast one target with holy magic. When thrown, it does 1d1 blunt damage and creates a ball of radius 1 to blast your enemies with holy magic. When set in a itrap, it blasts one target with holy magic." What's holy magic? Does it only affect undead? Only affect evil creatures? If I'm an evil creature and I use it, is it going to harm me in some way?

Potion of Speed - "When quaffed, it hastes you." Haste only means something to people who've played this type of game before. Maybe something like:
"When quaffed, it temporarily increases your speed."

Scroll of Phase Door - "When read, it teleports you away."
Suggested replacement - "When read, it teleports you a short distance away."
For raw newbies, it helps them to grasp the difference between this and scrolls of teleport. And for those who've played certain other variants, they would then recognize it as blink instead of teleportation.

And lastly, a thought:

Upon attempting to travel to a different area, a message appears that seems to indicate that you can't because you're hungry. You look at the screen and there's nothing on the status bar to indicate hunger. You're told how to eat, and if you try to eat at that point, it just goes on to offer you a choice of destination. The game lets you travel anyway, and upon arrival, you're told that you're dying of starvation even though there still isn't anything visible to indicate hunger, and then you're automatically fed from your food sources.

When I encountered that with my original character, it confused the heck out of me. If I could be dying of starvation, with nothing to visibly indicate that I was hungry, then how was I to know when I needed to eat? It was the first thing that made me wonder whether I'd chosen a game that was going to be too hard for me to figure out.

Also, the fact that it -seemed- to be telling me that I couldn't travel until I ate and then let me travel anyway was another source of confusion, and it came to mind that it must be some sort of buggy coding. That reflected badly on the game, because my immediate thought was that it must be very unfinished if such a bug that would happen to every character at the very beginning of the game hadn't been discovered and fixed yet. Of course, -now- I realize that it's just misleading text rather than buggy coding, but at the time, it gave me a bad impression.

Now, that, I think, would be a prime place to use a note triggered by the first attempt to leave Hobbiton. That way, you could explain the need to eat, and how to tell when you're hungry, versus the current method which tends to confuse rather than teach. Alternatively, the coding could be modified. If it's going to say you're hungry, it should at least show hunger on the status bar. If it's going to say you can't travel til you've eaten, then we shouldn't be able to. Less confusing, and it wouldn't look like a bug.

[Bandobras]

I've found some pages related to documenation:

http://rephial.org/wiki/UserManual

the manual, not finished nor revised yet, but seems nice

http://rephial.org/wiki/UserManual/ToDoList

the following seems wise

My approach to (re)writing the manual is that there are four types of information:

* flavour (descriptive info which may be vague, at times intentionally): for example, a description of the nature of powerful magic weapons (artifacts and ego items)
* useful information for playing the game: for example, information on how to understand the bonuses on magical weapons
* detailed but openly available information: e.g. how to calculate damage dealt in combat
* detailed, hidden information: e.g. a complete list of all artifacts and their attributes

http://www.thangorodrim.net/TANG/index.html

very old, but probably useful text

http://members.cox.net/nppangband/download.htm

NPP, they have some things, e.g. terrain features and 4GAI common with Un, so perhaps we could steal those parts of their manuals, no source code browsing online, unfortunately, archive download required

http://dev.rephial.org/trac/browser/trunk/lib/help

the current V help files

http://svn.berlios.de/svnroot/repos/unangband/trunk/unangband/lib/info/

in-game Un messages

http://svn.berlios.de/svnroot/repos/unangband/trunk/unangband/lib/help/

the current Un docs

[ekolis]

Speaking of "potions of slow poison", just for kicks someone should write a roguelike where "potions of slow poison" don't slow the effects of poison, they actually poison you slowly! Sort of like how the "wand of undead turning" would raise pets back to life in Nethack... for the longest time I had no idea it could be used to repel undead creatures! :P

Time flies! I can't, they're too fast! :P

[Bandobras]

I'll comment on those things that are correctable without touching the lib/help/*.txt documentation.

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.

Rod of Haste Monsters - gives only throwing info, not zapping.

Fixed.

Light Crossbow of Health Regeneration - "When thrown, it does 1d2+6 blunt damage. When shooting or set in a trap, it multiplies the base damage of bolts by 3. It is a useful ego item."
Shouldn't that mention something about the regeneration since it's already identified in a shop?

Filed a bug report.

Service of Rest until Dawn and Service of Rest until Dusk - no description. Of course, this should be obvious to even a kiddo with or without a description, but I thought I'd mention it.

Fixed. The rest for another day.

[Anne]

Flask of (monster-type) Blood - This may be intentional for all I know, but the description displays the monster recall rather than telling anything like what you can do with the item.

In the "Dungeon" help file, item feelings is discussed. I think this will need a going over. I know I sometimes find an item marked as "uncursed" or "very good", neither of which are mentioned there. And I think I've seen a "superb" unless I misremember, and that isn't mentioned there either.

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.


And here's a question - How do you coat a weapon? I can't seem to find the correct key. (I'm using the roguelike keyset.) And I couldn't find anything in the help files unless I just missed it in there. Is that supposed to be a mystery for people to discover on their own? If not, then that needs clarified someplace in the help.

[Pete Mack]

Flask of (monster-type) Blood - This may be intentional for all I know, but the description displays the monster recall rather than telling anything like what you can do with the item.

In the "Dungeon" help file, item feelings is discussed. I think this will need a going over. I know I sometimes find an item marked as "uncursed" or "very good", neither of which are mentioned there. And I think I've seen a "superb" unless I misremember, and that isn't mentioned there either.

UnAngband pseudo-ID has a LOT of possible states, that are determined both at time of creation and if any action like detect curses or detect magic is done. 'uncursed' usually means it's an average object to which detect curse has been applied, but for some classes it may be a magical object.
superb probably means an artifact.

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.

Both are possible, and do 10 damage when thrown, or 2 damage as a coating on arrows and edged weapons. Oil is more useful as a thrown object, outdoors. You can use it to burn up weak monsters, or expose light-sensitive monsters to sunlight. (The beorn quest, and possibly the Weathertop quest, although Weathertop is pretty much impossible now.)

And here's a question - How do you coat a weapon? I can't seem to find the correct key. (I'm using the roguelike keyset.) And I couldn't find anything in the help files unless I just missed it in there. Is that supposed to be a mystery for people to discover on their own? If not, then that needs clarified someplace in the help.

It's 'y' in the original keyset, or ^G in roguelike. And it is a bug in both the documentation and in pref.prf, where it is only called "Engrave a rune (apply)". It should read
"Engrave a rune or apply a coating"
so that searches for 'coat' work properly.

[Bandobras]

Just an explanation: all documentation (all texts) in Un is generated automatically, except various names of things, help files (lib/help), in-game notes (lib/info), wilderness location descriptions (lib/edit/dungeon.txt) and the short monster descriptions (but not the moster blows, resistances, etc.). I intended this thread for discussion mainly about help files (lib/help), perhaps also a little bit about the in-game messages (lib/info).

This is not to say that bug reports about other things are useless. Actually they are even more useful, because they often point to problems with item definitions (not just descriptions), game logic or at least the description generating code.

Now to the point:

Mushrooms of Mana - description says "When eaten, it provides nourishment and cures you of mana mites and adds mana to you." This needs some clarification. 'Adds mana' could mean that it replenishes mana up to your max, or it could mean it raises your max. Or maybe it would replenish if low and raise the max if not. Can't tell from this description.

You are right. I tried "replenish", but I got "replenishs mana of you", which was quite unnatural (though "hits to replenish mana of one target" further in the description was perfect), so I settled for "return", which gives "returns mana to you" and "hits to return mana to one target". Sorry, no chances of localizing Un, either, if even the grammar of the simplest languages on Earth brings such trouble.

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.

Rod of Slow Monsters - Only gives throwing info, not using.

Slow Monsters, actually. Fixed.

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.

More later...