[Un] Restuffing the documentation

[Anne]

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

Ahhh, I see. I understand now. I had assumed that descriptions were pulled from sources that were manually typed up, which is why I was including those here. I'll stick them into the other thread from here on out, to help keep this one cleaner and easier to read. Sorry for the misunderstanding.

Now, for the sake of keeping this thread organized, should I still report here as I find problems with help files and notes, things missing/outdated, etc? Or would you prefer to just get on with planning and such for now without the interruption of that type of post in the midst of it? I could always post them elsewhere if that would be better.

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.

Aha! Thank you -very- much.

[Bandobras]

Ahhh, I see. I understand now. I had assumed that descriptions were pulled from sources that were manually typed up, which is why I was including those here. I'll stick them into the other thread from here on out, to help keep this one cleaner and easier to read.

Great idea.

Now, for the sake of keeping this thread organized, should I still report here as I find problems with help files and notes, things missing/outdated, etc?

I think this is the perfect place and I guess Daven_26d1 and all interested will find it helpful, too. However if you find a minor typo in the in-game notes, you may as well report it elsewhere, because quite probably I'll just fix it right away without any impact on the documentation as a whole.

[Bandobras]

"If auto-haggle is on..."

Actually, there is such an option, but it's a birth-option ('=6'), you cannot change it mid-game. Do you think the note should be more verbose "If the birth option auto-haggle is turned on (default is off)..."?

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.

That sounds a very reasonable rule for rewriting the documentation (and correcting the notes). I don't like options, generally, so I think at least they should not pollute the front pages of documentation...

Should be 'succumbed' rather than 'succumb'.

Fixed.

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.

'W'ield, actually. Good point.

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?

No, it's a factor that determines the probability of success, if I don't oversimplify things? Perhaps we should calculate the probability and display here, then...

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

Yeah, in both cases of "power". How to say it better?

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?

Yes, and it's already fixed thanks to your remarks. It's now "causes it's wielder to fall like a feather". Cryptic, but not jargon any more.

Potion of Boldness - "When quaffed, it blasts you

Hehe, that was a funny bug. Fixed.

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

It's now "it makes you faster". Is your version better? I'm not a native speaker...

Scroll of Phase Door - "When read, it teleports you away."
Suggested replacement - "When read, it teleports you a short distance away."

Sounds reasonable, but it's the same object flag as in ?Teleportation, only a numerical factor (quite complex formula, actually) differs. Is it worth extending the engine? If so, I'll file a feature request to that effect.

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.

Is it really that misleading? Try reading it again...

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.

A good point. Fixed. I tried to enable eating from the menu, but it's too messy, e.g. when you gorge yourself or spit fire the rest of the window has to be updated... So now 'E' just exits the travel menu with a message (the same one-sentence warning, as before the travel menu).

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. [...]

Yeah, updated the bug report about auto-eating with your comments...

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.

So, how to make it clear that it's only a warning and that is does not mean the character is hungry (it means the character is not Full, actually)?

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.

Great idea.

[Anne]

Actually, there is such an option, but it's a birth-option ('=6'), you cannot change it mid-game. Do you think the note should be more verbose "If the birth option auto-haggle is turned on (default is off)..."?

I think it would be very helpful to specify in the "options" help file whenever changing a specific option mid-game wouldn't effect the current game. It would just avoid people becoming confused if they try it and it doesn't seem to work.

As luck would have it, I decided to go through that options file thoroughly today, and I came across the birth_haggle option. It's just in a different section now, and apparently haggling must have been the default an earlier version. Now it's the opposite.

Speaking of which, since I'm going to be testing various options, I decided to neaten up that options file for my own use, getting rid of options that are no longer there, moving options to the correct sections, etc. I'll see whether I can attach it here. Now this was ONLY neatening, not rewriting, but I figured that whoever does the rewrite might want to see it.

If anyone does download this copy:
* Options now appear in the order and under the sections where they appear in the Options screen.
* Options that no longer appear in the Options screen at all were removed.
* Added names of options that were not included in the text file, noting "(description is missing)" where applicable.
* Added a line to each option to indicate whether it is enabled or disabled by default.
* Didn't touch the "Windows flags" or "Leftover Information" sections since I don't know what I'm doing there.

By the way - since we're reserving this thread for text file discussion, I'm responding to the other stuff over on our bug report thread.

[Bandobras]

I think it would be very helpful to specify in the "options" help file whenever changing a specific option mid-game wouldn't effect the current game.

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

> [neat options description file]

Good work.

Edit: Actually, now that it's somewhat fixed, I'd wait with rewriting the options help file till the end, because before 0.6.2-gold we may, if UnAndrew does not object, swipe the options.c file from V, which has several ancient V options removed, and amend it with most of the Un-specific options. Then there'll be less to describe and the V help file will fit better.

