From: PatR <rankin@nethack.org>
Date: Sun, 3 Jan 2021 01:07:46 +0000 (-0800)
Subject: pickup_types documentation
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=c71dd6696d0ecb3d236d6895430bd10c0f7e9b86;p=nethack

pickup_types documentation

Another one from several years ago.  Document 'pickup_types:.'
as a way to set pickup_types to a value that won't ever cause
anything to be picked up, in order to leave all autopickup
decisions to player's autopickup exceptions.

Actually implementing pickup_types:none would require just as
much documentation plus extra code.
---

diff --git a/doc/Guidebook.mn b/doc/Guidebook.mn
index 451376619..56309501f 100644
--- a/doc/Guidebook.mn
+++ b/doc/Guidebook.mn
@@ -1,4 +1,4 @@
-.\" $NHDT-Branch: NetHack-3.7 $:$NHDT-Revision: 1.410 $ $NHDT-Date: 1608664223 2020/12/22 19:10:23 $
+.\" $NHDT-Branch: NetHack-3.7 $:$NHDT-Revision: 1.411 $ $NHDT-Date: 1609636060 2021/01/03 01:07:40 $
 .\"
 .\" This is an excerpt from the 'roff' man page from the 'groff' package.
 .\" Guidebook.mn currently does *not* fully adhere to these guidelines.
@@ -35,7 +35,7 @@
 .ds vr "NetHack 3.7
 .ds f0 "\*(vr
 .ds f1
-.ds f2 "December 19, 2020
+.ds f2 "January 2, 2021
 .
 .\" A note on some special characters:
 .\" \(lq = left double quote
@@ -3511,8 +3511,11 @@ Persistent.
 .lp "autopickup  "
 Automatically pick up things onto which you move (default on).
 Persistent.
+.lp ""
 See
 .op pickup_types
+and also
+.op autopickup_exception
 to refine the behavior.
 .lp "autoquiver  "
 This option controls what happens when you attempt the \(oqf\(cq (fire)
@@ -4002,15 +4005,30 @@ If this option is on and
 .op autopickup
 is also on, try to pick up things that you threw, even if they aren't in
 .op pickup_types
-or match an autopickup exception.  Default is on.  Persistent.
+or match an autopickup exception.
+Default is on.
+Persistent.
 .lp pickup_types
 Specify the object types to be picked up when
 .op autopickup
-is on.  Default is all types.  You can use
+is on.
+Default is all types.
+Persistent.
+.lp ""
+The value is a list of object symbols, such as
+\f(CRpickup_types:$?!\fP to pick up gold, scrolls, and potions.
+You can use
 .op autopickup_exception
-configuration file lines to further refine
-.op autopickup
-behavior.  Persistent.
+configuration file lines to further refine \f(CRautopickup\fP behavior.
+.lp ""
+There is no way to set \f(CRpickup_types\fP to \(lq\fInone\fP\(rq.
+(Setting it to an empty value reverts to \(lq\fIall\fP\(rq.)
+If you want to avoid automatically picking up any types of items but do
+want to have \f(CRautopickup\fP on in order to have
+\f(CRautopickup_exception\fP settings control what you do and don't pick
+up, you can set \f(CRpickup_types\fP to \(oq\f(CR.\fP\(cq.
+That is the type symbol for \fIvenom\fP and you won't come across
+any venom items so won't unintentionally pick such up.
 .lp pile_limit
 When walking across a pile of objects on the floor, threshold at which
 the message \(lqthere are few/several/many objects here\(rq is given instead
diff --git a/doc/Guidebook.tex b/doc/Guidebook.tex
index e55152a06..e96fccc03 100644
--- a/doc/Guidebook.tex
+++ b/doc/Guidebook.tex
@@ -45,7 +45,7 @@
 %.au
 \author{Original version - Eric S. Raymond\\
 (Edited and expanded for 3.7 by Mike Stephenson and others)}
-\date{December 19, 2020}
+\date{January 2, 2021}
 
 \maketitle
 
@@ -3790,8 +3790,12 @@ Walking into a closed door attempts to open it (default true).
 Persistent.
 %.lp
 \item[\ib{autopickup}]
-Automatically pick up things onto which you move (default on).  Persistent.
-See ``{\it pickup\verb+_+types\/}'' to refine the behavior.
+Automatically pick up things onto which you move (default on).
+Persistent.
+\\
+%.lp ""
+See ``{\it pickup\verb+_+types\/}'' and also
+``{\it autopickup\verb+_+exceptions\/}'' to refine the behavior.
 %.lp
 \item[\ib{autoquiver}]
 This option controls what happens when you attempt the `f' (fire)
@@ -4337,14 +4341,32 @@ or overLoaded), you will be asked if you want to continue.
 If this option is on and ``{\it autopickup\/}'' is also on, try to pick up
 things that you threw, even if they aren't in
 ``{\it pickup\verb+_+types\/}'' or
-match an autopickup exception.  Default is on.  Persistent.
+match an autopickup exception.
+Default is on.
+Persistent.
 %.lp
 \item[\ib{pickup\verb+_+types}]
 Specify the object types to be picked up when ``{\it autopickup\/}''
-is on.  Default is all types.  You can use
+is on.
+Default is all types.
+Persistent.
+\\
+%.lp ""
+The value is a list of object symbols, such as
+{\tt \verb&pickup_types:$?!&} to pick up gold, scrolls, and potions.
+You can use
 ``{\it autopickup\verb+_+exception\/}''
 configuration file lines to further refine ``{\it autopickup\/}'' behavior.
-Persistent.
+\\
+%.lp ""
+There is no way to set {\it pickup\verb+_+types\/} to ``{\it none}''.
+(Setting it to an empty value reverts to ``{\it all}''.)
+If you want to avoid automatically picking up any types of items but do
+want to have {\it autopickup\/} on in order to have
+{\it autopickup\verb+_+exceptions\/} control what you do and don't pick
+up, you can set {\it pickup\verb+_+types\/} to `{\tt .}'.
+That is the type symbol for {\it venom\/} and you won't come across
+any venom items so won't unintentionally pick such up.
 %.lp
 \item[\ib{pile\verb+_+limit}]
 When walking across a pile of objects on the floor, threshold at which