[Un] Restuffing the documentation

Collapse
X
 
  • Time
  • Show
Clear All
new posts
  • Bandobras
    Knight
    • Apr 2007
    • 726

    #31
    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&#37; 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.
    Last edited by Bandobras; March 1, 2008, 21:36.

    Comment

    • Anne
      Adept
      • Feb 2008
      • 134

      #32
      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

      Comment

      • Bandobras
        Knight
        • Apr 2007
        • 726

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

        Comment

        • Anne
          Adept
          • Feb 2008
          • 134

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

          Comment

          • Bandobras
            Knight
            • Apr 2007
            • 726

            #35
            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

            Comment

            • andrewdoull
              Unangband maintainer
              • Apr 2007
              • 872

              #36
              *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&#37; 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.
              The Roflwtfzomgbbq Quylthulg summons L33t Paladins -more-
              In UnAngband, the level dives you.
              ASCII Dreams: http://roguelikedeveloper.blogspot.com
              Unangband: http://unangband.blogspot.com

              Comment

              • andrewdoull
                Unangband maintainer
                • Apr 2007
                • 872

                #37
                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
                The Roflwtfzomgbbq Quylthulg summons L33t Paladins -more-
                In UnAngband, the level dives you.
                ASCII Dreams: http://roguelikedeveloper.blogspot.com
                Unangband: http://unangband.blogspot.com

                Comment

                • Anne
                  Adept
                  • Feb 2008
                  • 134

                  #38
                  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.

                  Actually, I didn't want to remove its description, it just didn't have one. lol.

                  Originally posted by andrewdoull
                  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.
                  I think that's an excellent idea. For one thing, it'll make it easier for more people to help out. And it'll be a handy place to list what needs done, etc.

                  Originally posted by andrewdoull
                  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...
                  That's terrific! It may even help me in my testing - knowing how something is supposed to work will help me to notice when something doesn't work as expected.

                  Comment

                  • Bandobras
                    Knight
                    • Apr 2007
                    • 726

                    #39
                    Originally posted by andrewdoull
                    As I've mentioned elsewhere,
                    I missed or forgotten that one.

                    Originally posted by andrewdoull
                    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.
                    Great idea.

                    Originally posted by andrewdoull
                    The help browser also makes bad assumptions about the screen size that we may want to avoid.
                    You mean 80-column text? That's pretty sane...

                    Originally posted by andrewdoull
                    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 guess they require also the initial text to be under ODFL, so if we ever want the lib/help files to go there (such as the excellent options.txt generated by Anne) we'd have to ask for triple-licensing all the generations of authors...

                    About lib/help files, I think a concise manual of Un, such as the one contained under lib/help, but updated, would be very valuable, regardless of the fact that in-game help notes are so much more attractive and unique. As the manual is a basic thing and is in a sorry state, I proposed to concentrate on it first, but with a wiki we could do everything at once much more easily, indeed.

                    Comment

                    • andrewdoull
                      Unangband maintainer
                      • Apr 2007
                      • 872

                      #40
                      You mean 80-column text? That's pretty sane...
                      Unless you want less than 80 columns. It's also painful to format with most modern text editors.

                      I guess they require also the initial text to be under ODFL, so if we ever want the lib/help files to go there (such as the excellent options.txt generated by Anne) we'd have to ask for triple-licensing all the generations of authors...
                      Yep. Which is why I have reservations about Berlios for wiki hosting.

                      About lib/help files, I think a concise manual of Un, such as the one contained under lib/help, but updated, would be very valuable, regardless of the fact that in-game help notes are so much more attractive and unique. As the manual is a basic thing and is in a sorry state, I proposed to concentrate on it first, but with a wiki we could do everything at once much more easily, indeed.
                      Agreed. Just need to find someone to host a decent wiki.

                      Andrew
                      The Roflwtfzomgbbq Quylthulg summons L33t Paladins -more-
                      In UnAngband, the level dives you.
                      ASCII Dreams: http://roguelikedeveloper.blogspot.com
                      Unangband: http://unangband.blogspot.com

                      Comment

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