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