roff(7): Fix content, style, and markup nits.

Content:
* Present concepts of font families, styles, and what makes special
  fonts special.
* Reform terminology: migrate to "page description language" from
  "device-independent output format" and "intermediate output".
* Elaborate on preprocessors' frequent use of their own languages.
* Drop redundant sentence about "tmac files".
* Add cross reference to groff_tmac(5) page when discussing availability
  of macro packages.

Style:
* Put vertical space before list of (relatively) well-known
  preprocessors that groff doesn't provide.
* Stop hyphenating adverbially enhanced attributive phrase.
* Tighten wording.
* Generally recast, particularly material I hadn't already edited.

Markup:
* Use `\|` more aggressively to improve kerning (avoid glyph crowding)
  when changing styles.
* Ensure that the example won't break in a confusing place.
* Bump copyright range.

1 files changed, 114 insertions, 124 deletions

diff --git a/man/roff.7.man b/man/roff.7.man
index d53b743c7..1a4c52f48 100644
--- a/man/roff.7.man
+++ b/man/roff.7.man
@@ -13,7 +13,7 @@ typesetting
 .\" Legal Terms
 .\" ====================================================================
 .\"
-.\" Copyright (C) 2000-2022 Free Software Foundation, Inc.
+.\" Copyright (C) 2000-2023 Free Software Foundation, Inc.
 .\"
 .\" This file is part of groff, the GNU roff type-setting system.
 .\"
@@ -319,7 +319,9 @@ The spaces are output at the beginning of the next line without being
 .I adjusted
 (see below).
 .
-Again, macro packages may provide other methods of producing indented paragraphs.
+Again,
+macro packages may provide other methods of producing indented
+paragraphs.
 .
 Trailing spaces on
 .I text lines
@@ -689,7 +691,7 @@ Some read-only predefined registers interpolate text.
 are identified either by a name or by a mounting position
 (a non-negative number).
 .
-Four font styles are available on all devices.
+Four styles are available on all devices.
 .
 .B R
 is \[lq]roman\[rq]:
@@ -711,11 +713,14 @@ underlined instead on terminal devices.
 is \f[BI]bold-italic\f[]\/, \" indulging a bit of man(7) evil here
 combining both of the foregoing style variations.
 .
-Typesetter devices typically offer one or more
+Typesetting devices group these four styles into
+.I families
+of text fonts;
+they also typically offer one or more
 .I special
-fonts as well;
-they provide glyphs that are not available in the multiple styles of
-text fonts.
+fonts that provide unstyled glyphs;
+see
+.MR groff_char @MAN7EXT@ .
 .
 .
 .P
@@ -799,7 +804,7 @@ A
 is a condition on the input or output,
 tested automatically by the formatter,
 that is associated with a macro,
-causing it to be called when that condition is fulfilled.
+calling it when that condition is fulfilled.
 .
 .
 .P
@@ -1059,7 +1064,7 @@ and paper terminals such as the IBM 2471
 (based on the Selectric line of typewriters)
 and the Teletype Corporation Model 37.
 .
-Proportionally-spaced type was unavailable.
+Proportionally spaced type was unavailable.
 .
 .
 .\" ====================================================================
@@ -1327,7 +1332,7 @@ to generalize its design.
 .
 To implement this revised architecture,
 he developed the font and device description file formats and the
-device-independent output format that remain in use today.
+page description language that remain in use today.
 .
 He described these novelties in the article
 \[lq]A Typesetter-independent TROFF\[rq],
@@ -1460,24 +1465,12 @@ a permissively licensed new implementation.
 .\" ====================================================================
 .SH "Using \f[I]roff\f[]"
 .\" ====================================================================
-.\" XXX GBR leaves off here.
 .
-Many people use
+When you read a man page,
+often a
 .I roff
-frequently without knowing it.
+is the program rendering it.
 .
-When you read a system manual page
-(man page),
-it is often a
-.I roff
-working in the background to render it.
-.
-But using a
-.I roff
-explicitly isn't difficult.
-.
-.
-.P
 Some
 .I roff
 implementations provide wrapper programs that make it easy to use the
@@ -1508,28 +1501,22 @@ arguments should be used to process it.
 .SS "The \f[I]roff\f[] pipeline"
 .\" ====================================================================
 .
-Each
-.I roff
-system consists of preprocessors,
-one or more
+A typical
 .I roff
-formatter programs,
-and a set of output drivers
-(or \[lq]device postprocessors\[rq]).
+document is prepared by running one or more processors in series,
+followed by a a formatter program and then an output driver
+(or \[lq]device postprocessor\[rq]).
 .
-This arrangement is designed to take advantage of a landmark Unix
-innovation in inter-process communication:
-the pipe.
-.
-That is,
-a series of programs termed a \[lq]pipeline\[rq] is called together
-.\" in an indeterminate order :P
-where the output of each program in the sequence is taken as the input
-for the next program,
-without (necessarily) passing through temporary files on a disk.
+Commonly,
+these programs are structured into a pipeline;
+that is,
+each is run in sequence such that the output of one is
+taken as the input
+to the next,
+without passing through secondary storage.
 .
 (On non-Unix systems,
-pipelines may have to be simulated.)
+pipelines may have to be simulated with temporary files.)
 .
 .
 .RS
