...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.
* 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.
* 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.
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.
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
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,
<https://pubs.opengroup.org/onlinepubs/9799919799.2024edition/utilities/compress.html>.
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.
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.
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.
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.
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.
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
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
* 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
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
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
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).
...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]
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")
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
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.
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.
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 '@'
The existing detection logic was not working on any groff since at least
1.22.3 (November 2014), as could be seen by uncommenting the "$(info
...)" line. The regex used to match "nroff --version" output was
insufficiently flexible.
Fixes:
$ (cd doc && rm -f Guidebook && PATH=$HOME/groff-1.22.3/usr/bin:/bin make Guidebook) | grep NROFF
NROFFISGROFF=
$ (cd doc && rm -f Guidebook && PATH=$HOME/groff-1.22.4/usr/bin:/bin make Guidebook) | grep NROFF
NROFFISGROFF=
$ (cd doc && rm -f Guidebook && PATH=$HOME/groff-1.23.0/usr/bin:/bin make Guidebook) | grep NROFF
NROFFISGROFF=
$ (cd doc && rm -f Guidebook && PATH=$HOME/groff-HEAD/usr/bin:/bin make Guidebook) | grep NROFF
NROFFISGROFF=
Use a different approach in Make to recording groff detection. Use
"grep -c" (which is POSIX-conforming) to count the number of matches so
that we can use the contents of the Make macro `NROFFISGROFF` as a sort
of Boolean, which reads more idiomatically (in my opinion).
Further, instead of trying to lexically analyze a matched line in the
output of "nroff --version" and parse components of a version number out
of it, use GNU troff's built-in facility for extracting its minor
version number by storing the output of a tiny *roff document that
reports that datum (and nothing else).
Ignore warnings in category "scale" in any version of groff, because the
`tmac.n` macro package provokes them.
Clarify comments.
groff 1.24 is in its second release candidate of this writing and
features a noteworthy revision to its syntax.
---snip---
NEWS:
* If your roff(7) documents follow any of the requests ... `so`, ...
with a comment after their file name argument, and did not place that
comment immediately after the file name, you are likely to get a
diagnostic message resembling the following.
warning: cannot open macro file 'e.tmac ': No such file or directory
Or, less likely, the formatter will open the wrong file, one with
spaces at the end of its name. That is because these requests are
now able to process file names containing space characters. (This
change also makes the request syntax consistent with that of `ds`,
`as`, and others.) A quick fix is to place the comment escape
sequence as early as possible. For example, we would change:
.mso e.tmac \" Load Eric Allman's package.
to:
.mso e.tmac\" Load Eric Allman's package.
to tell the formatter to load the "e.tmac" file rather than
"e.tmac ". See the items below for further details.
---end snip---
Work around this change while maintaining with older groff and other
*roff formatters.
1. Stop using space to separate comments from the argument to `so`.
2. Temporarily define a `So` macro to wrap the `soquiet` request (for
groff 1.23 and later) or `so` request (for everything else).
3. Abort formatting with an error diagnostic if the `nh` macro package
the Guidebook requires cannot be located.
Fixes:
$ (cd doc && rm -f Guidebook && make Guidebook)
troff:<standard input>:34: error: cannot open 'tmac.nh ': No such file or directory
troff:<standard input>:35: error: cannot open 'doc/tmac.nh': No such file or directory
Fixes warning in category "syntax" from the forthcoming groff 1.24.
troff:<standard input>:790: warning: ignoring a space on input line after output line continuation escape sequence
[94 more occurrences]
Starting a text line with leading spaces causes a break when filling.
Usually this is not what is intended.
Fixes:
$ nroff -ww -z -rCHECKSTYLE=4 -man doc/*.[67]
an.tmac:doc/makedefs.6:102: style: 1 leading space(s) on input line
Content:
* Document that the command has a default file list.
* Demote "COMMANDS" section to "Operations" subsection. The former term
is (1) too easily confused with Unix commands and (2) not a widely
used section heading in man pages.
Style:
* Italicize command names.
* Italicize file names.
* Use idiomatic man page cross references.
* Present operation and option letters in alphabetical order.
* Render option descriptions as full sentences.
* Set bug list as a bulleted list.
Markup:
* Break input lines at sentence boundaries.
* Favor use of man(7) font selection and alternation macros over roff(7)
font selection escape sequences.
* Drop numerous extraneous paragraphing macro calls. See subsection
"Horizontal and vertical spacing" of groff_man(7).
* Replace use of *roff requests to break lines and vertically space with
calls of paragraphing macros, which is what they're for. Two things
the page author didn't know: `.sp 1` already implies a break, so the
preceding `.br` was redundant. `.sp 1` without an argument already
means to vertically space by 1 vee; that is, the "1" argument was
superfluous. It was a bad idea anyway because the default
inter-paragraph spacing in man(7) is not one vee, but 0.4v--this
matters when typesetting. It has also been the case since 1979.
* Use `RS` and `RE` macros instead of a literal tab to achieve a
relative inset. Use of the macros is more idiomatic.
* Use `EX` and `EE` to attempt to set the examples in a monospaced font
family. These are extensions and are silently ignored by formatters
that don't support them.
groff_man(7):
.EX
.EE Begin and end example. After .EX, filling is disabled and a
constant‐width (monospaced) font is selected. Calling .EE
enables filling and restores the previous font.
.EX and .EE are extensions introduced in Ninth Edition Unix.
Documenter’s Workbench, Heirloom Doctools, and Plan 9
troffs, and mandoc (since 1.12.2) also support them.
Solaris troff does not. See subsection “Use of extensions”
in groff_man_style(7).
* Kill off useless trailing space on input line.
Follow Unix idioms and the guidelines presented in groff_man_style(7).[1]
* Present multiple synopses since the command has multiple operation
modes accessed via mutually inexpressible command letters. See the
POSIX standard for copious precedent.
* Stop implying that file name arguments are accepted alongside the `I`
option; see line 236 of util/dlb_main.c.
* Stop spacing around synopsis punctuation where unnecessary.
* Set metasyntactic variables (parameters) in italics, not roman or
bold.
* Spell ellipsis idiomatically for pleasant typesetting.
* Use `\c` escape sequence to force adjacency of tar-like option letters
to the mandatory operation letter.
* Use singular, not plural, for repeatable argument. The ellipsis does
the grammatical work of pluralization for us.
[1] Full disclosure: I wrote much of (the current form of) that man page.
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.
...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.
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.
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 <https://savannah.gnu.org/bugs/?64240>.
* 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
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
\F and \f do different things.
Fixes:
$ (cd doc && cat Guidebook.mn | tbl tmac.n - | groff > Guidebook.ps)
troff:<standard input>:3468: error: no font family named 'I' exists
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.
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.
One can observe the following problems when generating or viewing plain
text versions of the Guidebook. (There are three; "Guidebook" and
"Guidebook.txt" are identical, and are paginated; "Guidebook.dat" is not
paginated.)
1. The line "(Edited and expanded for NetHack 3.7.0 by Mike Stephenson
and others)" is overset.
2. So are Figures 1 and 2, by one character cell, when rendered with
groff 1.23.0 because of the way it handles boxed tables and those
with vertical rules at table boundaries.
https://git.savannah.gnu.org/cgit/groff.git/commit/?id=8f066786ea3cb5e1dbade1149e7d50ae978da202
3. When viewing the Guidebook in an 80-column terminal, the left and
right margins are asymmetric; you get 10 columns on the left but
only 5 on the right.
So:
* doc/Guidebook.mn: In nroff mode, set page offset to 5n and increase
line and title line lengths by 5n to 70n.
Now, the margins are symmetric, there's ample room for the figures, and
the expansion credit fits.
(One diagnostic remains when formatting with groff 1.23.0.
troff:tmac.n:762: error: cannot load font 'S' for emboldening
This is a groff bug and will be fixed in the next release. The
diagnostic is spurious and can be ignored.
See <https://savannah.gnu.org/bugs/?64866>.)
Explain behavior of GNU tbl when setting boxed tables on terminals.
Drop reference to bug fixed in groff 1.23.0
<https://savannah.gnu.org/bugs/?49390>.
There's not much to say about other tbls except that they handle boxed
tables _terribly_ on terminals.
$ cat ./hello-table.roff
.TS
box;
L.
hello
.TE
$ ./bin/tbl ./hello-table.roff|./bin/nroff|cat -s # Heirloom Doctools
_______
hello
_______
|
| |
DWB tbl behaves the same way. I expect all System V Unix-descended
tbls/nroffs do the same.
This is my attempt to revise the figure by working _with_ tbl(1)
and nroff(1)/troff(1) features instead of fighting them or enduring
suffering and significant maintenance challenges.
* Stop using mn(7) display macros; the other two figures didn't and they
don't appear to be buying much.
* Use `tr` character translation feature to temporarily remap characters
for clarity of input. It's convenient to input ordinary characters
here since the table's contents are (mostly) character-cell art.
Remap `-` to minus sign and `@` to the "reverse solidus" special
character. (`\` is the default *roff escape character. It can be
changed, but attempting that seems hopeless inside a tbl(1) table.)
Revert the translations after the table. (There's nothing special
about `@`; you could choose any other character that isn't otherwise
needed in the table.)
* Use `box` region option as with Figures 1 and 2. Perhaps this wasn't
done because those are meant to depict a terminal window, but Figure 2
depicts only part of one, so its top border is a fib.
* Use `expand` region option to obtain roughly the same spread-out
effect that the table was laboriously using empty columns and the `e`
column modifier for.
* Consequently, reduce the column count to 2; both have real content.
* Annotate both keycap diagrams--in part for clarity, but also to make
it more obvious that the columns will balance in width.
These changes don't require GNU extensions to *roff or tbl except,
arguably, the \(rs special character. But support for that special
character identifier is easily added to any device-independent troff;
see §23.2 of CSTR #54 (Kernighan 1992 revision) or groff_font(5). Or I
can prepare a patch--just ask me. But given that no one seems to have
complained about the disaster that AT&T tbl/nroff must have been making
of Figures 1 and 2 for decades, I'm guessing this isn't a practical
concern. Any if it _is_ a problem, `\e` can be used instead of `\(rs`.
(I didn't use it because what is wanted is the backslash glyph
specifically [to mirror `/`], not "the escape character". But given the
constraints imposed by use of tbl(1), it's an academic point.)
On my system, the figure captions in Guidebook.ps were getting set in
Courier roman. This was clearly unintentional. Here's why it didn't
work.
1. Figures 1 and 2 selected the previous font, but only after a table
had been set. But tbl(1) does not preserve identity of the previous
font. I investigated, and none of GNU, Heirloom Doctools, nor
Documenter's Workbench tbl implementations preserve it. So the user
can't rely on it. See
<https://savannah.gnu.org/bugs/index.php?64862>.
2. Figure 3 attempted to select the roman font (typically Times), but
did so in a table cell that was empty of text. It therefore did not
have any visible effect.
* doc/Guidebook.mn: Explicitly select font `R` after setting tables. On
typesetters, put half a vee of space between the table's box border
and the figure caption.
doc/Gbk-1pg-sfx.mn is already using one half of a sound technique: set
the page length to a very large value, guaranteed to overshoot the
vertical space required by the document's text. The other half is to,
at the end of the document, set the page length to the current vertical
position, so that it ends immediately.
https://www.gnu.org/software/groff/manual/groff.html.node/Manipulating-Spacing.html
String definitions were being used with a pointless leading double
quote. This syntax is used only to define strings containing leading
space characters. (You might also use it defensively if you're defining
one string whose contents start with the interpolation of another, and
the latter might interpolate leading space--but that is not the case
here.)
Remove unnecessary leading quotes from string definitions.
* doc/Guidebook.mn: Do it. Also annotate empty strings with comment.
* sys/unix/hints/include/gbdates-post.370: Don't put them back.
https://www.gnu.org/software/groff/manual/groff.html.node/Strings.html
Stop trying to deduce whether the document is being formatted for a
typesetter (a device that can use proportional fonts) or a terminal (a
device that generally can't) by asking the formatter to measure
formatted texts. Instead, use the built-in `n` and `t` conditions that
nroff and troff have supported for this purpose since 1976 at the
latest. All known troff implementations support these.
https://www.gnu.org/software/groff/manual/groff.html.node/Operators-in-Conditionals.html
These *roff control lines were ill-formed. `.fi` is a request to turn
on filling, not a closing bracket for an `if` request (*roff is not a
Bourne shell).
https://www.gnu.org/software/groff/manual/groff.html.node/Conditional-Blocks.html
Further, *roff generally does not accept more than one request per
input line. Exceptions to this rule are the control structuring
requests (`if`, `ie`, `el`, and in GNU troff, `while`, `do` and `nop`).
But here, only one (`do`-nested) request is governed by the `if` anyway.
* doc/Guidebook.mn: Remove workaround, in favor of...
* doc/tmac.n: ...setting automatic hyphenation mode appropriate to
hyphenation systems used by AT&T-descended troffs on the one hand
("suftab") and groff (TeX hyphenation patterns) on the other.
modify results of pull request #977 to target tmac.nh instead.
Guidebook update to trigger the process following pull request 977.
G. Branden Robinson