[Pkg-nethack-devel] nethack/doc Guidebook.mn,1.1.1.1,1.2 Guidebook.tex,1.1.1.1,1.2 Guidebook.txt,1.1.1.1,1.2

Tue, 09 Dec 2003 16:14:45 +0000

Update of /cvsroot/pkg-nethack/nethack/doc
In directory quantz:/tmp/cvs-serv9687/doc

Modified Files:
	Guidebook.mn Guidebook.tex Guidebook.txt 
Log Message:
Merge Nethack 3.4.3 upstream source.


Index: Guidebook.mn
===================================================================
RCS file: /cvsroot/pkg-nethack/nethack/doc/Guidebook.mn,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -u -d -r1.1.1.1 -r1.2

--- Guidebook.mn	7 Oct 2003 19:00:04 -0000	1.1.1.1
+++ Guidebook.mn	9 Dec 2003 16:14:43 -0000	1.2
@@ -5,7 +5,7 @@
 .ds vr "NetHack 3.4
 .ds f0 "\*(vr
 .ds f1
-.ds f2 "August 14, 2003
+.ds f2 "December 2, 2003
 .mt
 A Guide to the Mazes of Menace
 (Guidebook for NetHack)
@@ -525,6 +525,8 @@
 Kick something (usually a door).
 .lp e
 Eat food.
+.\" Make sure Elbereth is not hyphenated below, the exact spelling matters
+.hw Elbereth
 .lp E
 Engrave a message on the floor.
 Engraving the word ``Elbereth'' will cause most monsters to not attack
@@ -873,6 +875,57 @@
 .pg
 Ladders serve the same purpose as staircases, and the two types of
 inter-level connections are nearly indistinguishable during game play.
+.hn 2
+Shops and shopping
+.pg
+Occasionally you will run across a room with a shopkeeper near the door
+and many items lying on the floor.  You can buy items by picking them
+up and then using the `p' command.  You can inquire about the price
+of an item prior to picking it up by using the ``#chat'' command
+while standing on it.  Using an item prior to paying for it will incur a
+charge, and the shopkeeper won't allow you to leave the shop until you
+have paid any debt you owe.
+.pg
+You can sell items to a shopkeeper by dropping them to the floor while
+inside a shop.  You will either be offered an amount of gold and asked
+whether you're willing to sell, or you'll be told that the shopkeeper
+isn't interested (generally, your item needs to be compatible with the
+type of merchandise carried by the shop).
+.pg
+If you drop something in a shop by accident, the shopkeeper will usually
+claim ownership without offering any compensation.  You'll have to buy
+it back if you want to reclaim it.
+.pg
+Shopkeepers sometimes run out of money.  When that happens, you'll be
+offered credit instead of gold when you try to sell something.  Credit
+can be used to pay for purchases, but it is only good in the shop where
+it was obtained; other shopkeepers won't honor it.  (If you happen to
+find a "credit card" in the dungeon, don't bother trying to use it in
+shops; shopkeepers will not accept it.)
+.pg
+The `$' command, which reports the amount of gold you are carrying
+(in inventory, not inside bags or boxes), will also show current shop
+debt or credit, if any.  The `Iu' command lists unpaid items
+(those which still belong to the shop) if you are carrying any.
+The `Ix' command shows an inventory-like display of any unpaid
+items which have been used up, along with other shop fees, if any.
+.hn 3
+Shop idiosyncracies
+.pg
+Several aspects of shop behavior might be unexpected.
+.\" note: using * instead of \(bu is better for plain text output
+.lp * 2
+The price of a given item can vary due to a variety of factors.
+.lp * 2
+A shopkeeper treats the spot immediately inside the door as if it were
+outside the shop.
+.lp * 2
+While the shopkeeper watches you like a hawk, he will generally ignore
+any other customers.
+.lp * 2
+If a shop is "closed for inventory", it will not open of its own accord.
+.lp * 2
+Shops do not get restocked with new items, regardless of inventory depletion.
 
 .hn 1
 Monsters
@@ -1533,7 +1586,7 @@
 .pg
 There are several other challenges tracked by the game.  It is possible
 to eliminate one or more species of monsters by genocide; playing without
-this feature is considered a challenge.  When you game offers you an
+this feature is considered a challenge.  When the game offers you an
 opportunity to genocide monsters, you may respond with the monster type
 ``none'' if you want to decline.  You can change the form of an item into
 another item of the same type (``polypiling'') or the form of your own
@@ -1588,6 +1641,7 @@
 .hn 2
 Using a configuration file
 .pg