@@ -1547,30 +1534,37 @@ pipelines may have to be simulated.)
 .
 .P
 Once all preprocessors have run,
-they deliver a pure
+they deliver pure
 .I roff
-document to the formatter,
-which in turn generates intermediate output that is fed into an output
-driver for viewing,
+language input to the formatter,
+which in turn generates a document in a page description language that
+is then interpreted by a postprocessor for viewing,
 printing,
 or further processing.
 .
 .
 .P
-All of these parts use programming languages of their own;
-each language is totally unrelated to the other parts.
-.
-Moreover,
+Each program interprets input in a language that is independent of the
+others;
+some are purely descriptive,
+as with
+.MR @g@tbl @MAN1EXT@
+and
 .I roff
-macro packages that are tailored for special purposes can be included.
+output,
+and some permit the definition of macros,
+as with
+.MR @g@eqn @MAN1EXT@
+and
+.I roff
+input.
 .
 .
-.P
 Most
 .I roff
-input files use the macros of a document formatting package,
+input files employ the macros of a document formatting package,
 intermixed with instructions for one or more preprocessors,
-seasoned with escape sequences and requests directly from the
+and seasoned with escape sequences and requests from the
 .I roff
 language.
 .
@@ -1580,11 +1574,10 @@ since their formatting packages discourage direct use of
 requests;
 man pages are a prominent example.
 .
-The full power of the
+Many features of the
 .I roff
-formatting language is seldom needed by users;
-only programmers of macro packages need a substantial command of it.
-.
+language are seldom needed by users;
+only authors of macro packages need a substantial command of them.
 .
 .
 .\" ====================================================================
@@ -1657,6 +1650,8 @@ Other preprocessors for
 .I roff
 systems are known.
 .
+.
+.P
 .RS
 .TS
 tab (@);
@@ -1674,17 +1669,14 @@ ideal@draws diagrams using a constraint-based language.
 .
 A
 .I roff
-formatter interprets input in the
+formatter transforms
 .I roff
-language and transforms it into
-.I intermediate output
-intended for processing by a selected device.
-.
-Intermediate output uses its own language,
+language input into a single file in a page description language,
 described in
-.MR groff_out @MAN5EXT@ .
+.MR groff_out @MAN5EXT@ ,
+intended for processing by a selected device.
 .
-Intermediate output is specialized in its parameters,
+This page description language is specialized in its parameters,
 but not its syntax,
 for the selected device;
 the format is
@@ -1752,23 +1744,22 @@ particularly if they are similar.
 .P
 The names of the devices and their driver programs are not standardized.
 .
-Technologies change;
-the devices used for document preparation have greatly changed since
-CSTR\~#54 was first written in the 1970s.
+Technological fashions evolve;
+the devices used for document preparation when AT&T
+.I troff \" AT&T
+was first written in the 1970s are no longer used in production
+environments.
 .
-Such hardware is no longer used in production environments,
-and device capabilities
-(including resolution,
-support for multiple colors,
-and font repertoire)
-have tended to increase.
+Device capabilities have tended to increase,
+improving resolution and font repertoire,
+and adding color output and hyperlinking.
 .
 Further,
 to reduce file size and processing time,
 AT&T
-.IR troff 's
-device-independent output format placed low limits on the magnitudes of
-some of the quantities it could represent.
+.IR troff 's \" AT&T
+page description language placed low limits on the magnitudes of some
+quantities it could represent.
 .
 Its PostScript output driver,
 .MR dpost 1 ,
@@ -1824,9 +1815,6 @@ The macro definitions of a package are typically kept in a file called
 .BI tmac. name\/\c\" Italic correction comes before \c !
 ).
 .
-All tmac files are stored in one or more directories at standardized
-positions.
-.
 Details on the naming of macro packages and their placement is found
 in
 .MR groff_tmac @MAN5EXT@ .
@@ -1839,10 +1827,12 @@ the formatter by the command-line option
 see
 .MR @g@troff @MAN1EXT@ .
 .
-It can alternatively be specified within a document using the file
-inclusion requests of the
-.I roff
-language; see
+It can alternatively be specified within a document using the
+.B mso
+request of the
+.I groff
+language;
+see
 .MR groff @MAN7EXT@ .
 .
 .
@@ -1869,17 +1859,17 @@ a punningly-named package exercising many
 .I groff
 extensions.
 .
+See
+.MR groff_tmac @MAN5EXT@
+for more.
+.
 .
 .\" ====================================================================
 .SS "The \f[I]roff\f[] formatting language"
 .\" ====================================================================
 .
-The canonical reference for the AT&T
-.I troff
-language is Ossanna's \[lq]Troff User's Manual\[rq],
-CSTR\~#54,
-in its 1992 revision by Kernighan.
-.
+.\" TODO: Integrate this subsection with subsection "Other language
+.\" elements".
 The
 .I roff
 language provides requests,
