commit 83e3015e40c687af1215f8cdca9bee770c131337
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Sep 14 02:43:37 2024 -0500
Commit: Fabian Greffrath <fabian@greffrath.com>
CommitDate: Wed Jul 2 08:24:12 2025 +0200
man/iwad_paths.man: Adjust formatting
1. Break input lines at sentence endings.
2. Set file names in italics, not bold, as suggested in
groff_man_style(7) and for consistency with "default.cfg.template"
and "extra.cfg.template".
3. Use `\~\c` pair of escape sequences to continue a paragraph tag with
a word space over multiple macro calls.
4. Set "Current working directory" paragraph tag in roman since it is
neither a literal (so would be bold) nor a parameter (so would be
italic).
5. Set environment variables names in italics, not bold.
6. Use `\%` escape sequence to protect lengthy literals from
hyphenation.
7. Use typographer's quotation marks (`\(lq` and `\(rq` escape
sequences) to quote multi-word literals, in addition to setting them
in bold. These special characters degrade gracefully to the `"`
character on output devices (like terminals limited to the US-ASCII
for ISO Latin-1 charcter encodings) that don't support them.
roff(7):
A roff formatter attempts to detect boundaries between sentences,
and supplies additional inter‐sentence space between them. It
flags certain characters (normally “!”, “?”, and “.”) as
potentially ending a sentence. When the formatter encounters one
of these end‐of‐sentence characters at the end of an input line, or
one of them is followed by two (unescaped) spaces on the same input
line, it appends an inter‐word space followed by an inter‐sentence
space in the output. ...
Input conventions
Since troff fills text automatically, it is common practice in the
roff language to avoid visual composition of text in input files:
the esthetic appeal of the formatted output is what matters.
Therefore, roff input should be arranged such that it is easy for
authors and maintainers to compose and develop the document,
understand the syntax of roff requests, macro calls, and
preprocessor languages used, and predict the behavior of the
formatter. Several traditions have accrued in service of these
goals.
• Follow sentence endings in the input with newlines to ease their
recognition. It is frequently convenient to end text lines
after colons and semicolons as well, as these typically precede
independent clauses. Consider doing so after commas; they often
occur in lists that become easy to scan when itemized by line,
or constitute supplements to the sentence that are added,
deleted, or updated to clarify it. Parenthetical and quoted
phrases are also good candidates for placement on text lines by
themselves.
groff_man_style(7):
Use italics for file and path names, for environment
variables, for C data types, for enumeration or preprocessor
constants in C, for variant (user‐replaceable) portions of
syntax synopses, for the first occurrence (only) of a
technical concept being introduced, for names of journals
and of literary works longer than an article, and anywhere a
parameter requiring replacement by the user is encountered.
...
...
\% Control hyphenation. The location of this escape
sequence within a word marks a hyphenation point,
supplementing groff’s automatic hyphenation patterns. At
the beginning of a word, it suppresses any hyphenation
breaks within except those specified with \%.
...
\(lq
\(rq Left and right double quotation marks. Use these for paired
directional double quotes, “like this”.
---
man/iwad_paths.man | 76 +++++++++++++++++++++++++++++++++++-------------------
1 file changed, 50 insertions(+), 26 deletions(-)
diff --git a/man/iwad_paths.man b/man/iwad_paths.man
index a41aba41..5b426809 100644
--- a/man/iwad_paths.man
+++ b/man/iwad_paths.man
@@ -1,49 +1,73 @@
-To play, an IWAD file is needed. This is a large file containing all of the
-levels, graphics, sound effects, music and other material that make up the
-game. IWAD files are named according to the game; the standard names are:
+To play, an IWAD file is needed.
+This is a large file containing all of the levels, graphics,
+sound effects, music and other material that make up the game.
+IWAD files are named according to the game; the standard names are:
.TP
-\fBdoom.wad, doom1.wad, doom2.wad, tnt.wad, plutonia.wad\fR
+.IR doom.wad ,\~\c
+.IR doom1.wad ,\~\c
+.IR doom2.wad ,\~\c
+.IR tnt.wad ,\~\c
+.I plutonia.wad
Doom, Doom II, Final Doom
.TP
-\fBheretic.wad, heretic1.wad, hexen.wad, strife1.wad\fR
+.IR heretic.wad ,\~\c
+.IR hexen.wad ,\~\c
+.I strife.wad
Heretic, Hexen and Strife (commercial Doom engine games).
.TP
-\fBhacx.wad, chex.wad\fR
+.IR hacx.wad ,\~\c
+.I chex.wad
Hacx and Chex Quest - more obscure games based on the Doom engine.
.TP
-\fBfreedm.wad, freedoom1.wad, freedoom2.wad\fR
+.IR freedm.wad ,\~\c
+.IR freedoom1.wad ,\~\c
+.I freedoom2.wad
The Freedoom open content IWAD files.
.LP
The following directory paths are searched in order to find an IWAD:
.TP
-\fBCurrent working directory\fR
+Current working directory
Any IWAD files found in the current working directory will be used in
preference to IWADs found in any other directories.
.TP
-\fBDOOMWADDIR\fR
-This environment variable can be set to contain a path to a single directory
-in which to look for IWAD files. This environment variable is supported by
-most Doom source ports.
+.I DOOMWADDIR
+This environment variable can be set to contain a path to a single
+directory in which to look for IWAD files.
+This environment variable is supported by most Doom source ports.
.TP
-\fBDOOMWADPATH\fR
+.I DOOMWADPATH
This environment variable, if set, can contain a colon-separated list of
directories in which to look for IWAD files, or alternatively full paths to
specific IWAD files.
.TP
-\fB$HOME/.local/share/games/doom\fR
-Writeable directory in the user's home directory. The path can be overridden
-using the \fBXDG_DATA_HOME\fR environment variable (see the XDG Base Directory
-Specification).
+.I $HOME/.local/share/games/doom
+Writeable directory in the user's home directory.
+The path can be overridden using the
+.I \%XDG_DATA_HOME
+environment variable (see the XDG Base Directory Specification).
.TP
-\fB/usr/local/share/doom, /usr/local/share/games/doom, /usr/share/doom,
-/usr/share/games/doom\fR
-System-wide locations that can be accessed by all users. The path
-\fB/usr/share/games/doom\fR is a standard path that is supported by most
-Doom source ports. These paths can be overridden using the \fBXDG_DATA_DIRS\fR
+.I /usr/local/share/doom
+.TQ
+.I /usr/local/share/games/doom
+.TQ
+.I /usr/share/doom
+.TQ
+.I /usr/share/games/doom
+System-wide locations that can be accessed by all users.
+The path
+.I /usr/share/games/doom
+is a standard path that is supported by most Doom source ports.
+These paths can be overridden using the
+.I \%XDG_DATA_DIRS
environment variable (see the XDG Base Directory Specification).
.LP
-The above can be overridden on a one-time basis by using the \fB\-iwad\fR
-command line parameter to provide the path to an IWAD file to use. This
+The above can be overridden on a one-time basis by using the
+.B \-iwad
+command line parameter to provide the path to an IWAD file to use.This
parameter can also be used to specify the name of a particular IWAD to use
-from one of the above paths. For example, '\fB-iwad doom.wad\fR' will search
-the above paths for the file \fBdoom.wad\fR to use.
+from one of the above paths.
+For example,
+.RB \(lq "\-iwad doom.wad" \(rq
+will search the above paths for the file
+.I doom.wad
+to use.