From f886f71d491dd7205b9b064368001a34bf8fa9f0 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Tue, 10 Sep 2024 04:02:45 -0500 Subject: [PATCH 01/11] doc/Guidebook.mn: Fix table markup nits. Comment escape sequences inside table entries can wreak havoc. Use dummy character instead to visually indicate the deliberate trailing spaces. Move the comment explaining why they're there closer to what they document. It's okay to have _whole-line_ comments in table data, because they are on control lines (lines that start with a dot '.'). Also use the dummy character to indicate deliberately empty table cells. --- doc/Guidebook.mn | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/Guidebook.mn b/doc/Guidebook.mn index d55d3c6c4..c9182e31c 100644 --- a/doc/Guidebook.mn +++ b/doc/Guidebook.mn @@ -288,15 +288,15 @@ Dlvl:1 $:993 HP:9(12) Pw:3(3) AC:10 Exp:1/19 T:752 Hungry Conf .if t .sp 0.5v Figure 1 . -.\" Figure 2 uses trailing spaces to force the same width as Figure 1. .BR 1 .ft CR .TS center box tab(~); L. -Player the Rambler St:12 Dx:7 Co:18 In:11 Wi:9 Ch:15 \" -Neutral $:993 HP:9(12) Pw:3(3) AC:10 Exp:1/19 Hungry \" -Dlvl:1 T:752 Conf \" +.\" Use trailing spaces to force the same width as Figure 1. +Player the Rambler St:12 Dx:7 Co:18 In:11 Wi:9 Ch:15 \& +Neutral $:993 HP:9(12) Pw:3(3) AC:10 Exp:1/19 Hungry \& +Dlvl:1 T:752 Conf \& .TE .ft R .ce 1 @@ -2828,11 +2828,11 @@ center; a n. Dragon scale mail 1 Plate mail, Crystal plate mail 3 -Bronze plate mail, Splint mail, \" +Bronze plate mail, Splint mail, \& \ \ \ Banded mail, Dwarvish mithril-coat 4 Chain mail, Elven mithril-coat 5 Scale mail, Orcish chain mail 6 -Ring mail, Studded leather armor, \" +Ring mail, Studded leather armor, \& \ \ \ Dragon scales 7 Leather armor, Orcish ring mail 8 Leather jacket 9 From 2bbefa2e4d1dd7d26491de352833b411fd35f3d7 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Tue, 10 Sep 2024 04:16:08 -0500 Subject: [PATCH 02/11] doc/Guidebook.mn: Simplify table format. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The 'A' ("alphabetic") and 'N' ("numeric") column classifiers were being used to little benefit. Since 'A' was applying to every row of the table, none was more indented than any other, except via the inclusion of unadjustable, unbreakable space escape sequences `\ `, which work just as well with column classifier 'L' ("left"). In fact, even they are unnecessary; regular spaces will do. tbl(1): Ordinarily, a table entry is typeset rigidly. It is not filled, broken, hyphenated, adjusted, or populated with additional inter‐ sentence space. ...so furthermore convert the escaped spaces to regular ones. Similarly, 'N' applies several rules to manage alignment of decimal points. This table doesn't need them. Right-alignment of integers is just as easily achieved with the 'R' ("right") column classifier. --- doc/Guidebook.mn | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/Guidebook.mn b/doc/Guidebook.mn index c9182e31c..d25720602 100644 --- a/doc/Guidebook.mn +++ b/doc/Guidebook.mn @@ -2825,15 +2825,15 @@ Here is a list of the armor class values provided by suits of armor: .\" line and leading spaces to indent their second line. .TS center; -a n. +l r. Dragon scale mail 1 Plate mail, Crystal plate mail 3 Bronze plate mail, Splint mail, \& -\ \ \ Banded mail, Dwarvish mithril-coat 4 + Banded mail, Dwarvish mithril-coat 4 Chain mail, Elven mithril-coat 5 Scale mail, Orcish chain mail 6 Ring mail, Studded leather armor, \& -\ \ \ Dragon scales 7 + Dragon scales 7 Leather armor, Orcish ring mail 8 Leather jacket 9 none 10 From 5d005a3a958e4fa1ce6778b741c035dfd102b1fb Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Tue, 10 Sep 2024 04:51:20 -0500 Subject: [PATCH 03/11] doc/Guidebook.mn: Refactor achievement table. Use tbl(1); this sort of layout is what it's designed for. Use text blocks to enable lengthy achievement descriptions to break across lines. --- doc/Guidebook.mn | 112 +++++++++++++++-------------------------------- 1 file changed, 36 insertions(+), 76 deletions(-) diff --git a/doc/Guidebook.mn b/doc/Guidebook.mn index d25720602..f29a55d5f 100644 --- a/doc/Guidebook.mn +++ b/doc/Guidebook.mn @@ -3390,87 +3390,47 @@ it because they fall into the same category of \(lqbragging rights\(rq and to limit the number of questions during disclosure. Listed here roughly in order of difficulty and not necessarily in the order in which you might accomplish them. -.\" Vary the output between Guidebook.txt and Guidebook.{ps,pdf} -.ie n \{\ -.\" fixed-width font: default key width is fine; -.\" display longest entries (below) across two lines for Guidebook.txt -.PS "Mines'\~End" -.\} -.el \{\ -.\" proportional font: force blank line, indent, and use slightly wider key .sp -.in +5n -.PS "Mines'\~End\~" -.\} -.fi -.PL "" -Attained rank title . -.PL Shop -Entered a shop. -.PL Temple -Entered a temple. -.PL Mines -Entered the Gnomish Mines. -.PL Town -Entered Mine Town. -.PL Oracle -Consulted the Oracle of Delphi. -.PL Novel -Read a passage from a Discworld Novel. -.PL Sokoban -Entered Sokoban. -.PL "Big\~Room" -Entered the Big Room. -.ie n \{\ -.PL "Soko-Prize" -Explored to the top of Sokoban -.br -and found a special item there. -.PL "Mines'\~End" -Explored to the bottom of the Gnomish Mines -.br -and found a special item there. -.\} -.el \{\ -.PL "Soko-Prize" +.TS +center; +L Lz2 L. +\fIRank\fP \- Attained rank title \fIRank\fP. +Shop \- Entered a shop. +Temple \- Entered a temple. +Mines \- Entered the Gnomish Mines. +Town \- Entered Mine Town. +Oracle \- Consulted the Oracle of Delphi. +Novel \- Read a passage from a Discworld Novel. +Sokoban \- Entered Sokoban. +Big Room \- Entered the Big Room. +Soko-Prize \- T{ Explored to the top of Sokoban and found a special item there. -.PL "Mines'\~End" -Explored to the bottom of the Gnomish Mines and found a special item there. -.\} -.fi -.PL Medusa -Defeated Medusa. -.PL Tune +T} +Mines' End \- T{ +Explored to the bottom of the Gnomish Mines and found a special item +there. +T} +Medusa \- Defeated Medusa. +Tune \- T{ Discovered the tune that can be used to open and close the drawbridge on the Castle level. -.PL Bell -Acquired the Bell of Opening. -.PL Gehennom -Entered Gehennom. -.PL Candle -Acquired the Candelabrum of Invocation. -.PL Book -Acquired the Book of the Dead. -.PL Invocation +T} +Bell \- Acquired the Bell of Opening. +Gehennom \- Entered Gehennom. +Candle \- Acquired the Candelabrum of Invocation. +Book \- Acquired the Book of the Dead. +Invocation \- T{ Gained access to the bottommost level of Gehennom. -.PL Amulet -Acquired the fabled Amulet of Yendor. -.PL Endgame -Reached the Elemental Planes. -.PL Astral -Reached the Astral Plane level. -.PL Blind -Blind from birth. -.PL Deaf -Deaf from birth. -.PL Nudist -Never wore any armor. -.PL Pauper -Started out with no possessions. -.PL Ascended -Delivered the Amulet to its final destination. -.PE -.if t .in -5n \" undo proportional-width font-specific indentation +T} +Amulet \- Acquired the fabled Amulet of Yendor. +Endgame \- Reached the Elemental Planes. +Astral \- Reached the Astral Plane level. +Blind \- Blind from birth. +Deaf \- Deaf from birth. +Nudist \- Never wore any armor. +Pauper \- Started out with no possessions. +Ascended \- Delivered the Amulet to its final destination. +.TE .sp .lp "Notes: " .pg From 67d97d1e039bde0924e1c0ede94cde62c1c0bd7f Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Tue, 10 Sep 2024 05:03:55 -0500 Subject: [PATCH 04/11] doc/Guidebook.mn: Fix typo in escape sequence. \F and \f do different things. Fixes: $ (cd doc && cat Guidebook.mn | tbl tmac.n - | groff > Guidebook.ps) troff::3468: error: no font family named 'I' exists --- doc/Guidebook.mn | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/Guidebook.mn b/doc/Guidebook.mn index f29a55d5f..319f31502 100644 --- a/doc/Guidebook.mn +++ b/doc/Guidebook.mn @@ -3463,7 +3463,8 @@ instrument played closely enough\(embut not too close!\(emto the Castle level's drawbridge or can be given to you via prayer boon. .pg -\fIBlind\fP, \fIDeaf\fP, \fINudist\fP, and \FIPauper\fP are also conducts, and they can only be +\fIBlind\fP, \fIDeaf\fP, \fINudist\fP, +and \fIPauper\fP are also conducts, and they can only be enabled by setting the correspondingly named option in NETHACKOPTIONS or run-time configuration file prior to game start. In the case of \fIBlind\fP and \fIDeaf\fP, the option also enforces the conduct. From 1dd11dc9160e1ac2bd61257b2d63b51bb28d6b2f Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Tue, 10 Sep 2024 05:08:08 -0500 Subject: [PATCH 05/11] doc/tmac.n: Fix erroneous lines. I'm mindful of the license here, but suspect that these lines crept in after Matt Bishop's time. Text lines in a macro package can be insidious because they cause formatting operations to start even in the absence of an input document. The forthcoming groff 1.24 has a new diagnostic to help catch these situations. The groff Texinfo manual says: A '\"' comment on a line by itself is treated as a blank line, because after eliminating the comment, that is all that remains. Test \" comment Test => Test => => Test To compensate, it is common to combine the empty request with the comment escape sequence as '.\"', causing the input line to be ignored. Fixes: $ (cd doc && groff -t -M . -mn -mnh Guidebook.mn > /dev/null) troffrc:./tmac.n:1: text line in startup file troffrc:./tmac.n:764: text line in startup file --- doc/tmac.n | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/tmac.n b/doc/tmac.n index 270a78a06..640601bf0 100644 --- a/doc/tmac.n +++ b/doc/tmac.n @@ -1,4 +1,4 @@ -\" @(#)$Id: tmac.n,v 1.4 2002/01/19 13:41:15 michael.allison Exp $ +.\" @(#)$Id: tmac.n,v 1.4 2002/01/19 13:41:15 michael.allison Exp $ .\" The News macro package .\" .\" This is the macro package that is used to format news documents. It @@ -761,4 +761,3 @@ .\" couple of miscellaneous requests .bd S 3 3 \" embolden special font chars if B .hy 2 \" don't hyphenate last lines - From ade0c02b20933618f650ba3e1f4ac83d9e911fde Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Tue, 10 Sep 2024 05:16:30 -0500 Subject: [PATCH 06/11] Make it easier for the Guidebook to find macros. * doc/Guidebook.mn: Make the Guidebook buildable from the top of the source tree, not just inside the "doc" directory. Try to load its "nh" macro package from the current working directory and from "doc". * doc/tmac.nh: Allocate new register `nH` to the purpose of detecting multiple loads, and skip file content if detected. This is the 1970s nroff form of an "#include guard". groff's "an-ext.tmac" uses the same technique for portability. Also I removed a tab character. Per the groff Texinfo manual: One possibly irritating idiosyncrasy is that tabs should not be used to vertically align comments in the source document. Tab characters are not treated as separators between a request name and its first argument, nor between arguments. Here's an example of how one groff macro package works around the problem. $ sed -n '402,406p' contrib/mm/m.tmac .ds LetCN CONFIDENTIAL\" Confidential default .ds LetSA To Whom It May Concern:\" Salutation default .ds LetAT ATTENTION:\" Attention string .ds LetSJ SUBJECT:\" Subject string .ds LetRN In reference to:\" Reference string --- doc/Guidebook.mn | 3 ++- doc/tmac.nh | 4 ++++ 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/doc/Guidebook.mn b/doc/Guidebook.mn index 319f31502..67ad5dbb6 100644 --- a/doc/Guidebook.mn +++ b/doc/Guidebook.mn @@ -31,7 +31,8 @@ .lt 70n .\} . -.so tmac.nh \" extra macros which aren't in tmac.n +.so tmac.nh \" extra macros which aren't in tmac.n +.if !\n(nH .so doc/tmac.nh . .\" building Guidebook.txt doesn't have CR font available; groff 1.23 issues .\" a warning each time any font can't be loaded; earlier versions silently diff --git a/doc/tmac.nh b/doc/tmac.nh index 1a7ae1231..d4dd18a11 100644 --- a/doc/tmac.nh +++ b/doc/tmac.nh @@ -8,6 +8,10 @@ .\" cluttered as their number increased. It now uses the '.so' directive .\" to include this file. (tmac.n is passed to 'roff on the command line.) . +.\" Protect against being sourced twice. +.nr nH +1 +.if \n(nH>1 .nx +. .\" labeled paragraph start .\" .PS word .\" set the width for the label column From 6167de1a5467441d1dc2ae01ef936a6a2742b053 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Tue, 10 Sep 2024 05:31:07 -0500 Subject: [PATCH 07/11] doc/Guidebook.mn: Use different technique. ...to get a block paragraph from the `n` package, instead of manipulating indentation directly, which can lead to grief. --- doc/Guidebook.mn | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/Guidebook.mn b/doc/Guidebook.mn index 67ad5dbb6..e800218a0 100644 --- a/doc/Guidebook.mn +++ b/doc/Guidebook.mn @@ -430,13 +430,15 @@ Movement modifiers: .lp "" Other conditions and modifiers exist, but there isn't enough room to display them with the other status fields. +.\" Don't give the next paragraph a first-line indent. +.nr @p \n(pi \" Save mn's paragraph indentation. +.nr pi 0 .pg -.in -5n .\" outdent this paragraph The \f(CR#attributes\fP command (default key \f(CR\(haX\fP) will show all current status information in unabbreviated format. It also shows other information which might be included on the status lines if those had more room. -.in 0 .\" reset indentation +.nr pi \n(@p \" Restore mn's paragraph indentation. .hn 2 The message line (top) .pg From 37434a5fa90b06a78567ee0e9fc545c04c40786c Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Tue, 10 Sep 2024 05:33:02 -0500 Subject: [PATCH 08/11] doc/Guidebook.mn: Fix bad comment syntax. These lines were passing a spurious "." argument to the `BR` macro defined in "doc/tmac.nh". --- doc/Guidebook.mn | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/Guidebook.mn b/doc/Guidebook.mn index e800218a0..dfb24fc03 100644 --- a/doc/Guidebook.mn +++ b/doc/Guidebook.mn @@ -5494,7 +5494,7 @@ SOUND=MESG hide "^You miss the " "swing.wav" 75 .ft .ei .ed -.BR 0 .\" without this, the next section seems too close to this one +.BR 0 \" without this, the next section seems too close to this one .hn 2 Configuring Status Hilites .pg @@ -5678,7 +5678,7 @@ OPTION=hilite_status: condition/lev+fly/red&inverse .ft .ei .ed -.BR 0 .\" without this, the next section seems too close to this one +.BR 0 \" without this, the next section seems too close to this one .hn 2 Modifying NetHack Symbols .pg From cbff67b0d631d4d131e896b8250781aac7de0939 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Tue, 10 Sep 2024 05:34:36 -0500 Subject: [PATCH 09/11] doc/tmac.nh: Fix mistaken syntax. The forthcoming groff 1.24 has a new diagnostic that detects ill-formed numeric expressions. It has found one here. I'm not positive what was intended here, but it may have been an attempt to force interpretation of the first macro argument as a number. This change employs a more idiomatic (but still old-school) technique. The salient fact is that, in *roff, you can't affix a scaling unit after a closing parenthesis (or another scaling unit). In GNU troff the `\B` escape sequence, an extension, permits the testing of putative numeric expressions for validity. troff:./doc/Guidebook.mn:268: warning: expected end of line or an auto-increment argument in register definition request; got character 'v' See . --- doc/tmac.nh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/tmac.nh b/doc/tmac.nh index d4dd18a11..074e6df59 100644 --- a/doc/tmac.nh +++ b/doc/tmac.nh @@ -122,7 +122,7 @@ .\" $1 - repeat count for amount of padding (optional; default is 1) .de BR .ie \\.$==0 .nr bR 1v -.el .nr bR (\\$1-0)v +.el .nr bR 0\\$1v \0 .sp \\n(bR .br From e318d21afc8190836c511a2a6e8d86a9603bcdcb Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Tue, 10 Sep 2024 05:40:47 -0500 Subject: [PATCH 10/11] doc/tmac.nh (ED): Don't dedent below zero. This quietens several warnings from GNU troff in the "range" category. troff: backtrace: './doc/tmac.nh':92: macro 'ED' troff: backtrace: file './doc/Guidebook.mn':5950 troff:./doc/Guidebook.mn:5950: warning: treating -120u indentation as zero Unfortunately, the similar `ed` macro in Bishop's "mn" package contributes several more. But with this change (and its forerunners in this series), the NetHack Guidebook is now warning-free with "-wall -Wtab -Wrange" ("mn" has problems with tab characters too), even with the increasingly fastidious syntactical checks of the forthcoming groff 1.24 release. --- doc/tmac.nh | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/tmac.nh b/doc/tmac.nh index 074e6df59..fce6f786d 100644 --- a/doc/tmac.nh +++ b/doc/tmac.nh @@ -89,7 +89,8 @@ . if \\n(id=0 \{\ . di \" end diversion . fi \" resume filling -. in -\\n(piu \" dedent +. ie \\n(.i<\\n(pi .in 0 +. el .in -\\n(piu \" dedent . ev \" pop environment . ne \\n(dnu \" be sure you have room . nf \" don't reprocess display From d116052796d3810f8815650e9898e10d945de606 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Tue, 10 Sep 2024 06:04:14 -0500 Subject: [PATCH 11/11] Build *roff documents with groff warnings enabled. ...some of them, at any rate. We shut off (1) warnings provoked by Matt Bishop's "mn" macro package, and (2) warnings spuriously emitted by groff 1.23 and previous when "-wall" (or "-ww") is specified. Also update explanatory comments. --- sys/unix/Makefile.doc | 2 ++ sys/unix/hints/include/misc.370 | 10 +++++++++- 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/sys/unix/Makefile.doc b/sys/unix/Makefile.doc index cef4f936e..92473995b 100644 --- a/sys/unix/Makefile.doc +++ b/sys/unix/Makefile.doc @@ -19,6 +19,8 @@ GUIDEBOOK = Guidebook # regular ASCII file # Some versions of col need -x to keep them from converting spaces to tabs; # some versions of col don't do the conversion by default and don't # recognize the option. Sigh. +# +# col is unnecessary, but harmless, with groff. See grotty(1). COLCMD = col -bx #COLCMD = col -b diff --git a/sys/unix/hints/include/misc.370 b/sys/unix/hints/include/misc.370 index 7f8c40439..6608cf45a 100644 --- a/sys/unix/hints/include/misc.370 +++ b/sys/unix/hints/include/misc.370 @@ -76,6 +76,13 @@ NROFFISGROFF := $(shell echo `nroff --version | grep "GNU groff version"`) ifneq "$(NROFFISGROFF)" "" # get the version of groff and flag if it is gt or eq to 1.23 GROFFGE123 := $(shell expr `echo $(NROFFISGROFF) | cut -f2 -d.` \>= 23) +# or less than 1.24 +GROFFLT124 := $(shell expr `echo $(NROFFISGROFF) | cut -f2 -d.` \< 24) +# -Wtab -Wrange are for the sake of tmac.n. +NROFF_FLAGS := -wall -Wtab -Wrange +ifneq "$(GROFFLT124)" "" +NROFF_FLAGS += -Wel -Wscale +endif endif # NROFFISGROFF ifneq "$(NROFFISGROFF)" "" # It's groff @@ -83,7 +90,8 @@ ifneq "$(NROFFISGROFF)" "" # It's groff MAN2TXTPRE += -Tascii ifneq "$(GROFFGE123)" "" # It's groff 1.23 or greater #$(info GROFFGE123=$(GROFFGE123)) -# add the groff 1.23 specific plain text flag -P +# nroff in groff 1.23 supports the -P option to pass arguments to the +# output driver. -cbou are flags to grotty(1). MAN2TXTPRE += -P -cbou MAN2TXTPOST= else