man/default.cfg.template: Improve example format
Use `EX` and `EE` macros to turn off filling, obviating the need for
repeated `br` requests.
I must admit at the outset that these macros are extensions to the
original man(7) dialect of Seventh Edition Unix in 1979.
groff_man_style(7):
.EX
.EE Begin and end example. After .EX, filling is disabled and a
constant‐width (monospaced) font is selected. Calling .EE
enables filling and restores the previous font.
Example regions are useful for formatting code, shell
sessions, and text file contents. An example region is not
a “literal mode” of any sort: special character escape
sequences must still be used to produce correct glyphs for
', -, \, ^, `, and ~ (see subsection “Portability” below).
Sentence endings are still detected and additional inter‐
sentence space applied. If the amount of additional inter‐
sentence spacing is altered, the rendering of, for instance,
regular expressions using . or ? followed by multiple spaces
can change. Use the dummy character escape sequence \&
before the spaces.
.EX and .EE are extensions introduced in Ninth Edition Unix.
Documenter’s Workbench, Heirloom Doctools, and Plan 9
troffs, and mandoc (since 1.12.2) also support them.
Solaris troff does not.
"Solaris troff" means the AT&T System V-descended troff program that
Solaris shipped up through version 10 of that operating system. Solaris
11 adopted groff as its troff, and therefore handles these extensions
fine. (Its groff is pretty old, but not older than these macros, which
date to 2009 [or 1986 in Bell Labs Research Unix].)
man/*.template: Parallelize "AUTHORS" sections
Break input lines at sentence endings.
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.
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/*.template: Parallelize "AUTHORS" sections
Break input lines at sentence endings.
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.
man/*.template: Parallelize "AUTHORS" sections
Break input lines at sentence endings.
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.
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/server.template: Improve option formatting
1. Favor man(7) font selection macros over roff(7) font selection
escape sequences.
2. Break input lines at sentence endings.
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.
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.
man/setup.template: Improve sentence separation
Break input lines at sentence endings.
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.
man/strife.template: Improve formatting and markup
1. Use quotation to cite other sections of the same man page.
2. Break input lines at sentence endings.
3. Set "Doom" in titlecase, not full capitals. On the Chocolate master
branch, before my changes, the former is preponderant in
documentation.
$ git grep -wc DOOM man
man/INSTALL.template:9 (all of which are `#if` or `#ifdef`)
man/strife.template:2
$ git grep -wc Doom man
man/INSTALL.template:16
man/Makefile.am:2
man/bash-completion/doom.template.in:1
man/docgen:4
man/doom.template:5
man/heretic.template:1
man/hexen.template:1
man/iwad_paths.man:5
man/server.template:1
man/setup.template:1
man/strife.template:5
man/wikipages:1
4. Use man(7) font style macros, not asterisks, for typographical
emphasis. Man pages and Markdown employ different conventions.
5. Set the C standard library symbol "NULL" in italics, not roman.
groff_man_style(7):
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”.
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.