commit e2afcc351fbd5a3f9bbfb0780c99489dd09faae8
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Sep 14 02:23:47 2024 -0500
Commit: Fabian Greffrath <fabian@greffrath.com>
CommitDate: Wed Jul 2 08:24:12 2025 +0200
man/environ.man: Adjust formatting
1. Favor man(7) font selection macros over roff(7) font selection
escape sequences.
2. Use the groff man(7) extension `TQ` to stack multiple paragraph tags
rather than comma-separating them (which can get tedious if style
changes are required within tags).
3. Use quotation instead of boldface to cite other sections of the same
man page.
4. Use quotation _and_ boldface when presenting value literals for
environment variables. The use of both is for clarity when font
styling is lost (as when quoting man pages in emails--or Git commit
messages), and to indicate unambiguously to the reader portions of
the page that they might wish to copy and paste to a command line or
shell script.
groff_man_style(7):
As long as at most two styles are needed in a word, style
macros like .B and .BI usually result in more readable
roff source than \f escape sequences do.
...
.TQ Set an additional tag for a paragraph tagged with .TP,
planting a one‐line input trap as with .TP.
.TQ is a GNU extension supported by Heirloom Doctools troff
and mandoc (since 1.14.5) but not by Documenter’s Workbench,
Plan 9, or Solaris troffs. ...
...
Be frugal with italics for emphasis, and particularly with bold.
Article titles and brief runs of literal text, such as references
to individual characters or short strings, including section and
subsection headings of man pages, are suitable objects for
quotation; see the \(lq, \(rq, \(oq, and \(cq escape sequences in
subsection “Portability” below.
...
\(lq
\(rq Left and right double quotation marks. Use these for paired
directional double quotes, “like this”.
---
man/environ.man | 39 ++++++++++++++++++++++++++-------------
1 file changed, 26 insertions(+), 13 deletions(-)
diff --git a/man/environ.man b/man/environ.man
index f401202d..414f5037 100644
--- a/man/environ.man
+++ b/man/environ.man
@@ -1,21 +1,34 @@
.TP
-\fBDOOMWADDIR\fR, \fBDOOMWADPATH\fR
-See the section, \fBIWAD SEARCH PATHS\fR above.
+.I DOOMWADDIR
+.TQ
+.I DOOMWADPATH
+See section \(lqIWAD SEARCH PATHS\(rq above.
.TP
-\fBPCSOUND_DRIVER\fR
+.I PCSOUND_DRIVER
When running in PC speaker sound effect mode, this environment variable
-specifies a PC speaker driver to use for sound effect playback. Valid
-options are "Linux" for the Linux console mode driver, "BSD" for the
-NetBSD/OpenBSD PC speaker driver, and "SDL" for SDL-based emulated PC speaker
-playback (using the digital output).
+specifies a PC speaker driver to use for sound effect playback.
+Valid options are
+.RB \(lq Linux \(rq
+for the Linux console mode driver,
+.RB \(lq BSD \(rq
+for the NetBSD/OpenBSD PC speaker driver,
+and
+.RB \(lq SDL \(rq
+for SDL-based emulated PC speaker playback (using the digital output).
.TP
-\fBOPL_DRIVER\fR
+.I OPL_DRIVER
When using OPL MIDI playback, this environment variable specifies an
-OPL backend driver to use. Valid options are "SDL" for an SDL-based
-software emulated OPL chip, "Linux" for the Linux hardware OPL driver,
-and "OpenBSD" for the OpenBSD/NetBSD hardware OPL driver.
+OPL backend driver to use.
+Valid options are
+.RB \(lq SDL \(rq
+for an SDL-based software emulated OPL chip,
+.RB \(lq Linux \(rq
+for the Linux hardware OPL driver,
+and
+.RB \(lq OpenBSD \(rq
+for the OpenBSD/NetBSD hardware OPL driver.
.IP
Generally speaking, a real hardware OPL chip sounds better than software
-emulation; however, modern machines do not often include one. If
-present, it may still require extra work to set up and elevated
+emulation; however, modern machines do not often include one.
+If present, it may still require extra work to set up and elevated
security privileges to access.