nethack-gwaa-kiwi/nethack
1
0
Fork 0
Code Pull Requests Activity

doc/nethack.6: Revise "FILES" section

Browse Source 
* 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
This commit is contained in:
G. Branden Robinson
2026-05-06 04:39:57 -05:00
parent a562b80019
commit 6c9e8cb1c9
1 changed files with 164 additions and 100 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/nethack.6
+164 -100
View File
@@ -16,6 +16,22 @@
.ie \n(.g .hy 12 .ie \n(.g .hy 12
.el .hy 14 .el .hy 14
.ds Na Robert Patrick Rankin .ds Na Robert Patrick Rankin
.\" Define string to exercise groff's hyphenless break point feature.
.ie \n(.g .ds : \:
.el .ds : \" empty
.\" Define local versions of groff's "an-ext.tmac" macros if needed.
.ds %% \" empty
.if \n(.g .ig %%
.\" Add supplementary paragraph tag on its own line after TP.
.de TQ
. br
. ns
. \" Do not quote the argument to `TP`; the user might specify
. \" their own quotes for multi-word tags or to exercise AT&T troff
. \" quoting rules.
. TP \\$1\"
..
.%%
.SH NAME .SH NAME
nethack \- Exploring The Mazes of Menace nethack \- Exploring The Mazes of Menace
.SH SYNOPSIS .SH SYNOPSIS
@@ -319,7 +335,8 @@ option, which must be the first argument if it appears,
supplies a directory which is to serve as the playground. supplies a directory which is to serve as the playground.
It overrides the value from NETHACKDIR, HACKDIR, It overrides the value from NETHACKDIR, HACKDIR,
or the directory specified by the game administrator during compilation or the directory specified by the game administrator during compilation
(usually /usr/games/lib/nethackdir). (usually
.IR /usr/\*:games/\*:lib/\*:nethackdir ).
This option is usually only useful to the game administrator. This option is usually only useful to the game administrator.
The playground must contain several auxiliary files such as help files, The playground must contain several auxiliary files such as help files,
the list of top scorers, and a subdirectory the list of top scorers, and a subdirectory
@@ -429,117 +446,164 @@ development by the Usenet.
Andries Brouwer has made this request for the Andries Brouwer has made this request for the
distinction, as he may eventually release a new version of his own. distinction, as he may eventually release a new version of his own.
.SH FILES .SH FILES
.PP
Run-time configuration options were discussed above and use a platform Run-time configuration options were discussed above and use a platform
specific name for a file in a platform specific location. specific name for a file in a platform specific location.
For Unix, the For Unix, the
name is '.nethackrc' in the user's home directory. name is
.I .nethackrc
in the user's home directory.
.PP .PP
All other files are in the playground directory, All other files are in the playground directory,
normally /usr/games/lib/nethackdir. normally
If DLB was defined during the compile, the data files and special levels .IR /usr/\*:games/\*:lib/\*:nethackdir .
will be inside a larger file, normally nhdat, instead of being separate If DLB was defined during the compile,
files. the data files and special levels will be inside a larger file,
.PP normally
.DT .IR nhdat ,
.\" continuation lines begin with <backslash><space><tab> instead of being separate files.
.ta \w'cmdhelp, opthelp, wizhelp\ \ \ 'u .TP
nethack The program itself. .I nethack
.br The program itself.
Guidebook\ |\ Guidebook.txt NetHack's user manual. .TP
.br .I Guidebook
data, oracles, rumors Data files used by NetHack. .TQ
.br .I Guidebook.txt
bogusmon Another data file. NetHack's user manual.
.br .TP
engrave, epitaph, tribute Still more data files. .I data
.br .TQ
symbols Data file holding sets of specifications .I oracles
.br .TQ
\ for how to display monsters, objects, and .I rumors
.br Data files used by NetHack.
\ map features. .TP
.br .I bogusmon
options Data file containing a description of the Another data file.
.br .TP
\ build-time option settings. .I engrave
.br .TQ
help,\ hh,\ cmdhelp Help data files. .I epitaph
('cmdhelp' is obsolete.) .TQ
.br .I tribute
opthelp,\ optmenu,\ wizhelp More help data files. Still more data files.
.br .TP
keyhelp,\ usagehlp Even more help data files. .I symbols
.br Data file holding sets of specifications
*.lua Predefined special levels, dungeon control for how to display monsters, objects, and
.br map features.
\ for special levels, quest texts. .TP
.br .I options
history A short history of NetHack. Data file containing a description of the
.br build-time option settings.
license Rules governing redistribution. .TP
.br .I help
record The list of top scorers. .TQ
.br .I hh
logfile An extended list of games played .TQ
.br .I cmdhelp
\ (optional). Help data files.
.br .RI ( cmdhelp
xlogfile A more detailed version of 'logfile' is obsolete.)
.br .TP
\ (also optional). .I opthelp
.br .TQ
paniclog Record of exceptional conditions .I optmenu
.br .TQ
\ discovered during program execution. .I wizhelp
.br More help data files.
xlock.nn Description of dungeon level 'nn' of .TP
.br .I keyhelp
\ active game 'x' if there's a limit on the .TQ
.br .I usagehlp
\ number of simultaneously active games. Even more help data files.
.br .TP
UUcccccc.nn Alternate form for dungeon level 'nn' .RI * .lua
.br Predefined special levels, dungeon control
\ of active game by user 'UU' playing for special levels, quest texts.
.br .TP
\ character named 'cccccc' when there's no .I history
.br A short history of NetHack.
\ limit on number of active games. .TP
.br .I license
perm Lock file for xlock.0 or UUcccccc.0. Rules governing redistribution.
.br .TP
bonD0.nn Descriptions of the ghost and belongings .I record
.br The list of top scorers.
\ of a deceased adventurer who met his or .TP
.br .I logfile
\ her demise on level 'nn'. An extended list of games played
(optional).
.TP
.I xlogfile
A more detailed version of
.I logfile
(also optional).
.TP
.I paniclog
Record of exceptional conditions
discovered during program execution.
.TP
.RI x lock. nn
Description of dungeon level
.I nn
of active game
.I x
if there's a limit on the
number of simultaneously active games.
.TP
.RI UUcccccc . nn
Alternate form for dungeon level
.I nn
of active game by user
.I UU
playing character named
.I cccccc
when there's no
limit on number of active games.
.TP
.I perm
Lock file for
.RI x lock.0
or
.RI UUcccccc .0 .
.TP
.IR bonD0. nn
Descriptions of the ghost and belongings
of a deceased adventurer who met his or
her demise on level
.IR nn .
A subsequent A subsequent
.br character might encounter this old level.
\ character might encounter this old level. .TP
.br .I save/
.\"following line should contain <backslash><space><tab> Subdirectory containing saved games.
\ .TP
.br .I sysconf
save/ A subdirectory containing saved games. System-wide options.
.br
.\"following line should contain <backslash><space><tab>
\
.br
sysconf System-wide options.
Required if Required if
.br program is built with 'SYSCF' option
\ program is built with 'SYSCF' option enabled, ignored if not.
.br
\ enabled, ignored if not.
.PP .PP
The location of 'sysconf' is specified at build time and can't be changed The location of
except by updating source file "config.h" and rebuilding the program. .I sysconf
is specified at build time and can't be changed
except by updating source file
.\" We do the following in an ugly and non-idiomatic way to work around
.\" a DWB 3.3 nroff bug.
.\" troff: if-else overflow.; doc/nethack.6:623
.\" stack: }S }S }S }S }S }S }S }S }S }S }S }S }S }S }S }S RI
.\" Even at that, DWB insists on setting the period in roman.
"\c
.I config.h\c
"
and rebuilding the program.
.PP .PP
NetHack's Guidebook might not be present if whoever packaged or installed NetHack's Guidebook might not be present if whoever packaged or installed
the program distribution neglected to include it. the program distribution neglected to include it.
.PP .PP
In a perfect world, 'paniclog' would remain empty. In a perfect world,
.I paniclog
would remain empty.
.SH ENVIRONMENT .SH ENVIRONMENT
.DT .DT
.ta \w'NETHACKDIR or HACKDIR\ \ \ 'u .ta \w'NETHACKDIR or HACKDIR\ \ \ 'u