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
This commit is contained in:
G. Branden Robinson
2026-05-06 04:53:12 -05:00
parent e4476516cd
commit 44c8405000
+21 -47
View File
@@ -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