[Bandobras]

The knowledge screen with all seen help tips (the in-game help messages) is ready in SVN. The other help-oriented tweaks to the code for 0.6.2-beta2 are going along well, too.

Anne, how should I call you in beta2 changelog, when I mention the countless embarrassing bugs that turned out trivial to fix once you've spotted and reported them? The current description would be "the mysterious Anne", but perhaps you prefer something else...

[Anne]

lol The mysterious Anne is fine by me. Truthfully, it isn't necessary to mention me at all. It isn't as though I'm contributing anything of consequence to the game. If you think it's best to do it anyway for some reason, and Anne is a little too vague for your liking, I also go by Annebrk on the newsgroups, so you could always use that if you'd rather (although I think I've only posted there once). But I honestly don't care about credit for the piddling little bit that I do.

[Nick]

lol The mysterious Anne is fine by me. Truthfully, it isn't necessary to mention me at all. It isn't as though I'm contributing anything of consequence to the game. If you think it's best to do it anyway for some reason, and Anne is a little too vague for your liking, I also go by Annebrk on the newsgroups, so you could always use that if you'd rather (although I think I've only posted there once). But I honestly don't care about credit for the piddling little bit that I do.

Never underestimate how useful any feedback is for a maintainer. The biggest strength the Angband community has is its, um, communityness; positive contributions to that are our lifeblood.

[Bandobras]

But I honestly don't care about credit for the piddling little bit that I do.

Well, credit is actually for our advantage: if people see others contribute to Un (and are not eaten alive by jealous Undead maintainers), they may get encouraged to give the game a chance (and perhaps contribute, too).

As for "little bit", most of the bugs you've found with your fresh sight I'd never find in the source code and most were actually 90% fixed, by the fact they were spotted. What can I ask more for? Moreover, you are a great disputant: you have your views and you can appreciate the value in the fact that not everybody else has the same views. So whenever there was a more serious problem, my implemented solution, whether in accord or disagreement to your proposals, greatly benefited from our discussions. Well, you'll see in beta2, in particular in the travel auto-eating tweaks.

[Anne]

I would love to see more people try the game. The more I play it, the more I'm hooked. A great many of the problems I had when I first tried it were because of the options I'd fiddled with at the very beginning (like auto_more). Now that I'm using the defaults, it's a great deal more enjoyable!

I'm glad for what I've been able to do to help - you know I'm having fun doing it.

[Anne]

The 'Options' help file is now outdated again (er, well more so than before). Since you brought in options used on another game, would it be possible just use their corresponding help text, rather than wait for someone to rewrite ours, or do we add this to the todo list?

[Bandobras]

The 'Options' help file is now outdated again (er, well more so than before).

Yeah. That's how documentation becomes outdated. Ironically, I've changed the options code so that Daven_26d1 & Co have an easier time documenting them.

Since you brought in options used on another game, would it be possible just use their corresponding help text, rather than wait for someone to rewrite ours, or do we add this to the todo list?

Taking the options from V or changing their names to match V was in part intended, just as you propose, to help stealing the new V documentation. It'd be great if somebody did it now that 0.6.2 options are frozen.

The work would be to take the following file

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

(which is unfortunately outdated; I'd at least remove the old options, but I still don't have the Vanilla SVN access, AFAIK)

then remove from it all the options Un does not have (about 1/4, I guess) by looking at the options screen in a running Un

then add all Un options that are not in V, but are documented in Un help file from

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

then add a stub entries for the few remaining Un options.

This way we'd get an almost perfect documentation with minimal effort. Then when V help files and V manual are updated, we'll easily update our documentation as well (the V options are usually included in Un in the same order as in V and at the start of each section).

[Anne]

Okey-doke, I see there are line numbers in that text - do you want those left in or removed?

[Bandobras]

Okey-doke, I see there are line numbers in that text - do you want those left in or removed?

Removed or just use the version without line numbers (any of the "Download in other formats" options, at the bottom of the page)

http://dev.rephial.org/trac/browser/trunk/lib/help/option.txt?format=txt

[Anne]

Well good! Because I happened to have some free time this morning (God bless Saturdays) so I worked a new one up without the line numbers.

Inside this zip are two files. One is the options help file revised, with the date of the revision in the document name. Just in case someone makes any further revisions to it, I figured dates would help to make sure we're looking at the most current one. The other file is the list of changes I made, including a list of options that I removed, which I thought might be handy in the event that I just didn't recognize that an option was renamed rather than removed.

NOTE: THE FILE UPLOADED BELOW IS NOW OUTDATED. SEE LATER POST FOR NEW VERSION.