From a1e3943e1f6f8337b66589d32aecd50688fc20b2 Mon Sep 17 00:00:00 2001
From: PatR <rankin@nethack.org>
Date: Thu, 1 May 2025 15:43:57 -0700
Subject: [PATCH] fix #K4327 - inaccurate Guidebook for role/race/&c

The Guidebook states that the default values for 'role', 'race',
'gender', and 'alignment' are "random" but that's wrong.  Omitting
those options results in interactive prompting.
---
 doc/Guidebook.mn  | 19 ++++++++++++++-----
 doc/Guidebook.tex | 21 ++++++++++++++++-----
 2 files changed, 30 insertions(+), 10 deletions(-)

diff --git a/doc/Guidebook.mn b/doc/Guidebook.mn
index 7d3530359..e852ff559 100644
--- a/doc/Guidebook.mn
+++ b/doc/Guidebook.mn
@@ -47,7 +47,7 @@
 .ds f0 \*(vr
 .ds f1 \" empty
 .\"DO NOT REMOVE NH_DATESUB .ds f2 Date(%B %-d, %Y)
-.ds f2 April 20, 2025
+.ds f2 May 1, 2025
 .
 .\" A note on some special characters:
 .\" \(lq = left double quote
@@ -3788,7 +3788,8 @@ See
 .op role
 for a description of how to use negation to exclude choices.
 .lp ""
-Default is random.
+If \f(CRalign\fP is not specified, there is no default value;
+player will be prompted unless role and/or race forces a choice for alignment.
 Cannot be set with the \(oq\f(CRO\fP\(cq command.
 Persistent.
 .lp autodescribe
@@ -4014,7 +4015,8 @@ See
 .op role
 for a description of how to use negation to exclude choices.
 .lp ""
-Default is random.
+If \f(CRgender\fP is not specified, there is no default value;
+player will be prompted unless role and/or race forces a choice for gender.
 Cannot be set with the \(oq\f(CRO\fP\(cq command.
 Persistent.
 .lp "goldX   "
@@ -4284,6 +4286,11 @@ the role (that is, by suffixing one of
 If
 .op "\-@"
 is used for the role, then a random one will be automatically chosen.
+.lp ""
+On some systems, the default is the player's user name;
+on others, there is no default and the player will be prompted.
+The former can made to behave like the latter by specifying a generic name
+such as ``player''.
 Cannot be set with the \(oq\f(CRO\fP\(cq command.
 .lp "news    "
 Read the NetHack news file, if present (default on).
@@ -4544,7 +4551,8 @@ See
 .op role
 for a description of how to use negation to exclude choices.
 .lp ""
-Default is random.
+If \f(CRrace\fP is not specified, there is no default value;
+player will be prompted unless role forces a choice for race.
 Cannot be set with the \(oq\f(CRO\fP\(cq command.
 Persistent.
 .lp rest_on_space
@@ -4580,7 +4588,8 @@ option if they're all negations.
 .\" Only one positive value is allowed, and if present, it overrides any
 .\" negations.
 .lp ""
-Default is \f(CRrandom\fP.
+If \f(CRrole\fP is not specified, there is no default value;
+player will be prompted.
 Cannot be set with the \(oq\f(CRO\fP\(cq command.
 Persistent.
 .lp roguesymset
diff --git a/doc/Guidebook.tex b/doc/Guidebook.tex
index 6d7f1d38c..f590cefa3 100644
--- a/doc/Guidebook.tex
+++ b/doc/Guidebook.tex
@@ -48,7 +48,7 @@
 \author{Original version - Eric S. Raymond\\
 (Edited and expanded for 3.7.0 by Mike Stephenson and others)}
 %DO NOT REMOVE NH_DATESUB \date{Date(%B %-d, %Y)}
-\date{April 20, 2025}
+\date{May 1, 2025}
 
 \maketitle
 
@@ -4145,7 +4145,8 @@ See {\it role\/}
 for a description of how to use negation to exclude choices.
 %.lp ""
 \\
-Default is random.
+If {\tt align} is not specified, there is no default value;
+player will be prompted unless role and/or race forces a choice for alignment.
 Cannot be set with the `{\tt O}' command.  Persistent.
 %.lp
 \item[\ib{autodescribe}]
@@ -4400,7 +4401,8 @@ See {\it role\/}
 for a description of how to use negation to exclude choices.
 %.lp ""
 \\
-Default is random.
+If {\tt gender} is not specified, there is no default value;
+player will be prompted unless role and/or race forces a choice for gender.
 Cannot be set with the `{\tt O}' command.  Persistent.
 %.lp
 \item[\ib{goldX}]
@@ -4708,6 +4710,12 @@ the role (that is, by suffixing one of
 ``{\tt -A -B -C -H -K -M -P -Ra -Ro -S -T -V -W}'').
 If ``{\tt -@}'' is used for the role, then a random one will be
 automatically chosen.
+%.lp
+\\
+On some systems, the default is the player's user name;
+on others, there is no default and the player will be prompted.
+The former can made to behave like the latter by specifying a generic name
+such as ``player''.
 Cannot be set with the `{\tt O}' command.
 %.lp
 \item[\ib{news}]
@@ -4990,7 +4998,9 @@ See {\it role\/}
 for a description of how to use negation to exclude choices.
 %.lp ""
 \\
-Default is random.
+If {\tt race} is not specified, there is no default value;
+player will be prompted unless role forces a choice for race.
+unless role forces a choice for race.
 Cannot be set with the `{\tt O}' command.  Persistent.
 %.lp
 \item[\ib{rest\verb+_+on\verb+_+space}]
@@ -5025,7 +5035,8 @@ option if they're all negations.
 %.\" negations.
 %.lp ""
 \\
-Default is random.
+If {\tt role} is not specified, there is no default value;
+player will be prompted.
 Cannot be set with the `{\tt O}' command.  Persistent.
 %.lp
 \item[\ib{roguesymset}]