* 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.
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 \&.
...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.
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.htmlhttps://lists.gnu.org/archive/html/groff/2021-08/msg00040.htmlhttps://github.com/NetHack/NetHack/pull/977#issuecomment-1424996578
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
...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]
Portions of these man pages seem at one time to have been dynamically
selected, but the mechanism for doing so appears to be commented out in
the source tree: see "NHGREP" in sys/{unix,vms}/Makefile.doc.
Wrap them in *roff "ignore blocks" to keep their noise from cluttering
the man page actually seen by the users.
To update, run "perl DEVEL/nhgitset.pl"
Fixes:
- "nhcommit -a" has been fixed
- NHDT was hardwired in places
- no longer complain about a missing dat directory outside of the
NetHack source tree
- make update of gitinfo atomic
- Replace some hardwired directory separators with OS-dependent constructs
Backwards Incompatibilities:
- NH_DATESUB's DATE() is now Date() to match the other variables
- MSYS2 requires an additional Perl package - the MSYS2 docs have
been updated
New Help System:
- git nhhelp
This command mirrors "git help" for nh* commands.
- See git nhhelp nhsub for general help on substitution variables
New Substitution Variables:
-Brev()
An aBREViation of $PREFIX-Branch$:$PREFIX-Revision$ - this
may help get line length under control in file headers.
-Assert(TYPE=VALUE)
If TYPE does not match VALUE, do not substitute on this line.
TYPE P checks VALUE against nethack.substprefix
-Project(arg)
Returns nethack.projectname if there is no arg and an uppercase
version if arg is uc.
Other New Features:
- Add nethack.projectname
- Documentation updates - see "git nhhelp nhsub"
- On checkout or merge of a branch, check for nhgitset version updates
and provide an optional message to the user.
- Move NH_DATESUB substitutions here from cron job to keep dates in sync
- PREFIX-* keywords now available in NH_DATESUB templates
- Support use of nhgitset.pl from a different repo; note that update
checks will be dependent on keeping the original source repo up-to-date
and in the same location.
When I updated recover.6 last week, I was under the mis-impression that
the INSURANCE compile-time option had been made unconditional. It has
not, and after undoing that, there was no substantive change, so put it
back to how it was at release.
Update the man pages and generated text copies for nethack and recover.
I haven't looked at the other four (dlb, makedefs, dgn_comp, lev_comp).
recover's page referred to INSURANCE as being conditional, which is no
longer the case. nethack's page was missing a bunch of files to be
found in the playground and also a couple of environment variables.
I haven't read through the text of the page to try to see whether other
updates are warranted.
The generated text is wider than the previous copy (one or two space
right margin instead of 5 or so). I just used 'make nethack.txt' and
'make recover.txt' so don't know why that changed. (The older, wider
margin looks better, so if anyone knows how to fix this, please do.
And there's got to be a better way to force a blank line inside a
table than my <space><tab> hack.)
G. Branden Robinson