[groff] 10/10: groff(7): Revise introductory sections.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 341255963a8ad98df7c3572f6c75f8fce0591b40
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu Nov 11 00:35:22 2021 +1100

    groff(7): Revise introductory sections.
    
    * Rewrite introductory paragraphs.
    * Add "Input format" section.
    * Rewrite "groff elements" section.
---
 man/groff.7.man | 451 ++++++++++++++++++++++++++++++++++----------------------
 1 file changed, 278 insertions(+), 173 deletions(-)

diff --git a/man/groff.7.man b/man/groff.7.man
index 41f111c..7e3d9df 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -240,252 +240,323 @@ for a survey and the background of
 .I roff
 systems.
 .
-.I groff
-also refers to GNU
-.I roff
-system's front end,
-.MR groff @MAN1EXT@ .
-.
 .
 .P
-This document provides only short descriptions of roff language
-elements.
+This document is intended as a reference.
 .
-.IR "Groff: The GNU Implementation of troff" ,
-by Trent A.\& Fisher and Werner Lemberg,
-is the primary
+The primary
 .I groff
 manual,
-and is written in Texinfo.
+.IR "Groff: The GNU Implementation of troff" ,
+by Trent A.\& Fisher and Werner Lemberg,
+is a better resource for learners,
+containing many examples and much discussion.
 .
-You can browse it interactively with \[lq]info groff\[rq].
+It is written in Texinfo;
+you can browse it interactively with \[lq]info groff\[rq].
 .
+Additional formats,
+including plain text,
+HTML,
+DVI,
+and PDF,
+may be available in
+.IR \%@DOCDIR@ .
 .
-.P
-Historically, the
-.I roff language
-was called
-.IR troff .
-.I groff
-is compatible with the classical system and provides proper
-extensions.
-.
-So in GNU, the terms
-.IR roff ,
-.IR troff ,
-and
-.I groff language
-could be used as synonyms.
 .
-However
-.I troff
-slightly tends to refer more to the classical aspects, whereas
+.P
 .I groff
-emphasizes the GNU extensions, and
+is a member of a family of related
 .I roff
-is the general term for the language.
+languages that share many traits.
 .
+We use \[lq]roff\[rq] to denote features that are universal,
+or nearly so,
+among implementations of this family.
 .
-.P
-The general syntax for writing groff documents is relatively easy, but
-writing extensions to the roff language can be a bit harder.
+We apply the term \[lq]groff\[rq] to the language documented here,
+the GNU implementation of the overall system,
+and the command of that name.
 .
 .
 .P
-The roff language is line-oriented.
+GNU
+.IR troff , \" GNU
+installed on this system as
+.MR @g@troff @MAN1EXT@ ,
+is the
+.I formatter:
+a program that reads device and font descriptions
+(\c
+.MR groff_font @MAN5EXT@ ),
+interprets the
+.I groff
+language expressed in text input files,
+and translates that input into a device-independent output format
+(\c
+.MR groff_out @MAN5EXT@ )
+that is usually then post-processed by an output driver to produce
+PostScript,
+PDF,
+HTML,
+DVI,
+or terminal output.
 .
-There are only two kinds of lines, control lines and text lines.
 .
-The control lines start with a control character, by default a period
-.dquoted_char .
-or a single quote
-.dquoted_char \[aq] ;
-all other lines are text lines.
+.\" ====================================================================
+.SH "Input format"
+.\" ====================================================================
 .
+.I roff
+input files contain text interspersed with instructions to control the
+formatter.
 .
-.P
-.B Control lines
-represent commands, optionally with arguments.
+Even in the absence of such instructions,
+.I \%@g@troff
+still processes its input in several ways,
+by filling,
+hyphenating,
+breaking,
+and adjusting it,
+and supplementing it with inter-sentence space.
 .
-They have the following syntax.
 .
-The leading control character can be followed by a command name;
-arguments, if any, are separated by spaces (but not tab characters)
-from the command name and among themselves, for example,
-.RS
 .P
-.Text .command_name arg1 arg2
-.RE
+Input to
+.I \%@g@troff
+must be in one of two character encodings it can recognize:
+IBM code page 1047 on EBCDIC systems,
+and ISO\~Latin-1 (8859-1) otherwise.
 .
+Use of ISO\~646-1991:IRV (\[lq]US-ASCII\[rq]) or (equivalently) the
+\[lq]Basic Latin\[rq]
+subset of ISO\~10646 (\[lq]Unicode\[rq]) is recommended;
+see
+.MR groff_char @MAN7EXT@ .
 .
-.P
-For indentation, any number of space or tab characters can be inserted
-between the leading control character and the command name, but the
-control character must be on the first position of the line.
+.MR groff @MAN1EXT@
+and the
+.MR preconv @MAN1EXT@
+preprocessor can transform other encodings,
+including UTF-8,
+to satisfy
+.IR \%@g@troff 's
+requirements.
 .
 .
 .P