@@ -1895,13 +1885,14 @@ is not a mere markup language,
 but Turing-complete.
 .
 It has storage
-(registers);
+(registers),
 it can perform tests
 (as in conditional expressions like
-.RB \[lq] "(\[rs]n[i] >= 1)" \[rq]);
-it can jump or branch using the
-.B .if
-request;
+.RB \[lq] "(\[rs]n[i] >= 1)" \[rq]),
+its
+.\" Kerning between bold "i" and "f" and roman \[lq], \[rq] is tight.
+.RB \[lq] \|if\| \[rq]
+and related requests alter the flow of control,
 and macro definition permits unbounded recursion.
 .
 .
@@ -1911,19 +1902,20 @@ and
 .I escape sequences
 are instructions,
 predefined parts of the language,
-that perform formatting operations or otherwise change the state of the
-parser.
+that perform formatting operations,
+interpolate stored material,
+or otherwise change the state of the parser.
 .
 The user can define their own request-like elements by composing
 together text,
 requests,
 and escape sequences
-.IR "ad libitum" .
+.I "ad libitum."
 .
 .
 A document writer will not (usually) note any difference in usage for
 requests or macros;
-both are written on a line on their own starting with a dot.
+both are found on control lines.
 .
 However,
 there is a distinction;
@@ -1951,7 +1943,8 @@ quote to achieve both aims.
 .I groff
 cuts this knot by supporting a special character escape sequence for the
 neutral double quote,
-.RB \[lq] \[rs][dq] \[rq] ,
+.\" The kerning between a roman \[lq] and a bold backslash is tight.
+.RB \[lq] \|\[rs][dq] \[rq],
 which never performs quoting in the typesetting language,
 but is simply a glyph,
 .RB \[oq] \[dq] \[cq].
@@ -1960,23 +1953,23 @@ but is simply a glyph,
 .P
 .I Escape sequences
 start with a backslash,
-.RB \[lq] \[rs] \[rq].
+.RB \[lq] \|\[rs] \[rq].
 .
 They can appear almost anywhere,
 even in the midst of text on a line,
 and implement various features,
 including the insertion of special characters with
-.RB \[lq] \[rs]( \[rq]
+.RB \[lq] \|\[rs](\f[BI]xx\f[] \[rq]
 or
-.RB \[lq] \[rs][] \[rq],
+.RB \[lq] \|\[rs][\f[BI]xxx\f[]] \[rq],
 break suppression at input line endings with
-.RB \[lq] \[rs]c \[rq],
+.RB \[lq] \|\[rs]c \[rq],
 font changes with
-.RB \[lq] \[rs]f \[rq],
+.RB \[lq] \|\[rs]f\| \[rq],
 type size changes with
-.RB \[lq] \[rs]s \[rq],
+.RB \[lq] \|\[rs]s \[rq],
 in-line comments with
-.RB \[lq] \[rs]\[dq] \[rq],
+.RB \[lq] \|\[rs]\[dq] \[rq],
 and many others.
 .
 .
@@ -1985,7 +1978,7 @@ and many others.
 store text.
 .
 They are populated with the
-.B .ds
+.B ds
 request and interpolated using the
 .B \[rs]*
 escape sequence.
@@ -1996,7 +1989,7 @@ escape sequence.
 store numbers and measurements.
 .
 A register can be set with the request
-.B .nr
+.B nr
 and its value can be retrieved by the escape sequence
 .BR "\[rs]n" .
 .
@@ -2197,6 +2190,7 @@ the origin of our ideas of space and time,
 although in doing so I know that I introduce a
 controversial subject.\&  \[rs]" remainder of paragraph elided
 \&.
+.ne 3v \" Don't let a page break hide the blank line from the reader.
 \&.
 \&
 \[->]The experiences of an individual appear to us arranged
@@ -2342,7 +2336,7 @@ program.
 Vim's highlighting can be made to recognize
 .I roff
 files by setting the
-.I filetype
+.B filetype
 option in a Vim
 .IR modeline .
 .
@@ -2394,13 +2388,8 @@ and string names longer than two characters.
 This document was written by
 .MT groff\-bernd\:.warken\-72@\:web\:.de
 Bernd Warken
-.ME ,
-with the sections \[lq]Concepts\[rq],
-\[lq]History\[rq],
-\[lq]File name conventions\[rq],
+.ME
 and
-\[lq]Input conventions\[rq]
-mostly written by
 .MT g.branden\:.robinson@\:gmail\:.com
 G.\& Branden Robinson
 .ME .
@@ -2410,15 +2399,16 @@ G.\& Branden Robinson
 .SH "See also"
 .\" ====================================================================
 .
-There is a lot of documentation about
-.IR roff .
+Much
+.I roff
+documentation is available.
 .
-The original papers describing AT&T
+The Bell Labs papers describing AT&T
 .I troff
-are still available,
-and all aspects of
+remain available,
+and
 .I groff
-are documented in great detail.
+is documented comprehensively. \" ...one hopes.
 .
 .
 .\" ====================================================================