[Un] Restuffing the documentation

Collapse
X
 
  • Time
  • Show
Clear All
new posts

  • Anne
    replied
    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.

    Leave a comment:


  • Bandobras
    replied
    Originally posted by Anne
    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.

    Leave a comment:


  • Nick
    replied
    Originally posted by 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.

    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.

    Leave a comment:


  • Anne
    replied
    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.

    Leave a comment:


  • Bandobras
    replied
    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...

    Leave a comment:


  • Bandobras
    replied
    Originally posted by Anne
    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.
    Last edited by Bandobras; February 10, 2008, 23:03.

    Leave a comment:


  • Anne
    replied
    Originally posted by Bandobras
    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.
    Attached Files
    Last edited by Anne; February 10, 2008, 07:57.

    Leave a comment:


  • Bandobras
    replied
    Originally posted by Anne
    "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.

    Leave a comment:


  • Bandobras
    replied
    Originally posted by Anne
    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.

    Leave a comment:


  • Anne
    replied
    Originally posted by 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).
    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.

    Originally posted by Pete Mack
    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.

    Leave a comment:


  • Bandobras
    replied
    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:

    Originally posted by Anne
    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...

    Leave a comment:


  • Pete Mack
    replied
    Originally posted by 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.
    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.

    Leave a comment:


  • Anne
    replied
    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.

    Leave a comment:


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

    Originally posted by Anne
    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.

    Leave a comment:


  • ekolis
    replied
    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

    Leave a comment:

Working...
😀
😂
🥰
😘
🤢
😎
😞
😡
👍
👎
☕