From 75e2a6a669e593c06108d0176ea1c6485ddd946e Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Sat, 25 Oct 2025 19:19:44 -0500 Subject: [PATCH 01/39] doc/nethack.6: Fix invalid *roff syntax Also fix a case hidden by a comment. Fixes: $ nroff -ww -z -man doc/*.[67] troff:doc/nethack.6:68: warning: escape character ignored before '@' troff:doc/nethack.6:292: warning: escape character ignored before '@' --- doc/nethack.6 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/nethack.6 b/doc/nethack.6 index 85b99c389..605bb56ff 100644 --- a/doc/nethack.6 +++ b/doc/nethack.6 @@ -65,7 +65,7 @@ nethack \- Exploring The Mazes of Menace .I race ] [ -.B \-\@ +.B \-@ ] .PP Also @@ -240,7 +240,7 @@ character's gender. Any of the parts of the suffix may be left out. can be used to determine the character profession, also known as the role. You can specify either the male or female name for the character role, or the first three characters of the role as an abbreviation. -.\" .B "\-p \@" +.\" .B "\-p @" .\" has been retained to explicitly request that a random role be chosen. .\" It may need to be quoted with a backslash (\\@) if @ .\" is the "kill" character (see "stty") for the terminal, in order @@ -289,7 +289,7 @@ is already used for the .I Rogue role. .PP -.B \-\@ +.B \-@ tells nethack to choose any omitted characteristics (profession/role, race, gender, alignment) randomly without prompting. Otherwise, leaving out any of these characteristics will result in you From 387140956057e74790fdc4e0c80fa38d112b495e Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Sat, 25 Oct 2025 19:42:51 -0500 Subject: [PATCH 02/39] doc/nethack.6: Fix poor commented-out *roff syntax MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit groff_man_style(7): Portability ... \e Format the roff escape character on the output; widely used in man pages to render a backslash glyph. It works reliably as long as the “ec” request is not used, which should never happen in man pages, and it is slightly more portable than the more explicit \[rs] (“reverse solidus”) special character escape sequence. This change's purpose is to put things right in case the change I'm proposing next to delete this language entirely gets reverted. --- doc/nethack.6 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/nethack.6 b/doc/nethack.6 index 605bb56ff..7e0ddde02 100644 --- a/doc/nethack.6 +++ b/doc/nethack.6 @@ -242,7 +242,7 @@ You can specify either the male or female name for the character role, or the first three characters of the role as an abbreviation. .\" .B "\-p @" .\" has been retained to explicitly request that a random role be chosen. -.\" It may need to be quoted with a backslash (\\@) if @ +.\" It may need to be quoted with a backslash (\e@) if @ .\" is the "kill" character (see "stty") for the terminal, in order .\" to prevent the current input line from being cleared. .PP From d90422f0ce1708c8493fcec796acf61a4cd80ea6 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Sat, 25 Oct 2025 19:45:09 -0500 Subject: [PATCH 03/39] doc/nethack.6: Drop commented-out legacy remark Unix terminal drivers started transitioning away from paper terminals and toward video terminals, and therefore away from '#' and '@' as the "erase" and "kill" characters, respectively, before NetHack was born. --- doc/nethack.6 | 3 --- 1 file changed, 3 deletions(-) diff --git a/doc/nethack.6 b/doc/nethack.6 index 7e0ddde02..c9a5bcbfb 100644 --- a/doc/nethack.6 +++ b/doc/nethack.6 @@ -242,9 +242,6 @@ You can specify either the male or female name for the character role, or the first three characters of the role as an abbreviation. .\" .B "\-p @" .\" has been retained to explicitly request that a random role be chosen. -.\" It may need to be quoted with a backslash (\e@) if @ -.\" is the "kill" character (see "stty") for the terminal, in order -.\" to prevent the current input line from being cleared. .PP Likewise, .B \-r From 723afcd51fac7d70637553ff7006f913291d5ebc Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Sat, 25 Oct 2025 18:20:25 -0500 Subject: [PATCH 04/39] doc/*.6: Fix macro usage style errors Fixes: $ nroff -ww -z -rCHECKSTYLE=4 -man doc/*.[67] an.tmac:doc/dlb.6:41: style: .IR expects at least 2 arguments, got 1 an.tmac:doc/makedefs.6:125: style: .IR expects at least 2 arguments, got 1 an.tmac:doc/makedefs.6:131: style: .IR expects at least 2 arguments, got 1 an.tmac:doc/makedefs.6:137: style: .IR expects at least 2 arguments, got 1 an.tmac:doc/nethack.6:89: style: .BR expects at least 2 arguments, got 1 an.tmac:doc/nethack.6:129: style: .BR expects at least 2 arguments, got 1 an.tmac:doc/nethack.6:273: style: .BR expects at least 2 arguments, got 1 --- doc/dlb.6 | 2 +- doc/makedefs.6 | 6 +++--- doc/nethack.6 | 6 +++--- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/dlb.6 b/doc/dlb.6 index b58b12164..d4557ae18 100644 --- a/doc/dlb.6 +++ b/doc/dlb.6 @@ -38,7 +38,7 @@ dlb \- NetHack data librarian }\c .RB [ v ]\c .B I -.IR list-file +.I list-file .PP .B dlb {\c diff --git a/doc/makedefs.6 b/doc/makedefs.6 index f33dc42e1..e2813adc8 100644 --- a/doc/makedefs.6 +++ b/doc/makedefs.6 @@ -122,19 +122,19 @@ Generate the .TP .B -1 Generate the -.IR epitaph +.I epitaph file. .br .TP .B -2 Generate the -.IR engrave +.I engrave file. .br .TP .B -3 Generate the -.IR bogusmon +.I bogusmon file. .br .TP diff --git a/doc/nethack.6 b/doc/nethack.6 index c9a5bcbfb..a9c46e6fc 100644 --- a/doc/nethack.6 +++ b/doc/nethack.6 @@ -86,7 +86,7 @@ Also | .BR \-R | \-Rog | -.BR \-Ran +.B \-Ran | .BR \-S | \-Sam | @@ -126,7 +126,7 @@ Also .B \-\-help ] [ -.BR \-\-showpaths +.B \-\-showpaths ] .\" force line wrap now rather than have that happen after the opening brace .br @@ -267,7 +267,7 @@ The | .BR \-R | \-Rog | -.BR \-Ran +.B \-Ran | .BR \-S | \-Sam | From c91ee79dcb721a63e5371cc0d3b0bbea16bb43ef Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Sat, 25 Oct 2025 19:21:38 -0500 Subject: [PATCH 05/39] doc/nethack.6: Fix inelegant formatting Replace instances of blank line paragraphing with `PP` macro calls. There are three problems with the style of paragraphing that this commit fixes. 1. A `br` break request is redundant with an adjacent blank text line. 2. A `br` request is also redundant with a paragraphing macro call. 3. When you use a paragraphing macro call instead of a blank text line, you get the configured amount inter-paragraph space. When typesetting with the man(7) package, the default inter-paragraph space amount is 0.4v. A blank text line usually puts 1v of empty space into the document. See groff_man_style(7). Fixes: $ nroff -ww -z -rCHECKSTYLE=4 -man doc/*.[67] an.tmac:doc/nethack.6:435: style: blank line in input an.tmac:doc/nethack.6:442: style: blank line in input an.tmac:doc/nethack.6:535: style: blank line in input an.tmac:doc/nethack.6:539: style: blank line in input an.tmac:doc/nethack.6:543: style: blank line in input an.tmac:doc/nethack.6:568: style: blank line in input an.tmac:doc/nethack.6:572: style: blank line in input --- doc/nethack.6 | 21 +++++++-------------- 1 file changed, 7 insertions(+), 14 deletions(-) diff --git a/doc/nethack.6 b/doc/nethack.6 index a9c46e6fc..9e9fb97e0 100644 --- a/doc/nethack.6 +++ b/doc/nethack.6 @@ -429,15 +429,13 @@ Run-time configuration options were discussed above and use a platform specific name for a file in a platform specific location. For Unix, the name is '.nethackrc' in the user's home directory. - -.br +.PP All other files are in the playground directory, normally /usr/games/lib/nethackdir. If DLB was defined during the compile, the data files and special levels will be inside a larger file, normally nhdat, instead of being separate files. - -.br +.PP .DT .\" continuation lines begin with .ta \w'cmdhelp, opthelp, wizhelp\ \ \ 'u @@ -528,16 +526,13 @@ sysconf System-wide options. Required if \ program is built with 'SYSCF' option .br \ enabled, ignored if not. -.br - +.PP The location of 'sysconf' is specified at build time and can't be changed except by updating source file "config.h" and rebuilding the program. -.br - +.PP NetHack's Guidebook might not be present if whoever packaged or installed the program distribution neglected to include it. -.br - +.PP In a perfect world, 'paniclog' would remain empty. .SH ENVIRONMENT .DT @@ -561,12 +556,10 @@ MAILREADER Replacement for default reader NETHACKDIR or HACKDIR Playground. .br NETHACKOPTIONS String predefining several NetHack options. -.br - +.PP If the same option is specified in both NETHACKOPTIONS and .nethackrc, the value assigned in NETHACKOPTIONS takes precedence. -.br - +.PP SHOPTYPE and SPLEVTYPE can be used in debugging (wizard) mode. .br DEBUGFILES can be used if the program was built with 'DEBUG' enabled. From 56d0708ac711b0ac0e3b47b618a8336701ebfe2a Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Sat, 25 Oct 2025 19:31:08 -0500 Subject: [PATCH 06/39] doc/mnh.7: Migrate to use "NH_DATESUB" Aligns with other NetHack man pages and fixes: $ nroff -ww -z -rCHECKSTYLE=4 -man doc/*.[67] an.tmac:doc/mnh.7:2: style: .TH missing fourth argument; suggest package/project name and version (e.g., "groff 1.23.0") --- doc/mnh.7 | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/doc/mnh.7 b/doc/mnh.7 index df7fe5856..23c684925 100644 --- a/doc/mnh.7 +++ b/doc/mnh.7 @@ -1,5 +1,16 @@ +.\"DO NOT REMOVE NH_DATESUB .TH MAKEDEFS 6 "Date(%-d %B %Y)" Project(uc) .\" $NHDT-Branch: NetHack-3.6.2 $:$NHDT-Revision: 1.0 $ $NHDT-Date: 1541298620 2018/11/04 02:30:20 $ -.TH MNH 7 NETHACK +.TH MNH 7 "4 November 2018" NETHACK +.\"DO NOT REMOVE NH_DATESUB .ds Nd Date(%Y) +.ds Nd 2018 +.de NB +.ds Nb \\$2 +.. +.de NR +.ds Nr \\$2 +.. +.NB $NHDT-Branch: NetHack-3.6.2 $ +.NR $NHDT-Revision: 1.0 $ .SH NAME mnh \- additional text formatting macros for the NetHack Guidebook .SH SYNOPSIS From a33da9202977f7f66d820e761d203c3850410215 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Sat, 2 May 2026 03:16:36 -0500 Subject: [PATCH 07/39] doc/*.6: Tweak copyright notices in man pages Use *roff special character `\(co` for copyright sign. This special character identifier is _almost_ universally portable, dating back to Ossanna troff in 1976.[1] The exception is Plan 9 nroff, which claims to be thoroughly UTF-8 oriented and should be able to render a copyright sign.[2] If no glyph for the character is available, the output device driver degrades it to "c" (which is technically correct[3]), except for groff, which falls back to "(C)"[4] only on its "ascii" output device. All of groff's other devices have a a proper copyright sign.[5] References: [1] https://archive.org/details/unix-programmers-manual-seventh-edition-vol-2-1983/ (pp. 196ff., see esp. "Table II", p. 227) [2] https://github.com/9fans/plan9port/pull/735#issuecomment-3391733330 [3] https://www.copyright.gov/circs/circ03.pdf [4] https://github.com/GitMirroring/groff/blob/a4d6e619afc8042b12084527c3c11eae919533e2/tmac/tty.tmac#L123 [5] https://paste.c-net.org/ComradesCourage --- doc/dlb.6 | 8 +++++++- doc/makedefs.6 | 8 +++++++- doc/nethack.6 | 8 +++++++- doc/recover.6 | 8 +++++++- 4 files changed, 28 insertions(+), 4 deletions(-) diff --git a/doc/dlb.6 b/doc/dlb.6 index d4557ae18..ca01bd8c7 100644 --- a/doc/dlb.6 +++ b/doc/dlb.6 @@ -152,5 +152,11 @@ Should include an optional compression facility. Not all read-only files for NetHack can be read out of an archive; examining the source is the only way to know which files can be. .SH COPYRIGHT -This file is Copyright (C) \*(Na, \*(Nd for version \*(Nb:\*(Nr. +.\" All troffs and nroffs support `\(co` except Plan 9 nroff, but Plan 9 +.\" offers no test for special character availability, and its feature +.\" set too closely resembles DWB 3.3 to test for it. Use a string with +.\" any nroff-mode formatter not claiming groff compatiblity. +.ds co \(co +.if !\n(.g .if n .ds co (C)\" in principle, should be just "c" +This file is Copyright \*(co \*(Na, \*(Nd for version \*(Nb:\*(Nr. NetHack may be freely redistributed. See license for details. diff --git a/doc/makedefs.6 b/doc/makedefs.6 index e2813adc8..1af27082f 100644 --- a/doc/makedefs.6 +++ b/doc/makedefs.6 @@ -272,5 +272,11 @@ end the most recent conditional .SH AUTHOR The NetHack Development Team .SH COPYRIGHT -This file is Copyright (C) \*(Na, \*(Nd for version \*(Nb:\*(Nr. +.\" All troffs and nroffs support `\(co` except Plan 9 nroff, but Plan 9 +.\" offers no test for special character availability, and its feature +.\" set too closely resembles DWB 3.3 to test for it. Use a string with +.\" any nroff-mode formatter not claiming groff compatiblity. +.ds co \(co +.if !\n(.g .if n .ds co (C)\" in principle, should be just "c" +This file is Copyright \*(co \*(Na, \*(Nd for version \*(Nb:\*(Nr. NetHack may be freely redistributed. See license for details. diff --git a/doc/nethack.6 b/doc/nethack.6 index 9e9fb97e0..290d56932 100644 --- a/doc/nethack.6 +++ b/doc/nethack.6 @@ -570,7 +570,13 @@ recover(6) .PP Probably infinite. .SH COPYRIGHT -This file is Copyright (C) \*(Na, \*(Nd for version \*(Nb:\*(Nr. +.\" All troffs and nroffs support `\(co` except Plan 9 nroff, but Plan 9 +.\" offers no test for special character availability, and its feature +.\" set too closely resembles DWB 3.3 to test for it. Use a string with +.\" any nroff-mode formatter not claiming groff compatiblity. +.ds co \(co +.if !\n(.g .if n .ds co (C)\" in principle, should be just "c" +This file is Copyright \*(co \*(Na, \*(Nd for version \*(Nb:\*(Nr. NetHack may be freely redistributed. See license for details. .PP Dungeons & Dragons is a Trademark of Wizards of the Coast, Inc. diff --git a/doc/recover.6 b/doc/recover.6 index 90d56c8c9..818ee18f1 100644 --- a/doc/recover.6 +++ b/doc/recover.6 @@ -148,5 +148,11 @@ determine. should be taught to use the nethack playground locking mechanism to avoid conflicts. .SH COPYRIGHT -This file is Copyright (C) \*(Na, \*(Nd for version \*(Nb:\*(Nr. +.\" All troffs and nroffs support `\(co` except Plan 9 nroff, but Plan 9 +.\" offers no test for special character availability, and its feature +.\" set too closely resembles DWB 3.3 to test for it. Use a string with +.\" any nroff-mode formatter not claiming groff compatiblity. +.ds co \(co +.if !\n(.g .if n .ds co (C)\" in principle, should be just "c" +This file is Copyright \*(co \*(Na, \*(Nd for version \*(Nb:\*(Nr. NetHack may be freely redistributed. See license for details. From 2566ddefdf24d54f18ccb6335fa5bb3cfff527c1 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Sat, 2 May 2026 03:44:55 -0500 Subject: [PATCH 08/39] doc/*.6: Break input lines at sentence endings ...pacifying a warning from the forthcoming groff 1.25. Fixes: troff:doc/dlb.6:159: warning: end of sentence detected before end of text line [-w style] troff:doc/makedefs.6:53: warning: end of sentence detected before end of text line [-w style] troff:doc/makedefs.6:55: warning: end of sentence detected before end of text line [-w style] troff:doc/makedefs.6:58: warning: end of sentence detected before end of text line [-w style] troff:doc/makedefs.6:153: warning: end of sentence detected before end of text line [-w style] troff:doc/makedefs.6:159: warning: end of sentence detected before end of text line [-w style] troff:doc/makedefs.6:166: warning: end of sentence detected before end of text line [-w style] troff:doc/makedefs.6:222: warning: end of sentence detected before end of text line [-w style] troff:doc/makedefs.6:245: warning: end of sentence detected before end of text line [-w style] troff:doc/makedefs.6:279: warning: end of sentence detected before end of text line [-w style] troff:doc/mnh.7:30: warning: end of sentence detected before end of text line [-w style] troff:doc/nethack.6:225: warning: end of sentence detected before end of text line [-w style] troff:doc/nethack.6:226: warning: end of sentence detected before end of text line [-w style] troff:doc/nethack.6:230: warning: end of sentence detected before end of text line [-w style] troff:doc/nethack.6:234: warning: end of sentence detected before end of text line [-w style] troff:doc/nethack.6:236: warning: end of sentence detected before end of text line [-w style] troff:doc/nethack.6:524: warning: end of sentence detected before end of text line [-w style] troff:doc/nethack.6:577: warning: end of sentence detected before end of text line [-w style] troff:doc/recover.6:155: warning: end of sentence detected before end of text line [-w style] --- doc/dlb.6 | 3 ++- doc/makedefs.6 | 34 ++++++++++++++++++++++------------ doc/mnh.7 | 3 ++- doc/nethack.6 | 21 ++++++++++++++------- doc/recover.6 | 3 ++- 5 files changed, 42 insertions(+), 22 deletions(-) diff --git a/doc/dlb.6 b/doc/dlb.6 index ca01bd8c7..86ce7c6f2 100644 --- a/doc/dlb.6 +++ b/doc/dlb.6 @@ -159,4 +159,5 @@ examining the source is the only way to know which files can be. .ds co \(co .if !\n(.g .if n .ds co (C)\" in principle, should be just "c" This file is Copyright \*(co \*(Na, \*(Nd for version \*(Nb:\*(Nr. -NetHack may be freely redistributed. See license for details. +NetHack may be freely redistributed. +See license for details. diff --git a/doc/makedefs.6 b/doc/makedefs.6 index 1af27082f..260bb3ce5 100644 --- a/doc/makedefs.6 +++ b/doc/makedefs.6 @@ -50,14 +50,18 @@ makedefs \- NetHack miscellaneous build-time functions .B Makedefs is a build-time tool used for a variety of .BR NetHack (6) -source file creation and modification tasks. For historical reasons, +source file creation and modification tasks. +For historical reasons, .B makedefs -takes two types of command lines. When invoked with a short option, the -files operated on are determined when +takes two types of command lines. +When invoked with a short option, +the files operated on are determined when .B makedefs -is compiled. When invoked with a long option, the +is compiled. +When invoked with a long option, +the .B --input -and +and .B --output options are used to specify the files for the .BI -- command. @@ -150,20 +154,23 @@ Show debugging output. .br .TP .B --make \fR[\fIcommand\fR] -Execute a short command. Command is given without preceding dash. -.br +Execute a short command. +.I Command +is given without preceding dash. .TP .BI --input " file" Specify the input .I file -for the command (if needed). If the file is - standard +for the command (if needed). +If the file is - standard input is read. .br .TP .BI --output " file" Specify the output .I file -for the command (if needed). If the file is - standard +for the command (if needed). +If the file is - standard output is written. .br .TP @@ -219,7 +226,8 @@ command (and certain other commands) filter their input, on a line-by-line basis, according to control lines embedded in the input and on information gleaned from the .BR NetHack (6) -configuration. This allows certain changes such as embedding platform-specific +configuration. +This allows certain changes such as embedding platform-specific documentation into the master documentation files. .P Rules: @@ -242,7 +250,8 @@ Conditionals may be nested. will exit with an error code if any errors are detected; processing will continue (if it can) to allow as many errors as possible to be detected. .IP - 4 -Unknown identifiers are treated as both TRUE and as an error. Note that +Unknown identifiers are treated as both TRUE and as an error. +Note that .BR --undef " or " #undef in the .BR NetHack (6) @@ -279,4 +288,5 @@ The NetHack Development Team .ds co \(co .if !\n(.g .if n .ds co (C)\" in principle, should be just "c" This file is Copyright \*(co \*(Na, \*(Nd for version \*(Nb:\*(Nr. -NetHack may be freely redistributed. See license for details. +NetHack may be freely redistributed. +See license for details. diff --git a/doc/mnh.7 b/doc/mnh.7 index 23c684925..dd3b7e7a8 100644 --- a/doc/mnh.7 +++ b/doc/mnh.7 @@ -27,7 +27,8 @@ and .IR troff (1) macro definitions extends .IR tmac.n (7) -for the NetHack Guidebook. This document should be +for the NetHack Guidebook. +This document should be read as an addendum to the documentation for .IR tmac.n . .PP diff --git a/doc/nethack.6 b/doc/nethack.6 index 290d56932..526742958 100644 --- a/doc/nethack.6 +++ b/doc/nethack.6 @@ -222,18 +222,23 @@ Conversely, you must use the appropriate player name to restore a saved game. A .I playername suffix can be used to specify the profession, race, alignment and/or gender -of the character. The full syntax of the playername that includes a -suffix is "name-ppp-rrr-aaa-ggg". "ppp" are at least the first three letters +of the character. +The full syntax of the playername that includes a +suffix is "name-ppp-rrr-aaa-ggg". +"ppp" are at least the first three letters of the profession (this can also be specified using a separate .B \-p .I profession -option). "rrr" are at least the first three letters of the character's +option). +"rrr" are at least the first three letters of the character's race (this can also be specified using a separate .B \-r .I race -option). "aaa" are at least the first three letters of the character's +option). +"aaa" are at least the first three letters of the character's alignment, and "ggg" are at least the first three letters of the -character's gender. Any of the parts of the suffix may be left out. +character's gender. +Any of the parts of the suffix may be left out. .PP .B \-p .I profession @@ -521,7 +526,8 @@ save/ A subdirectory containing saved games. .\"following line should contain \ .br -sysconf System-wide options. Required if +sysconf System-wide options. +Required if .br \ program is built with 'SYSCF' option .br @@ -577,6 +583,7 @@ Probably infinite. .ds co \(co .if !\n(.g .if n .ds co (C)\" in principle, should be just "c" This file is Copyright \*(co \*(Na, \*(Nd for version \*(Nb:\*(Nr. -NetHack may be freely redistributed. See license for details. +NetHack may be freely redistributed. +See license for details. .PP Dungeons & Dragons is a Trademark of Wizards of the Coast, Inc. diff --git a/doc/recover.6 b/doc/recover.6 index 818ee18f1..cf116e09d 100644 --- a/doc/recover.6 +++ b/doc/recover.6 @@ -155,4 +155,5 @@ avoid conflicts. .ds co \(co .if !\n(.g .if n .ds co (C)\" in principle, should be just "c" This file is Copyright \*(co \*(Na, \*(Nd for version \*(Nb:\*(Nr. -NetHack may be freely redistributed. See license for details. +NetHack may be freely redistributed. +See license for details. From 9508a133d0ce7db6fbcfc4d733f48288265df0d3 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Sat, 2 May 2026 03:59:03 -0500 Subject: [PATCH 09/39] doc/*.6: Fix unescaped hyphens MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit groff_man_style(7): • Option dashes are specified with the \- escape sequence; this is an important practice to make them clearly visible and to facilitate copy‐and‐paste from the rendered man page to a shell prompt or text file. ... \- Minus sign. \- produces the basic Latin hyphen‐minus (U+002D) specifying Unix command‐line options and frequently used in file names. “-” is a hyphen in roff; some output devices format it as U+2010 (hyphen). --- doc/dlb.6 | 2 +- doc/makedefs.6 | 86 +++++++++++++++++++++++++------------------------- doc/nethack.6 | 2 +- 3 files changed, 45 insertions(+), 45 deletions(-) diff --git a/doc/dlb.6 b/doc/dlb.6 index 86ce7c6f2..c002537ce 100644 --- a/doc/dlb.6 +++ b/doc/dlb.6 @@ -144,7 +144,7 @@ Kenneth Lorber Not a good .I tar emulation; -.B - +.B \- does not mean stdin or stdout. .IP \(bu Should include an optional compression facility. diff --git a/doc/makedefs.6 b/doc/makedefs.6 index 260bb3ce5..12774dc71 100644 --- a/doc/makedefs.6 +++ b/doc/makedefs.6 @@ -21,30 +21,30 @@ makedefs \- NetHack miscellaneous build-time functions .SH SYNOPSIS .B makedefs { -.B -o +.B \-o | -.B -d +.B \-d | -.B -e +.B \-e | -.B -m +.B \-m | -.B -v +.B \-v | -.B -p +.B \-p | -.B -q +.B \-q | -.B -r +.B \-r | -.B -h +.B \-h } .P -.B makedefs --input +.B makedefs \-\-input .I file -.B --output +.B \-\-output .I file -.BI -- command +.BI \-\- command .SH DESCRIPTION .PP .B Makedefs @@ -60,39 +60,39 @@ the files operated on are determined when is compiled. When invoked with a long option, the -.B --input +.B \-\-input and -.B --output +.B \-\-output options are used to specify the files for the -.BI -- command. +.BI \-\- command. Each command is only available in one of the two formats. .SH SHORT COMMANDS Upper and lower case are both accepted for the short commands. .TP -.B -o +.B \-o Generate .I onames.h. .br .TP -.B -d +.B \-d Generate .I data.base. .br .TP -.B -e +.B \-e Generate .I dungeon.pdf. The input file .I dungeon.def is passed through the same logic as that used by the -.B --grep +.B \-\-grep command; see the .B MDGREP FUNCTIONS section below for details. .br .TP -.B -m +.B \-m Generate .I date.h and @@ -108,78 +108,78 @@ info and include related preprocessor #defines in file. .br .TP -.B -p +.B \-p Generate .I pm.h .br .TP -.B -q +.B \-q Generate the .I rumors file. .br .TP -.B -s +.B \-s Generate the .IR bogusmon ", " engrave ", and " epitaph " files." .br .TP -.B -1 +.B \-1 Generate the .I epitaph file. .br .TP -.B -2 +.B \-2 Generate the .I engrave file. .br .TP -.B -3 +.B \-3 Generate the .I bogusmon file. .br .TP -.B -h +.B \-h Generate the .B oracles file. .br .SH LONG COMMANDS .TP -.B --debug +.B \-\-debug Show debugging output. .br .TP -.B --make \fR[\fIcommand\fR] +.B \-\-make \fR[\fIcommand\fR] Execute a short command. .I Command is given without preceding dash. .TP -.BI --input " file" +.BI \-\-input " file" Specify the input .I file for the command (if needed). -If the file is - standard +If the file is \- standard input is read. .br .TP -.BI --output " file" +.BI \-\-output " file" Specify the output .I file for the command (if needed). -If the file is - standard +If the file is \- standard output is written. .br .TP -.B --svs \fR[\fIdelimiter\fR] +.B \-\-svs \fR[\fIdelimiter\fR] Generate a version string to standard output without a trailing newline. If specified, the delimiter is used between each part of the version string. .br .TP -.B --grep +.B \-\-grep Filter the input .I file to the output .IR file . @@ -188,22 +188,22 @@ See the section below for information on controlling the filtering operation. .br .TP -.B --grep-showvars +.B \-\-grep\-showvars Show the name and value for each variable known to the grep option. .br .TP -.B --grep-trace +.B \-\-grep\-trace Turn on debug tracing for the grep function ( -.B --grep +.B \-\-grep must be specified as well). .br .TP -.BI --grep-defined " symbol" +.BI \-\-grep\-defined " symbol" Exit shell true (0) if .I symbol is known and defined, otherwise exit shell false (1). .TP -.BI --grep-define " symbol" +.BI \-\-grep\-define " symbol" Force the value of .I symbol to be "defined." @@ -212,7 +212,7 @@ must already be known to .BR makedefs . .br .TP -.BI --grep-undef " symbol" +.BI \-\-grep\-undef " symbol" Force the definition of .I symbol to be "undefined." @@ -221,7 +221,7 @@ must already be known to .BR makedefs . .SH MDGREP FUNCTIONS The -.B --grep +.B \-\-grep command (and certain other commands) filter their input, on a line-by-line basis, according to control lines embedded in the input and on information gleaned from the @@ -252,7 +252,7 @@ continue (if it can) to allow as many errors as possible to be detected. .IP - 4 Unknown identifiers are treated as both TRUE and as an error. Note that -.BR --undef " or " #undef +.BR \-\-undef " or " #undef in the .BR NetHack (6) configuration are different from unknown. diff --git a/doc/nethack.6 b/doc/nethack.6 index 526742958..5ad003bb2 100644 --- a/doc/nethack.6 +++ b/doc/nethack.6 @@ -224,7 +224,7 @@ A suffix can be used to specify the profession, race, alignment and/or gender of the character. The full syntax of the playername that includes a -suffix is "name-ppp-rrr-aaa-ggg". +suffix is "name\-ppp\-rrr\-aaa\-ggg". "ppp" are at least the first three letters of the profession (this can also be specified using a separate .B \-p From fc0fd459b18a3d32c12e23f01f9da3a75151b63c Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Sat, 2 May 2026 04:01:20 -0500 Subject: [PATCH 10/39] doc/nethack.6: Drop spurious request arguments No *roff known to me interprets arguments to the `br` request. They don't complain, either, but some day that may change. https://savannah.gnu.org/bugs/?61450 --- doc/nethack.6 | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/nethack.6 b/doc/nethack.6 index 5ad003bb2..fe6523896 100644 --- a/doc/nethack.6 +++ b/doc/nethack.6 @@ -36,7 +36,7 @@ nethack \- Exploring The Mazes of Menace .BR \-w | \-\-windowtype .I interface ] -.br 1 +.br [ .BI \-\-nethackrc: RC-file | @@ -48,7 +48,7 @@ nethack \- Exploring The Mazes of Menace [ .BR \-dec " | " \-ibm ] -.br 1 +.br [ .B \-u .I playername @@ -106,7 +106,7 @@ Also [ .B \-v ] -.br 1 +.br [ .B \-p .I profession @@ -347,7 +347,7 @@ and the option can be used to skip any run-time configuration file. .PP .\" extra blank line -.br 1 +.br .PP Some options provide feedback and then exit rather than play the game: .PP From 82c174a8472e5834e699d83566727c7dfd1ff8a3 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Sat, 2 May 2026 04:15:08 -0500 Subject: [PATCH 11/39] doc/makedefs.6: Fix warning from DWB 3.3 nroff Not a serious issue in my opinion, but worth fixing. DWB does not misrender the document, and the "stack" referred to is not the runtime stack employed by the operating system, but one in the *roff language runtime. The diagnostic appears to be spurious in this case, but it isn't always. https://github.com/n-t-roff/DWB3.3/issues/10 --- doc/makedefs.6 | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/makedefs.6 b/doc/makedefs.6 index 12774dc71..55ef956a7 100644 --- a/doc/makedefs.6 +++ b/doc/makedefs.6 @@ -121,7 +121,11 @@ file. .TP .B \-s Generate the -.IR bogusmon ", " engrave ", and " epitaph " files." +.IR bogusmon , +.IR engrave , +and +.I epitaph +files. .br .TP .B \-1 From 32c1b24f32b8fe87d50bc8597414250c420a7f53 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Sat, 2 May 2026 04:20:02 -0500 Subject: [PATCH 12/39] doc/makedefs.6: Make punct styling consistent Elsewhere in this document, punctuation after italicized words is set in roman, not italics. --- doc/makedefs.6 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/makedefs.6 b/doc/makedefs.6 index 55ef956a7..b0176470d 100644 --- a/doc/makedefs.6 +++ b/doc/makedefs.6 @@ -71,17 +71,17 @@ Upper and lower case are both accepted for the short commands. .TP .B \-o Generate -.I onames.h. +.IR onames.h . .br .TP .B \-d Generate -.I data.base. +.IR data.base . .br .TP .B \-e Generate -.I dungeon.pdf. +.IR dungeon.pdf . The input file .I dungeon.def is passed through the From 0c915adea15621efbf39fb1a814987dd99460cf6 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Sat, 2 May 2026 04:22:50 -0500 Subject: [PATCH 13/39] doc/makedefs.6: Break text line at end of sentence Ensure that *roff programs detect the sentence ending here. https://www.gnu.org/software/groff/manual/groff.html.node/Sentences.html --- doc/makedefs.6 | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/makedefs.6 b/doc/makedefs.6 index b0176470d..0442c80dc 100644 --- a/doc/makedefs.6 +++ b/doc/makedefs.6 @@ -97,7 +97,8 @@ Generate .I date.h and .I options -file. It will read +file. +It will read .IR dat/gitinfo.txt , only if it is present, to obtain .B githash= From a562b80019a5a747d574f4136351469aa2a7cfb7 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Sat, 2 May 2026 04:23:15 -0500 Subject: [PATCH 14/39] doc/makedefs.6: Fix style nits * End sentence with period, like others in this document. * Set literal file name in italics like all others in this document, not bold. --- doc/makedefs.6 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/makedefs.6 b/doc/makedefs.6 index 0442c80dc..fd6fe8941 100644 --- a/doc/makedefs.6 +++ b/doc/makedefs.6 @@ -111,7 +111,7 @@ file. .TP .B \-p Generate -.I pm.h +.IR pm.h . .br .TP .B \-q @@ -149,7 +149,7 @@ file. .TP .B \-h Generate the -.B oracles +.I oracles file. .br .SH LONG COMMANDS From 6c9e8cb1c950d7d79d317bec2e3f2c2d58b60538 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Sat, 2 May 2026 05:11:18 -0500 Subject: [PATCH 15/39] doc/nethack.6: Revise "FILES" section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Define string to exercise groff's hyphenless break point feature. This helps with file names and URLs. On formatters that don't claim compatibility with groff, define the string as nothing, getting the same result as before (a _highly_ ragged right margin, jarring adjustment, or overset lines). * If the formatter does not claim compatibility with groff, define a copy of groff man(7)'s `TQ` macro to ease stacking of paragraph tags. * Set file name literals in italics. Stop quoting them (which was inconsistently done anyway). * Revise "FILES" section. - Drop redundant `PP` paragraphing call. $ mandoc -T lint doc/nethack.6 ... mandoc: doc/nethack.6:432:2: WARNING: skipping paragraph macro: PP after SH ... groff_man(7): .SH [heading‐text] Set heading‐text as a section heading. ... Text lines after the call are set as an ordinary paragraph (P). - Drop call of deprecated man(7) `DT` macro and invocation of `ta` request to set tab stops to attempt table-like layout. (The latter made the former nilpotent anyway.) Replace this material with calls of tagged paragraphing macro `TP` and groff man(7)'s `TQ` extension for setting multiple tags with a paragraph. The result takes up more screen lines, but renders well with more formatters. - Fine-tune styling of file names. groff_man_style(7): Use italics for file and path names, ... for variant (user‐replaceable) portions of syntax synopses, ... and anywhere a parameter requiring replacement by the user is encountered. An exception involves variant text in a context already typeset in italics, such as file or path names with replaceable components; in such cases, follow the convention of mathematical typography: set the file or path name in italics as usual but use roman for the variant part (see IR and RI below), and italics again in running roman text when referring to the variant material. Solaris 10, DWB 3.3, and Plan 9 from User Space nroffs formatted the table of file names and descriptions quite badly. Before: nethack The program itself. Guidebook | Guidebook.txt NetHack's user manual. data, oracles, rumors Data files used by NetHack. bogusmon Another data file. engrave, epitaph, tribute Still more data files. symbols Data file holding sets of speci- fications for how to display monsters, objects, and map features. options Data file containing a descrip- tion of the build-time option settings. help, hh, cmdhelp Help data files. ('cmdhelp' is obsolete.) ... Now (pagination on AT&T nroffs is omitted): nethack The program itself. Guidebook Guidebook.txt NetHack's user manual. data oracles rumors Data files used by NetHack. bogusmon Another data file. engrave epitaph tribute Still more data files. symbols Data file holding sets of specifications for how to display monsters, objects, and map features. options Data file containing a description of the build-time option settings. help hh cmdhelp Help data files. (cmdhelp is obsolete.) Fixes: an.tmac:doc/nethack.6:444: style: use of deprecated macro: .DT --- doc/nethack.6 | 264 +++++++++++++++++++++++++++++++------------------- 1 file changed, 164 insertions(+), 100 deletions(-) diff --git a/doc/nethack.6 b/doc/nethack.6 index fe6523896..f251a6928 100644 --- a/doc/nethack.6 +++ b/doc/nethack.6 @@ -16,6 +16,22 @@ .ie \n(.g .hy 12 .el .hy 14 .ds Na Robert Patrick Rankin +.\" Define string to exercise groff's hyphenless break point feature. +.ie \n(.g .ds : \: +.el .ds : \" empty +.\" Define local versions of groff's "an-ext.tmac" macros if needed. +.ds %% \" empty +.if \n(.g .ig %% +.\" Add supplementary paragraph tag on its own line after TP. +.de TQ +. br +. ns +. \" Do not quote the argument to `TP`; the user might specify +. \" their own quotes for multi-word tags or to exercise AT&T troff +. \" quoting rules. +. TP \\$1\" +.. +.%% .SH NAME nethack \- Exploring The Mazes of Menace .SH SYNOPSIS @@ -319,7 +335,8 @@ option, which must be the first argument if it appears, supplies a directory which is to serve as the playground. It overrides the value from NETHACKDIR, HACKDIR, or the directory specified by the game administrator during compilation -(usually /usr/games/lib/nethackdir). +(usually +.IR /usr/\*:games/\*:lib/\*:nethackdir ). This option is usually only useful to the game administrator. The playground must contain several auxiliary files such as help files, the list of top scorers, and a subdirectory @@ -429,117 +446,164 @@ development by the Usenet. Andries Brouwer has made this request for the distinction, as he may eventually release a new version of his own. .SH FILES -.PP Run-time configuration options were discussed above and use a platform specific name for a file in a platform specific location. For Unix, the -name is '.nethackrc' in the user's home directory. +name is +.I .nethackrc +in the user's home directory. .PP All other files are in the playground directory, -normally /usr/games/lib/nethackdir. -If DLB was defined during the compile, the data files and special levels -will be inside a larger file, normally nhdat, instead of being separate -files. -.PP -.DT -.\" continuation lines begin with -.ta \w'cmdhelp, opthelp, wizhelp\ \ \ 'u -nethack The program itself. -.br -Guidebook\ |\ Guidebook.txt NetHack's user manual. -.br -data, oracles, rumors Data files used by NetHack. -.br -bogusmon Another data file. -.br -engrave, epitaph, tribute Still more data files. -.br -symbols Data file holding sets of specifications -.br -\ for how to display monsters, objects, and -.br -\ map features. -.br -options Data file containing a description of the -.br -\ build-time option settings. -.br -help,\ hh,\ cmdhelp Help data files. -('cmdhelp' is obsolete.) -.br -opthelp,\ optmenu,\ wizhelp More help data files. -.br -keyhelp,\ usagehlp Even more help data files. -.br -*.lua Predefined special levels, dungeon control -.br -\ for special levels, quest texts. -.br -history A short history of NetHack. -.br -license Rules governing redistribution. -.br -record The list of top scorers. -.br -logfile An extended list of games played -.br -\ (optional). -.br -xlogfile A more detailed version of 'logfile' -.br -\ (also optional). -.br -paniclog Record of exceptional conditions -.br -\ discovered during program execution. -.br -xlock.nn Description of dungeon level 'nn' of -.br -\ active game 'x' if there's a limit on the -.br -\ number of simultaneously active games. -.br -UUcccccc.nn Alternate form for dungeon level 'nn' -.br -\ of active game by user 'UU' playing -.br -\ character named 'cccccc' when there's no -.br -\ limit on number of active games. -.br -perm Lock file for xlock.0 or UUcccccc.0. -.br -bonD0.nn Descriptions of the ghost and belongings -.br -\ of a deceased adventurer who met his or -.br -\ her demise on level 'nn'. +normally +.IR /usr/\*:games/\*:lib/\*:nethackdir . +If DLB was defined during the compile, +the data files and special levels will be inside a larger file, +normally +.IR nhdat , +instead of being separate files. +.TP +.I nethack +The program itself. +.TP +.I Guidebook +.TQ +.I Guidebook.txt +NetHack's user manual. +.TP +.I data +.TQ +.I oracles +.TQ +.I rumors +Data files used by NetHack. +.TP +.I bogusmon +Another data file. +.TP +.I engrave +.TQ +.I epitaph +.TQ +.I tribute +Still more data files. +.TP +.I symbols +Data file holding sets of specifications +for how to display monsters, objects, and +map features. +.TP +.I options +Data file containing a description of the +build-time option settings. +.TP +.I help +.TQ +.I hh +.TQ +.I cmdhelp +Help data files. +.RI ( cmdhelp +is obsolete.) +.TP +.I opthelp +.TQ +.I optmenu +.TQ +.I wizhelp +More help data files. +.TP +.I keyhelp +.TQ +.I usagehlp +Even more help data files. +.TP +.RI * .lua +Predefined special levels, dungeon control +for special levels, quest texts. +.TP +.I history +A short history of NetHack. +.TP +.I license +Rules governing redistribution. +.TP +.I record +The list of top scorers. +.TP +.I logfile +An extended list of games played +(optional). +.TP +.I xlogfile +A more detailed version of +.I logfile +(also optional). +.TP +.I paniclog +Record of exceptional conditions +discovered during program execution. +.TP +.RI x lock. nn +Description of dungeon level +.I nn +of active game +.I x +if there's a limit on the +number of simultaneously active games. +.TP +.RI UUcccccc . nn +Alternate form for dungeon level +.I nn +of active game by user +.I UU +playing character named +.I cccccc +when there's no +limit on number of active games. +.TP +.I perm +Lock file for +.RI x lock.0 +or +.RI UUcccccc .0 . +.TP +.IR bonD0. nn +Descriptions of the ghost and belongings +of a deceased adventurer who met his or +her demise on level +.IR nn . A subsequent -.br -\ character might encounter this old level. -.br -.\"following line should contain -\ -.br -save/ A subdirectory containing saved games. -.br -.\"following line should contain -\ -.br -sysconf System-wide options. +character might encounter this old level. +.TP +.I save/ +Subdirectory containing saved games. +.TP +.I sysconf +System-wide options. Required if -.br -\ program is built with 'SYSCF' option -.br -\ enabled, ignored if not. +program is built with 'SYSCF' option +enabled, ignored if not. .PP -The location of 'sysconf' is specified at build time and can't be changed -except by updating source file "config.h" and rebuilding the program. +The location of +.I sysconf +is specified at build time and can't be changed +except by updating source file +.\" We do the following in an ugly and non-idiomatic way to work around +.\" a DWB 3.3 nroff bug. +.\" troff: if-else overflow.; doc/nethack.6:623 +.\" stack: }S }S }S }S }S }S }S }S }S }S }S }S }S }S }S }S RI +.\" Even at that, DWB insists on setting the period in roman. +"\c +.I config.h\c +" +and rebuilding the program. .PP NetHack's Guidebook might not be present if whoever packaged or installed the program distribution neglected to include it. .PP -In a perfect world, 'paniclog' would remain empty. +In a perfect world, +.I paniclog +would remain empty. .SH ENVIRONMENT .DT .ta \w'NETHACKDIR or HACKDIR\ \ \ 'u From d2a49d4f8a316a639c072cab9565a0294332ca9e Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Sat, 2 May 2026 05:51:11 -0500 Subject: [PATCH 16/39] doc/nethack.6: Revise "ENVIRONMENT" section Explain meaning of stacked paragraph tags naming environment variables. Drop call of deprecated man(7) `DT` macro and invocation of `ta` request to set tab stops to attempt table-like layout. (The latter made the former nilpotent anyway.) Replace this material with calls of tagged paragraphing macro `TP` and groff man(7)'s `TQ` extension for setting multiple tags with a paragraph. The result takes up more screen lines, but renders well with more formatters. Set indentation of tagged paragraph using a constant numeric expression to accommodate pseudo-roff formatters that don't implement arithmetic evaluation. (Some of these ignore _any_ indentation, regardless.) Slightly recast descriptions of environment variables. Set file name literals in italics. Protect file and environment variable names from hyphenation. Fixes: an.tmac:doc/nethack.6:608: style: use of deprecated macro: .DT --- doc/nethack.6 | 88 ++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 62 insertions(+), 26 deletions(-) diff --git a/doc/nethack.6 b/doc/nethack.6 index f251a6928..35a92e8bf 100644 --- a/doc/nethack.6 +++ b/doc/nethack.6 @@ -605,34 +605,70 @@ In a perfect world, .I paniclog would remain empty. .SH ENVIRONMENT -.DT -.ta \w'NETHACKDIR or HACKDIR\ \ \ 'u -USER or LOGNAME Your login name. -.br -HOME Your home directory. -.br -SHELL Your shell. -.br -TERM The type of your terminal. -.br -HACKPAGER or PAGER Replacement for default pager. -.br -MAIL Mailbox file. -.br -MAILREADER Replacement for default reader -.br -\ (probably /bin/mail or /usr/ucb/mail). -.br -NETHACKDIR or HACKDIR Playground. -.br -NETHACKOPTIONS String predefining several NetHack options. +In some cases, +.I NetHack +attempts to access multiple environment variables in sequence +(via +.IR getenv (3) +or similar) +to determine information. +.TP 16n \" "NETHACKOPTIONS" + 2n +.I USER +.TQ +.I +LOGNAME +Your login name. +.TP +.I HOME +Your home directory. +.TP +.I SHELL +Your login shell +(not necessarily the one running when you started +.IR NetHack ). +.TP +.I TERM +Your terminal type. +.TP +.I HACKPAGER +.TQ +.I PAGER +Replacement for default pager. +.TP +.I MAIL +Mailbox file. +.TP +.I MAILREADER +Replacement for default reader +(probably +.I /bin/\*:mail +or +.IR /usr/\*:ucb/\*:mail ). +.TP +.I NETHACKDIR +.TQ +.I HACKDIR +Playground. +.TP +.I NETHACKOPTIONS +Predefined +.I NetHack +options. .PP -If the same option is specified in both NETHACKOPTIONS and .nethackrc, -the value assigned in NETHACKOPTIONS takes precedence. +If the same option is specified in both +.I \%NETHACKOPTIONS +and +.IR \%.nethackrc , +the value assigned in +.I \%NETHACKOPTIONS +takes precedence. .PP -SHOPTYPE and SPLEVTYPE can be used in debugging (wizard) mode. -.br -DEBUGFILES can be used if the program was built with 'DEBUG' enabled. +.I SHOPTYPE +and +.I \%SPLEVTYPE +can be used in debugging (wizard) mode. +.I \%DEBUGFILES +can be used if the program was built with 'DEBUG' enabled. .SH "SEE ALSO" .PP recover(6) From bbcfc474d0c68138de2f58679e4e4593c9a06684 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Sat, 2 May 2026 14:26:51 -0500 Subject: [PATCH 17/39] doc/*.[67]: Drop redundant calls and requests Sectioning and paragraphing macros always break the output line. (Sub)sectioning macros always set text after the heading as a paragraph. Fixes: $ mandoc -T lint doc/*.[67] # output edited doc/makedefs.6:49:2: WARNING: skipping paragraph macro: PP after SH doc/nethack.6:367:2: WARNING: skipping paragraph macro: br after PP doc/nethack.6:365:2: WARNING: skipping paragraph macro: PP empty doc/nethack.6:157:2: WARNING: skipping paragraph macro: PP after SH doc/nethack.6:431:2: WARNING: skipping paragraph macro: PP after SH doc/nethack.6:673:2: WARNING: skipping paragraph macro: PP after SH doc/nethack.6:676:2: WARNING: skipping paragraph macro: PP after SH doc/recover.6:29:2: WARNING: skipping paragraph macro: PP after SH doc/recover.6:125:2: WARNING: skipping paragraph macro: PP after SH doc/recover.6:141:2: WARNING: skipping paragraph macro: PP after SH doc/mnh.7:23:2: WARNING: skipping paragraph macro: PP after SH doc/mnh.7:46:2: WARNING: skipping paragraph macro: PP after SH --- doc/makedefs.6 | 1 - doc/mnh.7 | 2 -- doc/nethack.6 | 7 ------- doc/recover.6 | 3 --- 4 files changed, 13 deletions(-) diff --git a/doc/makedefs.6 b/doc/makedefs.6 index fd6fe8941..3cc5926df 100644 --- a/doc/makedefs.6 +++ b/doc/makedefs.6 @@ -46,7 +46,6 @@ makedefs \- NetHack miscellaneous build-time functions .I file .BI \-\- command .SH DESCRIPTION -.PP .B Makedefs is a build-time tool used for a variety of .BR NetHack (6) diff --git a/doc/mnh.7 b/doc/mnh.7 index dd3b7e7a8..77c8d9bfb 100644 --- a/doc/mnh.7 +++ b/doc/mnh.7 @@ -20,7 +20,6 @@ mnh \- additional text formatting macros for the NetHack Guidebook .\".B "troff \-mn" .\"[ options ] file ... .SH DESCRIPTION -.PP This package of .IR nroff (1) and @@ -43,7 +42,6 @@ mn(7) .SH AUTHOR Pat Rankin .SH REQUESTS -.PP In the .I Note column, diff --git a/doc/nethack.6 b/doc/nethack.6 index 35a92e8bf..92f813796 100644 --- a/doc/nethack.6 +++ b/doc/nethack.6 @@ -154,7 +154,6 @@ Also .\" Make sure path is not hyphenated below .hw nethackdir .SH DESCRIPTION -.PP .I NetHack is a display oriented Dungeons & Dragons(tm) - like game. The standard tty display and command structure resemble rogue. @@ -363,9 +362,6 @@ and the .B \-\-no\-nethackrc option can be used to skip any run-time configuration file. .PP -.\" extra blank line -.br -.PP Some options provide feedback and then exit rather than play the game: .PP The @@ -428,7 +424,6 @@ Use .RB \(oq "nethack \-\-usage | more" \(cq to read it a page at a time. .SH AUTHORS -.PP Jay Fenlason (+ Kenny Woodland, Mike Thome and Jon Payne) wrote the original hack, very much like rogue (but full of bugs). .PP @@ -670,10 +665,8 @@ can be used in debugging (wizard) mode. .I \%DEBUGFILES can be used if the program was built with 'DEBUG' enabled. .SH "SEE ALSO" -.PP recover(6) .SH BUGS -.PP Probably infinite. .SH COPYRIGHT .\" All troffs and nroffs support `\(co` except Plan 9 nroff, but Plan 9 diff --git a/doc/recover.6 b/doc/recover.6 index cf116e09d..b7298c015 100644 --- a/doc/recover.6 +++ b/doc/recover.6 @@ -26,7 +26,6 @@ recover \- recover a NetHack game interrupted by disaster ] .I "base1 base2" ... .SH DESCRIPTION -.PP Occasionally, a NetHack game will be interrupted by disaster when the game or the system crashes. Prior to NetHack v3.1, these games were lost because various information @@ -122,7 +121,6 @@ In either case, .I recover is easily compiled from the distribution utility directory. .SH NOTES -.PP Like .I nethack itself, @@ -138,7 +136,6 @@ will find them in the uncompressed form. .SH "SEE ALSO" nethack(6) .SH BUGS -.PP .I recover makes no attempt to find out if a base name specifies a game in progress. If multiple machines share a playground, this would be impossible to From 67e724cd75b6dc38d2e2fd4d11ce8645d5c31854 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Sun, 3 May 2026 00:46:25 -0500 Subject: [PATCH 18/39] doc/*.[67]: Set man page xrefs consistently NetHack's man pages already preponderantly use man(7) `IR` macro for this purpose. Align outliers. The "SEE ALSO" section of doc/mn.7 is a partial exception. While the rest of the document sets cross-referenced man page topics in italics, this section of the page does not. It seems likely that this decision was made in deliberate imitation of Seventh Edition Unix manuals (1979) or their descendants in USG/USL and BSD Unices. That feature of the Unix man pages, however, was not deliberate per Doug McIlroy, the author of the man(7) macros and editor of Volume 1 of the Seventh Edition Unix Programmer's Manual, per his communication on the groff mailing list. But NetHack has a policy of not modifying Matt Bishop's "mn" macro file or its man page, so I leave that exception in place. References: https://lists.gnu.org/archive/html/groff/2021-08/msg00023.html https://lists.gnu.org/archive/html/groff/2021-08/msg00040.html https://github.com/NetHack/NetHack/pull/977#issuecomment-1424996578 --- doc/makedefs.6 | 4 ++-- doc/mnh.7 | 2 +- doc/nethack.6 | 2 +- doc/recover.6 | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/makedefs.6 b/doc/makedefs.6 index 3cc5926df..b8d24b7d4 100644 --- a/doc/makedefs.6 +++ b/doc/makedefs.6 @@ -229,7 +229,7 @@ The command (and certain other commands) filter their input, on a line-by-line basis, according to control lines embedded in the input and on information gleaned from the -.BR NetHack (6) +.IR NetHack (6) configuration. This allows certain changes such as embedding platform-specific documentation into the master documentation files. @@ -258,7 +258,7 @@ Unknown identifiers are treated as both TRUE and as an error. Note that .BR \-\-undef " or " #undef in the -.BR NetHack (6) +.IR NetHack (6) configuration are different from unknown. .RE .P diff --git a/doc/mnh.7 b/doc/mnh.7 index 77c8d9bfb..802c806ec 100644 --- a/doc/mnh.7 +++ b/doc/mnh.7 @@ -38,7 +38,7 @@ and number registers are defined below. .SH FILES doc/tmac.nh .SH "SEE ALSO" -mn(7) +.IR mn (7) .SH AUTHOR Pat Rankin .SH REQUESTS diff --git a/doc/nethack.6 b/doc/nethack.6 index 92f813796..10d681f8f 100644 --- a/doc/nethack.6 +++ b/doc/nethack.6 @@ -665,7 +665,7 @@ can be used in debugging (wizard) mode. .I \%DEBUGFILES can be used if the program was built with 'DEBUG' enabled. .SH "SEE ALSO" -recover(6) +.IR recover (6) .SH BUGS Probably infinite. .SH COPYRIGHT diff --git a/doc/recover.6 b/doc/recover.6 index b7298c015..1fcdff662 100644 --- a/doc/recover.6 +++ b/doc/recover.6 @@ -134,7 +134,7 @@ but even a compression-using .I nethack will find them in the uncompressed form. .SH "SEE ALSO" -nethack(6) +.IR nethack (6) .SH BUGS .I recover makes no attempt to find out if a base name specifies a game in progress. From 103d5f27e76a383a9b12a2e2ef5a4a2ebdd3dfe5 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Sun, 3 May 2026 01:06:17 -0500 Subject: [PATCH 19/39] doc/makedefs.6: Drop redundant `br` requests Paragraphing macros in *roff systems generally break the output line, and the same is true of all of man(7)'s paragraphing macros. groff_man(7): Paragraphing macros These macros break the output line. An ordinary paragraph (P) indents all output lines by the same amount. A hanging paragraph (HP) is a cosmetic variant of P with a hanging indent. Definition lists frequently occur in man pages; these can be set as tagged paragraphs, which have one (TP) or more (TQ) leading tags followed by a paragraph that has an additional indentation. --- doc/makedefs.6 | 19 ------------------- 1 file changed, 19 deletions(-) diff --git a/doc/makedefs.6 b/doc/makedefs.6 index b8d24b7d4..fad5ed24e 100644 --- a/doc/makedefs.6 +++ b/doc/makedefs.6 @@ -71,12 +71,10 @@ Upper and lower case are both accepted for the short commands. .B \-o Generate .IR onames.h . -.br .TP .B \-d Generate .IR data.base . -.br .TP .B \-e Generate @@ -89,7 +87,6 @@ same logic as that used by the command; see the .B MDGREP FUNCTIONS section below for details. -.br .TP .B \-m Generate @@ -106,18 +103,15 @@ and info and include related preprocessor #defines in .I date.h file. -.br .TP .B \-p Generate .IR pm.h . -.br .TP .B \-q Generate the .I rumors file. -.br .TP .B \-s Generate the @@ -126,36 +120,30 @@ Generate the and .I epitaph files. -.br .TP .B \-1 Generate the .I epitaph file. -.br .TP .B \-2 Generate the .I engrave file. -.br .TP .B \-3 Generate the .I bogusmon file. -.br .TP .B \-h Generate the .I oracles file. -.br .SH LONG COMMANDS .TP .B \-\-debug Show debugging output. -.br .TP .B \-\-make \fR[\fIcommand\fR] Execute a short command. @@ -168,7 +156,6 @@ Specify the input for the command (if needed). If the file is \- standard input is read. -.br .TP .BI \-\-output " file" Specify the output @@ -176,12 +163,10 @@ Specify the output for the command (if needed). If the file is \- standard output is written. -.br .TP .B \-\-svs \fR[\fIdelimiter\fR] Generate a version string to standard output without a trailing newline. If specified, the delimiter is used between each part of the version string. -.br .TP .B \-\-grep Filter the input @@ -190,17 +175,14 @@ Filter the input See the .B MDGREP FUNCTIONS section below for information on controlling the filtering operation. -.br .TP .B \-\-grep\-showvars Show the name and value for each variable known to the grep option. -.br .TP .B \-\-grep\-trace Turn on debug tracing for the grep function ( .B \-\-grep must be specified as well). -.br .TP .BI \-\-grep\-defined " symbol" Exit shell true (0) if @@ -214,7 +196,6 @@ to be "defined." .I Symbol must already be known to .BR makedefs . -.br .TP .BI \-\-grep\-undef " symbol" Force the definition of From fb611b60bcd1ff76916a24b0fb0244c2dd4c8942 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Sun, 3 May 2026 01:15:25 -0500 Subject: [PATCH 20/39] doc/nethack.6: Spell "NetHack" thus ...when not referring specifically to the command's file name. --- doc/nethack.6 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/nethack.6 b/doc/nethack.6 index 10d681f8f..aac02424c 100644 --- a/doc/nethack.6 +++ b/doc/nethack.6 @@ -307,7 +307,7 @@ is already used for the role. .PP .B \-@ -tells nethack to choose any omitted characteristics (profession/role, race, +tells NetHack to choose any omitted characteristics (profession/role, race, gender, alignment) randomly without prompting. Otherwise, leaving out any of these characteristics will result in you being prompted during game startup for the information. @@ -326,7 +326,7 @@ changing the character name to \(lqwizard\(rq, if the player is allowed. Otherwise it will switch to .BR \-X . Control of who is allowed to use debug mode is done via the -.RI "\(lq" WIZARDS= "\(rq line in nethack's " sysconf " file." +.RI "\(lq" WIZARDS= "\(rq line in NetHack's " sysconf " file." .PP The .BR \-d " or " \-\-directory From 14430511bd9de82a8642f868a1d33b96211b7d07 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Sun, 3 May 2026 01:24:10 -0500 Subject: [PATCH 21/39] doc/nethack.6: Be more portable to old roffs (1/4) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Favor the very old `lq` and `rq` extension _strings_ over special characters of the same name. This fixes missing punctuation and text when rendering this document with DWB and Solaris 10 nroffs, and misrendered text with Plan 9 nroff. Before (DWB, Solaris 10): discovery mode (also known as explore mode). -D will start the game in debug mode (also known as wizard mode) after changing the character name to wizard, if the player is allowed. Otherwise it will switch to -X. Control of who is allowed to use debug mode is done via the Before (Plan 9): discovery mode (also known as explore mode). -D will start the game in debug mode (also known as wizard mode) after changing the character name to lqwizardrq, if the player is allowed. Otherwise it will switch to -X. Control of who is allowed to use debug mode is done via the lqWIZARDS=rq line in NetHack's sysconf file. After (all): The -X option will start the game in a special non-scoring discovery mode (also known as explore mode). -D will start the game in debug mode (also known as wizard mode) after changing the character name to "wizard", if the player is allowed. Otherwise it will switch to -X. Control of who is allowed to use debug mode is done via the "WIZARDS=" line in NetHack's sysconf file. (There are minor differences in the page offset amount, and Plan 9 uses UTF-8 double quotation marks, U+201C and U+201D.) groff_man(7): Strings The following strings are defined for use in man pages. None of these is necessary in a contemporary man page; see groff_man_style(7). ... ... \*(lq \*(rq interpolate special character escape sequences for left and right double‐quotation marks, \(lq and \(rq, respectively. (I see that I should reword the foregoing to something like "None is necessary in man pages targeting only contemporary *roff formatters".) History ... 4BSD (1980) added lq and rq strings. ... Unix System V (1988) incorporated the lq and rq strings. Except for EX/EE, James Clark implemented the foregoing features in early versions of groff. ... Plan 9 from User Space’s troff ... incorporated the lq and rq strings in 2025. groff_man_style(7): Notes Some tips on composing and troubleshooting your man pages follow. ... • When and how should I use quotation marks? As noted above in subsection “Font style macros”, apply quotation marks to “brief specimens of literal text, such as article titles, inline examples, mentions of individual characters or short strings, and (sub)section headings in man pages”. Multi‐ word literals, such as Unix commands with arguments, when set inline (as opposed to displayed between EX and EE), should be quoted to ensure that the boundaries of the literal are clear even when the material is stripped of font styling by, for example, copy‐and‐paste operations. groff, Heirloom Doctools troff, neatroff, and mandoc support all of the special characters \[oq], \[cq], \[lq], \[rq], \[aq], and \[dq] described in subsection “Portability” above. DWB, Plan 9, and Solaris troffs do not. Interpolating the strings \*(lq and \*(rq portably yields directional double quotation marks, if available, in all these formatters (though neatroff does not supply a man macro package), but they cannot reliably be used in macro arguments. Per the final sentence above, do a little dance to avoid using these strings in macro arguments. --- doc/nethack.6 | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/doc/nethack.6 b/doc/nethack.6 index aac02424c..d25f09a0d 100644 --- a/doc/nethack.6 +++ b/doc/nethack.6 @@ -216,7 +216,7 @@ below). On other systems, the default may be different, possibly NetHack.cnf. On MS-DOS, the name is defaults.nh in NetHack's directory (folder), while -.\" on the Macintosh or BeOS, it is \(lqNetHack Defaults\(rq, and +.\" on the Macintosh or BeOS, it is \*(lqNetHack Defaults\*(rq, and on VMS|OpenVMS it is nethack.ini in your home directory. The default configuration file may be overridden via the .BI \-\-nethackrc: "rc-file" @@ -322,11 +322,22 @@ option will start the game in a special non-scoring discovery mode (also known as explore mode). .B \-D will start the game in debug mode (also known as wizard mode) after -changing the character name to \(lqwizard\(rq, if the player is allowed. +changing the character name to \*(lqwizard\*(rq, +if the player is allowed. Otherwise it will switch to .BR \-X . Control of who is allowed to use debug mode is done via the -.RI "\(lq" WIZARDS= "\(rq line in NetHack's " sysconf " file." +.\" The `lq` and `rq` strings are not reliable in macro calls, because +.\" some nroffs interpolate `"` for them, messing up macro argument +.\" delimitation. Use an (initially) uglier method than `RI`. +.\".RI "\*(lq" WIZARDS= "\*(rq line in NetHack's " sysconf " file." +\*(lq\c +.I WIZARDS=\c +\*(rq +line in +NetHack's +.I sysconf +file. .PP The .BR \-d " or " \-\-directory From afeec3dd651cbcd0c749bb53a25cdccd319329fc Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Sun, 3 May 2026 01:40:41 -0500 Subject: [PATCH 22/39] doc/nethack.6: Be more portable to old roffs (2/4) Old *roffs don't support the `ti` special character. Compensate. Before (DWB, Solaris 10): The --nethackrc:RC-file option will use RC-file instead of the default run-time configuration file (typically /.nethackrc) and the --no-nethackrc option can be used to skip any run-time configuration file. Before (Plan 9): The --nethackrc:RC-file option will use RC-file instead of the default run-time configuration file (typically ti/.nethackrc) and the --no-nethackrc option can be used to skip any run-time configuration file. After (all): The --nethackrc:RC-file option will use RC-file instead of the default run-time configuration file (typically ~/.nethackrc) and the --no-nethackrc option can be used to skip any run-time configuration file. --- doc/nethack.6 | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/doc/nethack.6 b/doc/nethack.6 index d25f09a0d..061092fb6 100644 --- a/doc/nethack.6 +++ b/doc/nethack.6 @@ -16,6 +16,12 @@ .ie \n(.g .hy 12 .el .hy 14 .ds Na Robert Patrick Rankin +.\" DWB, Solaris 10, and Plan 9 troffs don't support `\(ti`. Assume the +.\" best, then detect these older troffs and fall back as needed. +.\" +.\" Put NO SPACE between special character and comment escape sequences. +.ds ~ \(ti\" The name "ti" is taken by *roff's `ti` request. +.if !\n(.g .ds ~ ~ .\" Define string to exercise groff's hyphenless break point feature. .ie \n(.g .ds : \: .el .ds : \" empty @@ -368,7 +374,7 @@ The option will use .I RC-file instead of the default run-time configuration file -.RI "(typically " \(ti/.nethackrc ")" +.RI "(typically " \*~/.nethackrc ")" and the .B \-\-no\-nethackrc option can be used to skip any run-time configuration file. From 1922fb687d1c37fcccf4a26d1fdb9aa85945e405 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Tue, 5 May 2026 07:12:23 -0500 Subject: [PATCH 23/39] doc/nethack.6: Be more portable to old roffs (3/4) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Unbreakable spaces in AT&T troff were always non-adjustable. Define a string to use groff's `\~` extension if possible. groff_man_style(7): Portability ... \~ Adjustable non‐breaking space. Use this escape sequence to prevent a break inside a short phrase or between a numerical quantity and its corresponding unit(s). Before starting the motor, set the output speed to\~1. There are 1,024\~bytes in 1\~KiB. CSTR\~#8 documents the B\~language. \~ is a GNU extension also supported by Heirloom Doctools troff 050915 (September 2005), mandoc 1.9.14 (2009‐11‐16), neatroff (commit 1c6ab0f6e, 2016‐09‐13), and Plan 9 from User Space troff (commit 93f8143600, 2022‐08‐12), but not by DWB or Solaris troffs. Fixes bad rendering in DWB 3.3 troff: @@ -999 +999 @@ - file. -s|-s~-v may also be followed by arguments -p + file. -s|-s -v may also be followed by arguments -p @@ -1005 +1005 @@ - entries which match both. -s|-s~-v may be followed by one + entries which match both. -s|-s -v may be followed by one Solaris 10 troff _would_ misrender as well, but a different portability problem keeps some of the foregoing text from rendering at all. --- doc/nethack.6 | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/doc/nethack.6 b/doc/nethack.6 index 061092fb6..0077408ec 100644 --- a/doc/nethack.6 +++ b/doc/nethack.6 @@ -25,6 +25,9 @@ .\" Define string to exercise groff's hyphenless break point feature. .ie \n(.g .ds : \: .el .ds : \" empty +.\" Define string to exercise groff's adjustable, unbreakable space. +.ie \n(.g .ds _ \~ +.el .ds _ \ \" backslash, space .\" Define local versions of groff's "an-ext.tmac" macros if needed. .ds %% \" empty .if \n(.g .ig %% @@ -387,7 +390,7 @@ option alone will print out the list of your scores on the current version. An immediately following .B \-v reports on all versions present in the score file. -.RB \(oq \-s | \-s\~\-v \(cq +.RB \(oq \-s | \-s\*_\-v \(cq may also be followed by arguments .B \-p .I profession @@ -399,7 +402,7 @@ Either can be specified multiple times to include more than one role or more than one race. When both are specified, score entries which match either the role or the race (or both) are printed rather than just entries which match both. -.RB \(oq \-s | \-s\~\-v \(cq +.RB \(oq \-s | \-s\*_\-v \(cq may be followed by one or more player names to print the scores of the players mentioned, by 'all' to print out all scores, or by a number to print that many top scores. From 4a76d66ad9eac9c81e3db60eec7b0553177e059e Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Tue, 5 May 2026 07:34:41 -0500 Subject: [PATCH 24/39] doc/nethack.6: Be more portable to old roffs (4/4) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Define strings for directional single quotation marks. groff_man_style(7): Notes Some tips on composing and troubleshooting your man pages follow. ... • When and how should I use quotation marks? ... Obtaining directional single quotation marks is more of a challenge. Historically, man pages used ` and ', which troff rendered on typesetters as ‘ and ’, exclusively for them. However, in recent years, some distributors of groff have chosen to override the meanings of these characters in man pages, remapping them to their Unicode Basic Latin code points. Unfortunately, ` and ' are the only reliable means of obtaining directional single quotation marks in AT&T troff; in that implementation, often no special character escape sequences exist to obtain them. Further, AT&T troff’s special character identifiers, like its font names, were device‐specific. To achieve quotation portably in man pages rendered both by AT&T and more modern troffs, consider adding a preamble to your page after the TH call as follows. .ie \n(.g \{\ . ds oq \[oq]\" . ds cq \[cq]\" .\} .el \{\ . ds oq `\" . ds cq '\" .\} You must then use the \* escape sequence to interpolate the quotation mark strings. The command .RB \*(oq "while !\& git pull; do sleep 10; done" \*(cq retries an update from the repository until it succeeds. If this procedure seems complex, petition your distributor to revert their remapping of the ` and ' characters. --- doc/nethack.6 | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/doc/nethack.6 b/doc/nethack.6 index 0077408ec..9a2631a41 100644 --- a/doc/nethack.6 +++ b/doc/nethack.6 @@ -16,12 +16,19 @@ .ie \n(.g .hy 12 .el .hy 14 .ds Na Robert Patrick Rankin -.\" DWB, Solaris 10, and Plan 9 troffs don't support `\(ti`. Assume the -.\" best, then detect these older troffs and fall back as needed. +.\" DWB, Solaris 10, and Plan 9 troffs don't support `\(ti`, `\(oq`, or +.\" `\(cq`. Assume the best, then detect these older troffs and fall +.\" back as needed. .\" .\" Put NO SPACE between special character and comment escape sequences. .ds ~ \(ti\" The name "ti" is taken by *roff's `ti` request. -.if !\n(.g .ds ~ ~ +.ds oq \(oq +.ds cq \(cq +.if !\n(.g \{\ +. ds ~ ~ +. ds oq ` +. ds cq ' +.\} .\" Define string to exercise groff's hyphenless break point feature. .ie \n(.g .ds : \: .el .ds : \" empty @@ -390,7 +397,7 @@ option alone will print out the list of your scores on the current version. An immediately following .B \-v reports on all versions present in the score file. -.RB \(oq \-s | \-s\*_\-v \(cq +.RB \*(oq \-s | \-s\*_\-v \*(cq may also be followed by arguments .B \-p .I profession @@ -402,7 +409,7 @@ Either can be specified multiple times to include more than one role or more than one race. When both are specified, score entries which match either the role or the race (or both) are printed rather than just entries which match both. -.RB \(oq \-s | \-s\*_\-v \(cq +.RB \*(oq \-s | \-s\*_\-v \*(cq may be followed by one or more player names to print the scores of the players mentioned, by 'all' to print out all scores, or by a number to print that many top scores. @@ -441,7 +448,7 @@ customize aspects of how the game operates. .BR \-\-usage " or " \-\-help will display information similar to this manual page, then exit. Use -.RB \(oq "nethack \-\-usage | more" \(cq +.RB \*(oq "nethack \-\-usage | more" \*(cq to read it a page at a time. .SH AUTHORS Jay Fenlason (+ Kenny Woodland, Mike Thome and Jon Payne) wrote the From 2c9bda8660b2fe377393314e5106262e08f25bba Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Tue, 5 May 2026 17:16:45 -0500 Subject: [PATCH 25/39] doc/nethack.6: Respell playername option argument Spell it as a hyphenated noun phrase. Use an ellipsis instead of pluralization to mark its repeatability. Slightly recast its description. --- doc/nethack.6 | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/doc/nethack.6 b/doc/nethack.6 index 9a2631a41..b3abff111 100644 --- a/doc/nethack.6 +++ b/doc/nethack.6 @@ -83,7 +83,7 @@ nethack \- Exploring The Mazes of Menace .br [ .B \-u -.I playername +.I player-name ] [ .BR \-X " | " \-D @@ -148,8 +148,8 @@ Also .I race ] [ -.I playernames -] +.I player-name\*_\c +\&.\|.\|.] .PP .B nethack [ @@ -241,7 +241,7 @@ to a string consisting of an @ character followed by the path and filename. .PP The .B \-u -.I playername +.I player-name option supplies the answer to the question "Who are you?". It overrides any name from the options or configuration file, USER, LOGNAME, or getlogin(), which will otherwise be tried in order. @@ -251,11 +251,12 @@ so you can have several saved games under different names. Conversely, you must use the appropriate player name to restore a saved game. .PP A -.I playername +.I player-name suffix can be used to specify the profession, race, alignment and/or gender of the character. -The full syntax of the playername that includes a -suffix is "name\-ppp\-rrr\-aaa\-ggg". +The full syntax of a +.I player-name +including a suffix is "name\-ppp\-rrr\-aaa\-ggg". "ppp" are at least the first three letters of the profession (this can also be specified using a separate .B \-p From 2b4b589a63d1550611c8480844e337c392e72730 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Tue, 5 May 2026 17:20:47 -0500 Subject: [PATCH 26/39] doc/nethack.6: Spell option argument as "rc-file" ...that is, not in capitals. Lowercase seems more consistent with Unix practice. --- doc/nethack.6 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/nethack.6 b/doc/nethack.6 index b3abff111..0e01bf061 100644 --- a/doc/nethack.6 +++ b/doc/nethack.6 @@ -70,7 +70,7 @@ nethack \- Exploring The Mazes of Menace ] .br [ -.BI \-\-nethackrc: RC-file +.BI \-\-nethackrc: rc-file | .B \-\-no\-nethackrc ] @@ -381,9 +381,9 @@ specified in the run-time configuration file. NetHack's #version command shows available interfaces. .PP The -.BI \-\-nethackrc: RC-file +.BI \-\-nethackrc: rc-file option will use -.I RC-file +.I rc-file instead of the default run-time configuration file .RI "(typically " \*~/.nethackrc ")" and the From 2011f8b4c1afbecfa0d7a2dc6359b0797a050fa9 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Tue, 5 May 2026 17:31:07 -0500 Subject: [PATCH 27/39] doc/nethack.6: Split non-playing synopses The `--showpaths` and `--version` options can't be (usefully) combined with `--usage` or `--help`, nor with each other. --- doc/nethack.6 | 19 +++++++------------ 1 file changed, 7 insertions(+), 12 deletions(-) diff --git a/doc/nethack.6 b/doc/nethack.6 index 0e01bf061..cfac65341 100644 --- a/doc/nethack.6 +++ b/doc/nethack.6 @@ -152,19 +152,14 @@ Also \&.\|.\|.] .PP .B nethack -[ -.B \-\-usage -| -.B \-\-help -] -[ +.RB { \-\-usage | \-\-help } +.PP +.B nethack .B \-\-showpaths -] -.\" force line wrap now rather than have that happen after the opening brace -.br -[ -.BR \-\-version [ :copy | :dump | :show ] -] +.PP +.B nethack +.BR \-\-version [ :copy | :dump\c +.RB | :show ] .ad .hy 14 .\" Make sure path is not hyphenated below From e4476516cd0ad1721925916c7df844706c86ee50 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Tue, 5 May 2026 17:45:09 -0500 Subject: [PATCH 28/39] doc/nethack.6: Revise scoreboard mode synopsis MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Set it as a hanging paragraph, as is idiomatic for Unix command synopses. Tighten formatting: set synopsis syntax characters adjacently to operands. Since viewing the scoreboard is a separate mode of operation, arrange first the options that select this mode.[1] Also drop explicit line breaks, permitting synopsis to exercise the configured line length of the selected output device. Before and after, as rendered with Solaris 10 troff: - nethack [ -d|--directory directory ] -s|--scores [ -v ] - [ -p profession ] [ -r race ] [ player-name ...] + nethack {-s|--scores} [-d|--directory directory] [-v] + [-p profession] [-r race] [player-name ...] Before and after, as rendered with groff, mandoc, and Heirloom Doctools troff: - nethack [ -d|--directory directory ] -s|--scores [ -v ] - [ -p profession ] [ -r race ] [ player‐name ...] + nethack {-s|--scores} [-d|--directory directory] [-v] [-p profession] + [-r race] [player‐name ...] Not shown: Literal text is in bold, and option arguments in italics. [1] See, for example, . --- doc/nethack.6 | 30 ++++++++++-------------------- 1 file changed, 10 insertions(+), 20 deletions(-) diff --git a/doc/nethack.6 b/doc/nethack.6 index cfac65341..45e8dc011 100644 --- a/doc/nethack.6 +++ b/doc/nethack.6 @@ -128,27 +128,17 @@ Also | .BR \-W | \-Wiz ] -.PP +.HP .B nethack -[ -.BR \-d | \-\-directory -.I directory -] -.BR \-s | \-\-scores -[ -.B \-v -] -.br -[ -.B \-p -.I profession -] -[ -.B \-r -.I race -] -[ -.I player-name\*_\c +.RB { \-s | \-\-scores } +.RB [ \-d | \-\-directory\*_\c +.IR directory ] +.RB [ \-v ] +.RB [ \-p\*_\c +.IR profession ] +.RB [ \-r\*_\c +.IR race ] +.RI [ player-name\*_\c \&.\|.\|.] .PP .B nethack From 44c840500042ae97a5257560bed8a05ec55a6893 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Tue, 5 May 2026 18:16:36 -0500 Subject: [PATCH 29/39] doc/nethack.6: Revise primary synopsis Set it as a hanging paragraph, as is idiomatic for Unix command synopses. Tighten formatting: set synopsis syntax characters adjacently to operands. Also drop explicit line breaks, permitting synopsis to exercise the configured line length of the selected output device. Temporarily disable adjustment in a manner more friendly to the system's (or user's) configuration.[1] Stop attempting to manipulate hyphenation; there's no portable way to do that.[2] Before and after, as rendered with Solaris 10, DWB 3.3, and Plan 9 troffs: - nethack [ -d|--directory directory ] [ -w|--windowtype - interface ] - [ --nethackrc:rc-file | --no-nethackrc ] [ -n ] [ -dec | - -ibm ] - [ -u player-name ] [ -X | -D ] [ -p profession ] [ -r race ] - [ -@ ] + nethack [-d|--directory directory] + [-w|--windowtype interface] + [--nethackrc:rc-file|--no-nethackrc] [-n] [-dec|-ibm] + [-u player-name] [-X|-D] [-p profession] [-r race] [-@] Not shown: Literal text is in bold, and option arguments in italics. (Full disclosure: The aforementioned formatters use different page offsets [left margin sizes], and Plan 9 nroff doesn't render _any_ typeface changes, ever, for any document using any macro package.) Before and after, as rendered with groff, mandoc, and Heirloom Doctools troff: - [ --nethackrc:rc-file | --no-nethackrc ] [ -n ] [ -dec | -ibm ] - [ -u player-name ] [ -X | -D ] [ -p profession ] [ -r race ] [ -@ ] + nethack [-d|--directory directory] [-w|--windowtype interface] + [--nethackrc:rc-file|--no-nethackrc] [-n] [-dec|-ibm] + [-u player-name] [-X|-D] [-p profession] [-r race] [-@] (Full disclosure: groff 1.24.x man(7) uses a default line length of 80n,[3] up from the 78n of its previous releases going back to 2002, and used by Heirloom Doctools and mandoc.) [1] https://cgit.git.savannah.gnu.org/cgit/groff.git/tree/tmac/an.tmac?h=1.24.1#n159 [2] https://cgit.git.savannah.gnu.org/cgit/groff.git/tree/tmac/an.tmac?h=1.24.1#n202 [3] https://cgit.git.savannah.gnu.org/cgit/groff.git/tree/NEWS?h=1.24.1#n509 --- doc/nethack.6 | 68 ++++++++++++++++----------------------------------- 1 file changed, 21 insertions(+), 47 deletions(-) diff --git a/doc/nethack.6 b/doc/nethack.6 index 45e8dc011..1944df6a4 100644 --- a/doc/nethack.6 +++ b/doc/nethack.6 @@ -51,54 +51,29 @@ .SH NAME nethack \- Exploring The Mazes of Menace .SH SYNOPSIS +.HP +.nr sA \n(.j \" Save the adjustment mode. .na -.hy 0 -.\" Some options ordering is explicit (-d first, -u before -D), others -.\" have been arranged to fit within an 80-column page with nearly full -.\" lines while avoiding splitting "[" and "-opt ]" or "[ -opt" and "]" -.\" across line boundaries. It would be better to do that with 'roff magic. .B nethack -[ -.BR \-d | \-\-directory -.I directory -] -.\" '.B token newline .I token' will include a space between the two tokens; -.\" '.BI token token' will not. Likewise for .BR, .RB, &c. -[ -.BR \-w | \-\-windowtype -.I interface -] -.br -[ -.BI \-\-nethackrc: rc-file -| -.B \-\-no\-nethackrc -] -[ -.B \-n -] -[ -.BR \-dec " | " \-ibm -] -.br -[ -.B \-u -.I player-name -] -[ -.BR \-X " | " \-D -] -[ -.B \-p -.I profession -] -[ -.B \-r -.I race -] -[ -.B \-@ +.RB [ \-d | \-\-directory\*_\c +.IR directory ] +.RB [ \-w | \-\-windowtype\*_\c +.IR interface ] +\%[\c +.BI \-\-nethackrc: rc-file\c +|\c +.B \-\-no\-nethackrc\c ] +.RB [ \-n ] +.RB [ \-dec | \-ibm ] +.RB [ \-u\*_\c +.IR player-name ] +.RB [ \-X | \-D ] +.RB [ \-p\*_\c +.IR profession ] +.RB [ \-r\*_\c +.IR race ] +.RB [ \-@ ] .PP Also [ @@ -150,8 +125,7 @@ Also .B nethack .BR \-\-version [ :copy | :dump\c .RB | :show ] -.ad -.hy 14 +.ad \n(sA \" Restore the adjustment mode. .\" Make sure path is not hyphenated below .hw nethackdir .SH DESCRIPTION From bdae11c61dd541d506b152b0f818d0d8b6cdf752 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Tue, 5 May 2026 18:37:27 -0500 Subject: [PATCH 30/39] doc/nethack.6: Revise role info in synopsis Revise presentation of backward-compatible role options. - Give them a metasyntactic variable name and present them in the main command synopsis. - Present the possible values in a typographical display, indented with filling disabled. --- doc/nethack.6 | 23 ++++++++--------------- 1 file changed, 8 insertions(+), 15 deletions(-) diff --git a/doc/nethack.6 b/doc/nethack.6 index 1944df6a4..554b8dd16 100644 --- a/doc/nethack.6 +++ b/doc/nethack.6 @@ -55,6 +55,7 @@ nethack \- Exploring The Mazes of Menace .nr sA \n(.j \" Save the adjustment mode. .na .B nethack +.RI [ role-option ] .RB [ \-d | \-\-directory\*_\c .IR directory ] .RB [ \-w | \-\-windowtype\*_\c @@ -75,34 +76,26 @@ nethack \- Exploring The Mazes of Menace .IR race ] .RB [ \-@ ] .PP -Also -[ +.I role-option +can be any of the following. +.PP +.RS +.nf .BR \-A | \-Arc -| .BR \-B | \-Bar -| .BR \-C | \-Cav -| .BR \-H | \-Hea -| .BR \-K | \-Kni -| .BR \-M | \-Mon -| .BR \-P | \-Pri -| .BR \-R | \-Rog -| .B \-Ran -| .BR \-S | \-Sam -| .BR \-T | \-Tou -| .BR \-V | \-Val -| .BR \-W | \-Wiz -] +.fi +.RE .HP .B nethack .RB { \-s | \-\-scores } From 4ab9ec36de61e8e19de70aa5a52466b2f2ea3483 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Tue, 5 May 2026 18:51:40 -0500 Subject: [PATCH 31/39] doc/makedefs.6: Tigthen formatting Set synopsis syntax characters adjacently to operands. --- doc/makedefs.6 | 28 ++++++++++------------------ 1 file changed, 10 insertions(+), 18 deletions(-) diff --git a/doc/makedefs.6 b/doc/makedefs.6 index fad5ed24e..fc3120a5c 100644 --- a/doc/makedefs.6 +++ b/doc/makedefs.6 @@ -20,24 +20,16 @@ makedefs \- NetHack miscellaneous build-time functions .SH SYNOPSIS .B makedefs -{ -.B \-o -| -.B \-d -| -.B \-e -| -.B \-m -| -.B \-v -| -.B \-p -| -.B \-q -| -.B \-r -| -.B \-h +{\c +.BR \-o |\c +.BR \-d |\c +.BR \-e |\c +.BR \-m |\c +.BR \-v |\c +.BR \-p |\c +.BR \-q |\c +.BR \-r |\c +.B \-h\c } .P .B makedefs \-\-input From b602b495bb287bbe715e607a684ae1b59952f4b7 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Tue, 5 May 2026 18:59:39 -0500 Subject: [PATCH 32/39] doc/makedefs.6: Clarify `-` as option argument Quote it, use fuller C standard I/O terminology, and use active voice. --- doc/makedefs.6 | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/doc/makedefs.6 b/doc/makedefs.6 index fc3120a5c..c9e617db6 100644 --- a/doc/makedefs.6 +++ b/doc/makedefs.6 @@ -146,15 +146,21 @@ is given without preceding dash. Specify the input .I file for the command (if needed). -If the file is \- standard -input is read. +If +.I file +is \*(lq\-\*(rq, +.B makedefs +reads the standard input stream. .TP .BI \-\-output " file" Specify the output .I file for the command (if needed). -If the file is \- standard -output is written. +If +.I file +is \*(lq\-\*(rq, +.B makedefs +writes to the standard input stream. .TP .B \-\-svs \fR[\fIdelimiter\fR] Generate a version string to standard output without a trailing newline. From 561d08e53b4ef50851d6dbe64addec7e72af1e7e Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Tue, 5 May 2026 19:23:30 -0500 Subject: [PATCH 33/39] doc/*.6: Improve formatting of carets MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ...on typesetters and UTF-8 terminals. groff_man_style(7): Portability ... Several special characters are also widely portable. Except for \-, \[em], and \[ga], AT&T troff did not consistently define the characters listed below, but its descendants, like DWB, Plan 9, or Solaris troff, can be made to support them by defining them in font description files, making them aliases of existing glyphs if necessary; see groff_font(5). groff’s extended notation for special characters, \[xx], is also supported by mandoc(1), Heirloom Doctools troff, and neatroff, but not DWB, Plan 9, or Solaris troffs. ... \[ha] Basic Latin circumflex accent (“hat”). Some output devices format “^” as U+02C6 (modifier letter circumflex accent). Notes Some tips on composing and troubleshooting your man pages follow. ... • Escape sequences of the form \[xx] don’t format correctly. The \[xx] special character escape sequence is a GNU troff extension also supported by mandoc, Heirloom Doctools troff, and neatroff. DWB, Plan 9, and Solaris troffs don’t implement it. If your man page requires portability to these formatters, spell such escape sequences as “\(xx”; no closing parenthesis is used. xx must be exactly two characters; groff_char(7) lists portable special character identifiers. --- doc/dlb.6 | 14 ++++++++------ doc/makedefs.6 | 16 +++++++++------- doc/recover.6 | 16 +++++++++------- 3 files changed, 26 insertions(+), 20 deletions(-) diff --git a/doc/dlb.6 b/doc/dlb.6 index c002537ce..e314989d2 100644 --- a/doc/dlb.6 +++ b/doc/dlb.6 @@ -11,6 +11,8 @@ .. .NB $NHDT-Branch: keni-gitset $ .NR $NHDT-Revision: 1.13 $ +.ie \n(.g .ds ^ \(ha +.el .ds ^ ^ .\" groff and AT&T-descended troffs use different hyphenation patterns. .\" Don't hyphenate the last word on a page or column, or .\" before/after last/first 2 characters of a word. @@ -69,18 +71,18 @@ Unlike is configured with a default set of file names to process. .ig .PP -^?ALLDOCS +\*^?ALLDOCS This facility is optional and may be excluded during NetHack configuration. -^: -^?DLB +\*^: +\*^?DLB This facility is optional but is included in this NetHack configuration. -^: +\*^: This facility is optional and was excluded from this NetHack configuration. -^. -^. +\*^. +\*^. .. .SS Operations .B c diff --git a/doc/makedefs.6 b/doc/makedefs.6 index c9e617db6..9c33ef6e3 100644 --- a/doc/makedefs.6 +++ b/doc/makedefs.6 @@ -10,6 +10,8 @@ .. .NB $NHDT-Branch: NetHack-5 $ .NR $NHDT-Revision: 1.22 $ +.ie \n(.g .ds ^ \(ha +.el .ds ^ ^ .\" groff and AT&T-descended troffs use different hyphenation patterns. .\" Don't hyphenate the last word on a page or column, or .\" before/after last/first 2 characters of a word. @@ -220,7 +222,7 @@ The default conditional state is printing enabled. .IP - 4 Any line .I NOT -starting with a caret (^) is either suppressed or passed through unchanged +starting with a caret (\*^) is either suppressed or passed through unchanged depending on the current conditional state. .IP - 4 Any line starting with a caret is a control line; as in C, zero or more spaces @@ -243,21 +245,21 @@ configuration are different from unknown. .P Control lines: .RS -.IP ^^ 4 +.IP \*^\*^ 4 a line starting with a (single) literal caret -.IP ^# +.IP \*^# a comment -.IP ^?\fIID +.IP \*^?\fIID if the .I ID is defined set the conditional state to TRUE -.IP ^!\fIID +.IP \*^!\fIID if the .I ID is not defined set the conditional state to TRUE -.IP ^: +.IP \*^: else; invert the conditional state -.IP ^. +.IP \*^. end the most recent conditional .RE .\".SH EXAMPLES diff --git a/doc/recover.6 b/doc/recover.6 index 1fcdff662..5d78684ee 100644 --- a/doc/recover.6 +++ b/doc/recover.6 @@ -10,7 +10,9 @@ .. .NB $NHDT-Branch: NetHack-5 $ .NR $NHDT-Revision: 1.12 $ -.\" groff and AT&T-descended troffs use different hyphenation patterns. +.ie \n(.g .ds ^ \(ha +.el .ds ^ ^ +.\" groff and AT&T-descended troffs use different hyphenation patterns. .\" Don't hyphenate the last word on a page or column, or .\" before/after last/first 2 characters of a word. .ie \n(.g .hy 12 @@ -49,26 +51,26 @@ specified by the game administrator during compilation (usually /usr/games/lib/nethackdir). .ig .PP -^?ALLDOCS +\*^?ALLDOCS For recovery to be possible, .I nethack must have been compiled with the INSURANCE option, and the run-time option .I checkpoint must also have been on. -^: -^?INSURANCE +\*^: +\*^?INSURANCE For recovery to be possible, .I nethack must have been compiled with the INSURANCE option (this configuration was), and the run-time option .I checkpoint must also have been on. -^: +\*^: This configuration of .I nethack was created without support for recovery. -^. -^. +\*^. +\*^. .. NetHack normally writes out files for levels as the player leaves them, so they will be ready for return visits. From 2d3f9b8c217a63ae0725ac22ff39700d1b83361b Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Tue, 5 May 2026 20:12:58 -0500 Subject: [PATCH 34/39] doc/recover.6: Revise synopsis MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Tighten formatting: set synopsis syntax characters adjacently to operands. Rename `-d` option argument from "directory" to "playground-directory" for clarity. Set operands more idiomatically. They are not given in pairs; instead "base" can be repeated arbitrarily. See, for example, the POSIX reference page for ls(1). https://pubs.opengroup.org/onlinepubs/9799919799/utilities/ls.html Format ellipsis idiomatically. groff_man_style(7): Notes ... The idiomatic roff ellipsis is three dots (periods) with thin space escape sequences \| internally separating them. Since dots both begin control lines and are candidate end‐of‐sentence characters, however, it is sometimes necessary to prefix and/or suffix an ellipsis with the dummy character escape sequence \&. --- doc/recover.6 | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/doc/recover.6 b/doc/recover.6 index 5d78684ee..922981d00 100644 --- a/doc/recover.6 +++ b/doc/recover.6 @@ -22,11 +22,10 @@ recover \- recover a NetHack game interrupted by disaster .SH SYNOPSIS .B recover -[ -.B \-d -.I directory -] -.I "base1 base2" ... +.RB [ \-d +.IR playground-directory ] +.I base +\&.\|.\|. .SH DESCRIPTION Occasionally, a NetHack game will be interrupted by disaster when the game or the system crashes. From 61a16e69832fd11dd83cbf55ec0cc0ed681a8451 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Tue, 5 May 2026 20:17:52 -0500 Subject: [PATCH 35/39] doc/recover.6: Fix style and markup nits * Identify NETHACKDIR and HACKDIR as environment variables. * ...and set them italics, not roman. * Set default playground directory name in italics, not roman. * Set command names in italics. * Refer to command operands as such, not as "options". * Use man page cross reference on first occurrence of "nethack" when referring to the command executable as opposed to the overall game. Because some text is commented out (`ig`nored), meaning the "first" occurrence appears twice (what's lexically present vs. what's formatted) do this twice as future-proofing. * Set file names in italics, not roman. Set variable parts of file names in roman. * Refer to "single-user systems" instead of "microcomputers"; the latter is becoming antiquated terminology. * Favor present tense over future. * Tighten wording. * Spell "save files" consistently as two words. --- doc/recover.6 | 70 ++++++++++++++++++++++++++++++++------------------- 1 file changed, 44 insertions(+), 26 deletions(-) diff --git a/doc/recover.6 b/doc/recover.6 index 922981d00..a1c8ad68b 100644 --- a/doc/recover.6 +++ b/doc/recover.6 @@ -27,32 +27,38 @@ recover \- recover a NetHack game interrupted by disaster .I base \&.\|.\|. .SH DESCRIPTION -Occasionally, a NetHack game will be interrupted by disaster -when the game or the system crashes. -Prior to NetHack v3.1, these games were lost because various information +Occasionally, a NetHack game is interrupted by disaster +when the program or the system crashes. +Prior to NetHack v3.1, these games were lost because information like the player's inventory was kept only in memory. Now, all pertinent information can be written out to disk, so such games can be recovered at the point of the last level change. .PP -The -.I base -options tell +.I Base +operands tell .I recover which files to process. -Each base option specifies recovery of a separate game. +Each +.I base +specifies recovery of a separate game. .PP The .B \-d option, which must be the first argument if it appears, -supplies a directory which is the NetHack playground. -It overrides the value from NETHACKDIR, HACKDIR, or the directory +supplies the directory housing the NetHack playground. +It overrides the value of the environment variables +.I NETHACKDIR +and +.IR HACKDIR , +and the directory specified by the game administrator during compilation -(usually /usr/games/lib/nethackdir). +(usually +.IR /usr/games/lib/nethackdir ). .ig .PP \*^?ALLDOCS For recovery to be possible, -.I nethack +.IR nethack (6) must have been compiled with the INSURANCE option, and the run-time option .I checkpoint must also have been on. @@ -71,26 +77,34 @@ was created without support for recovery. \*^. \*^. .. -NetHack normally writes out files for levels as the player leaves them, +.IR nethack (6) +normally writes out files for levels as the player leaves them, so they will be ready for return visits. -When checkpointing, NetHack also writes out the level entered and +When checkpointing, it also writes out the level entered and the current game state on every level change. -This naturally slows level changes down somewhat. +This procedure slows level changes. .PP -The level file names are of the form base.nn, where nn is an internal -bookkeeping number for the level. -The file base.0 is used for game identity, locking, and, when checkpointing, +The level file names are of the form +.IR base. nn, where +.I nn +is an internal bookkeeping number for the level. +The file +.I base.0 +is used for game identity, locking, and, when checkpointing, for the game state. Various OSes use different strategies for constructing the base name. -Microcomputers use the character name, possibly truncated and modified +Single-user systems use the character name, +possibly truncated and modified to be a legal filename on that system. Multi-user systems use the (modified) character name prefixed by a user number to avoid conflicts, -or "xlock" if the number of concurrent players is being limited. +or +.I xlock +if the number of concurrent players is being limited. It may be necessary to look in the playground to find the correct base name of the interrupted game. .I recover -will transform these level files into a save file of the same name as +transforms these level files into a save file of the same name that .I nethack would have used. .PP @@ -105,13 +119,16 @@ through setuid or setgid is tantamount to leaving the playground world-writable, with respect to both cheating and messing up other players. For a single-user system, this of course does not change anything, -so some of the microcomputer ports install +so some of these ports install .I recover by default. .PP For a multi-user system, -the game administrator may want to arrange for all .0 files in the -playground to be fed to recover when the host machine boots, +the game administrator may want to arrange for all +.I .0 +files in the playground to be fed to +.I recover +when the host machine boots, and handle game crashes individually. If the user population is sufficiently trustworthy, .I recover @@ -126,7 +143,7 @@ Like .I nethack itself, .I recover -will overwrite existing savefiles of the same name. +will overwrite existing save files of the same name. Savefiles created by .I recover are uncompressed; @@ -143,8 +160,9 @@ If multiple machines share a playground, this would be impossible to determine. .PP .I recover -should be taught to use the nethack playground locking mechanism to -avoid conflicts. +should be taught to use the +.I nethack +playground locking mechanism to avoid conflicts. .SH COPYRIGHT .\" All troffs and nroffs support `\(co` except Plan 9 nroff, but Plan 9 .\" offers no test for special character availability, and its feature From 74a3dc9d71cf5335f3bcc3c1536a6fba17a67886 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Wed, 6 May 2026 03:56:42 -0500 Subject: [PATCH 36/39] doc/makedefs.6: Fix style and markup nits * Set cross reference to "nethack" man page in lowercase, because that's the name under which it's installed, and POSIX systems are case-sensitive. * Refer to the "nethack" command using a man page cross reference only on its first occurrence. * Favor bullets over hyphens for itemized list. * Drop explicit indentation amounts from lists. The man(7) package's default suffices on all of Solaris 10, DWB 3.3, Plan 9, Heirloom Doctools, and GNU *roffs, and on mandoc(1). * Use tagged paragraphs to set synopses of syntax productions used in the documented file format. * Drop inset (indentation) of itemized and tagged lists; the bullets make the structure clear, and (with the foregoing change) this way the paragraphs align. --- doc/makedefs.6 | 41 ++++++++++++++++++++++------------------- 1 file changed, 22 insertions(+), 19 deletions(-) diff --git a/doc/makedefs.6 b/doc/makedefs.6 index 9c33ef6e3..81193649e 100644 --- a/doc/makedefs.6 +++ b/doc/makedefs.6 @@ -42,7 +42,7 @@ makedefs \- NetHack miscellaneous build-time functions .SH DESCRIPTION .B Makedefs is a build-time tool used for a variety of -.BR NetHack (6) +.IR nethack (6) source file creation and modification tasks. For historical reasons, .B makedefs @@ -210,58 +210,61 @@ The command (and certain other commands) filter their input, on a line-by-line basis, according to control lines embedded in the input and on information gleaned from the -.IR NetHack (6) +.I nethack configuration. This allows certain changes such as embedding platform-specific documentation into the master documentation files. .P Rules: -.RS -.IP - 4 +.IP \(bu The default conditional state is printing enabled. -.IP - 4 +.IP \(bu Any line .I NOT starting with a caret (\*^) is either suppressed or passed through unchanged depending on the current conditional state. -.IP - 4 +.IP \(bu Any line starting with a caret is a control line; as in C, zero or more spaces may be embedded in the line almost anywhere (except immediately after the caret); however the caret must be in column 1. -.IP - 4 +.IP \(bu Conditionals may be nested. -.IP - 4 +.IP \(bu .I Makedefs will exit with an error code if any errors are detected; processing will continue (if it can) to allow as many errors as possible to be detected. -.IP - 4 +.IP \(bu Unknown identifiers are treated as both TRUE and as an error. Note that .BR \-\-undef " or " #undef in the -.IR NetHack (6) +.I nethack configuration are different from unknown. -.RE .P Control lines: -.RS -.IP \*^\*^ 4 +.TP +.B +\*^\*^ a line starting with a (single) literal caret -.IP \*^# +.TP +.B \*^# a comment -.IP \*^?\fIID +.TP +.B \*^?\fIID if the .I ID is defined set the conditional state to TRUE -.IP \*^!\fIID +.TP +.B \*^!\fIID if the .I ID is not defined set the conditional state to TRUE -.IP \*^: +.TP +.B \*^: else; invert the conditional state -.IP \*^. +.TP +.B \*^. end the most recent conditional -.RE .\".SH EXAMPLES .SH AUTHOR The NetHack Development Team From 1d13d2ce623260ade844ce6d05093b7fdc9eb8fd Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Wed, 6 May 2026 04:30:52 -0500 Subject: [PATCH 37/39] doc/nethack.6: Fix markup nits Drop unnecessary quotation marks from macro call arguments. --- doc/nethack.6 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/nethack.6 b/doc/nethack.6 index 554b8dd16..f19de5012 100644 --- a/doc/nethack.6 +++ b/doc/nethack.6 @@ -187,7 +187,7 @@ while .\" on the Macintosh or BeOS, it is \*(lqNetHack Defaults\*(rq, and on VMS|OpenVMS it is nethack.ini in your home directory. The default configuration file may be overridden via the -.BI \-\-nethackrc: "rc-file" +.BI \-\-nethackrc: rc-file command line option or by setting NETHACKOPTIONS in your environment to a string consisting of an @ character followed by the path and filename. .PP @@ -337,7 +337,7 @@ The option will use .I rc-file instead of the default run-time configuration file -.RI "(typically " \*~/.nethackrc ")" +.RI "(typically " \*~/.nethackrc ) and the .B \-\-no\-nethackrc option can be used to skip any run-time configuration file. From 76303faeaba39e7d99ef4f7b5c53dd2ad3da71f3 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Wed, 6 May 2026 04:34:13 -0500 Subject: [PATCH 38/39] doc/*.6: Use typographer's double quotes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ...where available. groff_man_style(7): Notes ... • When and how should I use quotation marks? ... groff, Heirloom Doctools troff, neatroff, and mandoc support all of the special characters \[oq], \[cq], \[lq], \[rq], \[aq], and \[dq] described in subsection “Portability” above. DWB, Plan 9, and Solaris troffs do not. Interpolating the strings \*(lq and \*(rq portably yields directional double quotation marks, if available, in all these formatters (though neatroff does not supply a man macro package), but they cannot reliably be used in macro arguments. --- doc/makedefs.6 | 4 ++-- doc/nethack.6 | 12 ++++++------ 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/makedefs.6 b/doc/makedefs.6 index 81193649e..af3919c39 100644 --- a/doc/makedefs.6 +++ b/doc/makedefs.6 @@ -192,7 +192,7 @@ is known and defined, otherwise exit shell false (1). .BI \-\-grep\-define " symbol" Force the value of .I symbol -to be "defined." +to be \*(lqdefined.\*(rq .I Symbol must already be known to .BR makedefs . @@ -200,7 +200,7 @@ must already be known to .BI \-\-grep\-undef " symbol" Force the definition of .I symbol -to be "undefined." +to be \*(lqundefined.\*(rq .I Symbol must already be known to .BR makedefs . diff --git a/doc/nethack.6 b/doc/nethack.6 index f19de5012..081bd6c39 100644 --- a/doc/nethack.6 +++ b/doc/nethack.6 @@ -194,7 +194,7 @@ to a string consisting of an @ character followed by the path and filename. The .B \-u .I player-name -option supplies the answer to the question "Who are you?". +option supplies the answer to the question \*(lqWho are you?\*(rq. It overrides any name from the options or configuration file, USER, LOGNAME, or getlogin(), which will otherwise be tried in order. If none of these provides a useful name, the player will be asked for one. @@ -208,19 +208,19 @@ suffix can be used to specify the profession, race, alignment and/or gender of the character. The full syntax of a .I player-name -including a suffix is "name\-ppp\-rrr\-aaa\-ggg". -"ppp" are at least the first three letters +including a suffix is \*(lqname\-ppp\-rrr\-aaa\-ggg\*(rq. +\*(lqppp\*(rq are at least the first three letters of the profession (this can also be specified using a separate .B \-p .I profession option). -"rrr" are at least the first three letters of the character's +\*(lqrrr\*(rq are at least the first three letters of the character's race (this can also be specified using a separate .B \-r .I race option). -"aaa" are at least the first three letters of the character's -alignment, and "ggg" are at least the first three letters of the +\*(lqaaa\*(rq are at least the first three letters of the character's +alignment, and \*(lqggg\*(rq are at least the first three letters of the character's gender. Any of the parts of the suffix may be left out. .PP From 48ae0eb46e31f83743452580428e9314904784f4 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Wed, 6 May 2026 04:19:40 -0500 Subject: [PATCH 39/39] doc/nethack.6: Rewrite initial description I noticed that the "Dungeons & Dragons" trademark acknowledgement should be using the _registered_ trade mark sign instead of the more general one, as the mark's enjoyed registered status (in the U.S.) since 1978. https://tmsearch.uspto.gov/search/search-results/73123558 It occurred to me that updating the game description for a 2026 audience might be an improvement on one that assumes the reader is familiar with D&D, with Teletype machines ("TTYs"), and with the Rogue game, which NetHack arguably eclipsed in notoriety decades ago. So I rewrote it, and dropped the references to D&D. Besides, as of commit c99da87c700, NetHack is incompatible with "Strength Table I." in the AD&D Player's Handbook (TSR 2010, p. 9), so any grognard who lifts would snatch NetHack's D&D membership card away anyway. ;-) --- doc/nethack.6 | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/doc/nethack.6 b/doc/nethack.6 index 081bd6c39..7decd3bf5 100644 --- a/doc/nethack.6 +++ b/doc/nethack.6 @@ -123,10 +123,17 @@ can be any of the following. .hw nethackdir .SH DESCRIPTION .I NetHack -is a display oriented Dungeons & Dragons(tm) - like game. -The standard tty display and command structure resemble rogue. +is a fantasy-themed game of surival, +exploration, +and combat +set in the Mazes of Menace, +an elaborate underground complex. .PP -Other, more graphical display options exist for most platforms. +Traditionally, +the game's interface uses a Unix terminal connection, +depicting the interface on a grid of character cells +and responding to keyboard-entered commands. +Other interface options exist for most platforms. .PP To get started you really only need to know two commands. The command @@ -658,5 +665,3 @@ Probably infinite. This file is Copyright \*(co \*(Na, \*(Nd for version \*(Nb:\*(Nr. NetHack may be freely redistributed. See license for details. -.PP -Dungeons & Dragons is a Trademark of Wizards of the Coast, Inc.