autopickup_exceptions docs and tweak

- document it
-added a goto (shudder) to return to the menu choices after getting
a list of the autopickup_exceptions

doc/Guidebook.mn

@@ -5,7 +5,7 @@
 .ds vr "NetHack 3.4
 .ds f0 "\*(vr
 .ds f1
-.ds f2 "October 5, 2003
+.ds f2 "November 15, 2003
 .mt
 A Guide to the Mazes of Menace
 (Guidebook for NetHack)
@@ -1590,6 +1590,7 @@ in \fIsh\fP or \fIksh\fP.
 .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='',
@@ -1609,7 +1610,13 @@ A zero in any entry in such a sequence leaves the display of that
 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
@@ -1632,7 +1639,10 @@ Cannot be set with the `O' command.
 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 behaviour.
 .lp "autoquiver  "
 This option controls what happens when you attempt the `f' (fire)
 command with an empty quiver.  When true, the computer will fill
@@ -1988,7 +1998,12 @@ or overLoaded), you will be asked if you want to continue.
 .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
+behaviour.
 .lp prayconfirm
 Prompt for confirmation before praying (default on).
 .lp pushweapon
@@ -2253,6 +2268,53 @@ 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 build with that option defined, you can 
+further refine the behaviour 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
+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"
+.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.
+.hn 2
 Configuring User Sounds
 .pg
 Some platforms allow you to define sound files to be played when a message 

doc/Guidebook.tex

@@ -27,7 +27,7 @@
 \begin{document}
 %
 % input file: guidebook.mn
-% $Revision: 1.71 $ $Date: 2003/09/28 03:42:24 $
+% $Revision: 1.72 $ $Date: 2003/10/05 19:56:08 $
 %
 %.ds h0 "
 %.ds h1 %.ds h2 \%
@@ -40,7 +40,7 @@
 %.au
 \author{Eric S. Raymond\\
 (Extensively edited and expanded for 3.4)}
-\date{October 5, 2003}
+\date{November 15, 2003}
 
 \maketitle
 
@@ -2002,6 +2002,7 @@ and the {\it fruit\/} is set to ``papaya'', you would enter the command
 \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=}'',
@@ -2016,7 +2017,12 @@ A zero in any entry in such a sequence leaves the display of that
 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
@@ -2049,7 +2055,8 @@ that can be dug (default false).
 %.lp
 \item[\ib{autopickup}]
 Automatically pick up things onto which you move (default on).
-%.Ip
+See ``{\it pickup\_types\/}'' to refine the behaviour.
+%.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
@@ -2436,8 +2443,11 @@ or overLoaded), you will be asked if you want to continue.
 (Default `S').
 %.lp
 \item[\ib{pickup\_types}]
-Specify the object types to be picked up when {\it autopickup\/}
+Specify the object types to be picked up when ``{\it 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 ``{\it autopickup\_exception\/}'' configuration
+file lines to further refine ``{\it autopickup\/}'' behaviour.
 %.lp
 \item[\ib{prayconfirm}]
 Prompt for confirmation before praying (default on).
@@ -2782,6 +2792,53 @@ 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 build with that option defined, you can 
+further refine the behaviour 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.
+
+Some characters are treated specially if they occur as the first 
+character in the 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"
+\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.
+
 %.lp
 %.hn 2
 \subsection*{Configuring User Sounds}

src/options.c

@@ -2815,6 +2815,7 @@ boolean setinitial,setfromfile;
 		ape = ape->next;
 		numapes++;
 	}
+ape_again:
 	if (numapes > 0) {
 		tmpwin = create_nhwindow(NHW_MENU);
 		start_menu(tmpwin);
@@ -2825,8 +2826,8 @@ boolean setinitial,setfromfile;
 			add_menu(tmpwin, NO_GLYPH, &any, *action_titles[i],
 			      0, ATR_NONE, action_titles[i+1], MENU_UNSELECTED);
         	}
-		end_menu(tmpwin, "Adjust autopickup exception list how?");
+		end_menu(tmpwin, "Do what with autopickup exception list?");
-		if ((pick_cnt = select_menu(tmpwin, PICK_ANY, &pick_list)) > 0) {
+		if ((pick_cnt = select_menu(tmpwin, PICK_ONE, &pick_list)) > 0) {
 			for (pick_idx = 0; pick_idx < pick_cnt; ++pick_idx) {
 				opt_idx = pick_list[pick_idx].item.a_int - 1;
 			}
@@ -2834,11 +2835,12 @@ boolean setinitial,setfromfile;
 			pick_list = (menu_item *)0;
 		}
 		destroy_nhwindow(tmpwin);
+		if (pick_cnt < 1) return FALSE;
 	} /* else just ask for new pickup exception string */
 
 	if (opt_idx == 0) {
 		getlin("What new autopickup exception pattern?", &apebuf[1]);
-		if (apebuf[0] == '\033') retval = FALSE;
+		if (apebuf[1] == '\033') retval = FALSE;
 		apebuf[0] = '"';
 		Strcat(apebuf,"\"");
 		add_autopickup_exception(apebuf);
@@ -2854,6 +2856,7 @@ boolean setinitial,setfromfile;
 		}
 		display_nhwindow(tmpwin, FALSE);
 		destroy_nhwindow(tmpwin);
+		goto ape_again;
 	} else {
 		ape = iflags.autopickup_exceptions;
 		ilet = 'a';