+Any line in the configuration file starting with `#' is treated as a comment.
 Any line in the configuration file starting with ``OPTIONS='' may be
 filled out with options in the same syntax as in NETHACKOPTIONS.
 Any line starting with ``DUNGEON='', ``EFFECTS='', ``MONSTERS='',
@@ -1607,7 +1661,13 @@
 entry unchanged; this feature is not available using the option syntax.
 Such a sequence can be continued to multiple lines by putting a `\e'
 at the end of each line to be continued.
-Any line starting with `#' is treated as a comment.
+.pg
+If your copy of the game included the compile time AUTOPICKUP_EXCEPTIONS
+option, then any line starting with ``AUTOPICKUP_EXCEPTION='' is taken
+as defining an exception to the 
+.op pickup_types
+option. 
+There is a section of this Guidebook that discusses that.
 .pg
 The default name of the configuration file varies on different
 operating systems, but NETHACKOPTIONS can also be set to
@@ -1627,7 +1687,10 @@
 Automatically dig if you are wielding a digging tool and moving into a place
 that can be dug (default false).
 .lp "autopickup  "
-Automatically pick up things onto which you move (default on).
+Automatically pick up things onto which you move (default on). 
+See
+.op pickup_types
+to refine the behavior.
 .lp "autoquiver  "
 This option controls what happens when you attempt the `f' (fire)
 command with an empty quiver.  When true, the computer will fill
@@ -1840,13 +1903,17 @@
 Implemented by the Amiga, Gem, X11 and tty ports.
 Default '-'.
 .lp menu_deselect_page
-Menu character accelerator deselect all items on this page of a menu.
+Menu character accelerator to deselect all items on this page of a menu.
 Implemented by the Amiga, Gem and tty ports.
 Default '\e'.
 .lp menu_first_page
 Menu character accelerator to jump to the first page in a menu.
 Implemented by the Amiga, Gem and tty ports.
 Default '^'.
+.lp menu_headings
+Controls how the headings in a menu are highlighted.
+Values are 'bold', 'inverse', or 'underline'.
+Not all ports can actually display all three types.
 .lp menu_invert_all
 Menu character accelerator to invert all items in a menu.
 Implemented by the Amiga, Gem, X11 and tty ports.
@@ -1942,7 +2009,7 @@
 Send padding nulls to the terminal (default off).
 .lp number_pad
 Use the number keys to move instead of [yuhjklbn] (default 0 or off).