-.B Text lines
-represent the parts that is printed.
-They can be modified by escape sequences, which are recognized by a
-leading backslash
-.squoted_char \[rs] .
-These are in-line or even in-word formatting elements or functions.
-.
-Some of these take arguments separated by single quotes
-.dquoted_char \[aq] ,
-others are regulated by a length encoding introduced by an open
-parenthesis
-.squoted_char (
-or enclosed in brackets
-.squoted_char [
-and
-.squoted_char ] .
+.I groff
+input is organized into lines separated by the Unix newline character
+(U+000A) and parsed character by character.
 .
 .
 .\" ====================================================================
 .SH "\f[I]groff\f[] elements"
 .\" ====================================================================
 .
-The roff language elements add formatting information to a text file.
+Lines of input to any
+.I roff
+formatter can be classified as one of two types:
+control lines and text lines.
+.
 .
-The fundamental elements are predefined commands and variables that
-make roff a full-blown programming language.
+.P
+A
+.I control line
+starts with the
+.I control character,
+a dot
+.RB (\[lq] .\& \[rq])
+or the
+.I no-break control character,
+a neutral apostrophe
+.RB (\[lq] \[aq] \[rq]).
+.
+Either control character is followed by zero or more spaces or tabs
+and then an optional
+.I request,
+an instruction built in to the formatter.
+.
+Some requests take one or more
+.I arguments,
+which follow on the same line,
+separated from the request name and each other only by spaces.
 .
 .
 .P
-There are two kinds of roff commands, possibly with arguments.
-.B Requests
-are written on a line of their own starting with a dot
-.squoted_char .\&
-or a
-.dquoted_char \[aq] ,
-whereas
-.B Escape sequences
-are in-line functions and in-word formatting elements starting with a
-backslash
-.squoted_char \[rs] .
+Any input line that is not a control line is a
+.I text line.
+.
+See section \[lq]Line continuation\[rq] below for an exception to this
+rule.
+.
+Text lines generally become formatted output.
+.
+To start a text line with the control or no-break control character,
+prefix the character with the
+.B \[rs]&
+escape sequence.
 .
 .
 .P
-The user can define her own formatting commands using the
-.request .de
-request.
+.I Escape sequences
+start with the
+.I escape character,
+a backslash
+.B \[rs],
+and are followed by at least one additional character.
 .
-These commands are called
-.BR macros ,
-but they are used exactly like requests.
+They can appear anywhere in the input.
 .
-Macro packages are pre-defined sets of macros written in the groff
-language.
 .
-A user's possibilities to create escape sequences herself is very
-limited, only special characters can be mapped.
+.P
+With requests,
+the escape and control characters can be changed and,
+in
+.I groff,
+the escape mechanism can be turned off and back on.
 .
 .
 .P
-The groff language provides several kinds of variables with
-different interfaces.
+.I Macros
+permit the extension or replacement of the request repertoire.
+.
+Requests like
+.request .de
+(shown here with a leading control character to clarify its identity)
+can be invoked to define a macro,
+a user-directed abbreviation for a collection of input lines.
+.
+Macros are called on control lines much as requests are invoked,
+albeit with occasional differences in argument handling.
+.
+When a macro is called,
+its definition
+(or \[lq]body\[rq])
+is
+.I interpolated,
+as if typed at its call site.
 .
-There are pre-defined variables, but the user can define her own
-variables as well.
+Its contents are then parsed normally.
 .
 .
 .P
-.B String
-variables store character sequences.
+.I Strings
+store character sequences.
 .
-They are set with the
+They are defined with the
 .request .ds
-request and retrieved by the
+request and interpolated with the
 .esc *
-escape sequences.
+escape sequence.
 .
-Strings can have variables.
+Strings can be parameterized as macros can.
 .
 .
 .P
-.B Register
-variables can store numerical values, numbers with a scale unit, and
-occasionally string-like objects.
+.I Registers
+store numerical values.
 .
 They are set with the
 .request .nr
-request and retrieved by the
+request or
+.esc R
+escape sequence and interpolated with the
 .esc n
-escape sequences.
-.
-.
-.P
-.B Environments
-allow the user to temporarily store global formatting parameters like
-line length, font size, etc.\& for later reuse.
+escape sequence.
 .
-This is done by the
-.request .ev
-request.
+Some read-only predefined registers interpolate text.
 .
 .
 .P
-.B Fonts
-are identified either by a name or by an internal number.
+.I Fonts
+are identified either by a name or by a mounting position
+(a non-negative number).
 .
-The current font is chosen by the
+A font is selected for glyph rendering by the
 .request .ft
 request or by the
 .esc f
-escape sequences.
+escape sequence.
+.
+Four font styles are available on all devices.
 .
-Each device has special fonts, but the following fonts are available
-for all devices.
 .B R
-is the standard font Roman.
+is \[lq]Roman\[rq]:
+normal,
+upright text.
+.
 .B B
-is its
-.B bold
-counterpart.
+is
+.BR bold ,
+an upright typeface with a heavier weight.
 .
-The
-.I italic
-font is called
 .B I
-and is available everywhere, but on text devices it is displayed as an
-underlined Roman font.
+is
+.IR italic ,
+a face that is oblique on typesetter output devices and usually
+underlined instead on terminal devices.
+.
+.B BI
+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
+.I special
+fonts as well;
+they provide glyphs that are not available in the multiple styles of
+text fonts.
 .
-For the graphical output devices, there exist constant-width pendants
-of these fonts,
-.BR CR ,
-.BR CI ,
+.
+.P
+.I groff
+supports named
+.I colors
+for glyph rendering and drawing of geometric primitives.
+.
+Stroke and fill colors are distinct;
+the stroke color is used for glyphs.
+.
+Colors are defined with the
+.request .defcolor
+request,
+and selected with the
+.request .gcolor
+and
+.request .fcolor
+requests or
+.esc m
 and
-.BR CB .
-On text devices, all glyphs have a constant width anyway.
+.esc M
+escape sequences.
 .
 .
 .P
-.B Glyphs
+.I Glyphs
 are visual representation forms of
-.BR characters .
-In groff, the distinction between those two elements is not always
-obvious (and a full discussion is beyond the scope of this man page).
+.I characters.
 .
-A first approximation is that glyphs have a specific size and
-colour and are taken from a specific font; they can't be modified any
-more \[en] characters are the input, and glyphs are the output.
+In
+.I groff,
+the distinction between those two elements is not always obvious
+(and a full discussion is beyond our scope).
 .
-As soon as an output line has been generated, it no longer contains
-characters but glyphs.
+To roughly characterize,
+\[lq]A\[rq] is a character when we consider it in the abstract:
+to make it a glyph,
+we must select a typeface with which to render it,
+and determine its type size and color.
 .
-In this man page, we use either \[oq]glyph\[cq] or
-\[oq]character\[cq], whatever is more appropriate.
+The formatting process turns input characters into output glyphs.
 .
 A few characters commonly seen on keyboards are treated
 specially by
 .I roff
-languages and may not look correct in output;
+languages and may not look correct in output if used unthinkingly;
 they are
 the (double) quotation mark
 .RB ( \[dq] ),
-the apostrophe
+the neutral apostrophe
 .RB ( \[aq] ),
 the minus sign
 .RB ( \- ),
@@ -498,34 +569,68 @@ the grave accent
 and the tilde
 .RB ( \[ti] ).
 .
-All are available if required;
+All are available via
+.I special character
+escape sequences,
+along with numerous other symbols;
 see
 .MR groff_char @MAN7EXT@ .
 .
 .
 .P
-Moreover, there are some advanced roff elements.
+A further few language elements arise as page layouts become more
+sophisticated and demanding.
 .
-A
-.B diversion
-stores (formatted) information into a macro for later usage.
-See
-.MR groff_tmac @MAN5EXT@
-for more details.
+.
+.I Environments
+collect formatting parameters like line length and typeface.
 .
 A
-.B trap
-is a positional condition like a certain number of lines from page top
-or in a diversion or in the input.
+.I diversion
+stores formatted output for later use.
 .
-Some action can be prescribed to be run automatically when the
-condition is met.
+A
+.I trap
+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.
 .
 .
+.\" TODO: Move this paragraph to our Texinfo manual and roff(7).
 .P
-More detailed information and examples can be found in the
-.I groff
-Texinfo manual.
+Footnote support often exercises all three of the foregoing features.
+.
+A simple implementation might work as follows.
+.
+A pair of macros is defined:
+one starts a footnote and the other ends it.
+.
+The author calls the first macro where a footnote marker is desired.
+.
+The macro establishes a diversion so that the footnote text is collected
+at the place in the body text where its corresponding marker appears.
+.
+An environment is created for the footnote so that it is set at a
+smaller typeface.
+.
+The footnote text is formatted in the diversion using that environment,
+but it does not yet appear in the output.
+.
+The document author calls the footnote end macro,
+which returns to the previous environment and ends the diversion.
+.
+Later,
+after much more body text in the document,
+a trap,
+set a small distance above the page bottom,
+is sprung.
+.
+The macro called by the trap draws a line across the page and emits the
+stored diversion.
+.
+Thus,
+the footnote is rendered.
 .
 .
 .\" ====================================================================
@@ -708,8 +813,8 @@ There is a sophisticated interface for handling tab 
positions.
 .SH "Line continuation"
 .\" ====================================================================
 .
-.I groff
-distinguishes input and output line continuation.
+.I roff
+languages distinguish input and output line continuation.
 .
 .
 .P