doc/nethack.6: Be more portable to old roffs (1/4)

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.
This commit is contained in:
G. Branden Robinson
2026-05-06 04:53:12 -05:00
parent fb611b60bc
commit 14430511bd
+14 -3
View File
@@ -216,7 +216,7 @@ below).
On other systems, the default may be different, possibly NetHack.cnf.
On MS-DOS, the name is defaults.nh in NetHack's directory (folder),
while
.\" on the Macintosh or BeOS, it is \(lqNetHack Defaults\(rq, and
.\" on the Macintosh or BeOS, it is \*(lqNetHack Defaults\*(rq, and
on VMS|OpenVMS it is nethack.ini in your home directory.
The default configuration file may be overridden via the
.BI \-\-nethackrc: "rc-file"
@@ -322,11 +322,22 @@ option will start the game in a special non-scoring discovery mode
(also known as explore mode).
.B \-D
will start the game in debug mode (also known as wizard mode) after
changing the character name to \(lqwizard\(rq, if the player is allowed.
changing the character name to \*(lqwizard\*(rq,
if the player is allowed.
Otherwise it will switch to
.BR \-X .
Control of who is allowed to use debug mode is done via the
.RI "\(lq" WIZARDS= "\(rq line in NetHack's " sysconf " file."
.\" The `lq` and `rq` strings are not reliable in macro calls, because
.\" some nroffs interpolate `"` for them, messing up macro argument
.\" delimitation. Use an (initially) uglier method than `RI`.
.\".RI "\*(lq" WIZARDS= "\*(rq line in NetHack's " sysconf " file."
\*(lq\c
.I WIZARDS=\c
\*(rq
line in
NetHack's
.I sysconf
file.
.PP
The
.BR \-d " or " \-\-directory