-(number_pad:2 invokes the old DOS behaviour where `5' means `g', meta-`5'
+(number_pad:2 invokes the old DOS behavior where `5' means `g', meta-`5'
 means `G',  and meta-`0' means `I'.)
 .lp objects
 Set the characters used to display object classes
@@ -1976,7 +2043,12 @@
 .lp pickup_types
 Specify the object types to be picked up when
 .op autopickup
-is on.  Default is all types.
+is on.  Default is all types.  If your copy of the game has the experimental
+compile time option AUTOPICKUP_EXCEPTIONS included, you may be able to use 
+.op autopickup_exception
+configuration file lines to further refine
+.op autopickup
+behavior.
 .lp prayconfirm
 Prompt for confirmation before praying (default on).
 .lp pushweapon
@@ -2190,7 +2262,7 @@
 Platform-specific Customization options
 .pg
 Here are explanations of options that are used by specific platforms or ports 
-to customize and change the port behaviour.
+to customize and change the port behavior.
 .lp altkeyhandler
 Select an alternate keystroke handler dll to load (Win32 tty NetHack only).
 The name of the handler is specified without the .dll extension and without any
@@ -2218,7 +2290,7 @@
 .lp soundcard
 (default on, PC NetHack only).
 Cannot be set with the `O' command.
-.lp subkeyval
+.lp subkeyvalue
 (Win32 tty NetHack only).
 May be used to alter the value of keystrokes that the operating system
 returns to NetHack to help compensate for international keyboard issues.
@@ -2245,6 +2317,64 @@
 If the game display is difficult to read, try adjusting these scales;
 if this does not correct the problem, try !color.
 Cannot be set with the `O' command.
+.hn 2
+Configuring autopickup exceptions
+.pg
+There is an experimental compile time option called AUTOPICKUP_EXCEPTIONS.  
+If your copy of the game was built with that option defined, you can 
+further refine the behavior of the
+.op autopickup
+option beyond what is available through the 
+.op pickup_types
+option. 
+.pg
+By placing 
+.op autopickup_exception
+lines in your configuration
+file, you can define patterns to be checked when the game is about to
+autopickup something.
+.lp autopickup_exception
+Sets an exception to the 
+.op pickup_types
+option.
+The
+.op autopickup_exception
+option should be followed by a string of 1-80 characters to be used as a 
+pattern to match against the singular form of the description of an 
+object at your location.
+.pg
+You may use the following special characters in a pattern:
+.sd
+.si
+  *--- matches 0 or more characters.
+  ?--- matches any single character.
+.ei
+.ed
+.pg
+In addition, some characters are treated specially if they occur as the first 
+character in the string pattern, specifically:
+.sd
+.si
+< - always pickup an object that matches the pattern that follows.
+> - never pickup an object that matches the pattern that follows.
+.ei
+.ed
+.pg
+Can be set with the `O' command, but the setting is not preserved
+across saves and restores.
+.pg
+Here's a couple of examples of autopickup_exceptions:
+.sd
+.si
+autopickup_exception="<*arrow"
+autopickup_exception=">*corpse"
+autopickup_exception=">* cursed*"
+.ei
+.ed
+The first example above will result in autopickup of any type of arrow.
+The second example results in the exclusion of any corpse from autopickup.
+The last example results in the exclusion of items known to be cursed from autopickup.
+A `never pickup' rule takes precedence over an `always pickup' rule if both match.
 .hn 2
 Configuring User Sounds
 .pg

Index: Guidebook.txt
===================================================================
RCS file: /cvsroot/pkg-nethack/nethack/doc/Guidebook.txt,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -u -d -r1.1.1.1 -r1.2
--- Guidebook.txt	7 Oct 2003 19:00:05 -0000	1.1.1.1
+++ Guidebook.txt	9 Dec 2003 16:14:43 -0000	1.2
@@ -126,7 +126,7 @@
           as well as tracking and stealthy movement.
 
 
-          NetHack 3.4                                       August 14, 2003
+          NetHack 3.4                                      December 2, 2003
 
 
 
@@ -192,7 +192,7 @@
 
 
[...3609 lines suppressed...]
 
 
@@ -3474,7 +3606,7 @@
                    Helge Hafting            Mike Gallop
                Irina Rempt-Drijfhout      Mike Passaretti
 
-          Brand and product names are trademarks or  registered  trademarks
+          Brand  and  product names are trademarks or registered trademarks
           of their respective holders.
 
 
@@ -3492,7 +3624,7 @@
 
 
 
-          NetHack 3.4                                       August 14, 2003
+          NetHack 3.4                                      December 2, 2003
 
 
 

Index: Guidebook.tex
===================================================================
RCS file: /cvsroot/pkg-nethack/nethack/doc/Guidebook.tex,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -u -d -r1.1.1.1 -r1.2
--- Guidebook.tex	7 Oct 2003 19:00:04 -0000	1.1.1.1
+++ Guidebook.tex	9 Dec 2003 16:14:43 -0000	1.2
@@ -40,7 +40,7 @@
 %.au
 \author{Eric S. Raymond\\
 (Extensively edited and expanded for 3.4)}
-\date{August 14, 2003}
+\date{December 2, 2003}
 
 \maketitle
 
@@ -702,6 +702,10 @@
 \item[\tb{e}]
 Eat food.
 %.lp
+% Make sure Elbereth is not hyphenated below, the exact spelling matters.
+% (Only specified here to parallel Guidebook.mn; use of \tt font implicity
+% prevents automatic hyphenation in TeX and LaTeX.)
+\hyphenation{Elbereth}		%override the deduced syllable breaks
 \item[\tb{E}]
 Engrave a message on the floor.
 Engraving the word ``{\tt Elbereth}'' will cause most monsters to not attack
@@ -1162,6 +1166,73 @@
 Ladders serve the same purpose as staircases, and the two types of
 inter-level connections are nearly indistinguishable during game play.
 
+%.hn 2
+\subsection*{Shops and shopping}
+
+%.pg
+Occasionally you will run across a room with a shopkeeper near the door
+and many items lying on the floor.  You can buy items by picking them
+up and then using the `{\tt p}' command.  You can inquire about the price
+of an item prior to picking it up by using the ``{\tt \#chat}'' command
+while standing on it.  Using an item prior to paying for it will incur a
+charge, and the shopkeeper won't allow you to leave the shop until you
+have paid any debt you owe.
+
+%.pg
+You can sell items to a shopkeeper by dropping them to the floor while
+inside a shop.  You will either be offered an amount of gold and asked
+whether you're willing to sell, or you'll be told that the shopkeeper
+isn't interested (generally, your item needs to be compatible with the
+type of merchandise carried by the shop).
+
+%.pg
+If you drop something in a shop by accident, the shopkeeper will usually
+claim ownership without offering any compensation.  You'll have to buy
+it back if you want to reclaim it.
+
+%.pg
+Shopkeepers sometimes run out of money.  When that happens, you'll be
+offered credit instead of gold when you try to sell something.  Credit
+can be used to pay for purchases, but it is only good in the shop where
+it was obtained; other shopkeepers won't honor it.  (If you happen to
+find a ``credit card'' in the dungeon, don't bother trying to use it in
+shops; shopkeepers will not accept it.)
+
+%.pg
+The {\tt \$} command, which reports the amount of gold you are carrying
+(in inventory, not inside bags or boxes), will also show current shop
+debt or credit, if any.  The {\tt Iu} command lists unpaid items
+(those which still belong to the shop) if you are carrying any.
+The {\tt Ix} command shows an inventory-like display of any unpaid
+items which have been used up, along with other shop fees, if any.
+
+%.hn 3
+\subsubsection*{Shop idiosyncracies}
+
+%.pg
+Several aspects of shop behavior might be unexpected.
+
+\begin{itemize}
+% note: a bullet is the default item label so we could omit [$\bullet$] here
+%.lp \(bu 2
+\item[$\bullet$]
+The price of a given item can vary due to a variety of factors.
+%.lp \(bu 2
+\item[$\bullet$]
+A shopkeeper treats the spot immediately inside the door as if it were
+outside the shop.
+%.lp \(bu 2
+\item[$\bullet$]
+While the shopkeeper watches you like a hawk, he will generally ignore
+any other customers.
+%.lp \(bu 2
+\item[$\bullet$]
+If a shop is ``closed for inventory'', it will not open of its own accord.
+%.lp \(bu 2
+\item[$\bullet$]
+Shops do not get restocked with new items, regardless of inventory depletion.
+\end{itemize}
+
 %.hn 1
 \section{Monsters}
 
@@ -1928,7 +1999,7 @@
 %.pg
 There are several other challenges tracked by the game.  It is possible
 to eliminate one or more species of monsters by genocide; playing without
-this feature is considered a challenge.  When you game offers you an
+this feature is considered a challenge.  When the game offers you an
 opportunity to genocide monsters, you may respond with the monster type
 ``none'' if you want to decline.  You can change the form of an item into
 another item of the same type (``polypiling'') or the form of your own
@@ -1999,6 +2070,7 @@
 \subsection*{Using a configuration file}
 
 %.pg
+Any line in the configuration file starting with `{\tt \#}' is treated as a comment.
 Any line in the configuration file starting with ``{\tt OPTIONS=}'' may be
 filled out with options in the same syntax as in NETHACKOPTIONS.
 Any line starting with ``{\tt DUNGEON=}'', ``{\tt EFFECTS=}'',
@@ -2013,7 +2085,12 @@
 entry unchanged; this feature is not available using the option syntax.
 Such a sequence can be continued to multiple lines by putting a
 `{\tt \verb+\+}' at the end of each line to be continued.
-Any line starting with `{\tt \#}' is treated as a comment.
+
+%.pg
+If your copy of the game included the compile time AUTOPICKUP\_EXCEPTIONS 
+option, then any line starting with ``{\tt AUTOPICKUP\_EXCEPTION=}'' 
+is taken as defining an exception to the ``{\tt pickup\_types}'' option.
+There is a section of this Guidebook that discusses that.
 
 %.pg
 The default name of the configuration file varies on different
@@ -2042,7 +2119,8 @@
 %.lp
 \item[\ib{autopickup}]
 Automatically pick up things onto which you move (default on).
-%.Ip
+See ``{\it pickup\_types\/}'' to refine the behavior.
+%.lp
 \item[\ib{autoquiver}]
 This option controls what happens when you attempt the `f' (fire)
 command with an empty quiver.  When true, the computer will fill
@@ -2276,13 +2354,17 @@
 Implemented by the Amiga, Gem, X11 and tty ports.
 Default `-'.
 \item[\ib{menu\_deselect\_page}]
-Menu character accelerator deselect all items on this page of a menu.
+Menu character accelerator to deselect all items on this page of a menu.
 Implemented by the Amiga, Gem and tty ports.
 Default `\verb+\+'.
 \item[\ib{menu\_first\_page}]
 Menu character accelerator to jump to the first page in a menu.
 Implemented by the Amiga, Gem and tty ports.
 Default `\verb+^+'.
+\item[\ib{menu\_headings}]
+Controls how the headings in a menu are highlighted.
+Values are ``{\tt bold}'', ``{\tt inverse}'', or ``{\tt underline}''.
+Not all ports can actually display all three types.
 \item[\ib{menu\_invert\_all}]
 Menu character accelerator to invert all items in a menu.
 Implemented by the Amiga, Gem, X11 and tty ports.
@@ -2385,7 +2467,7 @@
 %.lp
 \item[\ib{number\_pad}]
 Use the number keys to move instead of {\tt [yuhjklbn]} (default 0 or off).
-(number\_pad:2 invokes the old DOS behaviour where `{\tt 5}' means `{\tt g}', 
+(number\_pad:2 invokes the old DOS behavior where `{\tt 5}' means `{\tt g}', 
 meta-`{\tt 5}' means `{\tt G}',  and meta-`{\tt 0}' means `{\tt I}'.)
 %.lp
 \item[\ib{objects}]
@@ -2421,8 +2503,11 @@
 (Default `S').
 %.lp
 \item[\ib{pickup\_types}]
-Specify the object types to be picked up when {\it autopickup\/}
-is on.  Default is all types.
+Specify the object types to be picked up when ``{\it autopickup\/}'' 
+is on.  Default is all types.  If your copy of the game has the
+experimental compile time option AUTOPICKUP\_EXCEPTIONS included,
+you may be able to use ``{\it autopickup\_exception\/}'' configuration
+file lines to further refine ``{\it autopickup\/}'' behavior.
 %.lp
 \item[\ib{prayconfirm}]
 Prompt for confirmation before praying (default on).
@@ -2701,7 +2786,7 @@
 
 %.pg
 Here are explanations of options that are used by specific platforms 
-or ports to customize and change the port behaviour.
+or ports to customize and change the port behavior.
 
 \blist{}
 %.lp
@@ -2739,7 +2824,7 @@
 (default off, {\it PC NetHack \/} only).
 Cannot be set with the `{\tt O}' command.
 %.lp
-\item[\ib{subkeyval}]
+\item[\ib{subkeyvalue}]
 ({\it Win32 tty NetHack \/} only).
 May be used to alter the value of keystrokes that the operating system
 returns to NetHack to help compensate for international keyboard issues.
@@ -2772,6 +2857,64 @@
 if this does not correct the problem, try {\tt !color}.
 Cannot be set with the `{\tt O}' command.
 \elist
+
+%.lp
+%.hn 2
+\subsection*{Configuring autopickup exceptions}
+
+%.pg
+There is an experimental compile time option called AUTOPICKUP_EXCEPTIONS.  
+If your copy of the game was built with that option defined, you can 
+further refine the behavior of the ``{\tt autopickup}'' option beyond 
+what is available through the ``{\tt pickup\_types}'' option.
+
+%.pg
+By placing ``{\tt autopickup\_exception}'' lines in your configuration
+file, you can define patterns to be checked when the game is about to
+autopickup something.
+
+\blist{}
+%.lp
+\item[\ib{autopickup\_exception}]
+Sets an exception to the `{\it pickup\_types}' option.
+The {\it autopickup\_exception\/} option should be followed by a string of 1--80
+characters to be used as a pattern to match against the singular form
+of the description of an object at your location.
+
+%.pg
+You may use the following special characters in a pattern:
+
+\begin{verbatim}
+    *--- matches 0 or more characters.
+    ?--- matches any single character.
+\end{verbatim}
+
+In addition, some characters are treated specially if they occur as the first 
+character in the specified string pattern, specifically:
+
+%.sd
+%.si
+{\tt <} --- always pickup an object that matches the pattern that follows.\\
+{\tt >} --- never pickup an object that matches the pattern that follows.
+%.ei
+%.ed
+
+Can be set with the `{\tt O}' command, but the setting is not preserved
+across saves and restores.
+\elist
+
+%.pg
+Here's a couple of examples of autopickup\_exceptions:
+\begin{verbatim}
+    autopickup_exception="<*arrow"
+    autopickup_exception=">*corpse"
+    autopickup_exception=">* cursed*"
+\end{verbatim}
+
+The first example above will result in autopickup of any type of arrow.
+The second example results in the exclusion of any corpse from autopickup.
+The last example results in the exclusion of items known to be cursed from autopickup.
+A `never pickup' rule takes precedence over an `always pickup' rule if both match.
 
 %.lp
 %.hn 2



