Adding upstream version 1.23.0.upstream/1.23.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 7529 insertions, 0 deletions

diff --git a/doc/groff.info-2 b/doc/groff.info-2
new file mode 100644
index 0000000..44572a0
--- /dev/null
+++ b/doc/groff.info-2
@@ -0,0 +1,7529 @@
+This is groff.info, produced by makeinfo version 7.0.3 from groff.texi.
+
+This manual documents GNU 'troff' version 1.23.0.
+
+   Copyright © 1994-2023 Free Software Foundation, Inc.
+
+     Permission is granted to copy, distribute and/or modify this
+     document under the terms of the GNU Free Documentation License,
+     Version 1.3 or any later version published by the Free Software
+     Foundation; with no Invariant Sections, no Front-Cover Texts, and
+     no Back-Cover Texts.  A copy of the license is included in the
+     section entitled "GNU Free Documentation License".
+INFO-DIR-SECTION Typesetting
+START-INFO-DIR-ENTRY
+* Groff: (groff).               The GNU roff document formatting system.
+END-INFO-DIR-ENTRY
+
+
+File: groff.info,  Node: Selecting Fonts,  Next: Font Families,  Prev: Using Fonts,  Up: Using Fonts
+
+5.19.1 Selecting Fonts
+----------------------
+
+We use "font" to refer to any of several means of identifying a font: by
+mounting position ('3'), by abstract style ('B'), or by its identifier
+('TB').
+
+ -- Request: .ft [font]
+ -- Escape sequence: \ff
+ -- Escape sequence: \f(fn
+ -- Escape sequence: \f[font]
+ -- Register: \n[.fn]
+     The 'ft' request selects the typeface FONT.  If the argument is
+     absent or 'P', it selects the previously chosen font.  If FONT is a
+     non-negative integer, it is interpreted as mounting position; the
+     font mounted there is selected.  If that position refers to an
+     abstract style, it is combined with the default family (see 'fam'
+     and '\F' below) to make a resolved font name.  If the mounting
+     position is not a style and no font is mounted there, GNU 'troff'
+     emits a warning in category 'font' and ignores the request.
+
+     If FONT matches a style name, it is combined with the current
+     family to make a resolved font name.  Otherwise, FONT is assumed to
+     already be a resolved font name.
+
+     The resolved font name is subject to translation (see request 'ftr'
+     below).  Next, the (possibly translated) font name's mounting
+     position is looked up; if not mounted, FONT is sought on the file
+     system as a font description file and, if located, automatically
+     mounted at the next available position (see register '.fp' below).
+     If the font was mounted using an identifier different from its font
+     description file name (see request 'fp' below), that file name is
+     then looked up.  If a font description file for the resolved font
+     name is not found, GNU 'troff' emits a warning in category 'font'
+     and ignores the request.
+
+     The '\f' escape sequence is similar, using one-character name (or
+     mounting position) F, two-character name FN, or a name FONT of
+     arbitrary length.  '\f[]' selects the previous font.  The syntax
+     form '\fP' is supported for backward compatibility, and '\f[P]' for
+     consistency.
+
+          eggs, bacon,
+          .ft I
+          spam,
+          .ft
+          and sausage.
+          .br
+          eggs, bacon, \fIspam,\fP and sausage.
+              => eggs, bacon, spam, and sausage
+              => eggs, bacon, spam, and sausage
+
+     The current and previously selected fonts are properties of the
+     environment (*note Environments::).
+
+     The read-only string-valued register '.fn' contains the resolved
+     font name of the selected font.
+
+     '\f' doesn't produce an input token in GNU 'troff'; it thus can be
+     used in requests that expect a single-character argument.  We can
+     assign a font to a margin character as follows (*note
+     Miscellaneous::).
+
+          .mc \f[I]x\f[]
+
+ -- Request: .ftr f [g]
+     Translate font F to font G.  Whenever a font named F is referred to
+     in a '\f' escape sequence, in the 'F' and 'S' conditional
+     operators, or in the 'ft', 'ul', 'bd', 'cs', 'tkf', 'special',
+     'fspecial', 'fp', or 'sty' requests, font G is used.  If G is
+     missing or equal to F the translation is undone.
+
+     Font translations cannot be chained.
+
+          .ftr XXX TR
+          .ftr XXX YYY
+          .ft XXX
+              error-> warning: can't find font 'XXX'
+
+ -- Request: .fzoom f [zoom]
+ -- Register: \n[.zoom]
+     Set magnification of font F to factor ZOOM, which must be a
+     non-negative integer multiple of 1/1000th.  This request is useful
+     to adjust the optical size of a font in relation to the others.  In
+     the example below, font 'CR' is magnified by 10% (the zoom factor
+     is thus 1.1).
+
+          .fam P
+          .fzoom CR 1100
+          .ps 12
+          Palatino and \f[CR]Courier\f[]
+
+     A missing or zero value of ZOOM is the same as a value of 1000,
+     which means no magnification.  F must be a resolved font name, not
+     an abstract style.
+
+     The magnification of a font is completely transparent to GNU
+     'troff'; a change of the zoom factor doesn't cause any effect
+     except that the dimensions of glyphs, (word) spaces, kerns, etc.,
+     of the affected font are adjusted accordingly.
+
+     The zoom factor of the current font is available in the read-only
+     register '.zoom', in multiples of 1/1000th.  It returns zero if
+     there is no magnification.
+
+
+File: groff.info,  Node: Font Families,  Next: Font Positions,  Prev: Selecting Fonts,  Up: Using Fonts
+
+5.19.2 Font Families
+--------------------
+
+To accommodate the wide variety of fonts available, GNU 'troff'
+distinguishes "font families" and "font styles".  A resolved font name
+is the catenation of a font family and a style.  Selecting an abstract
+style causes GNU 'troff' to combine it with the default font family.
+
+   You can thus compose a document using abstract styles exclusively for
+its body or running text, selecting a specific family only for titles or
+examples, for instance, and change the default family on the command
+line (recall *note Groff Options::).
+
+   Fonts for the devices 'ps', 'pdf', 'dvi', 'lj4', 'lbp', and the X11
+devices support this mechanism.  By default, GNU 'troff' uses the Times
+family with the four styles 'R', 'I', 'B', and 'BI'.
+
+ -- Request: .fam [family]
+ -- Register: \n[.fam]
+ -- Escape sequence: \Ff
+ -- Escape sequence: \F(fm
+ -- Escape sequence: \F[family]
+     Set the default font family, used in combination with abstract
+     styles to construct a resolved font name, to FAMILY (one-character
+     name F, two-character name FM).  If no argument is given, GNU
+     'troff' selects the previous font family; if there none, is it
+     falls back to the device's default(1) (*note Font
+     Families-Footnote-1::) or its own ('T').
+
+     The '\F' escape sequence works similarly.  In disanalogy to '\f',
+     '\FP' makes 'P' the default family.  Use '\F[]' to select the
+     previous default family.  The default font family is available in
+     the read-only string-valued register '.fam'; it is associated with
+     the environment (*note Environments::).
+
+          spam,     \" startup defaults are T (Times) R (roman)
+          .fam H    \" make Helvetica the default family
+          spam,     \" family H + style R = HR
+          .ft B     \" family H + style B = HB
+          spam,
+          .ft CR    \" Courier roman (default family not changed)
+          spam,
+          .ft       \" back to Helvetica bold
+          spam,
+          .fam T    \" make Times the default family
+          spam,     \" family T + style B = TB
+          .ft AR    \" font AR (not a style)
+          baked beans,
+          .ft R     \" family T + style R = TR
+          and spam.
+
+     '\F' doesn't produce an input token in GNU 'troff'.  As a
+     consequence, it can be used in requests like 'mc' (which expects a
+     single character as an argument) to change the font family on the
+     fly.
+
+          .mc \F[P]x\F[]
+
+ -- Request: .sty n style
+ -- Register: \n[.sty]
+     Associate an abstract style STYLE with mounting position N, which
+     must be a non-negative integer.  If the requests 'cs', 'bd', 'tkf',
+     'uf', or 'fspecial' are applied to an abstract style, they are
+     instead applied to the member of the current family corresponding
+     to that style.
+
+     The default family can be set with the '-f' option (*note Groff
+     Options::).  The 'styles' command in the 'DESC' file controls which
+     font positions (if any) are initially associated with abstract
+     styles rather than fonts.
+
+     *Caution:* The STYLE argument is not validated.  Errors may occur
+     later, when the formatter attempts to construct a resolved font
+     name, or format a character for output.
+
+          .nr BarPos \n[.fp]
+          .sty \n[.fp] Bar
+          .fam Foo
+          .ft \n[BarPos]
+          .tm .f=\n[.f]
+          A
+              error-> error: no font family named 'Foo' exists
+              error-> .f=41
+              error-> error: cannot format glyph: no current font
+
+     When an abstract style has been selected, the read-only
+     string-valued register '.sty' interpolates its name; this datum is
+     associated with the environment (*note Environments::).  Otherwise,
+     '.sty' interpolates nothing.
+
+
+File: groff.info,  Node: Font Families-Footnotes,  Up: Font Families
+
+   (1) *Note DESC File Format::.
+
+
+File: groff.info,  Node: Font Positions,  Next: Using Symbols,  Prev: Font Families,  Up: Using Fonts
+
+5.19.3 Font Positions
+---------------------
+
+To support typeface indirection through abstract styles, and for
+compatibility with AT&T 'troff', the formatter maintains a list of font
+"positions" at which fonts required by a document are "mounted".  An
+output device's description file 'DESC' typically configures a set of
+pre-mounted fonts; see *note Device and Font Description Files::.  A
+font need not be explicitly mounted before it is selected; GNU 'troff'
+will search 'GROFF_FONT_PATH' for it by name and mount it at the first
+free mounting position on demand.
+
+ -- Request: .fp pos id [font-description-file-name]
+ -- Register: \n[.f]
+ -- Register: \n[.fp]
+     Mount a font under the name ID at mounting position POS, a
+     non-negative integer.  When the formatter starts up, it reads the
+     output device's description to mount an initial set of faces, and
+     selects font position 1.  Position 0 is unused by default.  Unless
+     the FONT-DESCRIPTION-FILE-NAME argument is given, ID should be the
+     name of a font description file stored in a directory corresponding
+     to the selected output device.  GNU 'troff' does not traverse
+     directories to locate the font description file.
+
+     The optional third argument enables font names to be aliased, which
+     can be necessary in compatibility mode since AT&T 'troff' syntax
+     affords no means of identifying fonts with names longer than two
+     characters, like 'TBI' or 'ZCMI', in a font selection escape
+     sequence.  *Note Compatibility Mode::.  You can also alias fonts on
+     mounting for convenience or abstraction.  (See below regarding the
+     '.fp' register.)
+
+          .fp \n[.fp] SC ZCMI
+          Send a \f(SChand-written\fP thank-you note.
+          .fp \n[.fp] Emph TI
+          .fp \n[.fp] Strong TB
+          Are \f[Emph]these names\f[] \f[Strong]comfortable\f[]?
+
+     'DESC', 'P', and non-negative integers are not usable as font
+     identifiers.
+
+     The position of the currently selected font (or abstract style) is
+     available in the read-only register '.f'.  It is associated with
+     the environment (*note Environments::).
+
+     You can copy the value of '.f' to another register to save it for
+     later use.
+
+          .nr saved-font \n[.f]
+          ... text involving many font changes ...
+          .ft \n[saved-font]
+
+     The index of the next (non-zero) free font position is available in
+     the read-only register '.fp'.  Fonts not listed in the 'DESC' file
+     are automatically mounted at position '\n[.fp]' when selected with
+     the 'ft' request or '\f' escape sequence.  When mounting a font at
+     a position explicitly with the 'fp' request, this same practice
+     should be followed, although GNU 'troff' does not enforce this
+     strictly.
+
+
+File: groff.info,  Node: Using Symbols,  Next: Character Classes,  Prev: Font Positions,  Up: Using Fonts
+
+5.19.4 Using Symbols
+--------------------
+
+A "glyph" is a graphical representation of a "character".  While a
+character is an abstraction of semantic information, a glyph is
+something that can be seen on screen or paper.  A character has many
+possible representation forms (for example, the character 'A' can be
+written in an upright or slanted typeface, producing distinct glyphs).
+Sometimes, a sequence of characters map to a single glyph: this is a
+"ligature"--the most common is 'fi'.
+
+   Space characters never become glyphs in GNU 'troff'.  If not
+discarded (as when trailing on text lines), they are represented by
+horizontal motions in the output.
+
+   A "symbol" is simply a named glyph.  Within 'gtroff', all glyph names
+of a particular font are defined in its font file.  If the user requests
+a glyph not available in this font, 'gtroff' looks up an ordered list of
+"special fonts".  By default, the PostScript output device supports the
+two special fonts 'SS' (slanted symbols) and 'S' (symbols) (the former
+is looked up before the latter).  Other output devices use different
+names for special fonts.  Fonts mounted with the 'fonts' keyword in the
+'DESC' file are globally available.  To install additional special fonts
+locally (i.e., for a particular font), use the 'fspecial' request.
+
+   Here are the exact rules how 'gtroff' searches a given symbol:
+
+   * If the symbol has been defined with the 'char' request, use it.
+     This hides a symbol with the same name in the current font.
+
+   * Check the current font.
+
+   * If the symbol has been defined with the 'fchar' request, use it.
+
+   * Check whether the current font has a font-specific list of special
+     fonts; test all fonts in the order of appearance in the last
+     'fspecial' call if appropriate.
+
+   * If the symbol has been defined with the 'fschar' request for the
+     current font, use it.
+
+   * Check all fonts in the order of appearance in the last 'special'
+     call.
+
+   * If the symbol has been defined with the 'schar' request, use it.
+
+   * As a last resort, consult all fonts loaded up to now for special
+     fonts and check them, starting with the lowest font number.  This
+     can sometimes lead to surprising results since the 'fonts' line in
+     the 'DESC' file often contains empty positions, which are filled
+     later on.  For example, consider the following:
+
+          fonts 3 0 0 FOO
+
+     This mounts font 'foo' at font position 3.  We assume that 'FOO' is
+     a special font, containing glyph 'foo', and that no font has been
+     loaded yet.  The line
+
+          .fspecial BAR BAZ
+
+     makes font 'BAZ' special only if font 'BAR' is active.  We further
+     assume that 'BAZ' is really a special font, i.e., the font
+     description file contains the 'special' keyword, and that it also
+     contains glyph 'foo' with a special shape fitting to font 'BAR'.
+     After executing 'fspecial', font 'BAR' is loaded at font
+     position 1, and 'BAZ' at position 2.
+
+     We now switch to a new font 'XXX', trying to access glyph 'foo'
+     that is assumed to be missing.  There are neither font-specific
+     special fonts for 'XXX' nor any other fonts made special with the
+     'special' request, so 'gtroff' starts the search for special fonts
+     in the list of already mounted fonts, with increasing font
+     positions.  Consequently, it finds 'BAZ' before 'FOO' even for
+     'XXX', which is not the intended behaviour.
+
+   *Note Device and Font Description Files::, and *note Special Fonts::,
+for more details.
+
+   The 'groff_char(7)' man page houses a complete list of predefined
+special character names, but the availability of any as a glyph is
+device- and font-dependent.  For example, say
+
+     man -Tdvi groff_char > groff_char.dvi
+
+to obtain those available with the DVI device and default font
+configuration.(1)  (*note Using Symbols-Footnote-1::) If you want to use
+an additional macro package to change the fonts used, 'groff' (or
+'gtroff') must be run directly.
+
+     groff -Tdvi -mec -man groff_char.7 > groff_char.dvi
+
+   Special character names not listed in 'groff_char(7)' are derived
+algorithmically, using a simplified version of the Adobe Glyph List
+(AGL) algorithm, which is described in
+<https://github.com/adobe-type-tools/agl-aglfn>.  The (frozen) set of
+names that can't be derived algorithmically is called the "'groff' glyph
+list (GGL)".
+
+   * A glyph for Unicode character U+XXXX[X[X]], which is not a
+     composite character is named 'uXXXX[X[X]]'.  X must be an uppercase
+     hexadecimal digit.  Examples: 'u1234', 'u008E', 'u12DB8'.  The
+     largest Unicode value is 0x10FFFF. There must be at least four 'X'
+     digits; if necessary, add leading zeroes (after the 'u').  No zero
+     padding is allowed for character codes greater than 0xFFFF.
+     Surrogates (i.e., Unicode values greater than 0xFFFF represented
+     with character codes from the surrogate area U+D800-U+DFFF) are not
+     allowed either.
+
+   * A glyph representing more than a single input character is named
+
+          'u' COMPONENT1 '_' COMPONENT2 '_' COMPONENT3 ...
+
+     Example: 'u0045_0302_0301'.
+
+     For simplicity, all Unicode characters that are composites must be
+     maximally decomposed to NFD;(2) (*note Using Symbols-Footnote-2::)
+     for example, 'u00CA_0301' is not a valid glyph name since U+00CA
+     (LATIN CAPITAL LETTER E WITH CIRCUMFLEX) can be further decomposed
+     into U+0045 (LATIN CAPITAL LETTER E) and U+0302 (COMBINING
+     CIRCUMFLEX ACCENT).  'u0045_0302_0301' is thus the glyph name for
+     U+1EBE, LATIN CAPITAL LETTER E WITH CIRCUMFLEX AND ACUTE.
+
+   * groff maintains a table to decompose all algorithmically derived
+     glyph names that are composites itself.  For example, 'u0100'
+     (LATIN LETTER A WITH MACRON) is automatically decomposed into
+     'u0041_0304'.  Additionally, a glyph name of the GGL is preferred
+     to an algorithmically derived glyph name; 'groff' also
+     automatically does the mapping.  Example: The glyph 'u0045_0302' is
+     mapped to '^E'.
+
+   * glyph names of the GGL can't be used in composite glyph names; for
+     example, '^E_u0301' is invalid.
+
+ -- Escape sequence: \(nm
+ -- Escape sequence: \[name]
+ -- Escape sequence: \[base-glyph combining-component ...]
+     Typeset a special character NAME (two-character name NM) or a
+     composite glyph consisting of BASE-GLYPH overlaid with one or more
+     COMBINING-COMPONENTs.  For example, '\[A ho]' is a capital letter
+     "A" with a "hook accent" (ogonek).
+
+     There is no special syntax for one-character names--the analogous
+     form '\N' would collide with other escape sequences.  However, the
+     four escape sequences '\'', '\-', '\_', and '\`', are translated on
+     input to the special character escape sequences '\[aa]', '\[-]',
+     '\[ul]', and '\[ga]', respectively.
+
+     A special character name of length one is not the same thing as an
+     ordinary character: that is, the character 'a' is not the same as
+     '\[a]'.
+
+     If NAME is undefined, a warning in category 'char' is produced and
+     the escape is ignored.  *Note Warnings::, for information about the
+     enablement and suppression of warnings.
+
+     GNU 'troff' resolves '\[...]' with more than a single component as
+     follows:
+
+        * Any component that is found in the GGL is converted to the
+          'uXXXX' form.
+
+        * Any component 'uXXXX' that is found in the list of
+          decomposable glyphs is decomposed.
+
+        * The resulting elements are then concatenated with '_' in
+          between, dropping the leading 'u' in all elements but the
+          first.
+
+     No check for the existence of any component (similar to 'tr'
+     request) is done.
+
+     Examples:
+
+     '\[A ho]'
+          'A' maps to 'u0041', 'ho' maps to 'u02DB', thus the final
+          glyph name would be 'u0041_02DB'.  This is not the expected
+          result: the ogonek glyph 'ho' is a spacing ogonek, but for a
+          proper composite a non-spacing ogonek (U+0328) is necessary.
+          Looking into the file 'composite.tmac', one can find
+          '.composite ho u0328', which changes the mapping of 'ho' while
+          a composite glyph name is constructed, causing the final glyph
+          name to be 'u0041_0328'.
+
+     '\[^E u0301]'
+     '\[^E aa]'
+     '\[E a^ aa]'
+     '\[E ^ ']'
+          '^E' maps to 'u0045_0302', thus the final glyph name is
+          'u0045_0302_0301' in all forms (assuming proper calls of the
+          'composite' request).
+
+     It is not possible to define glyphs with names like 'A ho' within a
+     'groff' font file.  This is not really a limitation; instead, you
+     have to define 'u0041_0328'.
+
+ -- Escape sequence: \C'xxx'
+     Typeset the glyph of the special character XXX.  Normally, it is
+     more convenient to use '\[XXX]', but '\C' has some advantages: it
+     is compatible with AT&T device-independent 'troff' (and therefore
+     available in compatibility mode(3) (*note Using
+     Symbols-Footnote-3::)) and can interpolate special characters with
+     ']' in their names.  The delimiter need not be a neutral
+     apostrophe; see *note Delimiters::.
+
+ -- Request: .composite id1 id2
+     Map special character name ID1 to ID2 if ID1 is used in '\[...]'
+     with more than one component.  See above for examples.  This is a
+     strict rewriting of the special character name; no check is
+     performed for the existence of a glyph for either.  A set of
+     default mappings for many accents can be found in the file
+     'composite.tmac', loaded by the default 'troffrc' at startup.
+
+ -- Escape sequence: \N'n'
+     Typeset the glyph with code N in the current font ('n' is _not_ the
+     input character code).  The number N can be any non-negative
+     decimal integer.  Most devices only have glyphs with codes between
+     0 and 255; the Unicode output device uses codes in the range
+     0-65535.  If the current font does not contain a glyph with that
+     code, special fonts are _not_ searched.  The '\N' escape sequence
+     can be conveniently used in conjunction with the 'char' request:
+
+          .char \[phone] \f[ZD]\N'37'
+
+     The code of each glyph is given in the fourth column in the font
+     description file after the 'charset' command.  It is possible to
+     include unnamed glyphs in the font description file by using a name
+     of '---'; the '\N' escape sequence is the only way to use these.
+
+     No kerning is applied to glyphs accessed with '\N'.  The delimiter
+     need not be a neutral apostrophe; see *note Delimiters::.
+
+   A few escape sequences are also special characters.
+
+ -- Escape sequence: \'
+     An escaped neutral apostrophe is a synonym for '\[aa]' (acute
+     accent).
+
+ -- Escape sequence: \`
+     An escaped grave accent is a synonym for '\[ga]' (grave accent).
+
+ -- Escape sequence: \-
+     An escaped hyphen-minus is a synonym for '\[-]' (minus sign).
+
+ -- Escape sequence: \_
+     An escaped underscore ("low line") is a synonym for '\[ul]'
+     (underrule).  On typesetting devices, the underrule is
+     font-invariant and drawn lower than the underscore '_'.
+
+ -- Request: .cflags n c1 c2 ...
+     Assign properties encoded by the number N to characters C1, C2, and
+     so on.
+
+     Input characters, including special characters introduced by an
+     escape, have certain properties associated with them.(4)  (*note
+     Using Symbols-Footnote-4::) These properties can be modified with
+     this request.  The first argument is the sum of the desired flags
+     and the remaining arguments are the characters to be assigned those
+     properties.  Spaces between the CN arguments are optional.  Any
+     argument CN can be a character class defined with the 'class'
+     request rather than an individual character.  *Note Character
+     Classes::.
+
+     The non-negative integer N is the sum of any of the following.
+     Some combinations are nonsensical, such as '33' (1 + 32).
+
+     '1'
+          Recognize the character as ending a sentence if followed by a
+          newline or two spaces.  Initially, characters '.?!' have this
+          property.
+
+     '2'
+          Enable breaks before the character.  A line is not broken at a
+          character with this property unless the characters on each
+          side both have non-zero hyphenation codes.  This exception can
+          be overridden by adding 64.  Initially, no characters have
+          this property.
+
+     '4'
+          Enable breaks after the character.  A line is not broken at a
+          character with this property unless the characters on each
+          side both have non-zero hyphenation codes.  This exception can
+          be overridden by adding 64.  Initially, characters
+          '\-\[hy]\[em]' have this property.
+
+     '8'
+          Mark the glyph associated with this character as overlapping
+          other instances of itself horizontally.  Initially, characters
+          '\[ul]\[rn]\[ru]\[radicalex]\[sqrtex]' have this property.
+
+     '16'
+          Mark the glyph associated with this character as overlapping
+          other instances of itself vertically.  Initially, the
+          character '\[br]' has this property.
+
+     '32'
+          Mark the character as transparent for the purpose of
+          end-of-sentence recognition.  In other words, an
+          end-of-sentence character followed by any number of characters
+          with this property is treated as the end of a sentence if
+          followed by a newline or two spaces.  This is the same as
+          having a zero space factor in TeX.  Initially, characters
+          '"')]*\[dg]\[dd]\[rq]\[cq]' have this property.
+
+     '64'
+          Ignore hyphenation codes of the surrounding characters.  Use
+          this in combination with values 2 and 4 (initially, no
+          characters have this property).
+
+          For example, if you need an automatic break point after the
+          en-dash in numeric ranges like "3000-5000", insert
+
+               .cflags 68 \[en]
+
+          into your document.  However, this practice can lead to bad
+          layout if done thoughtlessly; in most situations, a better
+          solution instead of changing the 'cflags' value is to insert
+          '\:' right after the hyphen at the places that really need a
+          break point.
+
+     The remaining values were implemented for East Asian language
+     support; those who use alphabetic scripts exclusively can disregard
+     them.
+
+     '128'
+          Prohibit a line break before the character, but allow a line
+          break after the character.  This works only in combination
+          with flags 256 and 512 and has no effect otherwise.
+          Initially, no characters have this property.
+
+     '256'
+          Prohibit a line break after the character, but allow a line
+          break before the character.  This works only in combination
+          with flags 128 and 512 and has no effect otherwise.
+          Initially, no characters have this property.
+
+     '512'
+          Allow line break before or after the character.  This works
+          only in combination with flags 128 and 256 and has no effect
+          otherwise.  Initially, no characters have this property.
+
+     In contrast to values 2 and 4, the values 128, 256, and 512 work
+     pairwise.  If, for example, the left character has value 512, and
+     the right character 128, no break will be automatically inserted
+     between them.  If we use value 6 instead for the left character, a
+     break after the character can't be suppressed since the neighboring
+     character on the right doesn't get examined.
+
+ -- Request: .char c [contents]
+ -- Request: .fchar c [contents]
+ -- Request: .fschar f c [contents]
+ -- Request: .schar c [contents]
+     Define a new character or glyph C to be CONTENTS, which can be
+     empty.  More precisely, 'char' defines a 'groff' object (or
+     redefines an existing one) that is accessed with the name C on
+     input, and produces CONTENTS on output.  Every time glyph C needs
+     to be printed, CONTENTS is processed in a temporary environment and
+     the result is wrapped up into a single object.  Compatibility mode
+     is turned off and the escape character is set to '\' while CONTENTS
+     is processed.  Any emboldening, constant spacing, or track kerning
+     is applied to this object rather than to individual glyphs in
+     CONTENTS.
+
+     An object defined by these requests can be used just like a normal
+     glyph provided by the output device.  In particular, other
+     characters can be translated to it with the 'tr' or 'trin'
+     requests; it can be made the leader character with the 'lc'
+     request; repeated patterns can be drawn with it using the '\l' and
+     '\L' escape sequences; and words containing C can be hyphenated
+     correctly if the 'hcode' request is used to give the object a
+     hyphenation code.
+
+     There is a special anti-recursion feature: use of the object within
+     its own definition is handled like a normal character (not defined
+     with 'char').
+
+     The 'tr' and 'trin' requests take precedence if 'char' accesses the
+     same symbol.
+
+          .tr XY
+          X
+              => Y
+          .char X Z
+          X
+              => Y
+          .tr XX
+          X
+              => Z
+
+     The 'fchar' request defines a fallback glyph: 'gtroff' only checks
+     for glyphs defined with 'fchar' if it cannot find the glyph in the
+     current font.  'gtroff' carries out this test before checking
+     special fonts.
+
+     'fschar' defines a fallback glyph for font F: 'gtroff' checks for
+     glyphs defined with 'fschar' after the list of fonts declared as
+     font-specific special fonts with the 'fspecial' request, but before
+     the list of fonts declared as global special fonts with the
+     'special' request.
+
+     Finally, the 'schar' request defines a global fallback glyph:
+     'gtroff' checks for glyphs defined with 'schar' after the list of
+     fonts declared as global special fonts with the 'special' request,
+     but before the already mounted special fonts.
+
+     *Note Character Classes::.
+
+ -- Request: .rchar c ...
+ -- Request: .rfschar f c ...
+     Remove definition of each ordinary or special character C, undoing
+     the effect of a 'char', 'fchar', or 'schar' request.  Those
+     supplied by font description files cannot be removed.  Spaces and
+     tabs may separate C arguments.
+
+     The request 'rfschar' removes glyph definitions defined with
+     'fschar' for font F.
+
+
+File: groff.info,  Node: Using Symbols-Footnotes,  Up: Using Symbols
+
+   (1) Not all versions of the 'man' program support the '-T' option;
+use the subsequent example for an alternative.
+
+   (2) This is "Normalization Form D" as documented in Unicode Standard
+Annex #15 (<https://unicode.org/reports/tr15/>).
+
+   (3) *Note Compatibility Mode::.
+
+   (4) Output glyphs don't--to GNU 'troff', a glyph is simply a box with
+an index into a font, a given height above and depth below the baseline,
+and a width.
+
+
+File: groff.info,  Node: Character Classes,  Next: Special Fonts,  Prev: Using Symbols,  Up: Using Fonts
+
+5.19.5 Character Classes
+------------------------
+
+Classes are particularly useful for East Asian languages such as
+Chinese, Japanese, and Korean, where the number of needed characters is
+much larger than in European languages, and where large sets of
+characters share the same properties.
+
+ -- Request: .class name c1 c2 ...
+     Define a character class (or simply "class") NAME comprising the
+     characters C1, C2, and so on.
+
+     A class thus defined can then be referred to in lieu of listing all
+     the characters within it.  Currently, only the 'cflags' request can
+     handle references to character classes.
+
+     In the request's simplest form, each CN is a character (or special
+     character).
+
+          .class [quotes] ' \[aq] \[dq] \[oq] \[cq] \[lq] \[rq]
+
+     Since class and glyph names share the same name space, it is
+     recommended to start and end the class name with '[' and ']',
+     respectively, to avoid collisions with existing character names
+     defined by GNU 'troff' or the user (with 'char' and related
+     requests).  This practice applies the presence of ']' in the class
+     name to prevent the use of the special character escape form
+     '\[...]', thus you must use the '\C' escape to access a class with
+     such a name.
+
+     You can also use a character range notation consisting of a start
+     character followed by '-' and then an end character.  Internally,
+     GNU 'troff' converts these two symbol names to Unicode code points
+     (according to the 'groff' glyph list [GGL]), which then give the
+     start and end value of the range.  If that fails, the class
+     definition is skipped.
+
+     Furthermore, classes can be nested.
+
+          .class [prepunct] , : ; > }
+          .class [prepunctx] \C'[prepunct]' \[u2013]-\[u2016]
+
+     The class '[prepunctx]' thus contains the contents of the class
+     '[prepunct]' as defined above (the set ', : ; > }'), and characters
+     in the range between 'U+2013' and 'U+2016'.
+
+     If you want to include '-' in a class, it must be the first
+     character value in the argument list, otherwise it gets
+     misinterpreted as part of the range syntax.
+
+     It is not possible to use class names as end points of range
+     definitions.
+
+     A typical use of the 'class' request is to control line-breaking
+     and hyphenation rules as defined by the 'cflags' request.  For
+     example, to inhibit line breaks before the characters belonging to
+     the 'prepunctx' class defined in the previous example, you can
+     write the following.
+
+          .cflags 2 \C'[prepunctx]'
+
+     See the 'cflags' request in *note Using Symbols::, for more
+     details.
+
+
+File: groff.info,  Node: Special Fonts,  Next: Artificial Fonts,  Prev: Character Classes,  Up: Using Fonts
+
+5.19.6 Special Fonts
+--------------------
+
+Special fonts are those that 'gtroff' searches when it cannot find the
+requested glyph in the current font.  The Symbol font is usually a
+special font.
+
+   'gtroff' provides the following two requests to add more special
+fonts.  *Note Using Symbols::, for a detailed description of the glyph
+searching mechanism in 'gtroff'.
+
+   Usually, only non-TTY devices have special fonts.
+
+ -- Request: .special [s1 s2 ...]
+ -- Request: .fspecial f [s1 s2 ...]
+     Use the 'special' request to define special fonts.  Initially, this
+     list is empty.
+
+     Use the 'fspecial' request to designate special fonts only when
+     font F is active.  Initially, this list is empty.
+
+     Previous calls to 'special' or 'fspecial' are overwritten; without
+     arguments, the particular list of special fonts is set to empty.
+     Special fonts are searched in the order they appear as arguments.
+
+     All fonts that appear in a call to 'special' or 'fspecial' are
+     loaded.
+
+     *Note Using Symbols::, for the exact search order of glyphs.
+
+
+File: groff.info,  Node: Artificial Fonts,  Next: Ligatures and Kerning,  Prev: Special Fonts,  Up: Using Fonts
+
+5.19.7 Artificial Fonts
+-----------------------
+
+There are a number of requests and escape sequences for artificially
+creating fonts.  These are largely vestiges of the days when output
+devices did not have a wide variety of fonts, and when 'nroff' and
+'troff' were separate programs.  Most of them are no longer necessary in
+GNU 'troff'.  Nevertheless, they are supported.
+
+ -- Escape sequence: \H'height'
+ -- Escape sequence: \H'+height'
+ -- Escape sequence: \H'-height'
+ -- Register: \n[.height]
+     Change (increment, decrement) the height of the current font, but
+     not the width.  If HEIGHT is zero, restore the original height.
+     Default scaling unit is 'z'.
+
+     The read-only register '.height' contains the font height as set by
+     '\H'.
+
+     Currently, only the '-Tps' and '-Tpdf' devices support this
+     feature.
+
+     '\H' doesn't produce an input token in GNU 'troff'.  As a
+     consequence, it can be used in requests like 'mc' (which expects a
+     single character as an argument) to change the font on the fly:
+
+          .mc \H'+5z'x\H'0'
+
+     In compatibility mode, 'gtroff' behaves differently: If an
+     increment or decrement is used, it is always taken relative to the
+     current type size and not relative to the previously selected font
+     height.  Thus,
+
+          .cp 1
+          \H'+5'test \H'+5'test
+
+     prints the word 'test' twice with the same font height (five points
+     larger than the current font size).
+
+ -- Escape sequence: \S'slant'
+ -- Register: \n[.slant]
+     Slant the current font by SLANT degrees.  Positive values slant to
+     the right.  Only integer values are possible.
+
+     The read-only register '.slant' contains the font slant as set by
+     '\S'.
+
+     Currently, only the '-Tps' and '-Tpdf' devices support this
+     feature.
+
+     '\S' doesn't produce an input token in GNU 'troff'.  As a
+     consequence, it can be used in requests like 'mc' (which expects a
+     single character as an argument) to change the font on the fly:
+
+          .mc \S'20'x\S'0'
+
+     This escape is incorrectly documented in the AT&T 'troff' manual;
+     the slant is always set to an absolute value.
+
+ -- Request: .ul [lines]
+     The 'ul' request normally underlines subsequent lines if a TTY
+     output device is used.  Otherwise, the lines are printed in italics
+     (only the term 'underlined' is used in the following).  The single
+     argument is the quantity of input lines to be underlined; with no
+     argument, the next line is underlined.  If LINES is zero or
+     negative, stop the effects of 'ul' (if it was active).  Requests
+     and empty lines do not count for computing the number of underlined
+     input lines, even if they produce some output like 'tl'.  Lines
+     inserted by macros (e.g., invoked by a trap) do count.
+
+     At the beginning of 'ul', the current font is stored and the
+     underline font is activated.  Within the span of a 'ul' request, it
+     is possible to change fonts, but after the last line affected by
+     'ul' the saved font is restored.
+
+     This number of lines still to be underlined is associated with the
+     environment (*note Environments::).  The underline font can be
+     changed with the 'uf' request.
+
+     The 'ul' request does not underline spaces.
+
+ -- Request: .cu [lines]
+     The 'cu' request is similar to 'ul' but underlines spaces as well
+     (if a TTY output device is used).
+
+ -- Request: .uf font
+     Set the underline font (globally) used by 'ul' and 'cu'.  By
+     default, this is the font at position 2.  FONT can be either a
+     non-negative font position or the name of a font.
+
+ -- Request: .bd font [offset]
+ -- Request: .bd font1 font2 [offset]
+ -- Register: \n[.b]
+     Embolden FONT by overstriking its glyphs offset by OFFSET units
+     minus one.
+
+     Two syntax forms are available.
+
+        * Imitate a bold font unconditionally.  The first argument
+          specifies the font to embolden, and the second is the number
+          of basic units, minus one, by which the two glyphs are offset.
+          If the second argument is missing, emboldening is turned off.
+
+          FONT can be either a non-negative font position or the name of
+          a font.
+
+          OFFSET is available in the '.b' read-only register if a
+          special font is active; in the 'bd' request, its default unit
+          is 'u'.
+
+        * Imitate a bold form conditionally.  Embolden FONT1 by OFFSET
+          only if font FONT2 is the current font.  This request can be
+          issued repeatedly to set up different emboldening values for
+          different current fonts.  If the second argument is missing,
+          emboldening is turned off for this particular current font.
+
+          This affects special fonts only (either set up with the
+          'special' command in font files or with the 'fspecial'
+          request).
+
+ -- Request: .cs font [width [em-size]]
+     Switch to and from "constant glyph space mode".  If activated, the
+     width of every glyph is WIDTH/36 ems.  The em size is given
+     absolutely by EM-SIZE; if this argument is missing, the em value is
+     taken from the current font size (as set with the 'ps' request)
+     when the font is effectively in use.  Without second and third
+     argument, constant glyph space mode is deactivated.
+
+     Default scaling unit for EM-SIZE is 'z'; WIDTH is an integer.
+
+
+File: groff.info,  Node: Ligatures and Kerning,  Next: Dummy Characters,  Prev: Artificial Fonts,  Up: Using Fonts
+
+5.19.8 Ligatures and Kerning
+----------------------------
+
+Ligatures are groups of characters that are run together, i.e, producing
+a single glyph.  For example, the letters 'f' and 'i' can form a
+ligature 'fi' as in the word 'file'.  This produces a cleaner look
+(albeit subtle) to the printed output.  Usually, ligatures are not
+available in fonts for TTY output devices.
+
+   Most PostScript fonts support the fi and fl ligatures.  The C/A/T
+typesetter that was the target of AT&T 'troff' also supported 'ff',
+'ffi', and 'ffl' ligatures.  Advanced typesetters or 'expert' fonts may
+include ligatures for 'ft' and 'ct', although GNU 'troff' does not
+support these (yet).
+
+   Only the current font is checked for ligatures and kerns; neither
+special fonts nor special charcters defined with the 'char' request (and
+its siblings) are taken into account.
+
+ -- Request: .lg [flag]
+ -- Register: \n[.lg]
+     Switch the ligature mechanism on or off; if the parameter is
+     non-zero or missing, ligatures are enabled, otherwise disabled.
+     Default is on.  The current ligature mode can be found in the
+     read-only register '.lg' (set to 1 or 2 if ligatures are enabled,
+     0 otherwise).
+
+     Setting the ligature mode to 2 enables the two-character ligatures
+     (fi, fl, and ff) and disables the three-character ligatures (ffi
+     and ffl).
+
+   "Pairwise kerning" is another subtle typesetting mechanism that
+modifies the distance between a glyph pair to improve readability.  In
+most cases (but not always) the distance is decreased.  Typewriter-like
+fonts and fonts for terminals where all glyphs have the same width don't
+use kerning.
+
+ -- Request: .kern [flag]
+ -- Register: \n[.kern]
+     Switch kerning on or off.  If the parameter is non-zero or missing,
+     enable pairwise kerning, otherwise disable it.  The read-only
+     register '.kern' is set to 1 if pairwise kerning is enabled,
+     0 otherwise.
+
+     If the font description file contains pairwise kerning information,
+     glyphs from that font are kerned.  Kerning between two glyphs can
+     be inhibited by placing '\&' between them: 'V\&A'.
+
+     *Note Font Description File Format::.
+
+   "Track kerning" expands or reduces the space between glyphs.  This
+can be handy, for example, if you need to squeeze a long word onto a
+single line or spread some text to fill a narrow column.  It must be
+used with great care since it is usually considered bad typography if
+the reader notices the effect.
+
+ -- Request: .tkf f s1 n1 s2 n2
+     Enable track kerning for font F.  If the current font is F the
+     width of every glyph is increased by an amount between N1 and N2
+     (N1, N2 can be negative); if the current type size is less than or
+     equal to S1 the width is increased by N1; if it is greater than or
+     equal to S2 the width is increased by N2; if the type size is
+     greater than or equal to S1 and less than or equal to S2 the
+     increase in width is a linear function of the type size.
+
+     The default scaling unit is 'z' for S1 and S2, 'p' for N1 and N2.
+
+     The track kerning amount is added even to the rightmost glyph in a
+     line; for large values it is thus recommended to increase the line
+     length by the same amount to compensate.
+
+
+File: groff.info,  Node: Italic Corrections,  Next: Dummy Characters,  Prev: Ligatures and Kerning,  Up: Using Fonts
+
+5.19.9 Italic Corrections
+-------------------------
+
+When typesetting adjacent glyphs from typefaces of different slants, the
+space between them may require adjustment.
+
+ -- Escape sequence: \/
+     Apply an "italic correction": modify the spacing of the preceding
+     glyph so that the distance between it and the following glyph is
+     correct if the latter is of upright shape.  For example, if an
+     italic 'f' is followed immediately by a roman right parenthesis,
+     then in many fonts the top right portion of the 'f' overlaps the
+     top left of the right parenthesis, which is ugly.  Use this escape
+     sequence whenever an oblique glyph is immediately followed by an
+     upright glyph without any intervening space.
+
+ -- Escape sequence: \,
+     Apply a "left italic correction": modify the spacing of the
+     following glyph so that the distance between it and the preceding
+     glyph is correct if the latter is of upright shape.  For example,
+     if a roman left parenthesis is immediately followed by an
+     italic 'f', then in many fonts the bottom left portion of the 'f'
+     overlaps the bottom of the left parenthesis, which is ugly.  Use
+     this escape sequence whenever an upright glyph is followed
+     immediately by an oblique glyph without any intervening space.
+
+
+File: groff.info,  Node: Dummy Characters,  Prev: Italic Corrections,  Up: Using Fonts
+
+5.19.10 Dummy Characters
+------------------------
+
+As discussed in *note Requests and Macros::, the first character on an
+input line is treated specially.  Further, formatting a glyph has many
+consequences on formatter state (*note Environments::).  Occasionally,
+we want to escape this context or embrace some of those consequences
+without actually rendering a glyph to the output.
+
+ -- Escape sequence: \&
+     Interpolate a dummy character, which is constitutive of output but
+     invisible.(1)  (*note Dummy Characters-Footnote-1::) Its presence
+     alters the interpretation context of a subsequent input character,
+     and enjoys several applications.
+
+        * Prevent insertion of extra space after an end-of-sentence
+          character.
+
+               Test.
+               Test.
+                   => Test.  Test.
+               Test.\&
+               Test.
+                   => Test. Test.
+
+        * Prevent recognition of a control character.
+
+               .Test
+                   error-> warning: macro 'Test' not defined
+               \&.Test
+                   => .Test
+
+        * Prevent kerning between two glyphs.
+
+        * Translate a character to "nothing".
+
+               .tr JIjiK\&k\&UVuv
+               Post universitum, alea jacta est, OK?
+                   => Post vniversitvm, alea iacta est, O?
+
+     The dummy character escape sequence sees use in macro definitions
+     as a means of ensuring that arguments are treated as text even if
+     they begin with spaces or control characters.
+
+          .de HD \" typeset a simple bold heading
+          .  sp
+          .  ft B
+          \&\\$1 \" exercise: remove the \&
+          .  ft
+          .  sp
+          ..
+          .HD .\|.\|.\|surprised?
+
+   One way to think about the dummy character is to imagine placing the
+symbol '&' in the input at a certain location; if doing so has all the
+side effects on formatting that you desire except for sticking an ugly
+ampersand in the midst of your text, the dummy character is what you
+want in its place.
+
+ -- Escape sequence: \)
+     Interpolate a transparent dummy character--one that is transparent
+     to end-of-sentence detection.  It behaves as '\&', except that '\&'
+     is treated as letters and numerals normally are after '.', '?' and
+     '!'; '\&' cancels end-of-sentence detection, and '\)' does not.
+
+          .de Suffix-&
+          .  nop \&\\$1
+          ..
+          .
+          .de Suffix-)
+          .  nop \)\\$1
+          ..
+          .
+          Here's a sentence.\c
+          .Suffix-& '
+          Another one.\c
+          .Suffix-) '
+          And a third.
+              => Here's a sentence.' Another one.'  And a third.
+
+
+File: groff.info,  Node: Dummy Characters-Footnotes,  Up: Dummy Characters
+
+   (1) Opinions of this escape sequence's name abound.  "Zero-width
+space" is a popular misnomer: 'roff' formatters do not treat it like a
+space.  Ossanna called it a "non-printing, zero-width character", but
+the character causes _output_ even though it does not "print".  If no
+output line is pending, the dummy character starts one.  Contrast an
+empty input document with one containing only '\&'.  The former produces
+no output; the latter, a blank page.
+
+
+File: groff.info,  Node: Manipulating Type Size and Vertical Spacing,  Next: Colors,  Prev: Using Fonts,  Up: GNU troff Reference
+
+5.20 Manipulating Type Size and Vertical Spacing
+================================================
+
+These concepts were introduced in *note Page Geometry::.  The height of
+a font's tallest glyph is one em, which is equal to the type size in
+points.(1)  (*note Manipulating Type Size and Vertical
+Spacing-Footnote-1::) A vertical spacing of less than 120% of the type
+size can make a document hard to read.  Larger proportions can be useful
+to spread the text for annotations or proofreader's marks.  By default,
+GNU 'troff' uses 10 point type on 12 point spacing.  Typographers call
+the difference between type size and vertical spacing "leading".(2)
+(*note Manipulating Type Size and Vertical Spacing-Footnote-2::)
+
+* Menu:
+
+* Changing the Type Size::
+* Changing the Vertical Spacing::
+* Using Fractional Type Sizes::
+
+
+File: groff.info,  Node: Manipulating Type Size and Vertical Spacing-Footnotes,  Up: Manipulating Type Size and Vertical Spacing
+
+   (1) In text fonts, the tallest glyphs are typically parentheses.
+Unfortunately, in many cases the actual dimensions of the glyphs in a
+font do not closely match its declared type size!  For example, in the
+standard PostScript font families, 10-point Times sets better with
+9-point Helvetica and 11-point Courier than if all three were used at
+10 points.
+
+   (2) Rhyme with "sledding"; mechanical typography used lead metal
+(Latin _plumbum_).
+
+
+File: groff.info,  Node: Changing the Type Size,  Next: Changing the Vertical Spacing,  Prev: Manipulating Type Size and Vertical Spacing,  Up: Manipulating Type Size and Vertical Spacing
+
+5.20.1 Changing the Type Size
+-----------------------------
+
+ -- Request: .ps [size]
+ -- Request: .ps +size
+ -- Request: .ps -size
+ -- Escape sequence: \ssize
+ -- Register: \n[.s]
+     Use the 'ps' request or the '\s' escape sequence to change
+     (increase, decrease) the type size (in scaled points).  Specify
+     SIZE as either an absolute type size, or as a relative change from
+     the current size.  'ps' with no argument restores the previous
+     size.  The 'ps' request's default scaling unit is 'z'.  The
+     requested size is rounded to the nearest valid size (with ties
+     rounding down) within the limits supported by the device.  If the
+     requested size is non-positive, it is treated as 1u.
+
+     Type size alteration is incorrectly documented in the AT&T 'troff'
+     manual, which claims "if [the requested size] is invalid, the next
+     larger valid size will result, with a maximum of 36".(1)  (*note
+     Changing the Type Size-Footnote-1::)
+
+     The read-only string-valued register '.s' interpolates the type
+     size in points as a decimal fraction; it is associated with the
+     environment (*note Environments::).  To obtain the type size in
+     scaled points, interpolate the '.ps' register instead (*note Using
+     Fractional Type Sizes::).
+
+     The '\s' escape sequence supports a variety of syntax forms.
+
+     '\sN'
+          Set the type size to N points.  N must be a single digit.  If
+          N is 0, restore the previous size.
+
+     '\s+N'
+     '\s-N'
+          Increase or decrease the type size by N points.  N must be
+          exactly one digit.
+
+     '\s(NN'
+          Set the type size to NN points.  NN must be exactly two
+          digits.
+
+     '\s+(NN'
+     '\s-(NN'
+     '\s(+NN'
+     '\s(-NN'
+          Alter the type size in points by the two-digit value NN.
+
+     *Note Using Fractional Type Sizes::, for further syntactical forms
+     of the '\s' escape sequence that additionally accept decimal
+     fractions.
+
+          snap, snap,
+          .ps +2
+          grin, grin,
+          .ps +2
+          wink, wink, \s+2nudge, nudge,\s+8 say no more!
+          .ps 10
+
+   The '\s' escape sequence affects the environment immediately and
+doesn't produce an input token.  Consequently, it can be used in
+requests like 'mc', which expects a single character as an argument, to
+change the type size on the fly.
+
+     .mc \s[20]x\s[0]
+
+ -- Request: .sizes s1 s2 ... sn [0]
+     The 'DESC' file specifies which type sizes are allowed by the
+     output device; see *note DESC File Format::.  Use the 'sizes'
+     request to change this set of permissible sizes.  Arguments are in
+     scaled points; see *note Using Fractional Type Sizes::.  Each can
+     be a single type size (such as '12000'), or a range of sizes (such
+     as '4000-72000').  You can optionally end the list with a '0'.
+
+
+File: groff.info,  Node: Changing the Type Size-Footnotes,  Up: Changing the Type Size
+
+   (1) The claim appears to have been true of Ossanna 'troff' for the
+C/A/T device; Kernighan made device-independent 'troff' more flexible.
+
+
+File: groff.info,  Node: Changing the Vertical Spacing,  Next: Using Fractional Type Sizes,  Prev: Changing the Type Size,  Up: Manipulating Type Size and Vertical Spacing
+
+5.20.2 Changing the Vertical Spacing
+------------------------------------
+
+ -- Request: .vs [space]
+ -- Request: .vs +space
+ -- Request: .vs -space
+ -- Register: \n[.v]
+     Set the vertical spacing to, or alter it by, SPACE.  The default
+     scaling unit is 'p'.  If 'vs' is called without an argument, the
+     vertical spacing is reset to the previous value before the last
+     call to 'vs'.  GNU 'troff' emits a warning in category 'range' if
+     SPACE is negative; the vertical spacing is then set to the smallest
+     possible positive value, the vertical motion quantum (as found in
+     the '.V' register).
+
+     '.vs 0' isn't saved in a diversion since it doesn't result in a
+     vertical motion.  You must explicitly issue this request before
+     interpolating the diversion.
+
+     The read-only register '.v' contains the vertical spacing; it is
+     associated with the environment (*note Environments::).
+
+When a break occurs, GNU 'troff' performs the following procedure.
+
+   * Move the drawing position vertically by the "extra pre-vertical
+     line space", the minimum of all negative '\x' escape sequence
+     arguments in the pending output line.
+
+   * Move the drawing position vertically by the vertical line spacing.
+
+   * Write out the pending output line.
+
+   * Move the drawing position vertically by the "extra post-vertical
+     line space", the maximum of all positive '\x' escape sequence
+     arguments in the line that has just been output.
+
+   * Move the drawing position vertically by the "post-vertical line
+     spacing" (see below).
+
+   Prefer 'vs' or 'pvs' over 'ls' to produce double-spaced documents.
+'vs' and 'pvs' have finer granularity than 'ls'; moreover, some
+preprocessors assume single spacing.  *Note Manipulating Spacing::,
+regarding the '\x' escape sequence and the 'ls' request.
+
+ -- Request: .pvs [space]
+ -- Request: .pvs +space
+ -- Request: .pvs -space
+ -- Register: \n[.pvs]
+     Set the post-vertical spacing to, or alter it by, SPACE.  The
+     default scaling unit is 'p'.  If 'pvs' is called without an
+     argument, the post-vertical spacing is reset to the previous value
+     before the last call to 'pvs'.  GNU 'troff' emits a warning in
+     category 'range' if SPACE is negative; the post-vertical spacing is
+     then set to zero.
+
+     The read-only register '.pvs' contains the post-vertical spacing;
+     it is associated with the environment (*note Environments::).
+
+
+File: groff.info,  Node: Using Fractional Type Sizes,  Prev: Changing the Type Size,  Up: Manipulating Type Size and Vertical Spacing
+
+5.20.3 Using Fractional Type Sizes
+----------------------------------
+
+AT&T 'troff' interpreted all type size measurements in points.  Combined
+with integer arithmetic, this design choice made it impossible to
+support, for instance, ten and a half-point type.  In GNU 'troff', an
+output device can select a scaling factor that subdivides a point into
+"scaled points".  A type size expressed in scaled points can thus
+represent a non-integral type size.
+
+   A "scaled point" is equal to 1/SIZESCALE points, where SIZESCALE is
+specified in the device description file 'DESC', and defaults to 1.(1)
+(*note Using Fractional Type Sizes-Footnote-1::) Requests and escape
+sequences in GNU 'troff' interpret arguments that represent a type size
+in scaled points, which the formatter multiplies by SIZESCALE and
+converts to an integer.  Arguments treated in this way comprise those to
+the escape sequences '\H' and '\s', to the request 'ps', the third
+argument to the 'cs' request, and the second and fourth arguments to the
+'tkf' request.  Scaled points may be specified explicitly with the 'z'
+scaling unit.
+
+   For example, if SIZESCALE is 1000, then a scaled point is one
+thousandth of a point.  The request '.ps 10.5' is synonymous with '.ps
+10.5z' and sets the type size to 10,500 scaled points, or 10.5 points.
+Consequently, in GNU 'troff', the register '.s' can interpolate a
+non-integral type size.
+
+ -- Register: \n[.ps]
+     This read-only register interpolates the type size in scaled
+     points; it is associated with the environment (*note
+     Environments::).
+
+   It makes no sense to use the 'z' scaling unit in a numeric expression
+whose default scaling unit is neither 'u' nor 'z', so GNU 'troff'
+disallows this.  Similarly, it is nonsensical to use a scaling unit
+other than 'z' or 'u' in a numeric expression whose default scaling unit
+is 'z', and so GNU 'troff' disallows this as well.
+
+   Another GNU 'troff' scaling unit, 's', multiplies by the number of
+basic units in a scaled point.  Thus, '\n[.ps]s' is equal to '1m' by
+definition.  Do not confuse the 's' and 'z' scaling units.
+
+ -- Register: \n[.psr]
+ -- Register: \n[.sr]
+     Output devices may be limited in the type sizes they can employ.
+     The '.s' and '.ps' registers represent the type size selected by
+     the output driver as it understands a device's capability.  The
+     last _requested_ type size is interpolated in scaled points by the
+     read-only register '.psr' and in points as a decimal fraction by
+     the read-only string-valued register '.sr'.  Both are associated
+     with the environment (*note Environments::).
+
+     For example, if a type size of 10.95 points is requested, and the
+     nearest size permitted by a 'sizes' request (or by the 'sizes' or
+     'sizescale' directives in the device's 'DESC' file) is 11 points,
+     the output driver uses the latter value.
+
+   The '\s' escape sequence offers the following syntax forms that work
+with fractional type sizes and accept scaling units.  You may of course
+give them integral arguments.  The delimited forms need not use the
+neutral apostrophe; see *note Delimiters::.
+
+'\s[N]'
+'\s'N''
+     Set the type size to N scaled points; N is a numeric expression
+     with a default scaling unit of 'z'.
+
+'\s[+N]'
+'\s[-N]'
+'\s+[N]'
+'\s-[N]'
+'\s'+N''
+'\s'-N''
+'\s+'N''
+'\s-'N''
+     Increase or decrease the type size by N scaled points; N is a
+     numeric expression (which may start with a minus sign) with a
+     default scaling unit of 'z'.
+
+
+File: groff.info,  Node: Using Fractional Type Sizes-Footnotes,  Up: Using Fractional Type Sizes
+
+   (1) *Note Device and Font Description Files::.
+
+
+File: groff.info,  Node: Colors,  Next: Strings,  Prev: Manipulating Type Size and Vertical Spacing,  Up: GNU troff Reference
+
+5.21 Colors
+===========
+
+GNU 'troff' supports color output with a variety of color spaces and up
+to 16 bits per channel.  Some devices, particularly terminals, may be
+more limited.  When color support is enabled, two colors are current at
+any given time: the "stroke color", with which glyphs, rules (lines),
+and geometric objects like circles and polygons are drawn, and the "fill
+color", which can be used to paint the interior of a closed geometric
+figure.
+
+ -- Request: .color [n]
+ -- Register: \n[.color]
+     If N is missing or non-zero, enable the output of color-related
+     device-independent output commands (this is the default);
+     otherwise, disable them.  This request sets a global flag; it does
+     not produce an input token (*note Gtroff Internals::).
+
+     The read-only register '.color' is 1 if colors are enabled,
+     0 otherwise.
+
+     Color can also be disabled with the '-c' command-line option.
+
+ -- Request: .defcolor ident scheme color-component ...
+     Define a color named IDENT.  SCHEME selects a color space and
+     determines the quantity of required COLOR-COMPONENTs; it must be
+     one of 'rgb' (three components), 'cmy' (three), 'cmyk' (four), or
+     'gray' (one).  'grey' is accepted as a synonym of 'gray'.  The
+     color components can be encoded as a single hexadecimal value
+     starting with '#' or '##'.  The former indicates that each
+     component is in the range 0-255 (0-FF), the latter the range
+     0-65,535 (0-FFFF).
+
+          .defcolor half gray #7f
+          .defcolor pink rgb #FFC0CB
+          .defcolor magenta rgb  ##ffff0000ffff
+
+     Alternatively, each color component can be specified as a decimal
+     fraction in the range 0-1, interpreted using a default scaling unit
+     of 'f', which multiplies its value by 65,536 (but clamps it at
+     65,535).
+
+          .defcolor gray50 rgb 0.5 0.5 0.5
+          .defcolor darkgreen rgb 0.1f 0.5f 0.2f
+
+   Each output device has a color named 'default', which cannot be
+redefined.  A device's default stroke and fill colors are not
+necessarily the same.  For the 'dvi', 'html', 'pdf', 'ps', and 'xhtml'
+output devices, GNU 'troff' automatically loads a macro file defining
+many color names at startup.  By the same mechanism, the devices
+supported by 'grotty' recognize the eight standard ISO 6429/EMCA-48
+color names.(1)  (*note Colors-Footnote-1::)
+
+ -- Request: .gcolor [color]
+ -- Escape sequence: \mc
+ -- Escape sequence: \m(co
+ -- Escape sequence: \m[color]
+ -- Register: \n[.m]
+     Set the stroke color to COLOR.
+
+          .gcolor red
+          The next words
+          .gcolor
+          \m[red]are in red\m[]
+          and these words are in the previous color.
+
+     The escape sequence '\m[]' restores the previous stroke color, as
+     does a 'gcolor' request without an argument.
+
+     The name of the current stroke color is available in the read-only
+     string-valued register '.m'; it is associated with the environment
+     (*note Environments::).  It interpolates nothing when the stroke
+     color is the default.
+
+     '\m' doesn't produce an input token in GNU 'troff' (*note Gtroff
+     Internals::).  It therefore can be used in requests like 'mc'
+     (which expects a single character as an argument) to change the
+     color on the fly:
+
+          .mc \m[red]x\m[]
+
+ -- Request: .fcolor [color]
+ -- Escape sequence: \Mc
+ -- Escape sequence: \M(co
+ -- Escape sequence: \M[color]
+ -- Register: \n[.M]
+     Set the fill color for objects drawn with '\D'...'' escape
+     sequences.  The escape sequence '\M[]' restores the previous fill
+     color, as does an 'fcolor' request without an argument.
+
+     The name of the current fill color is available in the read-only
+     string-valued register '.M'; it is associated with the environment
+     (*note Environments::).  It interpolates nothing when the fill
+     color is the default.  '\M' doesn't produce an input token in GNU
+     'troff'.
+
+     Create an ellipse with a red interior as follows.
+
+          \M[red]\h'0.5i'\D'E 2i 1i'\M[]
+
+
+File: groff.info,  Node: Colors-Footnotes,  Up: Colors
+
+   (1) also known vulgarly as "ANSI colors"
+
+
+File: groff.info,  Node: Strings,  Next: Conditionals and Loops,  Prev: Colors,  Up: GNU troff Reference
+
+5.22 Strings
+============
+
+GNU 'troff' supports strings primarily for user convenience.
+Conventionally, if one would define a macro only to interpolate a small
+amount of text, without invoking requests or calling any other macros,
+one defines a string instead.  Only one string is predefined by the
+language.
+
+ -- String: \*[.T]
+     Contains the name of the output device (for example, 'utf8' or
+     'pdf').
+
+   The 'ds' request creates a string with a specified name and contents
+and the '\*' escape sequence dereferences its name, interpolating its
+contents.  If the string named by the '\*' escape sequence does not
+exist, it is defined as empty, nothing is interpolated, and a warning in
+category 'mac' is emitted.  *Note Warnings::, for information about the
+enablement and suppression of warnings.
+
+ -- Request: .ds name [contents]
+ -- Request: .ds1 name [contents]
+ -- Escape sequence: \*n
+ -- Escape sequence: \*(nm
+ -- Escape sequence: \*[name [arg1 arg2 ...]]
+     Define a string called NAME with contents CONTENTS.  If NAME
+     already exists as an alias, the target of the alias is redefined;
+     see 'als' and 'rm' below.  If 'ds' is called with only one
+     argument, NAME is defined as an empty string.  Otherwise, GNU
+     'troff' stores CONTENTS in copy mode.(1)  (*note
+     Strings-Footnote-1::)
+
+     The '\*' escape sequence interpolates a previously defined string
+     variable NAME (one-character name N, two-character name NM).  The
+     bracketed interpolation form accepts arguments that are handled as
+     macro arguments are; recall *note Calling Macros::.  In contrast to
+     macro calls, however, if a closing bracket ']' occurs in a string
+     argument, that argument must be enclosed in double quotes.  '\*' is
+     interpreted even in copy mode.  When defining strings, argument
+     interpolations must be escaped if they are to reference parameters
+     from the calling context; *Note Parameters::.
+
+          .ds cite (\\$1, \\$2)
+          Gray codes are explored in \*[cite Morgan 1998].
+              => Gray codes are explored in (Morgan, 1998).
+
+     *Caution:* Unlike other requests, the second argument to the 'ds'
+     request consumes the remainder of the input line, including
+     trailing spaces.  This means that comments on a line with such a
+     request can introduce unwanted space into a string when they are
+     set off from the material they annotate, as is conventional.
+
+          .ds H2O H\v'+.3m'\s'-2'2\v'-.3m'\s0O \" water
+
+     Instead, place the comment on another line or put the comment
+     escape sequence immediately adjacent to the last character of the
+     string.
+
+          .ds H2O H\v'+.3m'\s'-2'2\v'-.3m'\s0O\" water
+
+     Ending string definitions (and appendments) with a comment, even an
+     empty one, prevents unwanted space from creeping into them during
+     source document maintenance.
+
+          .ds author Alice Pleasance Liddell\"
+          .ds empty \" might be appended to later with .as
+
+     An initial neutral double quote '"' in CONTENTS is stripped to
+     allow embedding of leading spaces.  Any other '"' is interpreted
+     literally, but it is wise to use the special character escape
+     sequence '\[dq]' instead if the string might be interpolated as
+     part of a macro argument; see *note Calling Macros::.
+
+          .ds salutation "         Yours in a white wine sauce,\"
+          .ds c-var-defn "  char mydate[]=\[dq]2020-07-29\[dq];\"
+
+     Strings are not limited to a single input line of text.  '\<RET>'
+     works just as it does elsewhere.  The resulting string is stored
+     _without_ the newlines.  Care is therefore required when
+     interpolating strings while filling is disabled.
+
+          .ds foo This string contains \
+          text on multiple lines \
+          of input.
+
+     It is not possible to embed a newline in a string that will be
+     interpreted as such when the string is interpolated.  To achieve
+     that effect, use '\*' to interpolate a macro instead; see *note
+     Punning Names::.
+
+     Because strings are similar to macros, they too can be defined so
+     as to suppress AT&T 'troff' compatibility mode when used; see *note
+     Writing Macros:: and *note Compatibility Mode::.  The 'ds1' request
+     defines a string such that compatibility mode is off when the
+     string is later interpolated.  To be more precise, a "compatibility
+     save" input token is inserted at the beginning of the string, and a
+     "compatibility restore" input token at the end.
+
+          .nr xxx 12345
+          .ds aa The value of xxx is \\n[xxx].
+          .ds1 bb The value of xxx is \\n[xxx].
+          .
+          .cp 1
+          .
+          \*(aa
+              error-> warning: register '[' not defined
+              => The value of xxx is 0xxx].
+          \*(bb
+              => The value of xxx is 12345.
+
+ -- Request: .as name [contents]
+ -- Request: .as1 name [contents]
+     The 'as' request is similar to 'ds' but appends CONTENTS to the
+     string stored as NAME instead of redefining it.  If NAME doesn't
+     exist yet, it is created.  If 'as' is called with only one
+     argument, no operation is performed (beyond dereferencing the
+     string).
+
+          .as salutation " with shallots, onions and garlic,\"
+
+     The 'as1' request is similar to 'as', but compatibility mode is
+     switched off when the appended portion of the string is later
+     interpolated.  To be more precise, a "compatibility save" input
+     token is inserted at the beginning of the appended string, and a
+     "compatibility restore" input token at the end.
+
+   Several requests exist to perform rudimentary string operations.
+Strings can be queried ('length') and modified ('chop', 'substring',
+'stringup', 'stringdown'), and their names can be manipulated through
+renaming, removal, and aliasing ('rn', 'rm', 'als').
+
+ -- Request: .length reg anything
+     Compute the number of characters of ANYTHING and store the count in
+     the register REG.  If REG doesn't exist, it is created.  ANYTHING
+     is read in copy mode.
+
+          .ds xxx abcd\h'3i'efgh
+          .length yyy \*[xxx]
+          \n[yyy]
+              => 14
+
+ -- Request: .chop object
+     Remove the last character from the macro, string, or diversion
+     named OBJECT.  This is useful for removing the newline from the end
+     of a diversion that is to be interpolated as a string.  This
+     request can be used repeatedly on the same OBJECT; see *note Gtroff
+     Internals::, for details on nodes inserted additionally by GNU
+     'troff'.
+
+ -- Request: .substring str start [end]
+     Replace the string named STR with its substring bounded by the
+     indices START and END, inclusively.  The first character in the
+     string has index 0.  If END is omitted, it is implicitly set to the
+     largest valid value (the string length minus one).  Negative
+     indices count backward from the end of the string: the last
+     character has index -1, the character before the last has index -2,
+     and so on.
+
+          .ds xxx abcdefgh
+          .substring xxx 1 -4
+          \*[xxx]
+              => bcde
+          .substring xxx 2
+          \*[xxx]
+              => de
+
+ -- Request: .stringdown str
+ -- Request: .stringup str
+     Alter the string named STR by replacing each of its bytes with its
+     lowercase ('stringdown') or uppercase ('stringup') version (if one
+     exists).  Special characters in the string will often transform in
+     the expected way due to the regular naming convention for accented
+     characters.  When they do not, use substrings and/or catenation.
+
+          .ds resume R\['e]sum\['e]
+          \*[resume]
+          .stringdown resume
+          \*[resume]
+          .stringup resume
+          \*[resume]
+              => Résumé résumé RÉSUMÉ
+
+   (In practice, we would end the 'ds' request with a comment escape
+'\"' to prevent space from creeping into the definition during source
+document maintenance.)
+
+ -- Request: .rn old new
+     Rename the request, macro, diversion, or string OLD to NEW.
+
+ -- Request: .rm name
+     Remove the request, macro, diversion, or string NAME.  GNU 'troff'
+     treats subsequent invocations as if the name had never been
+     defined.
+
+ -- Request: .als new old
+     Create an alias NEW for the existing request, string, macro, or
+     diversion object named OLD, causing the names to refer to the same
+     stored object.  If OLD is undefined, a warning in category 'mac' is
+     produced, and the request is ignored.  *Note Warnings::, for
+     information about the enablement and suppression of warnings.
+
+     To understand how the 'als' request works, consider two different
+     storage pools: one for objects (macros, strings, etc.), and another
+     for names.  As soon as an object is defined, GNU 'troff' adds it to
+     the object pool, adds its name to the name pool, and creates a link
+     between them.  When 'als' creates an alias, it adds a new name to
+     the name pool that gets linked to the same object as the old name.
+
+     Now consider this example.
+
+          .de foo
+          ..
+          .
+          .als bar foo
+          .
+          .de bar
+          .  foo
+          ..
+          .
+          .bar
+              error-> input stack limit exceeded (probable infinite
+              error-> loop)
+
+     In the above, 'bar' remains an _alias_--another name for--the
+     object referred to by 'foo', which the second 'de' request
+     replaces.  Alternatively, imagine that the 'de' request
+     _dereferences_ its argument before replacing it.  Either way, the
+     result of calling 'bar' is a recursive loop that finally leads to
+     an error.  *Note Writing Macros::.
+
+     To remove an alias, call 'rm' on its name.  The object itself is
+     not destroyed until it has no more names.
+
+     When a request, macro, string, or diversion is aliased,
+     redefinitions and appendments "write through" alias names.  To
+     replace an alias with a separately defined object, you must use the
+     'rm' request on its name first.
+
+
+File: groff.info,  Node: Strings-Footnotes,  Up: Strings
+
+   (1) *Note Copy Mode::.
+
+
+File: groff.info,  Node: Conditionals and Loops,  Next: Writing Macros,  Prev: Strings,  Up: GNU troff Reference
+
+5.23 Conditionals and Loops
+===========================
+
+'groff' has 'if' and 'while' control structures like other languages.
+However, the syntax for grouping multiple input lines in the branches or
+bodies of these structures is unusual.
+
+* Menu:
+
+* Operators in Conditionals::
+* if-then::
+* if-else::
+* Conditional Blocks::
+* while::
+
+
+File: groff.info,  Node: Operators in Conditionals,  Next: if-then,  Prev: Conditionals and Loops,  Up: Conditionals and Loops
+
+5.23.1 Operators in Conditionals
+--------------------------------
+
+In 'if', 'ie', and 'while' requests, in addition to the numeric
+expressions described in *note Numeric Expressions::, several Boolean
+operators are available; the members of this expanded class are termed
+"conditional expressions".
+
+'c GLYPH'
+     True if GLYPH is available, where GLYPH is an ordinary character, a
+     special character '\(XX' or '\[XXX]', '\N'XXX'', or has been
+     defined by any of the 'char', 'fchar', 'fschar', or 'schar'
+     requests.
+
+'d NAME'
+     True if a string, macro, diversion, or request called NAME exists.
+
+'e'
+     True if the current page is even-numbered.
+
+'F FONT'
+     True if FONT exists.  FONT is handled as if it were opened with the
+     'ft' request (that is, font translation and styles are applied),
+     without actually mounting it.
+
+'m COLOR'
+     True if COLOR is defined.
+
+'n'
+     True if the document is being processed in 'nroff' mode.  *Note
+     troff and nroff Modes::.
+
+'o'
+     True if the current page is odd-numbered.
+
+'r REGISTER'
+     True if REGISTER exists.
+
+'S STYLE'
+     True if STYLE is available for the current font family.  Font
+     translation is applied.
+
+'t'
+     True if the document is being processed in 'troff' mode.  *Note
+     troff and nroff Modes::.
+
+'v'
+     Always false.  This condition is recognized only for compatibility
+     with certain other 'troff' implementations.(1)  (*note Operators in
+     Conditionals-Footnote-1::)
+
+   If the first argument to an 'if', 'ie', or 'while' request begins
+with a non-alphanumeric character apart from '!' (see below); it
+performs an output comparison test.  (2)  (*note Operators in
+Conditionals-Footnote-2::)
+
+''XXX'YYY''
+     True if formatting the comparands XXX and YYY produces the same
+     output commands.  The delimiter need not be a neutral apostrophe:
+     the output comparison operator accepts the same delimiters as most
+     escape sequences; see *note Delimiters::.  This "output comparison
+     operator" formats XXX and YYY in separate environments; after the
+     comparison, the resulting data are discarded.
+
+          .ie "|"\fR|\fP" true
+          .el false
+              => true
+
+     The resulting glyph properties, including font family, style, size,
+     and slant, must match, but not necessarily the requests and/or
+     escape sequences used to obtain them.  In the previous example, '|'
+     and '\fR|\fP' result in '|' glyphs in the same typefaces at the
+     same positions, so the comparands are equal.  If '.ft I' had been
+     added before the '.ie', they would differ: the first '|' would
+     produce an italic '|', not a roman one.  Motions must match in
+     orientation and magnitude to within the applicable horizontal and
+     vertical motion quanta of the device, after rounding.  '.if
+     "\u\d"\v'0'"' is false even though both comparands result in zero
+     net motion, because motions are not interpreted or optimized but
+     sent as-is to the output.(3)  (*note Operators in
+     Conditionals-Footnote-3::) On the other hand, '.if "\d"\v'0.5m'"'
+     is true, because '\d' is defined as a downward motion of one-half
+     em.(4)  (*note Operators in Conditionals-Footnote-4::)
+
+     Surround the comparands with '\?' to avoid formatting them; this
+     causes them to be compared character by character, as with string
+     comparisons in other programming languages.
+
+          .ie "\?|\?"\?\fR|\fP\?" true
+          .el false
+              => false
+
+     Since comparands protected with '\?' are read in copy mode (*note
+     Copy Mode::), they need not even be valid 'groff' syntax.  The
+     escape character is still lexically recognized, however, and
+     consumes the next character.
+
+          .ds a \[
+          .ds b \[
+          .if '\?\*a\?'\?\*b\?' a and b equivalent
+          .if '\?\\?'\?\\?' backslashes equivalent
+              => a and b equivalent
+
+   The above operators can't be combined with most others, but a leading
+'!', not followed immediately by spaces or tabs, complements an
+expression.
+
+     .nr x 1
+     .ie !r x register x is not defined
+     .el      register x is defined
+         => register x is defined
+
+   Spaces and tabs are optional immediately after the 'c', 'd', 'F',
+'m', 'r', and 'S' operators, but right after '!', they end the predicate
+and the conditional evaluates true.(5)  (*note Operators in
+Conditionals-Footnote-5::)
+
+     .nr x 1
+     .ie ! r x register x is not defined
+     .el       register x is defined
+         => r x register x is not defined
+
+The unexpected 'r x' in the output is a clue that our conditional was
+not interpreted as we planned, but matters may not always be so obvious.
+
+
+File: groff.info,  Node: Operators in Conditionals-Footnotes,  Up: Operators in Conditionals
+
+   (1) This refers to 'vtroff', a translator that would convert the
+C/A/T output from early-vintage AT&T 'troff' to a form suitable for
+Versatec and Benson-Varian plotters.
+
+   (2) Strictly, letters not otherwise recognized _are_ treated as
+output comparison delimiters.  For portability, it is wise to avoid
+using letters not in the list above; for example, Plan 9 'troff' uses
+'h' to test a mode it calls 'htmlroff', and GNU 'troff' may provide
+additional operators in the future.
+
+   (3) Because formatting of the comparands takes place in a dummy
+environment, vertical motions within them cannot spring traps.
+
+   (4) All of this is to say that the lists of output nodes created by
+formatting XXX and YYY must be identical.  *Note Gtroff Internals::.
+
+   (5) This bizarre behavior maintains compatibility with AT&T 'troff'.
+
+
+File: groff.info,  Node: if-then,  Next: if-else,  Prev: Operators in Conditionals,  Up: Conditionals and Loops
+
+5.23.2 if-then
+--------------
+
+ -- Request: .if cond-expr anything
+     Evaluate the conditional expression COND-EXPR, and if it evaluates
+     true (or to a positive value), interpret the remainder of the line
+     ANYTHING as if it were an input line.  Recall from *note Invoking
+     Requests:: that any quantity of spaces between arguments to
+     requests serves only to separate them; leading spaces in ANYTHING
+     are thus not seen.  ANYTHING effectively _cannot_ be omitted; if
+     COND-EXPR is true and ANYTHING is empty, the newline at the end of
+     the control line is interpreted as a blank input line (and
+     therefore a blank text line).
+
+          super\c
+          tanker
+          .nr force-word-break 1
+          super\c
+          .if ((\n[force-word-break] = 1) & \n[.int])
+          tanker
+              => supertanker super tanker
+
+ -- Request: .nop anything
+     Interpret ANYTHING as if it were an input line.  This is similar to
+     '.if 1'.  'nop' is not really "no operation"; its argument _is_
+     processed--unconditionally.  It can be used to cause text lines to
+     share indentation with surrounding control lines.
+
+          .als real-MAC MAC
+          .de wrapped-MAC
+          .  tm MAC: called with arguments \\$@
+          .  nop \\*[real-MAC]\\
+          ..
+          .als MAC wrapped-MAC
+          \# Later...
+          .als MAC real-MAC
+
+     In the above, we've used aliasing, 'nop', and the interpolation of
+     a macro as a string to interpose a wrapper around the macro 'MAC'
+     (perhaps to debug it).
+
+
+File: groff.info,  Node: if-else,  Next: while,  Prev: Operators in Conditionals,  Up: Conditionals and Loops
+
+5.23.3 if-else
+--------------
+
+ -- Request: .ie cond-expr anything
+ -- Request: .el anything
+     Use the 'ie' and 'el' requests to write an if-then-else.  The first
+     request is the "if" part and the latter is the "else" part.
+     Unusually among programming languages, any number of
+     non-conditional requests may be interposed between the 'ie' branch
+     and the 'el' branch.
+
+          .nr a 0
+          .ie \na a is non-zero.
+          .nr a +1
+          .el a was not positive but is now \na.
+              => a was not positive but is now 1.
+
+     Another way in which 'el' is an ordinary request is that it does
+     not lexically "bind" more tightly to its 'ie' counterpart than it
+     does to any other request.  This fact can surprise C programmers.
+
+          .nr a 1
+          .nr z 0
+          .ie \nz \
+          .  ie \na a is true
+          .  el     a is false
+          .el z is false
+              error-> warning: unbalanced 'el' request
+              => a is false
+
+     To conveniently nest conditionals, keep reading.
+
+
+File: groff.info,  Node: Conditional Blocks,  Next: while,  Prev: Operators in Conditionals,  Up: Conditionals and Loops
+
+5.23.4 Conditional Blocks
+-------------------------
+
+It is frequently desirable for a control structure to govern more than
+one request, macro call, text line, or a combination of the foregoing.
+The opening and closing brace escape sequences '\{' and '\}' define such
+groups.  These "conditional blocks" can furthermore be nested.
+
+ -- Escape sequence: \{
+ -- Escape sequence: \}
+     '\{' begins a conditional block; it must appear (after optional
+     spaces and tabs) immediately subsequent to the conditional
+     expression of an 'if', 'ie', or 'while' request,(1) (*note
+     Conditional Blocks-Footnote-1::) or as the argument to an 'el'
+     request.
+
+     '\}' ends a condition block and should appear on a line with other
+     occurrences of itself as necessary to match '\{' sequences.  It can
+     be preceded by a control character, spaces, and tabs.  Input after
+     any quantity of '\}' sequences on the same line is processed only
+     if all of the preceding conditions to which they correspond are
+     true.  Furthermore, a '\}' closing the body of a 'while' request
+     must be the last such escape sequence on an input line.
+
+     Brace escape sequences outside of control structures have no
+     meaning and produce no output.
+
+     *Caution:* Input lines using '\{' often end with '\RET', especially
+     in macros that consist primarily of control lines.  Forgetting to
+     use '\RET' on an input line after '\{' is a common source of error.
+
+   We might write the following in a page header macro.  If we delete
+'\RET', the header will carry an unwanted extra empty line (except on
+page 1).
+
+     .if (\\n[%] != 1) \{\
+     .  ie ((\\n[%] % 2) = 0) .tl \\*[even-numbered-page-title]
+     .  el                    .tl \\*[odd-numbered-page-title]
+     .\}
+
+   Let us take a closer look at how conditional blocks nest.
+
+     A
+     .if 0 \{ B
+     C
+     D
+     \}E
+     F
+         => A F
+
+     N
+     .if 1 \{ O
+     .  if 0 \{ P
+     Q
+     R\} S\} T
+     U
+         => N O U
+
+   The above behavior may challenge the intuition; it was implemented to
+retain compatibility with AT&T 'troff'.  For clarity, it is idiomatic to
+end input lines with '\{' (followed by '\<RET>' if appropriate), and to
+precede '\}' on an input line with nothing more than a control
+character, spaces, tabs, and other instances of itself.
+
+   We can use 'ie', 'el', and conditional blocks to simulate the
+multi-way "switch" or "case" control structures of other languages.  The
+following example is adapted from the 'groff' 'man' package.
+Indentation is used to clarify the logic.
+
+     .\" Simulate switch/case in roff.
+     .      ie '\\$2'1' .ds title General Commands\"
+     .el \{.ie '\\$2'2' .ds title System Calls\"
+     .el \{.ie '\\$2'3' .ds title Library Functions\"
+     .el \{.ie '\\$2'4' .ds title Kernel Interfaces\"
+     .el \{.ie '\\$2'5' .ds title File Formats\"
+     .el \{.ie '\\$2'6' .ds title Games\"
+     .el \{.ie '\\$2'7' .ds title Miscellaneous Information\"
+     .el \{.ie '\\$2'8' .ds title System Management\"
+     .el \{.ie '\\$2'9' .ds title Kernel Development\"
+     .el                .ds title \" empty
+     .\}\}\}\}\}\}\}\}
+
+
+File: groff.info,  Node: Conditional Blocks-Footnotes,  Up: Conditional Blocks
+
+   (1) *Note while::.
+
+
+File: groff.info,  Node: while,  Prev: if-else,  Up: Conditionals and Loops
+
+5.23.5 while
+------------
+
+'groff' provides a looping construct: the 'while' request.  Its syntax
+matches the 'if' request.
+
+ -- Request: .while cond-expr anything
+     Evaluate the conditional expression COND-EXPR, and repeatedly
+     execute ANYTHING unless and until COND-EXPR evaluates false.
+     ANYTHING, which is often a conditional block, is referred to as the
+     'while' request's "body".
+
+          .nr a 0 1
+          .while (\na < 9) \{\
+          \n+a,
+          .\}
+          \n+a
+              => 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
+
+     GNU 'troff' treats the body of a 'while' request similarly to that
+     of a 'de' request (albeit one not read in copy mode(1) (*note
+     while-Footnote-1::)), but stores it under an internal name and
+     deletes it when the loop finishes.  The operation of a macro
+     containing a 'while' request can slow significantly if the 'while'
+     body is large.  Each time the macro is executed, the 'while' body
+     is parsed and stored again.
+
+          .de xxx
+          .  nr num 10
+          .  while (\\n[num] > 0) \{\
+          .    \" many lines of code
+          .    nr num -1
+          .  \}
+          ..
+
+     An often better solution--and one that is more portable, since AT&T
+     'troff' lacked the 'while' request--is to instead write a recursive
+     macro.  It will be parsed only once.(2)  (*note while-Footnote-2::)
+
+          .de yyy
+          .  if (\\n[num] > 0) \{\
+          .    \" many lines of code
+          .    nr num -1
+          .    yyy
+          .  \}
+          ..
+          .
+          .de xxx
+          .  nr num 10
+          .  yyy
+          ..
+
+     To prevent infinite loops, the default number of available
+     recursion levels is 1,000 or somewhat less.(3)  (*note
+     while-Footnote-3::) You can disable this protective measure, or
+     raise the limit, by setting the 'slimit' register.  *Note
+     Debugging::.
+
+     As noted above, if a 'while' body begins with a conditional block,
+     its closing brace must end an input line.
+
+          .if 1 \{\
+          .  nr a 0 1
+          .  while (\n[a] < 10) \{\
+          .    nop \n+[a]
+          .\}\}
+              error-> unbalanced brace escape sequences
+
+ -- Request: .break
+     Exit a 'while' loop.  Do not confuse this request with a
+     typographical break or the 'br' request.
+
+ -- Request: .continue
+     Skip the remainder of a 'while' loop's body, immediately starting
+     the next iteration.
+
+
+File: groff.info,  Node: while-Footnotes,  Up: while
+
+   (1) *Note Copy Mode::.
+
+   (2) unless you redefine it
+
+   (3) "somewhat less" because things other than macro calls can be on
+the input stack
+
+
+File: groff.info,  Node: Writing Macros,  Next: Page Motions,  Prev: Conditionals and Loops,  Up: GNU troff Reference
+
+5.24 Writing Macros
+===================
+
+A "macro" is a stored collection of text and control lines that can be
+interpolated multiple times.  Use macros to define common operations.
+Macros are called in the same way that requests are invoked.  While
+requests exist for the purpose of creating macros, simply calling an
+undefined macro, or interpolating it as a string, will cause it to be
+defined as empty.  *Note Identifiers::.
+
+ -- Request: .de name [end]
+     Define a macro NAME, replacing the definition of any existing
+     request, macro, string, or diversion called NAME.  If NAME already
+     exists as an alias, the target of the alias is redefined; recall
+     *note Strings::.  GNU 'troff' enters copy mode,(1) (*note Writing
+     Macros-Footnote-1::) storing subsequent input lines as the macro
+     definition.  If the optional second argument is not specified, the
+     definition ends with the control line '..' (two dots).
+     Alternatively, END identifies a macro whose call syntax at the
+     start of a control line ends the definition of NAME; END is then
+     called normally.  A macro definition must end in the same
+     conditional block (if any) in which it began (*note Conditional
+     Blocks::).  Spaces or tabs are permitted after the control
+     character in the line containing this ending token (either '.' or
+     'END'), but a tab immediately after the token prevents its
+     recognition as the end of a macro definition.  The macro END can be
+     called with arguments.(2)  (*note Writing Macros-Footnote-2::)
+
+     Here is a small example macro called 'P' that causes a break and
+     inserts some vertical space.  It could be used to separate
+     paragraphs.
+
+          .de P
+          .  br
+          .  sp .8v
+          ..
+
+     We can define one macro within another.  Attempting to nest '..'
+     naïvely will end the outer definition because the inner definition
+     isn't interpreted as such until the outer macro is later
+     interpolated.  We can use an end macro instead.  Each level of
+     nesting should use a unique end macro.
+
+     An end macro need not be defined until it is called.  This fact
+     enables a nested macro definition to begin inside one macro and end
+     inside another.  Consider the following example.(3)  (*note Writing
+     Macros-Footnote-3::)
+
+          .de m1
+          .  de m2 m3
+          you
+          ..
+          .de m3
+          Hello,
+          Joe.
+          ..
+          .de m4
+          do
+          ..
+          .m1
+          know?
+          .  m3
+          What
+          .m4
+          .m2
+              => Hello, Joe.  What do you know?
+
+     A nested macro definition _can_ be terminated with '..' and nested
+     macros _can_ reuse end macros, but these control lines must be
+     escaped multiple times for each level of nesting.  The necessity of
+     this escaping and the utility of nested macro definitions will
+     become clearer when we employ macro parameters and consider the
+     behavior of copy mode in detail.
+
+   'de' defines a macro that inherits the compatibility mode enablement
+status of its context (*note Implementation Differences::).  Often it is
+desirable to make a macro that uses 'groff' features callable from
+contexts where compatibility mode is on; for instance, when writing
+extensions to a historical macro package.  To achieve this,
+compatibility mode needs to be switched off while such a macro is
+interpreted--without disturbing that state when it is finished.
+
+ -- Request: .de1 name [end]
+     The 'de1' request defines a macro to be interpreted with
+     compatibility mode disabled.  When NAME is called, compatibility
+     mode enablement status is saved; it is restored when the call
+     completes.  Observe the extra backlash before the interpolation of
+     register 'xxx'; we'll explore this subject in *note Copy Mode::.
+
+          .nr xxx 12345
+          .de aa
+          The value of xxx is \\n[xxx].
+          .  br
+          ..
+          .de1 bb
+          The value of xxx is \\n[xxx].
+          ..
+          .cp 1
+          .aa
+              error-> warning: register '[' not defined
+              => The value of xxx is 0xxx].
+          .bb
+              => The value of xxx is 12345.
+
+ -- Request: .dei name [end]
+ -- Request: .dei1 name [end]
+     The 'dei' request defines a macro with its name and end macro
+     indirected through strings.  That is, it interpolates strings named
+     NAME and END before performing the definition.
+
+     The following examples are equivalent.
+
+          .ds xx aa
+          .ds yy bb
+          .dei xx yy
+
+          .de aa bb
+
+     The 'dei1' request bears the same relationship to 'dei' as 'de1'
+     does to 'de'; it temporarily turns compatibility mode off when NAME
+     is called.
+
+ -- Request: .am name [end]
+ -- Request: .am1 name [end]
+ -- Request: .ami name [end]
+ -- Request: .ami1 name [end]
+     'am' appends subsequent input lines to macro NAME, extending its
+     definition, and otherwise working as 'de' does.
+
+     To make the previously defined 'P' macro set indented instead of
+     block paragraphs, add the necessary code to the existing macro.
+
+          .am P
+          .ti +5n
+          ..
+
+     The other requests are analogous to their 'de' counterparts.  The
+     'am1' request turns off compatibility mode during interpretation of
+     the appendment.  The 'ami' request appends indirectly, meaning that
+     strings NAME and END are interpolated with the resulting names used
+     before appending.  The 'ami1' request is similar to 'ami',
+     disabling compatibility mode during interpretation of the appended
+     lines.
+
+   Using 'trace.tmac', you can trace calls to 'de', 'de1', 'am', and
+'am1'.  You can also use the 'backtrace' request at any point desired to
+troubleshoot tricky spots (*note Debugging::).
+
+   *Note Strings::, for the 'als', 'rm', and 'rn' requests to create an
+alias of, remove, and rename a macro, respectively.
+
+   Macro identifiers share their name space with requests, strings, and
+diversions; see *note Identifiers::.  The 'am', 'as', 'da', 'de', 'di',
+and 'ds' requests (together with their variants) create a new object
+only if the name of the macro, diversion, or string is currently
+undefined or if it is defined as a request; normally, they modify the
+value of an existing object.  *Note the description of the 'als'
+request: als, for pitfalls when redefining a macro that is aliased.
+
+ -- Request: .return [anything]
+     Exit a macro, immediately returning to the caller.  If called with
+     an argument ANYTHING, exit twice--the current macro and the macro
+     one level higher.  This is used to define a wrapper macro for
+     'return' in 'trace.tmac'.
+
+* Menu:
+
+* Parameters::
+* Copy Mode::
+
+
+File: groff.info,  Node: Writing Macros-Footnotes,  Up: Writing Macros
+
+   (1) *Note Copy Mode::.
+
+   (2) While it is possible to define and call a macro '.', you can't
+use it as an end macro: during a macro definition, '..' is never handled
+as calling '.', even if '.de NAME .' explicitly precedes it.
+
+   (3) Its structure is adapted from, and isomorphic to, part of a
+solution by Tadziu Hoffman to the problem of reflowing text multiple
+times to find an optimal configuration for it.
+<https://lists.gnu.org/archive/html/groff/2008-12/msg00006.html>
+
+
+File: groff.info,  Node: Parameters,  Next: Copy Mode,  Prev: Writing Macros,  Up: Writing Macros
+
+5.24.1 Parameters
+-----------------
+
+Macro calls and string interpolations optionally accept a list of
+arguments; recall *note Calling Macros::.  At the time such an
+interpolation takes place, these "parameters" can be examined using a
+register and a variety of escape sequences starting with '\$'.  All such
+escape sequences are interpreted even in copy mode, a fact we shall
+motivate and explain below (*note Copy Mode::).
+
+ -- Register: \n[.$]
+     The count of parameters available to a macro or string is kept in
+     this read-only register.  The 'shift' request can change its value.
+
+   Any individual parameter can be accessed by its position in the list
+of arguments to the macro call, numbered from left to right starting at
+1, with one of the following escape sequences.
+
+ -- Escape sequence: \$n
+ -- Escape sequence: \$(nn
+ -- Escape sequence: \$[nnn]
+     Interpolate the Nth, NNth, or NNNth parameter.  The first form
+     expects only a single digit (1<=N<=9)), the second two digits
+     (01<=NN<=99)), and the third any positive integer NNN.  Macros and
+     strings accept an unlimited number of parameters.
+
+ -- Request: .shift [n]
+     Shift the parameters N places (1 by default).  This is a "left
+     shift": what was parameter I becomes parameter I-N.  The parameters
+     formerly in positions 1 to N are no longer available.  Shifting by
+     a non-positive amount performs no operation.  The register '.$' is
+     adjusted accordingly.
+
+   In practice, parameter interpolations are usually seen prefixed with
+an extra escape character.  This is because the '\$' family of escape
+sequences is interpreted even in copy mode.(1)  (*note
+Parameters-Footnote-1::)
+
+ -- Escape sequence: \$*
+ -- Escape sequence: \$@
+ -- Escape sequence: \$^
+     In some cases it is convenient to interpolate all of the parameters
+     at once (to pass them to a request, for instance).  The '\$*'
+     escape concatenates the parameters, separating them with spaces.
+     '\$@' is similar, concatenating the parameters, surrounding each
+     with double quotes and separating them with spaces.  If not in
+     compatibility mode, the interpolation depth of double quotes is
+     preserved (*note Calling Macros::).  '\$^' interpolates all
+     parameters as if they were arguments to the 'ds' request.
+
+          .de foo
+          . tm $1='\\$1'
+          . tm $2='\\$2'
+          . tm $*='\\$*'
+          . tm $@='\\$@'
+          . tm $^='\\$^'
+          ..
+          .foo " This is a "test"
+              error-> $1=' This is a '
+              error-> $2='test"'
+              error-> $*=' This is a  test"'
+              error-> $@='" This is a " "test""'
+              error-> $^='" This is a "test"'
+
+     '\$*' is useful when writing a macro that doesn't need to
+     distinguish its arguments, or even to not interpret them; examples
+     include macros that produce diagnostic messages by wrapping the
+     'tm' or 'ab' requests.  Use '\$@' when writing a macro that may
+     need to shift its parameters and/or wrap a macro or request that
+     finds the count significant.  If in doubt, prefer '\$@' to '\$*'.
+     An application of '\$^' is seen in 'trace.tmac', which redefines
+     some requests and macros for debugging purposes.
+
+ -- Escape sequence: \$0
+     Interpolate the name by which the macro being interpreted was
+     called.  The 'als' request can cause a macro to have more than one
+     name.  Applying string interpolation to a macro does not change
+     this name.
+
+          .de foo
+          .  tm \\$0
+          ..
+          .als bar foo
+          .
+          .de aaa
+          .  foo
+          ..
+          .de bbb
+          .  bar
+          ..
+          .de ccc
+          \\*[foo]\\
+          ..
+          .de ddd
+          \\*[bar]\\
+          ..
+          .
+          .aaa
+              error-> foo
+          .bbb
+              error-> bar
+          .ccc
+              error-> ccc
+          .ddd
+              error-> ddd
+
+
+File: groff.info,  Node: Parameters-Footnotes,  Up: Parameters
+
+   (1) If they were not, parameter interpolations would be similar to
+command-line parameters--fixed for the entire duration of a 'roff'
+program's run.  The advantage of interpolating '\$' escape sequences
+even in copy mode is that they can interpolate different contents from
+one call to the next, like function parameters in a procedural language.
+The additional escape character is the price of this power.
+
+
+File: groff.info,  Node: Copy Mode,  Prev: Parameters,  Up: Writing Macros
+
+5.24.2 Copy Mode
+----------------
+
+When GNU 'troff' processes certain requests, most importantly those
+which define or append to a macro or string, it does so in "copy mode":
+it copies the characters of the definition into a dedicated storage
+region, interpolating the escape sequences '\n', '\g', '\$', '\*', '\V',
+and '\?' normally; interpreting '\<RET>' immediately; discarding
+comments '\"' and '\#'; interpolating the current leader, escape, or tab
+character with '\a', '\e', and '\t', respectively; and storing all other
+escape sequences in an encoded form.
+
+   The complement of copy mode--a 'roff' formatter's behavior when not
+defining or appending to a macro, string, or diversion--where all macros
+are interpolated, requests invoked, and valid escape sequences processed
+immediately upon recognition, can be termed "interpretation mode".
+
+ -- Escape sequence: \\
+     The escape character, '\' by default, can escape itself.  This
+     enables you to control whether a given '\n', '\g', '\$', '\*',
+     '\V', or '\?' escape sequence is interpreted at the time the macro
+     containing it is defined, or later when the macro is called.(1)
+     (*note Copy Mode-Footnote-1::)
+
+          .nr x 20
+          .de y
+          .nr x 10
+          \&\nx
+          \&\\nx
+          ..
+          .y
+              => 20 10
+
+     You can think of '\\' as a "delayed" backslash; it is the escape
+     character followed by a backslash from which the escape character
+     has removed its special meaning.  Consequently, '\\' is not an
+     escape sequence in the usual sense.  In any escape sequence '\X'
+     that GNU 'troff' does not recognize, the escape character is
+     ignored and X is output.  An unrecognized escape sequence causes a
+     warning in category 'escape', with two exceptions--'\\' is the
+     first.
+
+ -- Escape sequence: \.
+     '\.' escapes the control character.  It is similar to '\\' in that
+     it isn't a true escape sequence.  It is used to permit nested macro
+     definitions to end without a named macro call to conclude them.
+     Without a syntax for escaping the control character, this would not
+     be possible.
+
+          .de m1
+          foo
+          .
+          .  de m2
+          bar
+          \\..
+          .
+          ..
+          .m1
+          .m2
+              => foo bar
+
+     The first backslash is consumed while the macro is read, and the
+     second is interpreted when macro 'm1' is called.
+
+   'roff' documents should not use the '\\' or '\.' character sequences
+outside of copy mode; they serve only to obfuscate the input.  Use '\e'
+to represent the escape character, '\[rs]' to obtain a backslash glyph,
+and '\&' before '.' and ''' where GNU 'troff' expects them as control
+characters if you mean to use them literally (recall *note Requests and
+Macros::).
+
+   Macro definitions can be nested to arbitrary depth.  The mechanics of
+parsing the escape character have significant consequences for this
+practice.
+
+     .de M1
+     \\$1
+     .  de M2
+     \\\\$1
+     .    de M3
+     \\\\\\\\$1
+     \\\\..
+     .    M3 hand.
+     \\..
+     .  M2 of
+     ..
+     This understeer is getting
+     .M1 out
+         => This understeer is getting out of hand.
+
+   Each escape character is interpreted twice--once in copy mode, when
+the macro is defined, and once in interpretation mode, when the macro is
+called.  As seen above, this fact leads to exponential growth in the
+quantity of escape characters required to delay interpolation of '\n',
+'\g', '\$', '\*', '\V', and '\?' at each nesting level, which can be
+daunting.  GNU 'troff' offers a solution.
+
+ -- Escape sequence: \E
+     '\E' represents an escape character that is not interpreted in copy
+     mode.  You can use it to ease the writing of nested macro
+     definitions.
+
+          .de M1
+          .  nop \E$1
+          .  de M2
+          .    nop \E$1
+          .    de M3
+          .      nop \E$1
+          \\\\..
+          .    M3 better.
+          \\..
+          .  M2 bit
+          ..
+          This vehicle handles
+          .M1 a
+              => This vehicle handles a bit better.
+
+     Observe that because '\.' is not a true escape sequence, we can't
+     use '\E' to keep '..' from ending a macro definition prematurely.
+     If the multiplicity of backslashes complicates maintenance, use end
+     macros.
+
+     '\E' is also convenient to define strings containing escape
+     sequences that need to work when used in copy mode (for example, as
+     macro arguments), or which will be interpolated at varying macro
+     nesting depths.  We might define strings to begin and end
+     superscripting as follows.(2)  (*note Copy Mode-Footnote-2::)
+
+          .ds { \v'-.9m\s'\En[.s]*7u/10u'+.7m'
+          .ds } \v'-.7m\s0+.9m'
+
+     When the 'ec' request is used to redefine the escape character,
+     '\E' also makes it easier to distinguish the semantics of an escape
+     character from the other meaning(s) its character might have.
+     Consider the use of an unusual escape character, '-'.
+
+          .nr a 1
+          .ec -
+          .de xx
+          --na
+          ..
+          .xx
+              => -na
+
+     This result may surprise you; some people expect '1' to be output
+     since register 'a' has clearly been defined with that value.  What
+     has happened?  The robotic replacement of '\' with '-' has led us
+     astray.  You might recognize the sequence '--' more readily with
+     the default escape character as '\-', the special character escape
+     sequence for the minus sign glyph.
+
+          .nr a 1
+          .ec -
+          .de xx
+          -Ena
+          ..
+          .xx
+              => 1
+
+
+File: groff.info,  Node: Copy Mode-Footnotes,  Up: Copy Mode
+
+   (1) Compare this to the '\def' and '\edef' commands in TeX.
+
+   (2) These are lightly adapted from the 'groff' implementation of the
+'ms' macros.
+
+
+File: groff.info,  Node: Page Motions,  Next: Drawing Geometric Objects,  Prev: Writing Macros,  Up: GNU troff Reference
+
+5.25 Page Motions
+=================
+
+*Note Manipulating Spacing::, for a discussion of the most commonly used
+request for vertical motion, 'sp', which spaces downward by one vee.
+
+ -- Request: .mk [reg]
+ -- Request: .rt [dist]
+     You can "mark" a location on a page for subsequent "return".  'mk'
+     takes an argument, a register name in which to store the current
+     page location.  If given no argument, it stores the location in an
+     internal register.  This location can be used later by the 'rt' or
+     the 'sp' requests (or the '\v' escape).
+
+     The 'rt' request returns _upward_ to the location marked with the
+     last 'mk' request.  If used with an argument, it returns to a
+     vertical position DIST from the top of the page (no previous call
+     to 'mk' is necessary in this case).  The default scaling unit is
+     'v'.
+
+     If a page break occurs between a 'mk' request and its matching 'rt'
+     request, the 'rt' request is silently ignored.
+
+     A simple implementation of a macro to set text in two columns
+     follows.
+
+          .nr column-length 1.5i
+          .nr column-gap 4m
+          .nr bottom-margin 1m
+          .
+          .de 2c
+          .  br
+          .  mk
+          .  ll \\n[column-length]u
+          .  wh -\\n[bottom-margin]u 2c-trap
+          .  nr right-side 0
+          ..
+          .
+          .de 2c-trap
+          .  ie \\n[right-side] \{\
+          .    nr right-side 0
+          .    po -(\\n[column-length]u + \\n[column-gap]u)
+          .    \" remove trap
+          .    wh -\\n[bottom-margin]u
+          .  \}
+          .  el \{\
+          .    \" switch to right side
+          .    nr right-side 1
+          .    po +(\\n[column-length]u + \\n[column-gap]u)
+          .    rt
+          .  \}
+          ..
+
+     Now let us apply our two-column macro.
+
+          .pl 1.5i
+          .ll 4i
+          This is a small test that shows how the
+          rt request works in combination with mk.
+
+          .2c
+          Starting here, text is typeset in two columns.
+          Note that this implementation isn't robust
+          and thus not suited for a real two-column
+          macro.
+              => This is a small test that shows how the
+              => rt request works in combination with mk.
+              =>
+              => Starting  here,    isn't    robust
+              => text is typeset    and   thus  not
+              => in two columns.    suited  for   a
+              => Note that  this    real two-column
+              => implementation     macro.
+
+   Several escape sequences enable fine control of movement about the
+page.
+
+ -- Escape sequence: \v'expr'
+     Vertically move the drawing position.  EXPR indicates the magnitude
+     of motion: positive is downward and and negative upward.  The
+     default scaling unit is 'v'.  The motion is relative to the current
+     drawing position unless EXPR begins with the boundary-relative
+     motion operator '|'.  *Note Numeric Expressions::.
+
+     Text processing continues at the new drawing position; usually,
+     vertical motions should be in balanced pairs to avoid a confusing
+     page layout.
+
+     '\v' will not spring a vertical position trap.  This can be useful;
+     for example, consider a page bottom trap macro that prints a marker
+     in the margin to indicate continuation of a footnote.  *Note
+     Traps::.
+
+   A few escape sequences that produce vertical motion are unusual.
+They are thought to originate early in AT&T 'nroff' history to achieve
+super- and subscripting by half-line motions on line printers and
+teletypewriters before the phototypesetter made more precise positioning
+available.  They are reckoned in ems--not vees--to maintain continuity
+with their original purpose of moving relative to the size of the type
+rather than the distance between text baselines (vees).(1)  (*note Page
+Motions-Footnote-1::)
+
+ -- Escape sequence: \r
+ -- Escape sequence: \u
+ -- Escape sequence: \d
+     Move upward 1m, upward .5m, and downward .5m, respectively.
+
+Let us see these escape sequences in use.
+
+     Obtain 100 cm\u3\d of \ka\d\092\h'|\nau'\r233\dU.
+
+   In the foregoing we have paired '\u' and '\d' to typeset a
+superscript, and later a full em negative ("reverse") motion to place a
+superscript above a subscript.  A numeral-width horizontal motion escape
+sequence aligns the proton and nucleon numbers, while '\k' marks a
+horizontal position to which '\h' returns so that we could stack them.
+(We shall discuss these horizontal motion escape sequences presently.)
+In serious applications, we often want to alter the type size of the
+-scripts and to fine-tune the vertical motions, as the 'groff' 'ms'
+package does with its super- and subscripting string definitions.
+
+ -- Escape sequence: \h'expr'
+     Horizontally move the drawing position.  EXPR indicates the
+     magnitude of motion: positive is rightward and negative leftward.
+     The default scaling unit is 'm'.  The motion is relative to the
+     current drawing position unless EXPR begins with the
+     boundary-relative motion operator '|'.  *Note Numeric
+     Expressions::.
+
+   The following string definition sets the TeX logo.(2)  (*note Page
+Motions-Footnote-2::)
+
+     .ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X\"
+
+   There are a number of special-case escape sequences for horizontal
+motion.
+
+ -- Escape sequence: \<SP>
+     Move right one word space.  (The input is a backslash followed by a
+     space.)  This escape sequence can be thought of as a
+     non-adjustable, unbreakable space.  Usually you want '\~' instead;
+     see *note Manipulating Filling and Adjustment::.
+
+ -- Escape sequence: \|
+     Move one-sixth em to the right on typesetting output devices.  If a
+     glyph named '\|' is defined in the current font, its width is used
+     instead, even on terminal output devices.
+
+ -- Escape sequence: \^
+     Move one-twelfth em to the right on typesetting output devices.  If
+     a glyph named '\^' is defined in the current font, its width is
+     used instead, even on terminal output devices.
+
+ -- Escape sequence: \0
+     Move right by the width of a numeral in the current font.
+
+   Horizontal motions are not discarded at the end of an output line as
+word spaces are.  *Note Breaking::.
+
+ -- Escape sequence: \w'anything'
+ -- Register: \n[st]
+ -- Register: \n[sb]
+ -- Register: \n[rst]
+ -- Register: \n[rsb]
+ -- Register: \n[ct]
+ -- Register: \n[ssc]
+ -- Register: \n[skw]
+     Interpolate the width of ANYTHING in basic units.  This escape
+     sequence allows several properties of formatted output to be
+     measured without writing it out.
+
+          The length of the string 'abc' is \w'abc'u.
+              => The length of the string 'abc' is 72u.
+
+     ANYTHING is processed in a dummy environment: this means that font
+     and type size changes, for example, may occur within it without
+     affecting subsequent output.
+
+     After each use, '\w' sets several registers.
+
+     'st'
+     'sb'
+          The maximum vertical displacements of the text baseline above
+          and below, respectively.  The sign convention is opposite that
+          of relative vertical motions; that is, depth below the
+          (original) baseline is negative.  These registers are
+          incorrectly documented in the AT&T 'troff' manual as "the
+          highest and lowest extent of [the argument to '\w'] relative
+          to the baseline".
+
+     'rst'
+     'rsb'
+          Like 'st' and 'sb', but taking account of the heights and
+          depths of glyphs.  In other words, these registers store the
+          highest and lowest vertical positions attained by ANYTHING,
+          doing what AT&T 'troff' documented 'st' and 'sb' as doing.
+
+     'ct'
+          Characterizes the geometry of glyphs occurring in ANYTHING.
+
+          0
+               only short glyphs, no descenders or tall glyphs
+
+          1
+               at least one descender
+
+          2
+               at least one tall glyph
+
+          3
+               at least one each of a descender and a tall glyph
+
+     'ssc'
+          The amount of horizontal space (possibly negative) that should
+          be added to the last glyph before a subscript.
+
+     'skw'
+          How far to right of the center of the last glyph in the '\w'
+          argument, the center of an accent from a roman font should be
+          placed over that glyph.
+
+ -- Escape sequence: \kp
+ -- Escape sequence: \k(ps
+ -- Escape sequence: \k[position]
+     Store the current horizontal position in the _input_ line in a
+     register with the name POSITION (one-character name P,
+     two-character name PS).  Use this, for example, to return to the
+     beginning of a string for highlighting or other decoration.
+
+ -- Register: \n[hp]
+     The current horizontal position at the input line.
+
+ -- Register: \n[.k]
+     A read-only register containing the current horizontal output
+     position (relative to the current indentation).
+
+ -- Escape sequence: \o'abc...'
+     Overstrike the glyphs of characters A, B, C, ...; the glyphs are
+     centered, written, and the drawing position advanced by the widest
+     of the glyphs.
+
+ -- Escape sequence: \zc
+     Format the character C with zero width; that is, without advancing
+     the drawing position.  Use '\z' to overstrike glyphs aligned to
+     their left edges, in contrast to '\o''s centering.
+
+ -- Escape sequence: \Z'anything'
+     Save the drawing position, format ANYTHING, then restore it.  Tabs
+     and leaders in the argument are ignored with an error diagnostic.
+
+     We might implement a strike-through macro thus.
+
+          .de ST
+          .nr width \w'\\$1'
+          \Z@\v'-.25m'\l'\\n[width]u'@\\$1
+          ..
+          .
+          This is
+          .ST "a test"
+          an actual emergency!
+
+
+File: groff.info,  Node: Page Motions-Footnotes,  Up: Page Motions
+
+   (1) At the 'grops' defaults of 10-point type on 12-point vertical
+spacing, the difference between half a vee and half an em can be subtle:
+large spacings like '.vs .5i' make it obvious.
+
+   (2) *Note Strings::, for an explanation of the trailing '\"'.
+
+
+File: groff.info,  Node: Drawing Geometric Objects,  Next: Traps,  Prev: Page Motions,  Up: GNU troff Reference
+
+5.26 Drawing Geometric Objects
+==============================
+
+A few of the formatter's escape sequences draw lines and other geometric
+objects.  Combined with each other and with page motion commands (*note
+Page Motions::), a wide variety of figures is possible.  For complex
+drawings, these operations can be cumbersome; the preprocessors 'gpic'
+or 'ggrn' are typically used instead.
+
+   The '\l' and '\L' escape sequences draw horizontal and vertical
+sequences of glyphs, respectively.  Even the simplest of output devices
+supports them.
+
+ -- Escape sequence: \l'l'
+ -- Escape sequence: \l'lc'
+     Draw a horizontal line of length L from the drawing position.
+     Rightward motion is positive.  Afterward, the drawing position is
+     at the right end of the line.  The default scaling unit is 'm'.
+
+     The optional second parameter C is a character with which to draw
+     the line.  The default is the baseline rule special character,
+     '\[ru]'.
+
+     If C is a valid scaling unit, put '\&' after L to disambiguate the
+     input.
+
+          .de textbox
+          \[br]\\$*\[br]\l'|0\[rn]'\l'|0\[ul]'
+          ..
+
+     The foregoing outputs a box rule (a vertical line), the text
+     argument(s), and another box rule.  We employ the boundary-relative
+     motion operator '|'.  Finally, the line-drawing escape sequences
+     draw a radical extender (a form of overline) and an underline from
+     the drawing position to the position coresponding to beginning of
+     the _input_ line.  The drawing position returns to just after the
+     right-hand box rule because the lengths of the drawn lines are
+     negative, as noted above.
+
+ -- Escape sequence: \L'l'
+ -- Escape sequence: \L'lc'
+     Draw a vertical line of length L from the drawing position.
+     Downward motion is positive.  The default scaling unit is 'v'.  The
+     default character is the box rule, '\[br]'.  As with vertical
+     motion escape sequences, text processing continues where the line
+     ends.  '\L' is otherwise similar to '\l'.
+
+          $ nroff <<EOF
+          This is a \L'3v'test.
+          EOF
+              => This is a
+              =>           |
+              =>           |
+              =>           |test.
+
+     When writing text, the drawing position is at the text baseline;
+     recall *note Page Geometry::.
+
+   The '\D' escape sequence provides "drawing commands" that direct the
+output device to render geometrical objects rather than glyphs.
+Specific devices may support only a subset, or may feature additional
+ones; consult the man page for the output driver in use.  Terminal
+devices in particular implement almost none.  *Note Graphics Commands::.
+
+   Rendering starts at the drawing position; when finished, the drawing
+position is left at the rightmost point of the object, even for closed
+figures, except where noted.  GNU 'troff' draws stroked (outlined)
+objects with the stroke color, and shades filled ones with the fill
+color.  *Note Colors::.  Coordinates H and V are horizontal and vertical
+motions relative to the drawing position or previous point in the
+command.  The default scaling unit for horizontal measurements (and
+diameters of circles) is 'm'; for vertical ones, 'v'.
+
+   Circles, ellipses, and polygons can be drawn filled or stroked.
+These are independent properties; if you want a filled, stroked figure,
+you must draw the same figure twice using each drawing command.  A
+filled figure is always smaller than an outlined one because the former
+is drawn only within its defined area, whereas strokes have a line
+thickness (set with '\D't'').
+
+     \h'1i'\v'1i'\
+     \# increase line thickness
+     \Z'\D't 5p''\
+     \# draw stroked (unfilled) polygon
+     \Z'\D'p 3 3 -6 0''\
+     \# draw filled (solid) polygon
+     \Z'\D'P 3 3 -6 0''
+
+ -- Escape sequence: \D'command argument ...'
+     Drawing command escape sequence parameters begin with an ordinary
+     character, COMMAND, selecting the type of object to be drawn,
+     followed by ARGUMENTs whose meaning is determined by COMMAND.
+
+     '\D'~ H1 V1 ... HN VN''
+          Draw a B-spline to each point in sequence, leaving the drawing
+          position at (HN, VN).
+
+     '\D'a HC VC H V''
+          Draw a circular arc centered at (HC, VC) counterclockwise from
+          the drawing position to a point (H, V) relative to the center.
+          (1)  (*note Drawing Geometric Objects-Footnote-1::)
+
+     '\D'c D''
+          Draw a circle of diameter D with its leftmost point at the
+          drawing position.
+
+     '\D'C D''
+          As '\D'C ...'', but the circle is filled.
+
+     '\D'e H V''
+          Draw an ellipse of width H and height V with its leftmost
+          point at the drawing position.
+
+     '\D'E X Y''
+          As '\D'e ...'', but the ellipse is filled.
+
+     '\D'l DX DY''
+          Draw line from the drawing position to (H, V).
+
+          The following is a macro for drawing a box around a text
+          argument; for simplicity, the box margin is a fixed at 0.2m.
+
+               .de TEXTBOX
+               .  nr @wd \w'\\$1'
+               \h'.2m'\
+               \h'-.2m'\v'(.2m - \\n[rsb]u)'\
+               \D'l 0 -(\\n[rst]u - \\n[rsb]u + .4m)'\
+               \D'l (\\n[@wd]u + .4m) 0'\
+               \D'l 0 (\\n[rst]u - \\n[rsb]u + .4m)'\
+               \D'l -(\\n[@wd]u + .4m) 0'\
+               \h'.2m'\v'-(.2m - \\n[rsb]u)'\
+               \\$1\
+               \h'.2m'
+               ..
+
+          The argument is measured with the '\w' escape sequence.  Its
+          width is stored in register '@wd'.  '\w' also sets the
+          registers 'rst' and 'rsb'; these contain its maximum vertical
+          extents of the argument.  Then, four lines are drawn to form a
+          box, offset by the box margin.
+
+     '\D'p H1 V1 ... HN VN''
+          Draw polygon with vertices at drawing position and each point
+          in sequence.  GNU 'troff' closes the polygon by drawing a line
+          from (HN, VN) back to the initial drawing position.
+          Afterward, the drawing position is left at (HN, VN).
+
+     '\D'P DX1 DY1 DX2 DY2 ...''
+          As '\D'P ...'', but the polygon is filled.
+
+          The following macro is like the '\D'l'' example, but shades
+          the box.  We draw the box before writing the text because
+          colors in GNU 'troff' have no transparency; in othe opposite
+          order, the filled polygon would occlude the text.
+
+               .de TEXTBOX
+               .  nr @wd \w'\\$1'
+               \h'.2m'\
+               \h'-.2m'\v'(.2m - \\n[rsb]u)'\
+               \M[lightcyan]\
+               \D'P 0 -(\\n[rst]u - \\n[rsb]u + .4m) \
+                    (\\n[@wd]u + .4m) 0 \
+                    0 (\\n[rst]u - \\n[rsb]u + .4m) \
+                    -(\\n[@wd]u + .4m) 0'\
+               \h'.2m'\v'-(.2m - \\n[rsb]u)'\
+               \M[]\
+               \\$1\
+               \h'.2m'
+               ..
+
+     '\D't N''
+          Set the stroke thickness of geometric objects to N basic
+          units.  A zero N selects the minimal supported thickness.  A
+          negative N selects a thickness proportional to the type size;
+          this is the default.
+
+   In a hazy penumbra between text rendering and drawing commands we
+locate the bracket-building escape sequence, '\b'.  It can assemble
+apparently large glyphs by vertically stacking ordinary ones.
+
+ -- Escape sequence: \b'contents'
+     Pile and center a sequence of glyphs vertically on the output line.
+     "Piling" stacks glyphs corresponding to each character in CONTENTS,
+     read from left to right, and placed from top to bottom.  GNU
+     'troff' separates the glyphs vertically by 1m, and the pile itself
+     is centered 0.5m above the text baseline.  The horizontal drawing
+     position is then advanced by the width of the widest glyph in the
+     pile.
+
+     This rather inflexible positioning algorithm doesn't work with the
+     'dvi' output device since its bracket pieces vary in height.
+     Instead, use the 'geqn' preprocessor.
+
+     *note Manipulating Spacing:: describes how to adjust the vertical
+     spacing of the output line with the '\x' escape sequence.
+
+     The application of '\b' that lends its name is construction of
+     brackets, braces, and parentheses when typesetting mathematics.  We
+     might construct a large opening (left) brace as follows.
+
+          \b'\[lt]\[bv]\[lk]\[bv]\[lb]'
+
+     See 'groff_char(7)' for a list of special character identifiers.
+
+
+File: groff.info,  Node: Drawing Geometric Objects-Footnotes,  Up: Drawing Geometric Objects
+
+   (1) (HC, VC) is adjusted to the point nearest the perpendicular
+bisector of the arc's chord.
+
+
+File: groff.info,  Node: Deferring Output,  Next: Traps,  Prev: Drawing Geometric Objects,  Up: GNU troff Reference
+
+5.27 Deferring Output
+=====================
+
+A few 'roff' language elements are generally not used in simple
+documents, but arise as page layouts become more sophisticated and
+demanding.  "Environments" collect formatting parameters like line
+length and typeface.  A "diversion" stores formatted output for later
+use.  A "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.
+
+   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.
+
+   Diversions and traps make the text formatting process non-linear.
+Let us imagine a set of text lines or paragraphs labelled 'A', 'B', and
+so on.  If we set up a trap that produces text 'T' (as a page footer,
+say), and we also use a diversion to store the formatted text 'D', then
+a document with input text in the order 'A B C D E F' might render as 'A
+B C E T F'.  The diversion 'D' will never be output if we do not call
+for it.
+
+   Environments of themselves are not a source of non-linearity in
+document formatting: environment switches have immediate effect.  One
+could always write a macro to change as many formatting parameters as
+desired with a single convenient call.  But because diversions can be
+nested and macros called by traps that are sprung by other trap-called
+macros, they may be called upon in varying contexts.  For example,
+consider a page header that is always to be set in Helvetica.  A
+document that uses Times for most of its body text, but Courier for
+displayed code examples, poses a challenge if a page break occurs in the
+middle of a code display; if the header trap assumes that the "previous
+font" is always Times, the rest of the example will be formatted in the
+wrong typeface.  One could carefully save all formatting parameters upon
+entering the trap and restore them upon leaving it, but this is verbose,
+error-prone, and not future-proof as the 'groff' language develops.
+Environments save us considerable effort.
+
+
+File: groff.info,  Node: Traps,  Next: Diversions,  Prev: Deferring Output,  Up: GNU troff Reference
+
+5.28 Traps
+==========
+
+"Traps" are locations in the output or conditions on the input that,
+when reached or fulfilled, call a specified macro.  These traps can
+occur at a given location on the page, at a given location in the
+current diversion (together, these are known as vertical position
+traps), at a blank line, at a line with leading space characters, after
+a quantity of input lines, or at the end of input.  Macros called by
+traps are passed no arguments.  Setting a trap is also called "planting"
+one.  It is said that a trap is "sprung" if its condition is fulfilled.
+
+* Menu:
+
+* Vertical Position Traps::
+* Diversion Traps::
+* Input Line Traps::
+* Blank Line Traps::
+* Leading Space Traps::
+* End-of-input Traps::
+
+
+File: groff.info,  Node: Vertical Position Traps,  Next: Page Location Traps,  Prev: Traps,  Up: Traps
+
+5.28.1 Vertical Position Traps
+------------------------------
+
+A "vertical position trap" calls a macro when the formatter's vertical
+drawing position reaches or passes, in the downward direction, a certain
+location on the output page or in a diversion.  Its applications include
+setting page headers and footers, body text in multiple columns, and
+footnotes.
+
+ -- Request: .vpt [flag]
+ -- Register: \n[.vpt]
+     Enable vertical position traps if FLAG is non-zero or absent;
+     disable them otherwise.  Vertical position traps are those set by
+     the 'wh' request or by 'dt' within a diversion.  The parameter that
+     controls whether vertical position traps are enabled is global.
+     Initially, vertical position traps are enabled.  The current value
+     is stored in the '.vpt' read-only register.
+
+     A page can't be ejected if 'vpt' is set to zero; see *note The
+     Implicit Page Trap::.
+
+* Menu:
+
+* Page Location Traps::
+* The Implicit Page Trap::
+* Diversion Traps::
+
+
+File: groff.info,  Node: Page Location Traps,  Next: The Implicit Page Trap,  Prev: Vertical Position Traps,  Up: Vertical Position Traps
+
+5.28.1.1 Page Location Traps
+............................
+
+A "page location trap" is a vertical position trap that applies to the
+page; that is, to undiverted output.  Many can be present; manage them
+with the 'wh' and 'ch' requests.
+
+ -- Request: .wh dist [name]
+     Plant macro NAME as page location trap at DIST.  The default
+     scaling unit is 'v'.  Non-negative values for DIST set the trap
+     relative to the top of the page; negative values set the trap
+     relative to the bottom of the page.  It is not possible to plant a
+     trap less than one basic unit from the page bottom: a DIST of '-0'
+     is interpreted as '0', the top of the page.(1)  (*note Page
+     Location Traps-Footnote-1::) An existing _visible_ trap (see below)
+     at DIST is removed; this is 'wh''s sole function if NAME is
+     missing.
+
+     A trap is sprung only if it is "visible", meaning that its location
+     is reachable on the page(2) (*note Page Location
+     Traps-Footnote-2::) and it is not hidden by another trap at the
+     same location already planted there.
+
+     A macro package might set headers and footers as follows; this
+     example configures vertical margins of one inch to the body text,
+     and one half-inch to the titles.  Observe the use of the no-break
+     control character with 'sp' request to position our text baselines,
+     and the page number character '%' used with the 'tl' request.
+
+          .\" hdfo.roff
+          .de hd                  \" page header
+          '  sp .5i
+          '  tl '\\*(Ti''\\*(Da'  \" title and date strings
+          '  sp .5i
+          ..
+          .de fo                  \" page footer
+          '  sp .5i
+          .  tl ''%''
+          .  bp
+          ..
+          .wh 0   hd             \" trap at top of the page
+          .wh -1i fo             \" trap 1 inch from bottom
+
+     To use these traps, copy the above (or load it from a file with the
+     'so' or 'mso' requests), then set up the strings it uses.
+
+          .so hdfo.roff
+          .ds Ti Final Report\"
+          .ds Da 21 May 2023\"
+          .ti
+          On 5 August of last year,
+          this committee tasked me with the investigation of the
+          CFIT (controlled flight into terrain) incident of
+          .\" ...and so on...
+
+     A trap above the top or at or below the bottom of the page can be
+     made visible by either moving it into the page area or increasing
+     the page length so that the trap is on the page.  Negative trap
+     values always use the _current_ page length; they are not converted
+     to an absolute vertical position.  We can use the 'ptr' request to
+     dump our page location traps to the standard error stream (*note
+     Debugging::).  Their positions are reported in basic units; an
+     'nroff' device example follows.
+
+          .pl 5i
+          .wh -1i xx
+          .ptr
+              error-> xx      -240
+          .pl 100i
+          .ptr
+              error-> xx      -240
+
+     It is possible to have more than one trap at the same location
+     (although only one at a time can be visible); to achieve this, the
+     traps must be defined at different locations, then moved to the
+     same place with the 'ch' request.  In the following example, the
+     many empty lines caused by the 'bp' request are not shown in the
+     output.
+
+          .de a
+          .  nop a
+          ..
+          .de b
+          .  nop b
+          ..
+          .de c
+          .  nop c
+          ..
+          .
+          .wh 1i a
+          .wh 2i b
+          .wh 3i c
+          .bp
+              => a b c
+          .ch b 1i
+          .ch c 1i
+          .bp
+              => a
+          .ch a 0.5i
+          .bp
+              => a b
+
+ -- Register: \n[.t]
+     The read-only register '.t' holds the distance to the next vertical
+     position trap.  If there are no traps between the current position
+     and the bottom of the page, it contains the distance to the page
+     bottom.  Within a diversion, in the absence of a diversion trap,
+     this distance is the largest representable integer in basic
+     units--effectively infinite.
+
+ -- Request: .ch name [dist]
+     Change the location of a trap by moving macro NAME to new location
+     DIST, or by unplanting it altogether if DIST is absent.  The
+     default scaling unit is 'v'.  Parameters to 'ch' are specified in
+     the opposite order from 'wh'.  If NAME is the earliest planted
+     macro of multiple traps at the same location, (re)moving it from
+     that location exposes the macro next least recently planted at the
+     same place.(3)  (*note Page Location Traps-Footnote-3::)
+
+     Changing a trap's location is useful for building up footnotes in a
+     diversion to allow more space at the bottom of the page for them.
+
+   The same macro can be installed simultaneously at multiple locations;
+however, only the earliest-planted instance--that has not yet been
+deleted with 'wh'--will be moved by 'ch'.  The following example (using
+an 'nroff' device) illustrates this behavior.  Blank lines have been
+elided from the output.
+
+     .de T
+     Trap sprung at \\n(nlu.
+     .br
+     ..
+     .wh 1i T
+     .wh 2i T
+     foo
+     .sp 11i
+     .bp
+     .ch T 4i
+     bar
+     .sp 11i
+     .bp
+     .ch T 5i
+     baz
+     .sp 11i
+     .bp
+     .wh 5i
+     .ch T 6i
+     qux
+     .sp 11i
+         => foo
+         => Trap sprung at 240u.
+         => Trap sprung at 480u.
+         => bar
+         => Trap sprung at 480u.
+         => Trap sprung at 960u.
+         => baz
+         => Trap sprung at 480u.
+         => Trap sprung at 1200u.
+         => qux
+         => Trap sprung at 1440u.
+
+ -- Register: \n[.ne]
+     The read-only register '.ne' contains the amount of space that was
+     needed in the last 'ne' request that caused a trap to be sprung; it
+     is useful in conjunction with the '.trunc' register.  *Note Page
+     Control::.  Since the '.ne' register is set only by traps, it
+     doesn't make sense to interpolate it outside of macros called by
+     traps.
+
+ -- Register: \n[.trunc]
+     A read-only register containing the amount of vertical space
+     truncated from an 'sp' request by the most recently sprung vertical
+     position trap, or, if the trap was sprung by an 'ne' request, minus
+     the amount of vertical motion produced by the 'ne' request.  In
+     other words, at the point a trap is sprung, it represents the
+     difference of what the vertical position would have been but for
+     the trap, and what the vertical position actually is.  Since the
+     '.trunc' register is set only by traps, it doesn't make sense to
+     interpolate it outside of macros called by traps.
+
+ -- Register: \n[.pe]
+     This Boolean-valued, read-only register interpolates 1 while a page
+     is being ejected, and 0 otherwise.
+
+     In the following example, we plant the same trap at the top and the
+     bottom of the page.  We also make the trap report its name and the
+     vertical drawing position.
+
+          .de T
+          .tm \\$0: page \\n%, nl=\\n[nl] .pe=\\n[.pe]
+          ..
+          .ll 46n
+          .wh 0 T
+          .wh -1v T
+          Those who can make you believe absurdities can make you
+          commit atrocities. \[em] Voltaire
+              error-> T: page 1, nl=0 .pe=0
+              error-> T: page 1, nl=2600 .pe=1
+              => Those who can make you believe absurdities can
+              => make you commit atrocities. -- Voltaire
+
+   When designing macros, keep in mind that diversions and traps do
+normally interact.  For example, if a trap calls a header macro (while
+outputting a diversion) that tries to change the font on the current
+page, the effect is not visible before the diversion has completely been
+printed (except for input protected with '\!' or '\?') since the data in
+the diversion is already formatted.  In most cases, this is not the
+expected behaviour.
+
+
+File: groff.info,  Node: Page Location Traps-Footnotes,  Up: Page Location Traps
+
+   (1) *Note The Implicit Page Trap::.
+
+   (2) A trap planted at '20i' or '-30i' will not be sprung on a page of
+length '11i'.
+
+   (3) It may help to think of each trap location as maintaining a
+queue; 'wh' operates on the head of the queue, and 'ch' operates on its
+tail.  Only the trap at the head of the queue is visible.
+
+
+File: groff.info,  Node: The Implicit Page Trap,  Next: Diversion Traps,  Prev: Page Location Traps,  Up: Vertical Position Traps
+
+5.28.1.2 The Implicit Page Trap
+...............................
+
+If, after starting GNU 'troff' without loading a macro package, you use
+the 'ptr' request to dump a list of the active traps to the standard
+error stream,(1) (*note The Implicit Page Trap-Footnote-1::) nothing is
+reported.  Yet the '.t' register will report a steadily decreasing value
+with every output line your document produces, and once the value of
+'.t' gets to within '.V' of zero, you will notice that something
+trap-like happens--the page is ejected, a new one begins, and the value
+of '.t' becomes large once more.
+
+   This "implicit page trap" always exists in the top-level
+diversion;(2) (*note The Implicit Page Trap-Footnote-2::) it works like
+a trap in some ways but not others.  Its purpose is to eject the current
+page and start the next one.  It has no name, so it cannot be moved or
+deleted with 'wh' or 'ch' requests.  You cannot hide it by placing
+another trap at its location, and can move it only by redefining the
+page length with 'pl'.  Its operation is suppressed when vertical page
+traps are disabled with GNU 'troff''s 'vpt' request.
+
+
+File: groff.info,  Node: The Implicit Page Trap-Footnotes,  Up: The Implicit Page Trap
+
+   (1) *Note Debugging::.
+
+   (2) *Note Diversions::.
+
+
+File: groff.info,  Node: Diversion Traps,  Next: Input Line Traps,  Prev: The Implicit Page Trap,  Up: Vertical Position Traps
+
+5.28.1.3 Diversion Traps
+........................
+
+A diversion is not formatted in the context of a page, so it lacks page
+location traps; instead it can have a "diversion trap".  There can exist
+at most one such vertical position trap per diversion.
+
+ -- Request: .dt [dist name]
+     Set a trap _within_ a diversion at location DIST, which is
+     interpreted relative to diversion rather than page boundaries.  If
+     invoked with fewer than two arguments, any diversion trap in the
+     current diversion is removed.  The register '.t' works within
+     diversions.  It is an error to invoke 'dt' in the top-level
+     diversion.  *Note Diversions::.
+
+
+File: groff.info,  Node: Input Line Traps,  Next: Blank Line Traps,  Prev: Diversion Traps,  Up: Traps
+
+5.28.2 Input Line Traps
+-----------------------
+
+ -- Request: .it [n name]
+ -- Request: .itc [n name]
+     Set an input line trap, calling macro NAME after processing the
+     next N productive input lines (recall *note Manipulating Filling
+     and Adjustment::).  Any existing input line trap in the environment
+     is replaced.  Without arguments, 'it' and 'itc' clear any input
+     line trap that has not yet sprung.
+
+     Consider a macro '.ST S N' which sets the next N input lines in the
+     font style S.
+
+          .de ST \" Use style $1 for next $2 text lines.
+          .  it \\$2 ES
+          .  ft \\$1
+          ..
+          .de ES \" end ST
+          .  ft R
+          ..
+          .ST I 1
+          oblique
+          face
+          .ST I 1
+          oblique\c
+          face
+              => oblique face obliqueface  (second "face" upright)
+
+     Unlike the 'ce' and 'rj' requests, 'it' counts lines interrupted
+     with the '\c' escape sequence separately (*note Line
+     Continuation::); 'itc' does not.  To see the difference, let's
+     change the previous example to use 'itc' instead.
+
+          ...
+          .  itc \\$2 ES
+          ...
+              => oblique face obliqueface  (second "face" oblique)
+
+     You can think of the 'ce' and 'rj' requests as implicitly creating
+     an input line trap with 'itc' that schedules a break when the trap
+     is sprung.
+
+          .de BR
+          .  br
+          .  internal: disable centering-without-filling
+          ..
+          .
+          .de ce
+          .  if \\n[.br] .br
+          .  itc \\$1 BR
+          .  internal: enable centering-without-filling
+          ..
+
+     Let us consider in more detail the sorts of input lines that are or
+     are not "productive".
+
+          .de Trap
+          TRAP SPRUNG
+          ..
+          .de Mac
+          .if r a \l'5n'
+          ..
+          .it 2 Trap
+          .
+          foo
+          .Mac
+          bar
+          baz
+          .it 1 Trap
+          .sp \" moves, but does not write or draw
+          qux
+          .itc 1 Trap
+          \h'5n'\c \" moves, but does not write or draw
+          jat
+
+     When 'Trap' gets called depends on whether the 'a' register is
+     defined; the control line with the 'if' request may or may not
+     produce written output.  We also see that the spacing request 'sp',
+     while certainly affecting the output, does not spring the input
+     line trap.  Similarly, the horizontal motion escape sequence '\h'
+     also affected the output, but was not "written".  Observe that we
+     had to follow it with '\c' and use 'itc' to prevent the newline at
+     the end of the text line from causing a word break, which, like an
+     ordinary space character, counts as written output.
+
+          $ groff -Tascii input-trap-example.groff
+              => foo bar TRAP SPRUNG baz
+              =>
+              => qux TRAP SPRUNG      jat TRAP SPRUNG
+          $ groff -Tascii -ra1 input-trap-example.groff
+              => foo _____ TRAP SPRUNG bar baz
+              =>
+              => qux TRAP SPRUNG      jat TRAP SPRUNG
+
+   Input line traps are associated with the environment (*note
+Environments::); switching to another environment suspends the current
+input line trap, and going back resumes it, restoring the count of
+qualifying lines enumerated in that environment.
+
+
+File: groff.info,  Node: Blank Line Traps,  Next: Leading Space Traps,  Prev: Input Line Traps,  Up: Traps
+
+5.28.3 Blank Line Traps
+-----------------------
+
+ -- Request: .blm [name]
+     Set a blank line trap, calling the macro NAME when GNU 'troff'
+     encounters a blank line in an input file, instead of the usual
+     behavior (*note Breaking::).  A line consisting only of spaces is
+     also treated as blank and subject to this trap.  If no argument is
+     supplied, the default blank line behavior is (re-)established.
+
+
+File: groff.info,  Node: Leading Space Traps,  Next: End-of-input Traps,  Prev: Blank Line Traps,  Up: Traps
+
+5.28.4 Leading Space Traps
+--------------------------
+
+ -- Request: .lsm [name]
+ -- Register: \n[lsn]
+ -- Register: \n[lss]
+     Set a leading space trap, calling the macro NAME when GNU 'troff'
+     encounters leading spaces in an input line; the implicit line break
+     that normally happens in this case is suppressed.  If no argument
+     is supplied, the default leading space behavior is (re-)established
+     (*note Breaking::).
+
+     The count of leading spaces on an input line is stored in register
+     'lsn', and the amount of corresponding horizontal motion in
+     register 'lss', irrespective of whether a leading space trap is
+     set.  When it is, the leading spaces are removed from the input
+     line, and no motion is produced before calling NAME.
+
+
+File: groff.info,  Node: End-of-input Traps,  Prev: Leading Space Traps,  Up: Traps
+
+5.28.5 End-of-input Traps
+-------------------------
+
+ -- Request: .em [name]
+     Set a trap at the end of input, calling macro NAME after the last
+     line of the last input file has been processed.  If no argument is
+     given, any existing end-of-input trap is removed.
+
+     For example, if the document had to have a section at the bottom of
+     the last page for someone to approve it, the 'em' request could be
+     used.
+
+          .de approval
+          \c
+          .  ne 3v
+          .  sp (\\n[.t]u - 3v)
+          .  in +4i
+          .  lc _
+          .  br
+          Approved:\t\a
+          .  sp
+          Date:\t\t\a
+          ..
+          .
+          .em approval
+
+     The '\c' in the above example needs explanation.  For historical
+     reasons (compatibility with AT&T 'troff'), the end-of-input macro
+     exits as soon as it causes a page break if no partially collected
+     line remains.(1)  (*note End-of-input Traps-Footnote-1::)
+
+     Let us assume that there is no '\c' in the above 'approval' macro,
+     that the page is full, and last output line has been broken with,
+     say, a 'br' request.  Because there is no more room, a 'ne' request
+     at this point causes a page ejection, which in turn makes 'troff'
+     exit immediately as just described.  In most situations, this is
+     not desired; people generally want to format the input after 'ne'.
+
+     To force processing of the whole end-of-input macro independently
+     of this behavior, it is thus advisable to (invisibly) ensure the
+     existence of a partially collected line ('\c') whenever there is a
+     chance that a page break can happen.  In the above example,
+     invoking the 'ne' request ensures that there is room for the
+     subsequent formatted output on the same page, so we need insert
+     '\c' only once.
+
+     The next example shows how to append three lines, then start a new
+     page unconditionally.  Since '.ne 1' doesn't give the desired
+     effect--there is always one line available or we are already at the
+     beginning of the next page--we temporarily increase the page length
+     by one line so that we can use '.ne 2'.
+
+          .de EM
+          .pl +1v
+          \c
+          .ne 2
+          line one
+          .br
+          \c
+          .ne 2
+          line two
+          .br
+          \c
+          .ne 2
+          line three
+          .br
+          .pl -1v
+          \c
+          'bp
+          ..
+          .em EM
+
+     This specific feature affects only the first potential page break
+     caused by the end-of-input macro; further page breaks emitted by
+     the macro are handled normally.
+
+     Another possible use of the 'em' request is to make GNU 'troff'
+     emit a single large page instead of multiple pages.  For example,
+     one may want to produce a long plain text file for reading in a
+     terminal or emulator without page footers and headers interrupting
+     the body of the document.  One approach is to set the page length
+     at the beginning of the document to a very large value to hold all
+     the text,(2) (*note End-of-input Traps-Footnote-2::) and
+     automatically adjust it to the exact height of the document after
+     the text has been output.
+
+          .de adjust-page-length
+          .  br
+          .  pl \\n[nl]u \" \n[nl]: current vertical position
+          ..
+          .
+          .de single-page-mode
+          .  pl 99999
+          .  em adjust-page-length
+          ..
+          .
+          .\" Activate the above code if configured.
+          .if \n[do-continuous-rendering] \
+          .  single-page-mode
+
+     Since only one end-of-input trap exists and another macro package
+     may already use it, care must be taken not to break the mechanism.
+     A simple solution would be to append the above macro to the macro
+     package's end-of-input macro using the 'am' request.
+
+
+File: groff.info,  Node: End-of-input Traps-Footnotes,  Up: End-of-input Traps
+
+   (1) While processing an end-of-input macro, the formatter assumes
+that the next page break must be the last; it goes into "sudden death
+overtime".
+
+   (2) Another, taken by the 'groff' 'man' macros, is to intercept 'ne'
+requests and wrap 'bp' ones.
+
+
+File: groff.info,  Node: Diversions,  Next: Punning Names,  Prev: Traps,  Up: GNU troff Reference
+
+5.29 Diversions
+===============
+
+In 'roff' systems it is possible to format text as if for output, but
+instead of writing it immediately, one can "divert" the formatted text
+into a named storage area.  It is retrieved later by specifying its name
+after a control character.  The same name space is used for such
+diversions as for strings and macros; see *note Identifiers::.  Such
+text is sometimes said to be "stored in a macro", but this coinage
+obscures the important distinction between macros and strings on one
+hand and diversions on the other; the former store _unformatted_ input
+text, and the latter capture _formatted_ output.  Diversions also do not
+interpret arguments.  Applications of diversions include "keeps"
+(preventing a page break from occurring at an inconvenient place by
+forcing a set of output lines to be set as a group), footnotes, tables
+of contents, and indices.  For orthogonality it is said that GNU 'troff'
+is in the "top-level diversion" if no diversion is active (that is,
+formatted output is being "diverted" immediately to the output device).
+
+   Dereferencing an undefined diversion will create an empty one of that
+name and cause a warning in category 'mac' to be emitted.  *Note
+Warnings::, for information about the enablement and suppression of
+warnings.  A diversion does not exist for the purpose of testing with
+the 'd' conditional operator until its initial definition ends (*note
+Operators in Conditionals::).  The following requests are used to create
+and alter diversions.
+
+ -- Request: .di [name]
+ -- Request: .da [name]
+     Start collecting formatted output in a diversion called NAME.  The
+     'da' request appends to a diversion called NAME, creating it if
+     necessary.  If NAME already exists as an alias, the target of the
+     alias is replaced or appended to; recall *note Strings::.  The
+     pending output line is diverted as well.  Switching to another
+     environment (with the 'ev' request) before invoking 'di' or 'da'
+     avoids including any pending output line in the diversion; see
+     *note Environments::.
+
+     Invoking 'di' or 'da' without an argument stops diverting output to
+     the diversion named by the most recent corresponding request.  If
+     'di' or 'da' is called without an argument when there is no current
+     diversion, a warning in category 'di' is produced.  *Note
+     Warnings::, for information about the enablement and suppression of
+     warnings.
+
+          Before the diversion.
+          .di yyy
+          In the diversion.
+          .br
+          .di
+          After the diversion.
+          .br
+              => After the diversion.
+          .yyy
+              => Before the diversion.  In the diversion.
+
+   GNU 'troff' supports "box" requests to exclude a partially collected
+line from a diversion, as this is often desirable.
+
+ -- Request: .box [name]
+ -- Request: .boxa [name]
+     Divert (or append) output to NAME, similarly to the 'di' and 'da'
+     requests, respectively.  Any pending output line is _not_ included
+     in the diversion.  Without an argument, stop diverting output; any
+     pending output line inside the diversion is discarded.
+
+          Before the box.
+          .box xxx
+          In the box.
+          .br
+          Hidden treasure.
+          .box
+          After the box.
+          .br
+              => Before the box.  After the box.
+          .xxx
+              => In the box.
+
+   Apart from pending output line inclusion and the request names that
+populate them, boxes are handled exactly as diversions are.  All of the
+following 'groff' language elements can be used with them
+interchangeably.
+
+ -- Register: \n[.z]
+ -- Register: \n[.d]
+     Diversions may be nested.  The read-only string-valued register
+     '.z' contains the name of the current diversion.  The read-only
+     register '.d' contains the current vertical place in the diversion.
+     If the input text is not being diverted, '.d' reports the same
+     location as the register 'nl'.
+
+ -- Register: \n[.h]
+     The read-only register '.h' stores the "high-water mark" on the
+     current page or in the current diversion.  It corresponds to the
+     text baseline of the lowest line on the page.(1)  (*note
+     Diversions-Footnote-1::)
+
+          .tm .h==\n[.h], nl==\n[nl]
+              => .h==0, nl==-1
+          This is a test.
+          .br
+          .sp 2
+          .tm .h==\n[.h], nl==\n[nl]
+              => .h==40, nl==120
+
+     As implied by the example, vertical motion does not produce text
+     baselines and thus does not increase the value interpolated by
+     '\n[.h]'.
+
+ -- Register: \n[dn]
+ -- Register: \n[dl]
+     After completing a diversion, the writable registers 'dn' and 'dl'
+     contain its vertical and horizontal sizes.  Only the lines just
+     processed are counted: for the computation of 'dn' and 'dl', the
+     requests 'da' and 'boxa' are handled as if 'di' and 'box' had been
+     used, respectively--lines that have been already stored in the
+     diversion (box) are not taken into account.
+
+          .\" Center text both horizontally and vertically.
+          .\" Macro .(c starts centering mode; .)c terminates it.
+          .
+          .\" Disable the escape character with .eo so that we
+          .\" don't have to double backslashes on the "\n"s.
+          .eo
+          .de (c
+          .  br
+          .  ev (c
+          .  evc 0
+          .  in 0
+          .  nf
+          .  di @c
+          ..
+          .de )c
+          .  br
+          .  ev
+          .  di
+          .  nr @s (((\n[.t]u - \n[dn]u) / 2u) - 1v)
+          .  sp \n[@s]u
+          .  ce 1000
+          .  @c
+          .  ce 0
+          .  sp \n[@s]u
+          .  br
+          .  fi
+          .  rr @s
+          .  rm @c
+          ..
+          .ec
+
+ -- Escape sequence: \!anything
+ -- Escape sequence: \?anything\?
+     "Transparently" embed ANYTHING into the current diversion,
+     preventing requests, macro calls, and escape sequences from being
+     interpreted when read into a diversion.  This is useful for
+     preventing them from taking effect until the diverted text is
+     actually output.  The '\!' escape sequence transparently embeds
+     input up to and including the end of the line.  The '\?' escape
+     sequence transparently embeds input until its own next occurrence.
+
+     ANYTHING may not contain newlines; use '\!' by itself to embed
+     newlines in a diversion.  The escape sequence '\?' is also
+     recognized in copy mode and turned into a single internal code; it
+     is this code that terminates ANYTHING.  Thus the following example
+     prints 4.
+
+          .nr x 1
+          .nf
+          .di d
+          \?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
+          .di
+          .nr x 2
+          .di e
+          .d
+          .di
+          .nr x 3
+          .di f
+          .e
+          .di
+          .nr x 4
+          .f
+
+     Both escape sequences read the data in copy mode.
+
+     If '\!' is used in the top-level diversion, its argument is
+     directly embedded into GNU 'troff''s intermediate output.  This can
+     be used, for example, to control a postprocessor that processes the
+     data before it is sent to an output driver.
+
+     The '\?' escape used in the top-level diversion produces no output
+     at all; its argument is simply ignored.
+
+ -- Request: .output contents
+     Emit CONTENTS directly to GNU 'troff''s intermediate output
+     (subject to copy mode interpretation); this is similar to '\!' used
+     at the top level.  An initial neutral double quote in CONTENTS is
+     stripped to allow embedding of leading spaces.
+
+     This request can't be used before the first page has started--if
+     you get an error, simply insert '.br' before the 'output' request.
+
+     Use with caution!  It is normally only needed for mark-up used by a
+     postprocessor that does something with the output before sending it
+     to the output device, filtering out CONTENTS again.
+
+ -- Request: .asciify div
+     "Unformat" the diversion DIV in a way such that Unicode basic Latin
+     (ASCII) characters, characters translated with the 'trin' request,
+     space characters, and some escape sequences, that were formatted
+     and diverted into DIV are treated like ordinary input characters
+     when DIV is reread.  Doing so can be useful in conjunction with the
+     'writem' request.  'asciify' can be also used for gross hacks; for
+     example, the following sets register 'n' to 1.
+
+          .tr @.
+          .di x
+          @nr n 1
+          .br
+          .di
+          .tr @@
+          .asciify x
+          .x
+
+     'asciify' cannot return all items in a diversion to their source
+     equivalent: nodes such as those produced by the '\N' escape
+     sequence will remain nodes, so the result cannot be guaranteed to
+     be a pure string.  *Note Copy Mode::.  Glyph parameters such as the
+     type face and size are not preserved; use 'unformat' to achieve
+     that.
+
+ -- Request: .unformat div
+     Like 'asciify', unformat the diversion DIV.  However, 'unformat'
+     handles only tabs and spaces between words, the latter usually
+     arising from spaces or newlines in the input.  Tabs are treated as
+     input tokens, and spaces become adjustable again.  The vertical
+     sizes of lines are not preserved, but glyph information (font, type
+     size, space width, and so on) is retained.
+
+
+File: groff.info,  Node: Diversions-Footnotes,  Up: Diversions
+
+   (1) Thus, the "water" gets "higher" proceeding _down_ the page.
+
+
+File: groff.info,  Node: Punning Names,  Next: Environments,  Prev: Diversions,  Up: GNU troff Reference
+
+5.30 Punning Names
+==================
+
+Macros, strings, and diversions share a name space; recall *note
+Identifiers::.  Internally, the same mechanism is used to store them.
+You can thus call a macro with string interpolation syntax and vice
+versa.
+
+     .de subject
+     Typesetting
+     ..
+     .de predicate
+     rewards attention to detail
+     ..
+     \*[subject] \*[predicate].
+     Truly.
+         => Typesetting
+         =>  rewards attention to detail Truly.
+
+What went wrong?  Strings don't contain newlines, but macros do.  String
+interpolation placed a newline at the end of '\*[subject]', and the next
+thing on the input was a space.  Then when '\*[predicate]' was
+interpolated, it was followed by the empty request '.' on a line by
+itself.  If we want to use macros as strings, we must take interpolation
+behavior into account.
+
+     .de subject
+     Typesetting\\
+     ..
+     .de predicate
+     rewards attention to detail\\
+     ..
+     \*[subject] \*[predicate].
+     Truly.
+         => Typesetting rewards attention to detail.  Truly.
+
+By ending each text line of the macros with an escaped '\<RET>', we get
+the desired effect (*note Line Continuation::).(1)  (*note Punning
+Names-Footnote-1::) What would have happened if we had used only one
+backslash at a time instead?
+
+   Interpolating a string does not hide existing macro arguments.  We
+can also place the escaped newline outside the string interpolation
+instead of within the string definition.  Thus, in a macro, a more
+efficient way of doing
+
+     .xx \\$@
+
+is
+
+     \\*[xx]\\
+
+The latter calling syntax doesn't change the value of '\$0', which is
+then inherited from the calling macro (*note Parameters::).
+
+   Diversions can be also called with string syntax.  It is sometimes
+convenient to copy one-line diversions to a string.
+
+     .di xx
+     the
+     .ft I
+     interpolation system
+     .ft
+     .br
+     .di
+     .ds yy This is a test of \*(xx\c
+     \*(yy.
+         => This is a test of the interpolation system.
+
+As the previous example shows, it is possible to store formatted output
+in strings.  The '\c' escape sequence prevents the subsequent newline
+from being interpreted as a break (again, *note Line Continuation::).
+
+   Copying multi-output line diversions produces unexpected results.
+
+     .di xxx
+     a funny
+     .br
+     test
+     .br
+     .di
+     .ds yyy This is \*[xxx]\c
+     \*[yyy].
+         => test This is a funny.
+
+   Usually, it is not predictable whether a diversion contains one or
+more output lines, so this mechanism should be avoided.  With AT&T
+'troff', this was the only solution to strip off a final newline from a
+diversion.  Another disadvantage is that the spaces in the copied string
+are already formatted, preventing their adjustment.  This can cause ugly
+results.
+
+   A clean solution to this problem is available in GNU 'troff', using
+the requests 'chop' to remove the final newline of a diversion, and
+'unformat' to make the horizontal spaces adjustable again.
+
+     .box xxx
+     a funny
+     .br
+     test
+     .br
+     .box
+     .chop xxx
+     .unformat xxx
+     This is \*[xxx].
+         => This is a funny test.
+
+   *Note Gtroff Internals::.
+
+
+File: groff.info,  Node: Punning Names-Footnotes,  Up: Punning Names
+
+   (1) The backslash is doubled.  *Note Copy Mode::.
+
+
+File: groff.info,  Node: Environments,  Next: Suppressing Output,  Prev: Diversions,  Up: GNU troff Reference
+
+5.31 Environments
+=================
+
+As discussed in *note Deferring Output::, environments store most of the
+parameters that determine the appearance of text.  A default environment
+named '0' exists when GNU 'troff' starts up; it is modified by
+formatting-related requests and escape sequences.
+
+   You can create new environments and switch among them.  Only one is
+current at any given time.  Active environments are managed using a
+"stack", a data structure supporting "push" and "pop" operations.  The
+current environment is at the top of the stack.  The same environment
+name can be pushed onto the stack multiple times, possibly interleaved
+with others.  Popping the environment stack does not destroy the current
+environment; it remains accessible by name and can be made current again
+by pushing it at any time.  Environments cannot be renamed or deleted,
+and can only be modified when current.  To inspect the environment
+stack, use the 'pev' request; see *note Debugging::.
+
+   Environments store the following information.
+
+   * a partially collected line, if any
+
+   * data about the most recently output glyph and line (registers
+     '.cdp', '.cht', '.csk', '.n', '.w')
+
+   * typeface parameters (size, family, style, height and slant,
+     inter-word and inter-sentence space sizes)
+
+   * page parameters (line length, title length, vertical spacing, line
+     spacing, indentation, line numbering, centering, right-alignment,
+     underlining, hyphenation parameters)
+
+   * filling enablement; adjustment enablement and mode
+
+   * tab stops; tab, leader, escape, control, no-break control,
+     hyphenation, and margin characters
+
+   * input line traps
+
+   * stroke and fill colors
+
+ -- Request: .ev [ident]
+ -- Register: \n[.ev]
+     Enter the environment IDENT, which is created if it does not
+     already exist, using the same parameters as for the default
+     environment used at startup.  With no argument, GNU 'troff'
+     switches to the previous environment.
+
+     Invoking 'ev' with an argument puts environment IDENT onto the top
+     of the environment stack.  (If it isn't already present in the
+     stack, this is a proper push.)  Without an argument, 'ev' pops the
+     environment stack, making the previous environment current.  It is
+     an error to pop the environment stack with no previous environment
+     available.  The read-only string-valued register '.ev' contains the
+     name of the current environment--the one at the top of the stack.
+
+          .ev footnote-env
+          .fam N
+          .ps 6
+          .vs 8
+          .ll -.5i
+          .ev
+
+          ...
+
+          .ev footnote-env
+          \[dg] Observe the smaller text and vertical spacing.
+          .ev
+
+     We can familiarize ourselves with stack behavior by wrapping the
+     'ev' request with a macro that reports the contents of the '.ev'
+     register to the standard error stream.
+
+          .de EV
+          .  ev \\$1
+          .  tm environment is now \\n[.ev]
+          ..
+          .
+          .EV foo
+          .EV bar
+          .EV
+          .EV baz
+          .EV
+          .EV
+          .EV
+
+              error-> environment is now foo
+              error-> environment is now bar
+              error-> environment is now foo
+              error-> environment is now baz
+              error-> environment is now foo
+              error-> environment is now 0
+              error-> error: environment stack underflow
+              error-> environment is now 0
+
+ -- Request: .evc environment
+     Copy the contents of ENVIRONMENT to the current environment.
+
+     The following environment data are not copied.
+
+        * a partially collected line, if present;
+
+        * the interruption status of the previous input line (due to use
+          of the '\c' escape sequence);
+
+        * the count of remaining lines to center, to right-justify, or
+          to underline (with or without underlined spaces)--these are
+          set to zero;
+
+        * the activation status of temporary indentation;
+
+        * input line traps and their associated data;
+
+        * the activation status of line numbering (which can be
+          reactivated with '.nm +0'); and
+
+        * the count of consecutive hyphenated lines (set to zero).
+
+ -- Register: \n[.w]
+ -- Register: \n[.cht]
+ -- Register: \n[.cdp]
+ -- Register: \n[.csk]
+     The '\n[.w]' register contains the width of the last glyph
+     formatted in the environment.
+
+     The '\n[.cht]' register contains the height of the last glyph
+     formatted in the environment.
+
+     The '\n[.cdp]' register contains the depth of the last glyph
+     formatted in the environment.  It is positive for glyphs extending
+     below the baseline.
+
+     The '\n[.csk]' register contains the "skew" (how far to the right
+     of the glyph's center that GNU 'troff' should place an accent) of
+     the last glyph formatted in the environment.
+
+ -- Register: \n[.n]
+     The '\n[.n]' register contains the length of the previous output
+     line emitted in the environment.
+
+
+File: groff.info,  Node: Suppressing Output,  Next: Colors,  Prev: Environments,  Up: GNU troff Reference
+
+5.32 Suppressing Output
+=======================
+
+ -- Escape sequence: \O[num]
+     Suppress GNU 'troff' output of glyphs and geometric objects.  The
+     sequences '\O2', '\O3', '\O4', and '\O5' are intended for internal
+     use by 'grohtml'.
+
+     '\O0'
+          Disable the emission of glyphs and geometric objects to the
+          output driver, provided that this sequence occurs at the
+          outermost suppression level (see '\O3' and '\04' below).
+          Horizontal motions corresponding to non-overstruck glyph
+          widths still occur.
+
+     '\O1'
+          Enable the emission of glyphs and geometric objects to the
+          output driver, provided that this sequence occurs at the
+          outermost suppression level.
+
+     '\O0' and '\O1' also reset the four registers 'opminx', 'opminy',
+     'opmaxx', and 'opmaxy' to -1.  These four registers mark the top
+     left and bottom right hand corners of a box encompassing all
+     written or drawn output.
+
+     '\O2'
+          At the outermost suppression level, enable emission of glyphs
+          and geometric objects, and write to the standard error stream
+          the page number and values of the four aforementioned
+          registers encompassing glyphs written since the last
+          interpolation of a '\O' sequence, as well as the page offset,
+          line length, image file name (if any), horizontal and vertical
+          device motion quanta, and input file name.  Numeric values are
+          in basic units.
+
+     '\O3'
+          Begin a nested suppression level.  'grohtml' uses this
+          mechanism to create images of output preprocessed with 'gpic',
+          'geqn', and 'gtbl'.  At startup, GNU 'troff' is at the
+          outermost suppression level.  'pre-grohtml' generates these
+          sequences when processing the document, using GNU 'troff' with
+          the 'ps' output device, Ghostscript, and the PNM tools to
+          produce images in PNG format.  They start a new page if the
+          device is not 'html' or 'xhtml', to reduce the number of
+          images crossing a page boundary.
+
+     '\O4'
+          End a nested suppression level.
+
+     '\O[5PFILE]'
+          At the outermost suppression level, write the name 'file' to
+          the standard error stream at position P, which must be one of
+          'l', 'r', 'c', or 'i', corresponding to left, right, centered,
+          and inline alignments within the document, respectively.  FILE
+          is a name associated with the production of the next image.
+
+ -- Register: \n[.O]
+     Output suppression nesting level applied by '\O3' and '\O4' escape
+     sequences.
+
+
+File: groff.info,  Node: I/O,  Next: Postprocessor Access,  Prev: Suppressing Output,  Up: GNU troff Reference
+
+5.33 I/O
+========
+
+'gtroff' has several requests for including files:
+
+ -- Request: .so file
+ -- Request: .soquiet file
+     Replace the 'so' request's control line with the contents of the
+     file named by the argument, "sourcing" it.  FILE is sought in the
+     directories specified by '-I' command-line option.  If FILE does
+     not exist, a warning in category 'file' is produced and the request
+     has no further effect.  *Note Warnings::, for information about the
+     enablement and suppression of warnings.
+
+     'so' can be useful for large documents; e.g., allowing each chapter
+     of a book to be kept in a separate file.  However, files
+     interpolated with 'so' are not preprocessed; to overcome this
+     limitation, see the 'gsoelim(1)' man page.
+
+     Since GNU 'troff' replaces the entire control line with the
+     contents of a file, it matters whether 'file' is terminated with a
+     newline or not.  Assume that file 'xxx' contains only the word
+     'foo' without a trailing newline.
+
+          $ printf 'foo' > xxx
+
+          The situation is
+          .so xxx
+          bar.
+              => The situation is foobar.
+
+     'soquiet' works the same way, except that no warning diagnostic is
+     issued if FILE does not exist.
+
+ -- Request: .pso command
+     Read the standard output from the specified COMMAND and include it
+     in place of the 'pso' request.
+
+     It is an error to use this request in safer mode, which is the
+     default.  Invoke GNU 'troff' or a front end with the '-U' option to
+     enable unsafe mode.
+
+     The comment regarding a final newline for the 'so' request is valid
+     for 'pso' also.
+
+ -- Request: .mso file
+ -- Request: .msoquiet file
+     Identical to the 'so' and 'soquiet' requests, respectively, except
+     that 'gtroff' searches for the specified FILE in the same
+     directories as macro files for the '-m' command-line option.  If
+     the file name to be included has the form 'NAME.tmac' and it isn't
+     found, these requests try to include 'tmac.NAME' and vice versa.
+
+ -- Request: .trf file
+ -- Request: .cf file
+     Transparently output the contents of FILE.  Each line is output as
+     if it were preceded by '\!'; however, the lines are _not_ subject
+     to copy mode interpretation.  If the file does not end with a
+     newline, 'trf' adds one.  Both requests cause a break.
+
+     When used in a diversion, these requests embed a node (*note Gtroff
+     Internals::) in it that, when reread, causes the contents of FILE
+     to be transparently copied to the output.  In AT&T 'troff', the
+     contents of FILE are immediately copied to the output regardless of
+     whether there is a current diversion; this behaviour is so
+     anomalous that it must be considered a bug.
+
+     While 'cf' copies the contents of FILE completely unprocessed,
+     'trf' disallows characters such as NUL that are not valid 'gtroff'
+     input characters (*note Identifiers::).
+
+     For 'cf', within a diversion, "completely unprocessed" means that
+     each line of a file to be inserted is handled as if it were
+     preceded by '\!\\!'.
+
+     To define a macro 'x' containing the contents of file 'f', use
+
+          .ev 1
+          .di x
+          .trf f
+          .di
+          .ev
+
+     The calls to 'ev' prevent the partially collected output line from
+     becoming part of the diversion (*note Diversions::).
+
+ -- Request: .nx [file]
+     Force 'gtroff' to continue processing of the file specified as an
+     argument.  If no argument is given, immediately jump to the end of
+     file.
+
+ -- Request: .rd [prompt [arg1 arg2 ...]]
+     Read from standard input, and include what is read as though it
+     were part of the input file.  Text is read until a blank line is
+     encountered.
+
+     If standard input is a TTY input device (keyboard), write PROMPT to
+     standard error, followed by a colon (or send BEL for a beep if no
+     argument is given).
+
+     Arguments after PROMPT are available for the input.  For example,
+     the line
+
+          .rd data foo bar
+
+     with the input 'This is \$2.' prints
+
+          This is bar.
+
+   Using the 'nx' and 'rd' requests, it is easy to set up form letters.
+The form letter template is constructed like this, putting the following
+lines into a file called 'repeat.let':
+
+     .ce
+     \*(td
+     .sp 2
+     .nf
+     .rd
+     .sp
+     .rd
+     .fi
+     Body of letter.
+     .bp
+     .nx repeat.let
+
+When this is run, a file containing the following lines should be
+redirected in.  Requests included in this file are executed as though
+they were part of the form letter.  The last block of input is the 'ex'
+request, which tells GNU 'troff' to stop processing.  If this were not
+there, 'troff' would not know when to stop.
+
+     Trent A. Fisher
+     708 NW 19th Av., #202
+     Portland, OR  97209
+
+     Dear Trent,
+
+     Len Adollar
+     4315 Sierra Vista
+     San Diego, CA  92103
+
+     Dear Mr. Adollar,
+
+     .ex
+
+ -- Request: .pi pipe
+     Pipe the output of 'gtroff' to the shell command(s) specified by
+     PIPE.  This request must occur before 'gtroff' has a chance to
+     print anything.
+
+     It is an error to use this request in safer mode, which is the
+     default.  Invoke GNU 'troff' or a front end with the '-U' option to
+     enable unsafe mode.
+
+     Multiple calls to 'pi' are allowed, acting as a chain.  For
+     example,
+
+          .pi foo
+          .pi bar
+          ...
+
+     is the same as '.pi foo | bar'.
+
+     The intermediate output format of GNU 'troff' is piped to the
+     specified commands.  Consequently, calling 'groff' without the '-Z'
+     option normally causes a fatal error.
+
+ -- Request: .sy cmds
+ -- Register: \n[systat]
+     Execute the shell command(s) specified by CMDS.  The output is not
+     saved anywhere, so it is up to the user to do so.
+
+     It is an error to use this request in safer mode; this is the
+     default.  Give GNU 'troff' or a front end program the '-U' option
+     to enable unsafe mode.
+
+     The following code fragment introduces the current time into a
+     document.
+
+          .sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\
+                       (localtime(time))[2,1,0]' > /tmp/x\n[$$]
+          .so /tmp/x\n[$$]
+          .sy rm /tmp/x\n[$$]
+          \nH:\nM:\nS
+
+     This works by having the Perl script (run by 'sy') write 'nr'
+     requests that set the registers 'H', 'M', and 'S' to a temporary
+     file.  The 'roff' document then reads the temporary file using the
+     'so' request.
+
+     The registers 'seconds', 'minutes', and 'hours', initialized at
+     startup of GNU 'troff', should satisfy most requirements.  Use the
+     'af' request to format their values for output.
+
+          .af hours 00
+          .af minutes 00
+          .af seconds 00
+          \n[hours]:\n[minutes]:\n[seconds]
+              => 02:17:54
+
+     The writable register 'systat' contains the return value of the
+     'system()' function executed by the last 'sy' request.
+
+ -- Request: .open stream file
+ -- Request: .opena stream file
+     Open the specified FILE for writing and associates the specified
+     STREAM with it.
+
+     The 'opena' request is like 'open', but if the file exists, append
+     to it instead of truncating it.
+
+     It is an error to use these requests in safer mode; this is the
+     default.  Give GNU 'troff' or a front end program the '-U' option
+     to enable unsafe mode.
+
+ -- Request: .write stream data
+ -- Request: .writec stream data
+     Write to the file associated with the specified STREAM.  The stream
+     must previously have been the subject of an open request.  The
+     remainder of the line is interpreted as the 'ds' request reads its
+     second argument: an initial neutral double quote in CONTENTS is
+     stripped to allow embedding of leading spaces, and it is read in
+     copy mode.
+
+     The 'writec' request is like 'write', but only 'write' appends a
+     newline to the data.
+
+ -- Request: .writem stream xx
+     Write the contents of the macro or string XX to the file associated
+     with the specified STREAM.
+
+     XX is read in copy mode, i.e., already formatted elements are
+     ignored.  Consequently, diversions must be unformatted with the
+     'asciify' request before calling 'writem'.  Usually, this means a
+     loss of information.
+
+ -- Request: .close stream
+     Close the specified STREAM; the stream is no longer an acceptable
+     argument to the 'write' request.
+
+     Here a simple macro to write an index entry.
+
+          .open idx test.idx
+          .
+          .de IX
+          .  write idx \\n[%] \\$*
+          ..
+          .
+          .IX test entry
+          .
+          .close idx
+
+ -- Escape sequence: \Ve
+ -- Escape sequence: \V(ev
+ -- Escape sequence: \V[env]
+     Interpolate the contents of the specified environment variable ENV
+     (one-character name E, two-character name EV) as returned by the
+     function 'getenv(3)'.  '\V' is interpreted even in copy mode (*note
+     Copy Mode::).
+
+
+File: groff.info,  Node: Postprocessor Access,  Next: Miscellaneous,  Prev: I/O,  Up: GNU troff Reference
+
+5.34 Postprocessor Access
+=========================
+
+Two escape sequences and two requests enable documents to pass
+information directly to a postprocessor.  These are useful for
+exercising device-specific capabilities that the 'groff' language does
+not abstract or generalize; examples include the embedding of hyperlinks
+and image files.  Device-specific functions are documented in each
+output driver's man page, such as 'gropdf(1)', 'grops(1)', or
+'grotty(1)'.
+
+ -- Request: .device xxx ...
+ -- Escape sequence: \X'xxx ...'
+     Embed all XXX arguments into GNU 'troff' output as parameters to a
+     device control command 'x X'.  The meaning and interpretation of
+     such parameters is determined by the output driver or other
+     postprocessor.
+
+     The 'device' request processes its arguments in copy mode (*note
+     Copy Mode::).  An initial neutral double quote in CONTENTS is
+     stripped to allow embedding of leading spaces.  By contrast, within
+     '\X' arguments, the escape sequences '\&', '\)', '\%', and '\:' are
+     ignored; '\<SP>' and '\~' are converted to single space characters;
+     and '\\' has its escape character stripped.  So that the basic
+     Latin subset of the Unicode character set(1) (*note Postprocessor
+     Access-Footnote-1::) can be reliably encoded in device control
+     commands, seven special character escape sequences ('\-', '\[aq]',
+     '\[dq]', '\[ga]', '\[ha]', '\[rs]', and '\[ti]',) are mapped to
+     basic Latin characters; see the 'groff_char(7)' man page.  For this
+     transformation, character translations and special character
+     definitions are ignored.(2)  (*note Postprocessor
+     Access-Footnote-2::) The use of any other escape sequence in '\X'
+     parameters is normally an error.
+
+     If the 'use_charnames_in_special' directive appears in the output
+     device's 'DESC' file, the use of special character escape sequences
+     is _not_ an error; they are simply output verbatim (with the
+     exception of the seven mapped to Unicode basic Latin characters,
+     discussed above).  'use_charnames_in_special' is currently employed
+     only by 'grohtml'.
+
+ -- Request: .devicem name
+ -- Escape sequence: \Yn
+ -- Escape sequence: \Y(nm
+ -- Escape sequence: \Y[name]
+     This is approximately equivalent to '\X'\*[NAME]'' (one-character
+     name N, two-character name NM).  However, the contents of the
+     string or macro NAME are not interpreted; also it is permitted for
+     NAME to have been defined as a macro and thus contain newlines (it
+     is not permitted for the argument to '\X' to contain newlines).
+     The inclusion of newlines requires an extension to the AT&T 'troff'
+     output format, and confuses drivers that do not know about this
+     extension (*note Device Control Commands::).
+
+ -- Request: .tag name
+ -- Request: .taga name
+     Reserved for internal use.
+
+
+File: groff.info,  Node: Postprocessor Access-Footnotes,  Up: Postprocessor Access
+
+   (1) that is, ISO 646:1991-IRV or, popularly, "US-ASCII"
+
+   (2) They are bypassed because these parameters are not rendered as
+glyphs in the output; instead, they remain abstract characters--in a PDF
+bookmark or a URL, for example.
+
+
+File: groff.info,  Node: Miscellaneous,  Next: Gtroff Internals,  Prev: Postprocessor Access,  Up: GNU troff Reference
+
+5.35 Miscellaneous
+==================
+
+We document here GNU 'troff' features that fit poorly elsewhere.
+
+ -- Request: .nm [start [increment [space [indentation]]]]
+ -- Register: \n[ln]
+ -- Register: \n[.nm]
+     Begin (or, with no arguments, cease) numbering output lines.  START
+     assigns the number of the _next_ output line.  Only line numbers
+     divisible by INCREMENT are marked (default: '1').  SPACE configures
+     the horizontal spacing between the number and the text (default:
+     '1').  Any given INDENTATION is applied to the numbers (default:
+     '0').  The third and fourth arguments are reckoned in numeral
+     widths ('\0').  START must be non-negative and INCREMENT positive.
+
+     The formatter aligns the number to the right in a width of three
+     numeral spaces plus INDENTATION, then catenates SPACE and the
+     output line.  The line length is _not_ reduced.  Depending on the
+     value of the page offset,(1) (*note Miscellaneous-Footnote-1::)
+     numbers wider than the allocated space protrude into the left
+     margin, or shift the output line to the right.
+
+     Line numbering parameters corresponding to missing arguments are
+     not altered.  After numbering is disabled, '.nm +0' resumes it
+     using the previously active parameters.
+
+     The parameters of 'nm' are associated with the environment (*note
+     Environments::).
+
+     While numbering is enabled, the output line number register 'ln' is
+     updated as each line is output, even if no line number is formatted
+     with it because it is being skipped (it is not a multiple of
+     INCREMENT) or because numbering is suppressed (see the 'nn' request
+     below).
+
+     The '.nm' register tracks the enablement status of numbering.
+     Temporary suspension of numbering with the 'nn' request does _not_
+     alter its value.
+
+          .po 5n
+          .ll 44n
+          Programming,
+          when stripped of all its circumstantial irrelevancies,
+          .nm 999 1 1 -4
+          boils down to no more and no less than
+          .nm +0 3
+          very effective thinking so as to avoid unmastered
+          .nn 2
+          complexity,
+          to very vigorous separation of your many
+          different concerns.
+          .br
+          \(em Edsger Dijkstra
+          .sp
+          .nm 1 1 1
+          This guy's arrogance takes your breath away.
+          .br
+          \(em John Backus
+              =>      Programming,  when  stripped of all its cir-
+              =>  999 cumstantial irrelevancies, boils down to  no
+              =>      more  and no less than very effective think-
+              =>      ing so as to avoid unmastered complexity, to
+              =>      very vigorous separation of your  many  dif-
+              =>      ferent concerns.
+              => 1002 -- Edsger Dijkstra
+              =>
+              =>    1 This guy's arrogance takes your breath away.
+              =>    2 -- John Backus
+
+ -- Request: .nn [skip]
+ -- Register: \n[.nn]
+     Suppress numbering of the next SKIP output lines that would
+     otherwise be numbered.  The default is 1.  'nn' can be invoked when
+     line numbering is not active; suppression of numbering will take
+     effect for SKIP lines once 'nm' enables it.
+
+     The '.nn' register stores the count of output lines still to have
+     their numbering suppressed.
+
+     This count is associated with the environment (*note
+     Environments::).
+
+   To test whether the current output line will be numbered, you must
+check both the '.nm' and '.nn' registers.
+
+       .de is-numbered
+       .  nop This line
+       .  ie (\\n[.nm] & (1-\\n[.nn])) IS
+       .  el                           ISN'T
+       .  nop numbered.
+       .  br
+       ..
+       Test line numbering.
+       .is-numbered
+       .nm 1
+       .nn 1
+       .is-numbered
+       .is-numbered
+       .nm
+       .is-numbered
+         => Test line numbering.  This line ISN'T numbered.
+         => This line ISN'T numbered.
+         =>   1 This line IS numbered.
+         => This line ISN'T numbered.
+
+ -- Request: .mc [margin-character [distance]
+     Begin (or, with no arguments, cease) writing a "margin-character"
+     to the right of each output line.  The DISTANCE argument separates
+     MARGIN-CHARACTER from the right margin.  If absent, the most recent
+     value is used; the default is 10 points.  If an output line exceeds
+     the line length, the margin character is appended to it.  No margin
+     character is written on lines produced by the 'tl' request.
+
+     The margin character is a property of the output line; the margin
+     character last configured when the line is output controls.  If the
+     margin character is disabled before an output line breaks, none is
+     output (but see below).
+
+     The margin character is associated with the environment (*note
+     Environments::).
+
+          .ll 5i
+          .nf
+          .mc \[br]
+          This paragraph is marked with a margin character.
+          .sp
+          As seen above, vertical space isn't thus marked.
+          \&
+          An output line that is present, but empty, is.
+              => This paragraph is marked with a margin character.  |
+              =>
+              => As seen above, vertical space isn't thus marked.   |
+              =>                                                    |
+              => An output line that is present, but empty, is.     |
+
+   For compatibility with AT&T 'troff', a call to 'mc' to set the margin
+character can't be undone immediately; at least one line gets a margin
+character.
+
+     .ll 10n
+     .nf
+     .mc |
+     .mc *
+     .mc
+     foo
+     bar
+         => foo        *
+         => bar
+
+   The margin character mechanism is commonly used to annotate changes
+in documents.  The 'groff' distribution ships a program, 'gdiffmk', to
+assist with this task.(2)  (*note Miscellaneous-Footnote-2::)
+
+ -- Request: .psbb file
+ -- Register: \n[llx]
+ -- Register: \n[lly]
+ -- Register: \n[urx]
+ -- Register: \n[ury]
+     Retrieve the bounding box of the PostScript image found in FILE,
+     which must conform to Adobe's "Document Structuring Conventions"
+     (DSC), locate a '%%BoundingBox' comment, and store the (upper-,
+     lower-, -left, -right) values into the registers 'llx', 'lly',
+     'urx', and 'ury'.  If an error occurs (for example, if no
+     '%%BoundingBox' comment is present), the formatter sets these
+     registers to 0.
+
+     The search path for FILE can be controlled with the '-I'
+     command-line option.
+
+
+File: groff.info,  Node: Miscellaneous-Footnotes,  Up: Miscellaneous
+
+   (1) Recall *note Line Layout::.
+
+   (2) Historically, tools named 'nrchbar' and 'changebar' were
+developed for marking changes with margin characters and could be found
+in archives of the 'comp.sources.unix' USENET group.  Some proprietary
+Unices also offer(ed) a 'diffmk' program.
+
+
+File: groff.info,  Node: Gtroff Internals,  Next: Debugging,  Prev: Miscellaneous,  Up: GNU troff Reference
+
+5.36 'gtroff' Internals
+=======================
+
+'gtroff' processes input in three steps.  One or more input characters
+are converted to an "input token".(1)  (*note Gtroff
+Internals-Footnote-1::) Then, one or more input tokens are converted to
+an "output node".  Finally, output nodes are converted to the
+intermediate output language understood by all output devices.
+
+   Actually, before step one happens, 'gtroff' converts certain escape
+sequences into reserved input characters (not accessible by the user);
+such reserved characters are used for other internal processing also -
+this is the very reason why not all characters are valid input.  *Note
+Identifiers::, for more on this topic.
+
+   For example, the input string 'fi\[:u]' is converted into a character
+token 'f', a character token 'i', and a special token ':u' (representing
+u umlaut).  Later on, the character tokens 'f' and 'i' are merged to a
+single output node representing the ligature glyph 'fi' (provided the
+current font has a glyph for this ligature); the same happens with ':u'.
+All output glyph nodes are 'processed', which means that they are
+invariably associated with a given font, font size, advance width, etc.
+During the formatting process, 'gtroff' itself adds various nodes to
+control the data flow.
+
+   Macros, diversions, and strings collect elements in two chained
+lists: a list of input tokens that have been passed unprocessed, and a
+list of output nodes.  Consider the following diversion.
+
+     .di xxx
+     a
+     \!b
+     c
+     .br
+     .di
+
+It contains these elements.
+
+node list            token list   element number
+                                  
+line start node      --           1
+glyph node 'a'       --           2
+word space node      --           3
+--                   'b'          4
+--                   '\n'         5
+glyph node 'c'       --           6
+vertical size node   --           7
+vertical size node   --           8
+--                   '\n'         9
+
+Elements 1, 7, and 8 are inserted by 'gtroff'; the latter two (which are
+always present) specify the vertical extent of the last line, possibly
+modified by '\x'.  The 'br' request finishes the pending output line,
+inserting a newline input token, which is subsequently converted to a
+space when the diversion is reread.  Note that the word space node has a
+fixed width that isn't adjustable anymore.  To convert horizontal space
+nodes back to input tokens, use the 'unformat' request.
+
+   Macros only contain elements in the token list (and the node list is
+empty); diversions and strings can contain elements in both lists.
+
+   The 'chop' request simply reduces the number of elements in a macro,
+string, or diversion by one.  Exceptions are "compatibility save" and
+"compatibility ignore" input tokens, which are ignored.  The 'substring'
+request also ignores those input tokens.
+
+   Some requests like 'tr' or 'cflags' work on glyph identifiers only;
+this means that the associated glyph can be changed without destroying
+this association.  This can be very helpful for substituting glyphs.  In
+the following example, we assume that glyph 'foo' isn't available by
+default, so we provide a substitution using the 'fchar' request and map
+it to input character 'x'.
+
+     .fchar \[foo] foo
+     .tr x \[foo]
+
+Now let us assume that we install an additional special font 'bar' that
+has glyph 'foo'.
+
+     .special bar
+     .rchar \[foo]
+
+Since glyphs defined with 'fchar' are searched before glyphs in special
+fonts, we must call 'rchar' to remove the definition of the fallback
+glyph.  Anyway, the translation is still active; 'x' now maps to the
+real glyph 'foo'.
+
+   Macro and request arguments preserve compatibility mode enablement.
+
+     .cp 1     \" switch to compatibility mode
+     .de xx
+     \\$1
+     ..
+     .cp 0     \" switch compatibility mode off
+     .xx caf\['e]
+         => café
+
+Since compatibility mode is enabled while 'de' is invoked, the macro
+'xx' enables compatibility mode when it is called.  Argument '$1' can
+still be handled properly because it inherits the compatibility mode
+enablement status that was active at the point where 'xx' was called.
+
+   After interpolation of the parameters, the compatibility save and
+restore tokens are removed.
+
+
+File: groff.info,  Node: Gtroff Internals-Footnotes,  Up: Gtroff Internals
+
+   (1) Except the escape sequences '\f', '\F', '\H', '\m', '\M', '\R',
+'\s', and '\S', which are processed immediately if not in copy mode.
+
+
+File: groff.info,  Node: Debugging,  Next: Implementation Differences,  Prev: Gtroff Internals,  Up: GNU troff Reference
+
+5.37 Debugging
+==============
+
+          Standard troff voodoo, just put a power of two backslashes in
+    front of it until it works and if you still have problems add a \c.
+                                                         -- Ron Natalie
+
+   GNU 'troff' is not the easiest language to debug, in part thanks to
+its design features of recursive interpolation and the use of
+multi-stage pipeline processing in the surrounding system.  Nevertheless
+there exist several features useful for troubleshooting.
+
+   Preprocessors use the 'lf' request to preserve the identity of the
+line numbers and names of input files.  GNU 'troff' emits a variety of
+error diagnostics and supports several categories of warning; the output
+of these can be selectively suppressed.  A trace of the formatter's
+input processing stack can be emitted when errors or warnings occur by
+means of GNU 'troff''s '-b' option, or produced on demand with the
+'backtrace' request.  The 'tm' and related requests can be used to emit
+customized diagnostic messages or for instrumentation while
+troubleshooting.  The 'ex' and 'ab' requests cause early termination
+with successful and error exit codes respectively, to halt further
+processing when continuing would be fruitless.  Examine the state of the
+formatter with requests that write lists of defined names (macros,
+strings, and diversions), environments, registers, and page location
+traps to the standard error stream.
+
+ -- Request: .lf line [file]
+     Set the input line number (and, optionally, the file name) GNU
+     'troff' shall use for error and warning messages.  LINE is the
+     input line number of the _next_ line.  Without an argument, the
+     request is ignored.
+
+     'lf''s primary purpose is to aid the debugging of documents that
+     undergo preprocessing.  Programs like 'tbl' that transform input in
+     their own languages into 'roff' requests use it so that any
+     diagnostic messages emitted by 'troff' correspond to the source
+     document.
+
+ -- Request: .tm message
+ -- Request: .tm1 message
+ -- Request: .tmc message
+     Send MESSAGE, which consumes the remainder of the input line and
+     cannot contain special characters, to the standard error stream,
+     followed by a newline.  Leading spaces in MESSAGE are ignored.
+
+     'tm1' is similar, but recognizes and strips a leading neutral
+     double quote from MESSAGE to allow the embedding of leading spaces.
+
+     'tmc' works as 'tm1', but does not append a newline.
+
+ -- Request: .ab [message]
+     Write any MESSAGE to the standard error stream (like 'tm') and then
+     abort GNU 'troff'; that is, stop processing and terminate with a
+     failure status.
+
+ -- Request: .ex
+     Exit GNU 'troff'; that is, stop processing and terminate with a
+     successful status.  To stop processing only the current file, use
+     the 'nx' request; see *note I/O::.
+
+   When doing something involved, it is useful to leave the debugging
+statements in the code and have them turned on by a command-line flag.
+
+     .if \n[DB] .tm debugging output
+
+To activate such statements, use the '-r' option to set the register.
+
+     groff -rDB=1 file
+
+   If it is known in advance that there are many errors and no useful
+output, GNU 'troff' can be forced to suppress formatted output with the
+'-z' option.
+
+ -- Request: .pev
+     Report the state of the current environment followed by that of all
+     other environments to the standard error stream.
+
+ -- Request: .pm
+     Report, to the standard error stream, the names of all defined
+     macros, strings, and diversions with their sizes in bytes.
+
+ -- Request: .pnr
+     Report the names and contents of all currently defined registers to
+     the standard error stream.
+
+ -- Request: .ptr
+     Report the names and positions of all page location traps to the
+     standard error stream.  Empty slots in the list, where a trap has
+     been planted but subsequently (re)moved, are printed as well.
+
+ -- Request: .fl
+     Instruct 'gtroff' to flush its output immediately.  The intent is
+     for interactive use, but this behaviour is currently not
+     implemented in 'gtroff'.  Contrary to Unix 'troff', TTY output is
+     sent to a device driver also ('grotty'), making it non-trivial to
+     communicate interactively.
+
+     This request causes a line break.
+
+ -- Request: .backtrace
+     Write the state of the input stack to the standard error stream.
+
+     Consider the following in a file 'test'.
+
+          .de xxx
+          .  backtrace
+          ..
+          .de yyy
+          .  xxx
+          ..
+          .
+          .yyy
+              error-> troff: backtrace: 'test':2: macro 'xxx'
+              error-> troff: backtrace: 'test':5: macro 'yyy'
+              error-> troff: backtrace: file 'test':8
+
+     The '-b' option of GNU 'troff' causes a backtrace to be generated
+     on each error or warning.  Some warnings have to be enabled; *Note
+     Warnings::.
+
+ -- Register: \n[slimit]
+     If greater than 0, sets the maximum quantity of objects on GNU
+     'troff''s internal input stack.  If less than or equal to 0, there
+     is no limit: recursion can continue until program memory is
+     exhausted.  The default is 1,000.
+
+ -- Request: .warnscale su
+     Set the scaling unit used in certain warnings to SU, which can take
+     the values 'u', 'i', 'c', 'p', and 'P'.  The default is 'i'.
+
+ -- Request: .spreadwarn [limit]
+     Emit a 'break' warning if the additional space inserted for each
+     space between words in an output line adjusted to both margins with
+     '.ad b' is larger than or equal to LIMIT.  A negative value is
+     treated as zero; an absent argument toggles the warning on and off
+     without changing LIMIT.  The default scaling unit is 'm'.  At
+     startup, 'spreadwarn' is inactive and LIMIT is 3m.
+
+     For example,
+
+          .spreadwarn 0.2m
+
+     causes a warning if 'break' warnings are not suppressed and
+     'gtroff' must add 0.2m or more for each inter-word space in a line.
+     *Note Warnings::.
+
+   GNU 'troff' has command-line options for reporting warnings ('-w')
+and backtraces ('-b') when a warning or an error occurs.
+
+ -- Request: .warn [n]
+ -- Register: \n[.warn]
+     Select the categories, or "types", of reported warnings.  N is the
+     sum of the numeric codes associated with each warning category that
+     is to be enabled; all other categories are disabled.  The
+     categories and their associated codes are listed in *note
+     Warnings::.  For example, '.warn 0' disables all warnings, and
+     '.warn 1' disables all warnings except those about missing glyphs.
+     If no argument is given, all warning categories are enabled.
+
+     The read-only register '.warn' contains the sum of the numeric
+     codes of enabled warning categories.
+
+* Menu:
+
+* Warnings::
+
+
+File: groff.info,  Node: Warnings,  Prev: Debugging,  Up: Debugging
+
+5.37.1 Warnings
+---------------
+
+Warning diagnostics emitted by GNU 'troff' are divided into named,
+numbered categories.  The name associated with each warning category is
+used by the '-w' and '-W' options.  Each category is also assigned a
+power of two; the sum of enabled category values is used by the 'warn'
+request and the '.warn' register.
+
+   Warnings of each category are produced under the following
+circumstances.
+
+'char'
+'1'
+     No mounted font defines a glyph for the requested character.  This
+     category is enabled by default.
+
+'number'
+'2'
+     An invalid numeric expression was encountered.  This category is
+     enabled by default.  *Note Numeric Expressions::.
+
+'break'
+'4'
+     A filled output line could not be broken such that its length was
+     less than the output line length '\n[.l]'.  This category is
+     enabled by default.
+
+'delim'
+'8'
+     The closing delimiter in an escape sequence was missing or
+     mismatched.
+
+'el'
+'16'
+     The 'el' request was encountered with no prior corresponding 'ie'
+     request.  *Note if-else::.
+
+'scale'
+'32'
+     A scaling unit inappropriate to its context was used in a numeric
+     expression.
+
+'range'
+'64'
+     A numeric expression was out of range for its context.
+
+'syntax'
+'128'
+     A self-contradictory hyphenation mode was requested; an empty or
+     incomplete numeric expression was encountered; an operand to a
+     numeric operator was missing; an attempt was made to define a
+     recursive, empty, or nonsensical character class; or a 'groff'
+     extension conditional expression operator was used while in
+     compatibility mode.
+
+'di'
+'256'
+     A 'di', 'da', 'box', or 'boxa' request was invoked without an
+     argument when there was no current diversion.
+
+'mac'
+'512'
+     An undefined string, macro, or diversion was used.  When such an
+     object is dereferenced, an empty one of that name is automatically
+     created.  So, unless it is later deleted, at most one warning is
+     given for each.
+
+     This warning is also emitted upon an attempt to move an unplanted
+     trap macro (*note Page Location Traps::).  In such cases, the
+     unplanted macro is _not_ dereferenced, so it is not created if it
+     does not exist.
+
+'reg'
+'1024'
+     An undefined register was used.  When an undefined register is
+     dereferenced, it is automatically defined with a value of 0.  So,
+     unless it is later deleted, at most one warning is given for each.
+
+'tab'
+'2048'
+     A tab character was encountered where a number was expected, or
+     appeared in an unquoted macro argument.
+
+'right-brace'
+'4096'
+     A right brace escape sequence '\}' was encountered where a number
+     was expected.
+
+'missing'
+'8192'
+     A request was invoked with a mandatory argument absent.
+
+'input'
+'16384'
+     An invalid character occurred on the input stream.
+
+'escape'
+'32768'
+     An unsupported escape sequence was encountered.
+
+'space'
+'65536'
+     A space was missing between a request or macro and its argument.
+     This warning is produced when an undefined name longer than two
+     characters is encountered and the first two characters of the name
+     constitute a defined name.  No request is invoked, no macro called,
+     and an empty macro is not defined.  This category is enabled by
+     default.  It never occurs in compatibility mode.
+
+'font'
+'131072'
+     A non-existent font was selected, or the selection was ignored
+     because a font selection escape sequence was used after the output
+     line continuation escape sequence on an input line.  This category
+     is enabled by default.
+
+'ig'
+'262144'
+     An invalid escape sequence occurred in input ignored using the 'ig'
+     request.  This warning category diagnoses a condition that is an
+     error when it occurs in non-ignored input.
+
+'color'
+'524288'
+     An undefined color was selected, an attempt was made to define a
+     color using an unrecognized color space, an invalid component in a
+     color definition was encountered, or an attempt was made to
+     redefine a default color.
+
+'file'
+'1048576'
+     An attempt was made to load a file that does not exist.  This
+     category is enabled by default.
+
+   Two warning names group other warning categories for convenience.
+
+'all'
+     All warning categories except 'di', 'mac' and 'reg'.  This
+     shorthand is intended to produce all warnings that are useful with
+     macro packages written for AT&T 'troff' and its descendants, which
+     have less fastidious diagnostics than GNU 'troff'.
+
+'w'
+     All warning categories.  Authors of documents and macro packages
+     targeting 'groff' are encouraged to use this setting.
+
+
+File: groff.info,  Node: Implementation Differences,  Next: Safer Mode,  Prev: Debugging,  Up: GNU troff Reference
+
+5.38 Implementation Differences
+===============================
+
+GNU 'troff' has a number of features that cause incompatibilities with
+documents written for other versions of 'troff'.  Some GNU extensions to
+'troff' have become supported by other implementations.
+
+* Menu:
+
+* Safer Mode::
+* Compatibility Mode::
+* Other Differences::
+
+
+File: groff.info,  Node: Safer Mode,  Next: Compatibility Mode,  Prev: Implementation Differences,  Up: Implementation Differences
+
+5.38.1 Safer Mode
+-----------------
+
+The formatter operates in "safer" mode by default; to mitigate risks
+from untrusted input documents, the 'pi' and 'sy' requests are disabled.
+GNU 'troff''s '-U' option enables "unsafe mode", restoring their
+function and enabling additional 'groff' extension requests, 'open',
+'opena', and 'pso'.  *Note I/O::.
+
+
+File: groff.info,  Node: Compatibility Mode,  Next: Safer Mode,  Prev: Other Differences,  Up: Implementation Differences
+
+5.38.2 Compatibility Mode
+-------------------------
+
+Long identifier names may be GNU 'troff''s most obvious innovation.
+AT&T 'troff' interprets '.dsabcd' as defining a string 'ab' with
+contents 'cd'.  Normally, GNU 'troff' interprets this as a call of a
+macro named 'dsabcd'.  AT&T 'troff' also interprets '\*[' and '\n[' as
+an interpolation of a string or register, respectively, named '['.  In
+GNU 'troff', however, the '[' is normally interpreted as delimiting a
+long name.  In compatibility mode, GNU 'troff' interprets names in the
+traditional way; they thus can be two characters long at most.
+
+ -- Request: .cp [n]
+ -- Register: \n[.C]
+     If N is missing or non-zero, turn on compatibility mode; otherwise,
+     turn it off.
+
+     The read-only register '.C' is 1 if compatibility mode is on,
+     0 otherwise.
+
+     Compatibility mode can be also turned on with the '-C' command-line
+     option.
+
+ -- Request: .do name
+ -- Register: \n[.cp]
+     The 'do' request interprets the string, request, diversion, or
+     macro NAME (along with any further arguments) with compatibility
+     mode disabled.  Compatibility mode is restored (only if it was
+     active) when the _expansion_ of NAME is interpreted; that is, the
+     restored compatibility state applies to the contents of the macro,
+     string, or diversion NAME as well as data read from files or pipes
+     if NAME is any of the 'so', 'soquiet', 'mso', 'msoquiet', or 'pso'
+     requests.
+
+     The following example illustrates several aspects of 'do' behavior.
+
+          .de mac1
+          FOO
+          ..
+          .de1 mac2
+          groff
+          .mac1
+          ..
+          .de mac3
+          compatibility
+          .mac1
+          ..
+          .de ma
+          \\$1
+          ..
+          .cp 1
+          .do mac1
+          .do mac2 \" mac2, defined with .de1, calls "mac1"
+          .do mac3 \" mac3 calls "ma" with argument "c1"
+          .do mac3 \[ti] \" groff syntax accepted in .do arguments
+              => FOO groff FOO compatibility c1 ~
+
+     The read-only register '.cp', meaningful only when dereferenced
+     from a 'do' request, is 1 if compatibility mode was on when the
+     'do' request was encountered, and 0 if it was not.  This register
+     is specialized and may require a statement of rationale.
+
+     When writing macro packages or documents that use GNU 'troff'
+     features and which may be mixed with other packages or documents
+     that do not--common scenarios include serial processing of man
+     pages or use of the 'so' or 'mso' requests--you may desire correct
+     operation regardless of compatibility mode enablement in the
+     surrounding context.  It may occur to you to save the existing
+     value of '\n(.C' into a register, say, '_C', at the beginning of
+     your file, turn compatibility mode off with '.cp 0', then restore
+     it from that register at the end with '.cp \n(_C'.  At the same
+     time, a modular design of a document or macro package may lead you
+     to multiple layers of inclusion.  You cannot use the same register
+     name everywhere lest you "clobber" the value from a preceding or
+     enclosing context.  The two-character register name space of AT&T
+     'troff' is confining and mnemonically challenging; you may wish to
+     use the more capacious name space of GNU 'troff'.  However,
+     attempting '.nr _my_saved_C \n(.C' will not work in compatibility
+     mode; the register name is too long.  "This is exactly what 'do' is
+     for," you think, '.do nr _my_saved_C \n(.C'.  The foregoing will
+     always save zero to your register, because 'do' turns compatibility
+     mode _off_ while it interprets its argument list.
+
+     To robustly save compatibility mode before switching it off, use
+
+          .do nr _my_saved_C \n[.cp]
+          .cp 0
+
+     at the beginning of your file, followed by
+
+          .cp \n[_my_saved_C]
+          .do rr _my_saved_C
+
+     at the end.  As in the C language, we all have to share one big
+     name space, so choose a register name that is unlikely to collide
+     with other uses.
+
+   Normally, GNU 'troff' preserves the interpolation depth in delimited
+arguments, but not in compatibility mode.
+
+     .ds xx '
+     \w'abc\*(xxdef'
+         => 168 (normal mode on a terminal device)
+         => 72def' (compatibility mode on a terminal device)
+
+   Furthermore, the escape sequences '\f', '\H', '\m', '\M', '\R', '\s',
+and '\S' are transparent for the purpose of recognizing a control
+character at the beginning of a line only in compatibility mode.  For
+example, this code produces bold output in both cases, but the text
+differs.
+
+     .de xx
+     Hello!
+     ..
+     \fB.xx\fP
+         => .xx (normal mode)
+         => Hello! (compatibility mode)
+
+   Normally, the syntax form '\s'N accepts only a single character (a
+digit) for N, consistently with other forms that originated in AT&T
+'troff', like '\*', '\$', '\f', '\g', '\k', '\n', and '\z'.  In
+compatibility mode only, a non-zero N must be in the range 4-39.  Legacy
+documents relying upon this quirk of parsing(1) (*note Compatibility
+Mode-Footnote-1::) should be migrated to another '\s' form.
+
+
+File: groff.info,  Node: Compatibility Mode-Footnotes,  Up: Compatibility Mode
+
+   (1) The Graphic Systems C/A/T phototypesetter (the original device
+target for AT&T 'troff') supported only a few discrete type sizes in the
+range 6-36 points, so Ossanna contrived a special case in the parser to
+do what the user must have meant.  Kernighan warned of this in the 1992
+revision of CSTR #54 (§2.3), and more recently, McIlroy referred to it
+as a "living fossil".
+
+
+File: groff.info,  Node: Other Differences,  Prev: Compatibility Mode,  Up: Implementation Differences
+
+5.38.3 Other Differences
+------------------------
+
+'groff' request names unrecognized by other 'troff' implementations will
+likely be ignored by them; escape sequences that are 'groff' extensions
+are liable to be interpreted as if the escape character were not
+present.  For example, the adjustable, non-breaking escape sequence '\~'
+is also supported by Heirloom Doctools 'troff' 050915 (September 2005),
+'mandoc' 1.9.5 (2009-09-21), 'neatroff' (commit 1c6ab0f6e, 2016-09-13),
+and Plan 9 from User Space 'troff' (commit 93f8143600, 2022-08-12), but
+not by Solaris or Documenter's Workbench 'troff's.  *Note Manipulating
+Filling and Adjustment::.
+
+   GNU 'troff' does not allow the use of the escape sequences '\|',
+'\^', '\&', '\{', '\}', '\<SP>', '\'', '\`', '\-', '\_', '\!', '\%', and
+'\c' in identifiers; AT&T 'troff' does.  The '\A' escape sequence (*note
+Identifiers::) may be helpful in avoiding use of these escape sequences
+in names.
+
+   When adjusting to both margins, AT&T 'troff' at first adjusts spaces
+starting from the right; GNU 'troff' begins from the left.  Both
+implementations adjust spaces from opposite ends on alternating output
+lines in this adjustment mode to prevent "rivers" in the text.
+
+   GNU 'troff' does not always hyphenate words as AT&T 'troff' does.
+The AT&T implementation uses a set of hard-coded rules specific to
+English, while GNU 'troff' uses language-specific hyphenation pattern
+files derived from TeX.  Furthermore, in old versions of 'troff' there
+was a limited amount of space to store hyphenation exceptions (arguments
+to the 'hw' request); GNU 'troff' has no such restriction.
+
+   GNU 'troff' predefines a string '.T' containing the argument given to
+the '-T' command-line option, namely the current output device (for
+example, 'pdf' or 'utf8').  The existence of this string is a common
+feature of post-CSTR #54 'troff's(1) (*note Other
+Differences-Footnote-1::) but valid values are specific to each
+implementation.
+
+   AT&T 'troff' ignored attempts to remove read-only registers; GNU
+'troff' honors such requests.  *Note Built-in Registers::.
+
+   The (read-only) register '.T' interpolates 1 if GNU 'troff' is called
+with the '-T' command-line option, and 0 otherwise.  This behavior
+differs from AT&T 'troff', which interpolated 1 only if 'nroff' was the
+formatter and was called with '-T'.
+
+   AT&T 'troff' and other implementations handle the 'lf' request
+differently.  For them, its LINE argument changes the line number of the
+_current_ line.
+
+   AT&T 'troff' had only environments named '0', '1', and '2'.  In GNU
+'troff', any number of environments may exist, using any valid
+identifiers for their names (*note Identifiers::.)
+
+   Fractional type sizes cause one noteworthy incompatibility.  In AT&T
+'troff' the 'ps' request ignores scaling units and thus '.ps 10u' sets
+the type size to 10 points, whereas in GNU 'troff' it sets the type size
+to 10 _scaled_ points.  *Note Using Fractional Type Sizes::.
+
+   The 'ab' request differs from AT&T 'troff': GNU 'troff' writes no
+message to the standard error stream if no arguments are given, and it
+exits with a failure status instead of a successful one.
+
+   The 'bp' request differs from AT&T 'troff': GNU 'troff' does not
+accept a scaling unit on the argument, a page number; the former
+(somewhat uselessly) does.
+
+   The 'pm' request differs from AT&T 'troff': GNU 'troff' reports the
+sizes of macros, strings, and diversions in bytes and ignores an
+argument to report only the sum of the sizes.
+
+   Unlike AT&T 'troff', GNU 'troff' does not ignore the 'ss' request if
+the output is a terminal device; instead, the values of minimal
+inter-word and additional inter-sentence space are each rounded down to
+the nearest multiple of 12.
+
+   In GNU 'troff' there is a fundamental difference between
+(unformatted) characters and (formatted) glyphs.  Everything that
+affects how a glyph is output is stored with the glyph node; once a
+glyph node has been constructed, it is unaffected by any subsequent
+requests that are executed, including 'bd', 'cs', 'tkf', 'tr', or 'fp'
+requests.  Normally, glyphs are constructed from characters immediately
+before the glyph is added to an output line.  Macros, diversions, and
+strings are all, in fact, the same type of object; they contain a
+sequence of intermixed character and glyph nodes.  Special characters
+transform from one to the other: before being added to the output, they
+behave as characters; afterward, they are glyphs.  A glyph node does not
+behave like a character node when it is processed by a macro: it does
+not inherit any of the special properties that the character from which
+it was constructed might have had.  For example, the input
+
+     .di x
+     \\\\
+     .br
+     .di
+     .x
+
+produces '\\' in GNU 'troff'.  Each pair of backslashes becomes one
+backslash _glyph_; the resulting backslashes are thus not interpreted as
+escape _characters_ when they are reread as the diversion is output.
+AT&T 'troff' _would_ interpret them as escape characters when rereading
+them and end up printing one '\'.
+
+   One correct way to obtain a printable backslash in most documents is
+to use the '\e' escape sequence; this always prints a single instance of
+the current escape character,(2) (*note Other Differences-Footnote-2::)
+regardless of whether or not it is used in a diversion; it also works in
+both GNU 'troff' and AT&T 'troff'.
+
+   The other correct way, appropriate in contexts independent of the
+backslash's common use as a 'troff' escape character--perhaps in
+discussion of character sets or other programming languages--is the
+character escape '\(rs' or '\[rs]', for "reverse solidus", from its name
+in the ECMA-6 (ISO/IEC 646) standard.(3)  (*note Other
+Differences-Footnote-3::)
+
+   To store an escape sequence in a diversion that is interpreted when
+the diversion is reread, either use the traditional '\!' transparent
+output facility, or, if this is unsuitable, the new '\?' escape
+sequence.  *Note Diversions:: and *note Gtroff Internals::.
+
+   In the somewhat pathological case where a diversion exists containing
+a partially collected line and a partially collected line at the
+top-level diversion has never existed, AT&T 'troff' will output the
+partially collected line at the end of input; GNU 'troff' will not.
+
+
+File: groff.info,  Node: Other Differences-Footnotes,  Up: Other Differences
+
+   (1) DWB 3.3, Solaris, Heirloom Doctools, and Plan 9 'troff' all
+support it.
+
+   (2) Naturally, if you've changed the escape character, you need to
+prefix the 'e' with whatever it is--and you'll likely get something
+other than a backslash in the output.
+
+   (3) The 'rs' special character identifier was not defined in AT&T
+'troff''s font description files, but is in those of its lineal
+descendant, Heirloom Doctools 'troff', as of the latter's 060716 release
+(July 2006).
+
+
+File: groff.info,  Node: File Formats,  Next: Copying This Manual,  Prev: GNU troff Reference,  Up: Top
+
+6 File Formats
+**************
+
+All files read and written by 'gtroff' are text files.  The following
+two sections describe their format.
+
+* Menu:
+
+* gtroff Output::
+* Device and Font Description Files::
+
+
+File: groff.info,  Node: gtroff Output,  Next: Device and Font Description Files,  Prev: File Formats,  Up: File Formats
+
+6.1 'gtroff' Output
+===================
+
+This section describes the 'groff' intermediate output format produced
+by GNU 'troff'.
+
+   As 'groff' is a wrapper program around GNU 'troff' and automatically
+calls an output driver (or "postprocessor"), this output does not show
+up normally.  This is why it is called _intermediate_.  'groff' provides
+the option '-Z' to inhibit postprocessing such that the produced
+intermediate output is sent to standard output just as it is when
+calling GNU 'troff' directly.
+
+   Here, the term "troff output" describes what is output by GNU
+'troff', while "intermediate output" refers to the language that is
+accepted by the parser that prepares this output for the output drivers.
+This parser handles whitespace more flexibly than AT&T's implementation
+and implements obsolete elements for compatibility; otherwise, both
+formats are the same.(1)  (*note gtroff Output-Footnote-1::)
+
+   The main purpose of the intermediate output concept is to facilitate
+the development of postprocessors by providing a common programming
+interface for all devices.  It has a language of its own that is
+completely different from the 'gtroff' language.  While the 'gtroff'
+language is a high-level programming language for text processing, the
+intermediate output language is a kind of low-level assembler language
+by specifying all positions on the page for writing and drawing.
+
+   The intermediate output produced by 'gtroff' is fairly readable,
+while output from AT&T 'troff' is rather hard to understand because of
+strange habits that are still supported, but not used any longer by
+'gtroff'.
+
+* Menu:
+
+* Language Concepts::
+* Command Reference::
+* Intermediate Output Examples::
+* Output Language Compatibility::
+
+
+File: groff.info,  Node: gtroff Output-Footnotes,  Up: gtroff Output
+
+   (1) The parser and postprocessor for intermediate output can be found
+in the file
+'GROFF-SOURCE-DIR/src/libs/libdriver/input.cpp'.
+
+
+File: groff.info,  Node: Language Concepts,  Next: Command Reference,  Prev: gtroff Output,  Up: gtroff Output
+
+6.1.1 Language Concepts
+-----------------------
+
+The fundamental operation of the GNU 'troff' formatter is the
+translation of the 'groff' input language into a device-independent form
+primarily concerned with what has to be written or drawn at specific
+positions on the output device.  This language is simple and imperative.
+In the following discussion, the term "command" always refers to this
+intermediate output language, and never to the 'groff' language intended
+for direct use by document authors.  Intermediate output commands
+comprise several categories: glyph output; font, color, and text size
+selection; motion of the printing position; page advancement; drawing of
+geometric objects; and device control commands, a catch-all for
+operations not easily classified as any of the foregoing, such as
+directives to start and stop output, identify the intended output
+device, or place URL hyperlinks in supported output formats.
+
+* Menu:
+
+* Separation::
+* Argument Units::
+* Document Parts::
+
+
+File: groff.info,  Node: Separation,  Next: Argument Units,  Prev: Language Concepts,  Up: Language Concepts
+
+6.1.1.1 Separation
+..................
+
+AT&T 'troff' output has strange requirements regarding whitespace.  The
+'gtroff' output parser, however, is more tolerant, making whitespace
+maximally optional.  Such characters, i.e., the tab, space, and newline,
+always have a syntactical meaning.  They are never printable because
+spacing within the output is always done by positioning commands.
+
+   Any sequence of space or tab characters is treated as a single
+"syntactical space".  It separates commands and arguments, but is only
+required when there would occur a clashing between the command code and
+the arguments without the space.  Most often, this happens when
+variable-length command names, arguments, argument lists, or command
+clusters meet.  Commands and arguments with a known, fixed length need
+not be separated by syntactical space.
+
+   A line break is a syntactical element, too.  Every command argument
+can be followed by whitespace, a comment, or a newline character.  Thus
+a "syntactical line break" is defined to consist of optional syntactical
+space that is optionally followed by a comment, and a newline character.
+
+   The normal commands, those for positioning and text, consist of a
+single letter taking a fixed number of arguments.  For historical
+reasons, the parser allows stacking of such commands on the same line,
+but fortunately, in 'gtroff''s intermediate output, every command with
+at least one argument is followed by a line break, thus providing
+excellent readability.
+
+   The other commands--those for drawing and device controlling--have a
+more complicated structure; some recognize long command names, and some
+take a variable number of arguments.  So all 'D' and 'x' commands were
+designed to request a syntactical line break after their last argument.
+Only one command, 'x X', has an argument that can span several input
+lines; all other commands must have all of their arguments on the same
+line as the command, i.e., the arguments may not be split by a line
+break.
+
+   Empty lines (these are lines containing only space and/or a comment),
+can occur everywhere.  They are just ignored.
+
+
+File: groff.info,  Node: Argument Units,  Next: Document Parts,  Prev: Separation,  Up: Language Concepts
+
+6.1.1.2 Argument Units
+......................
+
+Some commands take integer arguments that are assumed to represent
+values in a measurement unit, but the letter for the corresponding
+scaling unit is not written with the output command arguments.  Most
+commands assume the scaling unit 'u', the basic unit of the device, some
+use 'z', the scaled point unit of the device, while others, such as the
+color commands, expect plain integers.
+
+   Single characters can have the eighth bit set, as can the names of
+fonts and special characters.  The names of characters and fonts can be
+of arbitrary length.  A character that is to be printed is always in the
+current font.
+
+   A string argument is always terminated by the next whitespace
+character (space, tab, or newline); an embedded '#' character is
+regarded as part of the argument, not as the beginning of a comment
+command.  An integer argument is already terminated by the next
+non-digit character, which then is regarded as the first character of
+the next argument or command.
+
+
+File: groff.info,  Node: Document Parts,  Prev: Argument Units,  Up: Language Concepts
+
+6.1.1.3 Document Parts
+......................
+
+A correct intermediate output document consists of two parts, the
+"prologue" and the "body".
+
+   The task of the prologue is to set the general device parameters
+using three exactly specified commands.  'gtroff''s prologue is
+guaranteed to consist of the following three lines (in that order):
+
+     x T DEVICE
+     x res N H V
+     x init
+
+with the arguments set as outlined in *note Device Control Commands::.
+The parser for the intermediate output format is able to interpret
+additional whitespace and comments as well even in the prologue.
+
+   The body is the main section for processing the document data.
+Syntactically, it is a sequence of any commands different from the ones
+used in the prologue.  Processing is terminated as soon as the first
+'x stop' command is encountered; the last line of any 'gtroff'
+intermediate output always contains such a command.
+
+   Semantically, the body is page oriented.  A new page is started by a
+'p' command.  Positioning, writing, and drawing commands are always done
+within the current page, so they cannot occur before the first 'p'
+command.  Absolute positioning (by the 'H' and 'V' commands) is done
+relative to the current page; all other positioning is done relative to
+the current location within this page.
+
+
+File: groff.info,  Node: Command Reference,  Next: Intermediate Output Examples,  Prev: Language Concepts,  Up: gtroff Output
+
+6.1.2 Command Reference
+-----------------------
+
+This section describes all intermediate output commands, both from AT&T
+'troff' as well as the 'gtroff' extensions.
+
+* Menu:
+
+* Comment Command::
+* Simple Commands::
+* Graphics Commands::
+* Device Control Commands::
+* Obsolete Command::
+
+
+File: groff.info,  Node: Comment Command,  Next: Simple Commands,  Prev: Command Reference,  Up: Command Reference
+
+6.1.2.1 Comment Command
+.......................
+
+'#ANYTHING<end of line>'
+     A comment.  Ignore any characters from the '#' character up to the
+     next newline character.
+
+     This command is the only possibility for commenting in the
+     intermediate output.  Each comment can be preceded by arbitrary
+     syntactical space; every command can be terminated by a comment.
+
+
+File: groff.info,  Node: Simple Commands,  Next: Graphics Commands,  Prev: Comment Command,  Up: Command Reference
+
+6.1.2.2 Simple Commands
+.......................
+
+The commands in this subsection have a command code consisting of a
+single character, taking a fixed number of arguments.  Most of them are
+commands for positioning and text writing.  These commands are tolerant
+of whitespace.  Optionally, syntactical space can be inserted before,
+after, and between the command letter and its arguments.  All of these
+commands are stackable; i.e., they can be preceded by other simple
+commands or followed by arbitrary other commands on the same line.  A
+separating syntactical space is necessary only when two integer
+arguments would clash or if the preceding argument ends with a string
+argument.
+
+'C ID<whitespace>'
+     Typeset the glyph of the special character ID.  Trailing
+     syntactical space is necessary to allow special character names of
+     arbitrary length.  The drawing position is not advanced.
+
+'c G'
+     Typeset the glyph of the ordinary character C.  The drawing
+     position is not advanced.
+
+'f N'
+     Select the font mounted at position N.  N cannot be negative.
+
+'H N'
+     Horizontally move the drawing position to N basic units from the
+     left edge of the page.  N cannot be negative.
+
+'h N'
+     Move the drawing position right N basic units.  AT&T 'troff'
+     allowed negative N; GNU 'troff' does not produce such values, but
+     'groff''s output driver library handles them.
+
+'m COLOR-SCHEME [COMPONENT ...]'
+     Select the stroke color using the COMPONENTs in the color space
+     SCHEME.  Each COMPONENT is an integer between 0 and 65535.  The
+     quantity of components and their meanings vary with each SCHEME.
+     This command is a 'groff' extension.
+
+     'mc CYAN MAGENTA YELLOW'
+          Use the CMY color scheme with components cyan, magenta, and
+          yellow.
+
+     'md'
+          Use the default color (no components; black in most cases).
+
+     'mg GRAY'
+          Use a grayscale color scheme with a component ranging between
+          0 (black) and 65535 (white).
+
+     'mk CYAN MAGENTA YELLOW BLACK'
+          Use the CMYK color scheme with components cyan, magenta,
+          yellow, and black.
+
+     'mr RED GREEN BLUE'
+          Use the RGB color scheme with components red, green, and blue.
+
+'N N'
+     Typeset the glyph with index N in the current font.  N is normally
+     a non-negative integer.  The drawing position is not advanced.  The
+     'html' and 'xhtml' devices use this command with negative N to
+     produce unbreakable space; the absolute value of N is taken and
+     interpreted in basic units.
+
+'n B A'
+     Indicate a break.  No action is performed; the command is present
+     to make the output more easily parsed.  The integers B and A
+     describe the vertical space amounts before and after the break,
+     respectively.  GNU 'troff' issues this command but 'groff''s output
+     driver library ignores it.  See 'v' and 'V' below.
+
+'p N'
+     Begin a new page, setting its number to N.  Each page is
+     independent, even from those using the same number.  The vertical
+     drawing position is set to 0.  All positioning, writing, and
+     drawing commands are interpreted in the context of a page, so a
+     'p' command must precede them.
+
+'s N'
+     Set type size to N scaled points (unit 'z' in GNU 'troff'.  AT&T
+     'troff' used unscaled points 'p' instead; see *note Output Language
+     Compatibility::.
+
+'t XYZ<whitespace>'
+'t XYZ DUMMY-ARG<whitespace>'
+     Typeset a word XYZ; that is, set a sequence of ordinary glyphs
+     named X, Y, Z, ..., terminated by a space character or a line
+     break; an optional second integer argument is ignored (this allows
+     the formatter to generate an even number of arguments).  Each glyph
+     is set at the current drawing position, and the position is then
+     advanced horizontally by the glyph's width.  A glyph's width is
+     read from its metrics in the font description file, scaled to the
+     current type size, and rounded to a multiple of the horizontal
+     motion quantum.  Use the 'C' command to emplace glyphs of special
+     characters.  The 't' command is a 'groff' extension and is output
+     only for devices whose 'DESC' file contains the 'tcommand'
+     directive; see *note DESC File Format::.
+
+'u N XYZ<whitespace>'
+     Typeset word XYZ with track kerning.  As 't', but after placing
+     each glyph, the drawing position is further advanced horizontally
+     by N basic units ('u').  The 'u' command is a 'groff' extension and
+     is output only for devices whose 'DESC' file contains the
+     'tcommand' directive; see *note DESC File Format::.
+
+'V N'
+     Vertically move the drawing position to N basic units from the top
+     edge of the page.  N cannot be negative.
+
+'v N'
+     Move the drawing position down N basic units.  AT&T 'troff' allowed
+     negative N; GNU 'troff' does not produce such values, but 'groff''s
+     output driver library handles them.
+
+'w'
+     Indicate an inter-word space.  No action is performed; the command
+     is present to make the output more easily parsed.  Only adjustable,
+     breakable inter-word spaces are thus described; those resulting
+     from '\~' or horizontal motion escape sequences are not.  GNU
+     'troff' issues this command but 'groff''s output driver library
+     ignores it.  See 'h' and 'H' above.
+
+
+File: groff.info,  Node: Graphics Commands,  Next: Device Control Commands,  Prev: Simple Commands,  Up: Command Reference
+
+6.1.2.3 Graphics Commands
+.........................
+
+Each graphics or drawing command in the intermediate output starts with
+the letter 'D', followed by one or two characters that specify a
+subcommand; this is followed by a fixed or variable number of integer
+arguments that are separated by a single space character.  A 'D' command
+may not be followed by another command on the same line (apart from a
+comment), so each 'D' command is terminated by a syntactical line break.
+
+   'gtroff' output follows the classical spacing rules (no space between
+command and subcommand, all arguments are preceded by a single space
+character), but the parser allows optional space between the command
+letters and makes the space before the first argument optional.  As
+usual, each space can be any sequence of tab and space characters.
+
+   Some graphics commands can take a variable number of arguments.  In
+this case, they are integers representing a size measured in basic units
+'u'.  The arguments called H1, H2, ..., HN stand for horizontal
+distances where positive means right, negative left.  The arguments
+called V1, V2, ..., VN stand for vertical distances where positive means
+down, negative up.  All these distances are offsets relative to the
+current location.
+
+   Each graphics command directly corresponds to a similar 'gtroff' '\D'
+escape sequence.  *Note Drawing Geometric Objects::.
+
+   Unknown 'D' commands are assumed to be device-specific.  Its
+arguments are parsed as strings; the whole information is then sent to
+the postprocessor.
+
+   In the following command reference, the syntax element <line break>
+means a syntactical line break as defined above.
+
+'D~ H1 V1 H2 V2 ... HN VN<line break>'
+     Draw B-spline from current position to offset (H1,V1), then to
+     offset (H2,V2), if given, etc., up to (HN,VN).  This command takes
+     a variable number of argument pairs; the current position is moved
+     to the terminal point of the drawn curve.
+
+'Da H1 V1 H2 V2<line break>'
+     Draw arc from current position to (H1,V1)+(H2,V2) with center at
+     (H1,V1); then move the current position to the final point of the
+     arc.
+
+'DC D<line break>'
+'DC D DUMMY-ARG<line break>'
+     Draw a solid circle using the current fill color with diameter D
+     (integer in basic units 'u') with leftmost point at the current
+     position; then move the current position to the rightmost point of
+     the circle.  An optional second integer argument is ignored (this
+     allows the formatter to generate an even number of arguments).
+     This command is a 'gtroff' extension.
+
+'Dc D<line break>'
+     Draw circle line with diameter D (integer in basic units 'u') with
+     leftmost point at the current position; then move the current
+     position to the rightmost point of the circle.
+
+'DE H V<line break>'
+     Draw a solid ellipse in the current fill color with a horizontal
+     diameter of H and a vertical diameter of V (both integers in basic
+     units 'u') with the leftmost point at the current position; then
+     move to the rightmost point of the ellipse.  This command is a
+     'gtroff' extension.
+
+'De H V<line break>'
+     Draw an outlined ellipse with a horizontal diameter of H and a
+     vertical diameter of V (both integers in basic units 'u') with the
+     leftmost point at current position; then move to the rightmost
+     point of the ellipse.
+
+'DF COLOR-SCHEME [COMPONENT ...]<line break>'
+     Set fill color for solid drawing objects using different color
+     schemes; the analogous command for setting the color of text, line
+     graphics, and the outline of graphic objects is 'm'.  The color
+     components are specified as integer arguments between 0 and 65535.
+     The number of color components and their meaning vary for the
+     different color schemes.  These commands are generated by
+     'gtroff''s escape sequences '\D'F ...'' and '\M' (with no other
+     corresponding graphics commands).  No position changing.  This
+     command is a 'gtroff' extension.
+
+     'DFc CYAN MAGENTA YELLOW<line break>'
+          Set fill color for solid drawing objects using the CMY color
+          scheme, having the 3 color components CYAN, MAGENTA, and
+          YELLOW.
+
+     'DFd<line break>'
+          Set fill color for solid drawing objects to the default fill
+          color value (black in most cases).  No component arguments.
+
+     'DFg GRAY<line break>'
+          Set fill color for solid drawing objects to the shade of gray
+          given by the argument, an integer between 0 (black) and 65535
+          (white).
+
+     'DFk CYAN MAGENTA YELLOW BLACK<line break>'
+          Set fill color for solid drawing objects using the CMYK color
+          scheme, having the 4 color components CYAN, MAGENTA, YELLOW,
+          and BLACK.
+
+     'DFr RED GREEN BLUE<line break>'
+          Set fill color for solid drawing objects using the RGB color
+          scheme, having the 3 color components RED, GREEN, and BLUE.
+
+'Df N<line break>'
+     The argument N must be an integer in the range -32767 to 32767.
+
+     0 <= N <= 1000
+          Set the color for filling solid drawing objects to a shade of
+          gray, where 0 corresponds to solid white, 1000 (the default)
+          to solid black, and values in between to intermediate shades
+          of gray; this is obsoleted by command 'DFg'.
+
+     N < 0 or N > 1000
+          Set the filling color to the color that is currently being
+          used for the text and the outline, see command 'm'.  For
+          example, the command sequence
+
+               mg 0 0 65535
+               Df -1
+
+          sets all colors to blue.
+
+     No position changing.  This command is a 'gtroff' extension.
+
+'Dl H V<line break>'
+     Draw line from current position to offset (H,V) (integers in basic
+     units 'u'); then set current position to the end of the drawn line.
+
+'Dp H1 V1 H2 V2 ... HN VN<line break>'
+     Draw a polygon line from current position to offset (H1,V1), from
+     there to offset (H2,V2), etc., up to offset (HN,VN), and from there
+     back to the starting position.  For historical reasons, the
+     position is changed by adding the sum of all arguments with odd
+     index to the actual horizontal position and the even ones to the
+     vertical position.  Although this doesn't make sense it is kept for
+     compatibility.  This command is a 'gtroff' extension.
+
+'DP H1 V1 H2 V2 ... HN VN<line break>'
+     Draw a solid polygon in the current fill color rather than an
+     outlined polygon, using the same arguments and positioning as the
+     corresponding 'Dp' command.  This command is a 'gtroff' extension.
+
+'Dt N<line break>'
+     Set the current line thickness to N (an integer in basic units 'u')
+     if N>0; if N=0 select the smallest available line thickness; if N<0
+     set the line thickness proportional to the type size (this is the
+     default before the first 'Dt' command was specified).  For
+     historical reasons, the horizontal position is changed by adding
+     the argument to the actual horizontal position, while the vertical
+     position is not changed.  Although this doesn't make sense it is
+     kept for compatibility.  This command is a 'gtroff' extension.
+
+
+File: groff.info,  Node: Device Control Commands,  Next: Obsolete Command,  Prev: Graphics Commands,  Up: Command Reference
+
+6.1.2.4 Device Control Commands
+...............................
+
+Each device control command starts with the letter 'x', followed by a
+space character (optional or arbitrary space or tab in 'gtroff') and a
+subcommand letter or word; each argument (if any) must be preceded by a
+syntactical space.  All 'x' commands are terminated by a syntactical
+line break; no device control command can be followed by another command
+on the same line (except a comment).
+
+   The subcommand is basically a single letter, but to increase
+readability, it can be written as a word, i.e., an arbitrary sequence of
+characters terminated by the next tab, space, or newline character.  All
+characters of the subcommand word but the first are simply ignored.  For
+example, 'gtroff' outputs the initialization command 'x i' as 'x init'
+and the resolution command 'x r' as 'x res'.
+
+   In the following, the syntax element <line break> means a syntactical
+line break (*note Separation::).
+
+'xF NAME<line break>'
+     The 'F' stands for FILENAME.
+
+     Use NAME as the intended name for the current file in error
+     reports.  This is useful for remembering the original file name
+     when 'gtroff' uses an internal piping mechanism.  The input file is
+     not changed by this command.  This command is a 'gtroff' extension.
+
+'xf N S<line break>'
+     The 'f' stands for FONT.
+
+     Mount font position N (a non-negative integer) with font named S (a
+     text word).  *Note Font Positions::.
+
+'xH N<line break>'
+     The 'H' stands for HEIGHT.
+
+     Set glyph height to N (a positive integer in scaled points 'z').
+     AT&T 'troff' uses the unit points ('p') instead.  *Note Output
+     Language Compatibility::.
+
+'xi<line break>'
+     The 'i' stands for INIT.
+
+     Initialize device.  This is the third command of the prologue.
+
+'xp<line break>'
+     The 'p' stands for PAUSE.
+
+     Parsed but ignored.  The AT&T 'troff' manual documents this command
+     as
+
+          pause device, can be restarted
+
+     but GNU 'troff' output drivers do nothing with this command.
+
+'xr N H V<line break>'
+     The 'r' stands for RESOLUTION.
+
+     Resolution is N, while H is the minimal horizontal motion, and V
+     the minimal vertical motion possible with this device; all
+     arguments are positive integers in basic units 'u' per inch.  This
+     is the second command of the prologue.
+
+'xS N<line break>'
+     The 'S' stands for SLANT.
+
+     Set slant to N (an integer in basic units 'u').
+
+'xs<line break>'
+     The 's' stands for STOP.
+
+     Terminates the processing of the current file; issued as the last
+     command of any intermediate 'troff' output.
+
+'xt<line break>'
+     The 't' stands for TRAILER.
+
+     Generate trailer information, if any.  In GNU 'troff', this is
+     ignored.
+
+'xT XXX<line break>'
+     The 'T' stands for TYPESETTER.
+
+     Set the name of the output driver to XXX, a sequence of
+     non-whitespace characters terminated by whitespace.  The possible
+     names correspond to those of 'groff''s '-T' option.  This is the
+     first command of the prologue.
+
+'xu N<line break>'
+     The 'u' stands for UNDERLINE.
+
+     Configure underlining of spaces.  If N is 1, start underlining of
+     spaces; if N is 0, stop underlining of spaces.  This is needed for
+     the 'cu' request in 'nroff' mode and is ignored otherwise.  This
+     command is a 'gtroff' extension.
+
+'xX ANYTHING<line break>'
+     The 'x' stands for X-ESCAPE.
+
+     Send string ANYTHING uninterpreted to the device.  If the line
+     following this command starts with a '+' character this line is
+     interpreted as a continuation line in the following sense.  The '+'
+     is ignored, but a newline character is sent instead to the device,
+     the rest of the line is sent uninterpreted.  The same applies to
+     all following lines until the first character of a line is not a
+     '+' character.  This command is generated by the 'gtroff' escape
+     sequence '\X'.  The line-continuing feature is a 'gtroff'
+     extension.
+
+
+File: groff.info,  Node: Obsolete Command,  Prev: Device Control Commands,  Up: Command Reference
+
+6.1.2.5 Obsolete Command
+........................
+
+In AT&T 'troff' output, the writing of a single glyph is mostly done by
+a very strange command that combines a horizontal move and a single
+character giving the glyph name.  It doesn't have a command code, but is
+represented by a 3-character argument consisting of exactly 2 digits and
+a character.
+
+DDG
+     Move right DD (exactly two decimal digits) basic units 'u', then
+     print glyph G (represented as a single character).
+
+     In GNU 'troff', arbitrary syntactical space around and within this
+     command is allowed.  Only when a preceding command on the same line
+     ends with an argument of variable length is a separating space
+     obligatory.  In AT&T 'troff', large clusters of these and other
+     commands are used, mostly without spaces; this made such output
+     almost unreadable.
+
+   For modern high-resolution devices, this command does not make sense
+because the width of the glyphs can become much larger than two decimal
+digits.  In 'gtroff', this is only used for the devices 'X75', 'X75-12',
+'X100', and 'X100-12'.  For other devices, the commands 't' and 'u'
+provide a better functionality.
+
+
+File: groff.info,  Node: Intermediate Output Examples,  Next: Output Language Compatibility,  Prev: Command Reference,  Up: gtroff Output
+
+6.1.3 Intermediate Output Examples
+----------------------------------
+
+This section presents the intermediate output generated from the same
+input for three different devices.  The input is the sentence 'hell
+world' fed into 'gtroff' on the command line.
+
+High-resolution device 'ps'
+
+     This is the standard output of 'gtroff' if no '-T' option is given.
+
+          shell> echo "hell world" | groff -Z -T ps
+
+          x T ps
+          x res 72000 1 1
+          x init
+          p1
+          x font 5 TR
+          f5
+          s10000
+          V12000
+          H72000
+          thell
+          wh2500
+          tw
+          H96620
+          torld
+          n12000 0
+          x trailer
+          V792000
+          x stop
+
+     This output can be fed into 'grops' to get its representation as a
+     PostScript file.
+
+Low-resolution device 'latin1'
+
+     This is similar to the high-resolution device except that the
+     positioning is done at a minor scale.  Some comments (lines
+     starting with '#') were added for clarification; they were not
+     generated by the formatter.
+
+          shell> echo "hell world" | groff -Z -T latin1
+
+          # prologue
+          x T latin1
+          x res 240 24 40
+          x init
+          # begin a new page
+          p1
+          # font setup
+          x font 1 R
+          f1
+          s10
+          # initial positioning on the page
+          V40
+          H0
+          # write text 'hell'
+          thell
+          # inform about space, and issue a horizontal jump
+          wh24
+          # write text 'world'
+          tworld
+          # announce line break, but do nothing because...
+          n40 0
+          # ...the end of the document has been reached
+          x trailer
+          V2640
+          x stop
+
+     This output can be fed into 'grotty' to get a formatted text
+     document.
+
+AT&T 'troff' output
+     Since a computer monitor has a much lower resolution than modern
+     printers, the intermediate output for X11 devices can use the
+     jump-and-write command with its 2-digit displacements.
+
+          shell> echo "hell world" | groff -Z -T X100
+
+          x T X100
+          x res 100 1 1
+          x init
+          p1
+          x font 5 TR
+          f5
+          s10
+          V16
+          H100
+          # write text with jump-and-write commands
+          ch07e07l03lw06w11o07r05l03dh7
+          n16 0
+          x trailer
+          V1100
+          x stop
+
+     This output can be fed into 'xditview' or 'gxditview' for
+     displaying in X.
+
+     Due to the obsolete jump-and-write command, the text clusters in
+     the AT&T 'troff' output are almost unreadable.
+
+
+File: groff.info,  Node: Output Language Compatibility,  Prev: Intermediate Output Examples,  Up: gtroff Output
+
+6.1.4 Output Language Compatibility
+-----------------------------------
+
+The intermediate output language of AT&T 'troff' was first documented in
+'A Typesetter-independent TROFF', by Brian Kernighan, and by 1992 the
+AT&T 'troff' manual was updated to incorprate a description of it.
+
+   The GNU 'troff' intermediate output format is compatible with this
+specification except for the following features.
+
+   * The classical quasi-device independence is not yet implemented.
+
+   * The old hardware was very different from what we use today.  So the
+     'groff' devices are also fundamentally different from the ones in
+     AT&T 'troff'.  For example, the AT&T PostScript device is called
+     'post' and has a resolution of only 720 units per inch, suitable
+     for printers 20 years ago, while 'groff''s 'ps' device has a
+     resolution of 72000 units per inch.  Maybe, by implementing some
+     rescaling mechanism similar to the classical quasi-device
+     independence, 'groff' could emulate AT&T's 'post' device.
+
+   * The B-spline command 'D~' is correctly handled by the intermediate
+     output parser, but the drawing routines aren't implemented in some
+     of the postprocessor programs.
+
+   * The argument of the commands 's' and 'x H' has the implicit unit
+     scaled point 'z' in 'gtroff', while AT&T 'troff' has point ('p').
+     This isn't an incompatibility but a compatible extension, for both
+     units coincide for all devices without a 'sizescale' parameter in
+     the 'DESC' file, including all postprocessors from AT&T and
+     'groff''s text devices.  The few 'groff' devices with a 'sizescale'
+     parameter either do not exist for AT&T 'troff', have a different
+     name, or seem to have a different resolution.  So conflicts are
+     very unlikely.
+
+   * The position changing after the commands 'Dp', 'DP', and 'Dt' is
+     illogical, but as old versions of 'gtroff' used this feature it is
+     kept for compatibility reasons.
+
+
+File: groff.info,  Node: Device and Font Description Files,  Prev: gtroff Output,  Up: File Formats
+
+6.2 Device and Font Description Files
+=====================================
+
+The 'groff' font and output device description formats are slight
+extensions of those used by AT&T device-independent 'troff'.  In
+distinction to the AT&T implementation, 'groff' lacks a binary format;
+all files are text files.(1)  (*note Device and Font Description
+Files-Footnote-1::) The device and font description files for a device
+NAME are stored in a 'devNAME' directory.  The device description file
+is called 'DESC', and, for each font supported by the device, a font
+description file is called 'F', where F is usually an abbreviation of a
+font's name and/or style.  For example, the 'ps' (PostScript) device has
+'groff' font description files for Times roman ('TR') and Zapf Chancery
+Medium italic ('ZCMI'), among many others, while the 'utf8' device (for
+terminal emulators) has only font descriptions for the roman, italic,
+bold, and bold-italic styles ('R', 'I', 'B', and 'BI', respectively).
+
+   Device and font description files are read both by the formatter, GNU
+'troff', and by output drivers.  The programs delegate these files'
+processing to an internal library, 'libgroff', ensuring their consistent
+interpretation.
+
+* Menu:
+
+* DESC File Format::
+* Font Description File Format::
+
+
+File: groff.info,  Node: Device and Font Description Files-Footnotes,  Up: Device and Font Description Files
+
+   (1) Plan 9 'troff' has also abandoned the binary format.
+
+
+File: groff.info,  Node: DESC File Format,  Next: Font Description File Format,  Prev: Device and Font Description Files,  Up: Device and Font Description Files
+
+6.2.1 'DESC' File Format
+------------------------
+
+The 'DESC' file contains a series of directives; each begins a line.
+Their order is not important, with two exceptions: (1) the 'res'
+directive must precede any 'papersize' directive; and (2) the 'charset'
+directive must come last (if at all).  If a directive name is repeated,
+later entries in the file override previous ones (except that the paper
+dimensions are computed based on the 'res' directive last seen when
+'papersize' is encountered).  Spaces and/or tabs separate words and are
+ignored at line boundaries.  Comments start with the '#' character and
+extend to the end of a line.  Empty lines are ignored.
+
+'family FAM'
+     The default font family is FAM.
+
+'fonts N F1 ... FN'
+     Fonts F1, ..., FN are mounted at font positions M+1, ..., M+N where
+     M is the number of 'styles' (see below).  This directive may extend
+     over more than one line.  A font name of '0' causes no font to be
+     mounted at the corresponding position.
+
+'hor N'
+     The horizontal motion quantum is N basic units.  All horizontal
+     quantities are rounded to multiples of N.
+
+'image_generator PROGRAM'
+     Use PROGRAM to generate PNG images from PostScript input.  Under
+     GNU/Linux, this is usually 'gs', but under other systems (notably
+     Cygwin) it might be set to another name.  The 'grohtml' driver uses
+     this directive.
+
+'paperlength N'
+     The vertical dimension of the output medium is N basic units
+     (deprecated: use 'papersize' instead).
+
+'papersize FORMAT-OR-DIMENSION-PAIR-OR-FILE-NAME ...'
+     The dimensions of the output medium are as according to the
+     argument, which is either a standard paper format, a pair of
+     dimensions, or the name of a plain text file containing either of
+     the foregoing.
+
+     Recognized paper formats are the ISO and DIN formats 'A0'-'A7',
+     'B0'-'B7', 'C0'-'C7', 'D0'-'D7'; the U.S. paper types 'letter',
+     'legal', 'tabloid', 'ledger', 'statement', and 'executive'; and the
+     envelope formats 'com10', 'monarch', and 'DL'.  Matching is
+     performed without regard for lettercase.
+
+     Alternatively, the argument can be a custom paper format in the
+     format 'LENGTH,WIDTH' (with no spaces before or after the comma).
+     Both LENGTH and WIDTH must have a unit appended; valid units are
+     'i' for inches, 'c' for centimeters, 'p' for points, and 'P' for
+     picas.  Example: '12c,235p'.  An argument that starts with a digit
+     is always treated as a custom paper format.
+
+     Finally, the argument can be a file name (e.g., '/etc/papersize');
+     if the file can be opened, the first line is read and a match
+     attempted against each of the other forms.  No comment syntax is
+     supported.
+
+     More than one argument can be specified; each is scanned in turn
+     and the first valid paper specification used.
+
+'paperwidth N'
+     The horizontal dimension of the output medium is N basic units
+     (deprecated: use 'papersize' instead).
+
+'pass_filenames'
+     Direct GNU 'troff' to emit the name of the source file being
+     processed.  This is achieved with the intermediate output command
+     'x F', which 'grohtml' interprets.
+
+'postpro PROGRAM'
+     Use PROGRAM as the postprocessor.
+
+'prepro PROGRAM'
+     Use PROGRAM as a preprocessor.  The 'html' and 'xhtml' output
+     devices use this directive.
+
+'print PROGRAM'
+     Use PROGRAM as a spooler program for printing.  If omitted, the
+     '-l' and '-L' options of 'groff' are ignored.
+
+'res N'
+     The device resolution is N basic units per inch.
+
+'sizes S1 ... SN 0'
+     The device has fonts at S1, ..., SN scaled points (see below).  The
+     list of sizes must be terminated by '0'.  Each SI can also be a
+     range of sizes M-N.  The list can extend over more than one line.
+
+'sizescale N'
+     A typographical point is subdivided into N scaled points.  The
+     default is '1'.  *Note Using Fractional Type Sizes::.
+
+'styles S1 ... SM'
+     The first M mounting positions are associated with styles S1, ...,
+     SM.
+
+'tcommand'
+     The postprocessor can handle the 't' and 'u' intermediate output
+     commands.
+
+'unicode'
+     The output device supports the complete Unicode repertoire.  This
+     directive is useful only for devices that produce character
+     entities instead of glyphs.
+
+     If 'unicode' is present, no 'charset' section is required in the
+     font description files since the Unicode handling built into
+     'groff' is used.  However, if there are entries in a font
+     description file's 'charset' section, they either override the
+     default mappings for those particular characters or add new
+     mappings (normally for composite characters).
+
+     The 'utf8', 'html', and 'xhtml' output devices use this directive.
+
+'unitwidth N'
+     Quantities in the font description files are in basic units for
+     fonts whose type size is N scaled points.
+
+'unscaled_charwidths'
+     Make the font handling module always return unscaled character
+     widths.  The 'grohtml' driver uses this directive.
+
+'use_charnames_in_special'
+     GNU 'troff' should encode special characters inside device control
+     commands; see *note Postprocessor Access::.  The 'grohtml' driver
+     uses this directive.
+
+'vert N'
+     The vertical motion quantum is N basic units.  All vertical
+     quantities are rounded to multiples of N.
+
+'charset'
+     This line and everything following it in the file are ignored.  It
+     is recognized for compatibility with other 'troff' implementations.
+     In GNU 'troff', character set repertoire is described on a per-font
+     basis.
+
+   GNU 'troff' recognizes but ignores the directives 'spare1', 'spare2',
+and 'biggestfont'.
+
+   The 'res', 'unitwidth', 'fonts', and 'sizes' lines are mandatory.
+Directives not listed above are ignored by GNU 'troff' but may be used
+by postprocessors to obtain further information about the device.
+
+
+File: groff.info,  Node: Font Description File Format,  Prev: DESC File Format,  Up: Device and Font Description Files
+
+6.2.2 Font Description File Format
+----------------------------------
+
+On typesetting output devices, each font is typically available at
+multiple sizes.  While paper measurements in the device description file
+are in absolute units, measurements applicable to fonts must be
+proportional to the type size.  'groff' achieves this using the
+precedent set by AT&T device-independent 'troff': one font size is
+chosen as a norm, and all others are scaled linearly relative to that
+basis.  The "unit width" is the number of basic units per point when the
+font is rendered at this nominal size.
+
+   For instance, 'groff''s 'lbp' device uses a 'unitwidth' of 800.  Its
+Times roman font 'TR' has a 'spacewidth' of 833; this is also the width
+of its comma, period, centered period, and mathematical asterisk, while
+its 'M' is 2,963 basic units.  Thus, an 'M' on the 'lbp' device is 2,963
+basic units wide at a notional type size of 800 points.(1)  (*note Font
+Description File Format-Footnote-1::)
+
+   A font description file has two sections.  The first is a sequence of
+directives, and is parsed similarly to the 'DESC' file described above.
+Except for the directive names that begin the second section, their
+ordering is immaterial.  Later directives of the same name override
+earlier ones, spaces and tabs are handled in the same way, and the same
+comment syntax is supported.  Empty lines are ignored throughout.
+
+'name F'
+     The name of the font is F.  'DESC' is an invalid font name.  Simple
+     integers are valid, but their use is discouraged.(2)  (*note Font
+     Description File Format-Footnote-2::)
+
+'spacewidth N'
+     The width of an unadjusted inter-word space is N basic units.
+
+   The directives above must appear in the first section; those below
+are optional.
+
+'slant N'
+     The font's glyphs have a slant of N degrees; a positive N slants in
+     the direction of text flow.
+
+'ligatures LIG1 ... LIGN [0]'
+     Glyphs LIG1, ..., LIGN are ligatures; possible ligatures are 'ff',
+     'fi', 'fl', 'ffi' and 'ffl'.  For compatibility with other 'troff'
+     implementations, the list of ligatures may be terminated with
+     a '0'.  The list of ligatures must not extend over more than one
+     line.
+
+'special'
+     The font is "special": when a glyph is requested that is not
+     present in the current font, it is sought in any mounted fonts that
+     bear this property.
+
+   Other directives in this section are ignored by GNU 'troff', but may
+be used by postprocessors to obtain further information about the font.
+
+   The second section contains one or two subsections.  These can appear
+in either order; the first one encountered commences the second section.
+Each starts with a directive on a line by itself.  A 'charset'
+subsection is mandatory unless the associated 'DESC' file contains the
+'unicode' directive.  Another subsection, 'kernpairs', is optional.
+
+   The directive 'charset' starts the character set subsection.(3)
+(*note Font Description File Format-Footnote-3::) It precedes a series
+of glyph descriptions, one per line.  Each such glyph description
+comprises a set of fields separated by spaces or tabs and organized as
+follows.
+
+     NAME METRICS TYPE CODE [ENTITY-NAME] ['--' COMMENT]
+
+NAME identifies the glyph: if NAME is a printable character C, it
+corresponds to the 'troff' ordinary character C.  If NAME is a
+multi-character sequence not beginning with '\', it corresponds to the
+GNU 'troff' special character escape sequence '\[NAME]'.  A name
+consisting of three minus signs, '---', is special and indicates that
+the glyph is unnamed: such glyphs can be accessed only by the '\N'
+escape sequence in 'troff'.  A special character named '---' can still
+be defined using 'char' and similar requests.  The NAME '\-' defines the
+minus sign glyph.  Finally, NAME can be the unbreakable one-sixth and
+one-twelfth space escape sequences, '\|' and '\^' ("thin" and "hair"
+spaces, respectively), in which case only the width metric described
+below is interpreted; a font can thus customize the widths of these
+spaces.
+
+   The form of the METRICS field is as follows.
+
+     WIDTH[','[HEIGHT[','[DEPTH[','[ITALIC-CORRECTION
+       [','[LEFT-ITALIC-CORRECTION[','[SUBSCRIPT-CORRECTION]]]]]]]]]]
+
+There must not be any spaces, tabs, or newlines between these
+"subfields" (which have been split here into two lines only for better
+legibility).  The subfields are in basic units expressed as decimal
+integers.  Unspecified subfields default to '0'.  Since there is no
+associated binary format, these values are not required to fit into the
+C language data type 'char' as they are in AT&T device-independent
+'troff'.
+
+   The WIDTH subfield gives the width of the glyph.  The HEIGHT subfield
+gives the height of the glyph (upward is positive); if a glyph does not
+extend above the baseline, it should be given a zero height, rather than
+a negative height.  The DEPTH subfield gives the depth of the glyph,
+that is, the distance below the baseline to which the glyph extends
+(downward is positive); if a glyph does not extend below the baseline,
+it should be given a zero depth, rather than a negative depth.  Italic
+corrections are relevant to glyphs in italic or oblique styles.  The
+ITALIC-CORRECTION is the amount of space that should be added after an
+oblique glyph to be followed immediately by an upright glyph.  The
+LEFT-ITALIC-CORRECTION is the amount of space that should be added
+before an oblique glyph to be preceded immediately by an upright glyph.
+The SUBSCRIPT-CORRECTION is the amount of space that should be added
+after an oblique glyph to be followed by a subscript; it should be less
+than the italic correction.
+
+   For fonts used with typesetting devices, the TYPE field gives a
+featural description of the glyph: it is a bit mask recording whether
+the glyph is an ascender, descender, both, or neither.  When a '\w'
+escape sequence is interpolated, these values are bitwise or-ed together
+for each glyph and stored in the 'nr' register.  In font descriptions
+for terminal devices, all glyphs might have a type of zero, regardless
+of their appearance.
+
+'0'
+     means the glyph lies entirely between the baseline and a horizontal
+     line at the "x-height" of the font; typical examples are 'a', 'c',
+     and 'x';
+
+'1'
+     means the glyph descends below the baseline, like 'p';
+
+'2'
+     means the glyph ascends above the font's x-height, like 'A' or 'b';
+     and
+
+'3'
+     means the glyph is both an ascender and a descender--this is true
+     of parentheses in some fonts.
+
+   The CODE field gives a numeric identifier that the postprocessor uses
+to render the glyph.  The glyph can be specified to 'troff' using this
+code by means of the '\N' escape sequence.  CODE can be any integer.(4)
+(*note Font Description File Format-Footnote-4::)
+
+   The ENTITY-NAME field defines an identifier for the glyph that the
+postprocessor uses to print the GNU 'troff' glyph NAME.  This field is
+optional; it was introduced so that the 'grohtml' output driver could
+encode its character set.  For example, the glyph '\[Po]' is represented
+by '&pound;' in HTML 4.0.  For efficiency, these data are now compiled
+directly into 'grohtml'.  'grops' uses the field to build sub-encoding
+arrays for PostScript fonts containing more than 256 glyphs.  Anything
+on the line after the ENTITY-NAME field or '--' is ignored.
+
+   A line in the 'charset' section can also have the form
+
+     NAME "
+
+identifying NAME as another name for the glyph mentioned in the
+preceding line.  Such aliases can be chained.
+
+   The directive 'kernpairs' starts a list of kerning adjustments to be
+made to adjacent glyph pairs from this font.  It contains a sequence of
+lines formatted as follows.
+
+     G1 G2 N
+
+The foregoing means that when glyph G1 is typeset immediately before G2,
+the space between them should be increased by N.  Most kerning pairs
+should have a negative value for N.
+
+
+File: groff.info,  Node: Font Description File Format-Footnotes,  Up: Font Description File Format
+
+   (1) 800-point type is not practical for most purposes, but using it
+enables the quantities in the font description files to be expressed as
+integers.
+
+   (2) 'groff' requests and escape sequences interpret non-negative font
+names as mounting positions instead.  Further, a font named '0' cannot
+be automatically mounted by the 'fonts' directive of a 'DESC' file.
+
+   (3) For typesetter devices, this directive is misnamed since it
+starts a list of glyphs, not characters.
+
+   (4) that is, any integer parsable by the C standard library's
+'strtol(3)' function
+
+
+File: groff.info,  Node: Copying This Manual,  Next: Request Index,  Prev: Font Description File Format,  Up: Top
+
+Appendix A Copying This Manual
+******************************
+
+                     Version 1.3, 3 November 2008
+
+     Copyright © 2000-2018 Free Software Foundation, Inc.
+     <http://fsf.org/>
+
+     Everyone is permitted to copy and distribute verbatim copies
+     of this license document, but changing it is not allowed.
+
+  0. PREAMBLE
+
+     The purpose of this License is to make a manual, textbook, or other
+     functional and useful document "free" in the sense of freedom: to
+     assure everyone the effective freedom to copy and redistribute it,
+     with or without modifying it, either commercially or
+     noncommercially.  Secondarily, this License preserves for the
+     author and publisher a way to get credit for their work, while not
+     being considered responsible for modifications made by others.
+
+     This License is a kind of "copyleft", which means that derivative
+     works of the document must themselves be free in the same sense.
+     It complements the GNU General Public License, which is a copyleft
+     license designed for free software.
+
+     We have designed this License in order to use it for manuals for
+     free software, because free software needs free documentation: a
+     free program should come with manuals providing the same freedoms
+     that the software does.  But this License is not limited to
+     software manuals; it can be used for any textual work, regardless
+     of subject matter or whether it is published as a printed book.  We
+     recommend this License principally for works whose purpose is
+     instruction or reference.
+
+  1. APPLICABILITY AND DEFINITIONS
+
+     This License applies to any manual or other work, in any medium,
+     that contains a notice placed by the copyright holder saying it can
+     be distributed under the terms of this License.  Such a notice
+     grants a world-wide, royalty-free license, unlimited in duration,
+     to use that work under the conditions stated herein.  The
+     "Document", below, refers to any such manual or work.  Any member
+     of the public is a licensee, and is addressed as "you".  You accept
+     the license if you copy, modify or distribute the work in a way
+     requiring permission under copyright law.
+
+     A "Modified Version" of the Document means any work containing the
+     Document or a portion of it, either copied verbatim, or with
+     modifications and/or translated into another language.
+
+     A "Secondary Section" is a named appendix or a front-matter section
+     of the Document that deals exclusively with the relationship of the
+     publishers or authors of the Document to the Document's overall
+     subject (or to related matters) and contains nothing that could
+     fall directly within that overall subject.  (Thus, if the Document
+     is in part a textbook of mathematics, a Secondary Section may not
+     explain any mathematics.)  The relationship could be a matter of
+     historical connection with the subject or with related matters, or
+     of legal, commercial, philosophical, ethical or political position
+     regarding them.
+
+     The "Invariant Sections" are certain Secondary Sections whose
+     titles are designated, as being those of Invariant Sections, in the
+     notice that says that the Document is released under this License.
+     If a section does not fit the above definition of Secondary then it
+     is not allowed to be designated as Invariant.  The Document may
+     contain zero Invariant Sections.  If the Document does not identify
+     any Invariant Sections then there are none.
+
+     The "Cover Texts" are certain short passages of text that are
+     listed, as Front-Cover Texts or Back-Cover Texts, in the notice
+     that says that the Document is released under this License.  A
+     Front-Cover Text may be at most 5 words, and a Back-Cover Text may
+     be at most 25 words.
+
+     A "Transparent" copy of the Document means a machine-readable copy,
+     represented in a format whose specification is available to the
+     general public, that is suitable for revising the document
+     straightforwardly with generic text editors or (for images composed
+     of pixels) generic paint programs or (for drawings) some widely
+     available drawing editor, and that is suitable for input to text
+     formatters or for automatic translation to a variety of formats
+     suitable for input to text formatters.  A copy made in an otherwise
+     Transparent file format whose markup, or absence of markup, has
+     been arranged to thwart or discourage subsequent modification by
+     readers is not Transparent.  An image format is not Transparent if
+     used for any substantial amount of text.  A copy that is not
+     "Transparent" is called "Opaque".
+
+     Examples of suitable formats for Transparent copies include plain
+     ASCII without markup, Texinfo input format, LaTeX input format,
+     SGML or XML using a publicly available DTD, and standard-conforming
+     simple HTML, PostScript or PDF designed for human modification.
+     Examples of transparent image formats include PNG, XCF and JPG.
+     Opaque formats include proprietary formats that can be read and
+     edited only by proprietary word processors, SGML or XML for which
+     the DTD and/or processing tools are not generally available, and
+     the machine-generated HTML, PostScript or PDF produced by some word
+     processors for output purposes only.
+
+     The "Title Page" means, for a printed book, the title page itself,
+     plus such following pages as are needed to hold, legibly, the
+     material this License requires to appear in the title page.  For
+     works in formats which do not have any title page as such, "Title
+     Page" means the text near the most prominent appearance of the
+     work's title, preceding the beginning of the body of the text.
+
+     The "publisher" means any person or entity that distributes copies
+     of the Document to the public.
+
+     A section "Entitled XYZ" means a named subunit of the Document
+     whose title either is precisely XYZ or contains XYZ in parentheses
+     following text that translates XYZ in another language.  (Here XYZ
+     stands for a specific section name mentioned below, such as
+     "Acknowledgements", "Dedications", "Endorsements", or "History".)
+     To "Preserve the Title" of such a section when you modify the
+     Document means that it remains a section "Entitled XYZ" according
+     to this definition.
+
+     The Document may include Warranty Disclaimers next to the notice
+     which states that this License applies to the Document.  These
+     Warranty Disclaimers are considered to be included by reference in
+     this License, but only as regards disclaiming warranties: any other
+     implication that these Warranty Disclaimers may have is void and
+     has no effect on the meaning of this License.
+
+  2. VERBATIM COPYING
+
+     You may copy and distribute the Document in any medium, either
+     commercially or noncommercially, provided that this License, the
+     copyright notices, and the license notice saying this License
+     applies to the Document are reproduced in all copies, and that you
+     add no other conditions whatsoever to those of this License.  You
+     may not use technical measures to obstruct or control the reading
+     or further copying of the copies you make or distribute.  However,
+     you may accept compensation in exchange for copies.  If you
+     distribute a large enough number of copies you must also follow the
+     conditions in section 3.
+
+     You may also lend copies, under the same conditions stated above,
+     and you may publicly display copies.
+
+  3. COPYING IN QUANTITY
+
+     If you publish printed copies (or copies in media that commonly
+     have printed covers) of the Document, numbering more than 100, and
+     the Document's license notice requires Cover Texts, you must
+     enclose the copies in covers that carry, clearly and legibly, all
+     these Cover Texts: Front-Cover Texts on the front cover, and
+     Back-Cover Texts on the back cover.  Both covers must also clearly
+     and legibly identify you as the publisher of these copies.  The
+     front cover must present the full title with all words of the title
+     equally prominent and visible.  You may add other material on the
+     covers in addition.  Copying with changes limited to the covers, as
+     long as they preserve the title of the Document and satisfy these
+     conditions, can be treated as verbatim copying in other respects.
+
+     If the required texts for either cover are too voluminous to fit
+     legibly, you should put the first ones listed (as many as fit
+     reasonably) on the actual cover, and continue the rest onto
+     adjacent pages.
+
+     If you publish or distribute Opaque copies of the Document
+     numbering more than 100, you must either include a machine-readable
+     Transparent copy along with each Opaque copy, or state in or with
+     each Opaque copy a computer-network location from which the general
+     network-using public has access to download using public-standard
+     network protocols a complete Transparent copy of the Document, free
+     of added material.  If you use the latter option, you must take
+     reasonably prudent steps, when you begin distribution of Opaque
+     copies in quantity, to ensure that this Transparent copy will
+     remain thus accessible at the stated location until at least one
+     year after the last time you distribute an Opaque copy (directly or
+     through your agents or retailers) of that edition to the public.
+
+     It is requested, but not required, that you contact the authors of
+     the Document well before redistributing any large number of copies,
+     to give them a chance to provide you with an updated version of the
+     Document.
+
+  4. MODIFICATIONS
+
+     You may copy and distribute a Modified Version of the Document
+     under the conditions of sections 2 and 3 above, provided that you
+     release the Modified Version under precisely this License, with the
+     Modified Version filling the role of the Document, thus licensing
+     distribution and modification of the Modified Version to whoever
+     possesses a copy of it.  In addition, you must do these things in
+     the Modified Version:
+
+       A. Use in the Title Page (and on the covers, if any) a title
+          distinct from that of the Document, and from those of previous
+          versions (which should, if there were any, be listed in the
+          History section of the Document).  You may use the same title
+          as a previous version if the original publisher of that
+          version gives permission.
+
+       B. List on the Title Page, as authors, one or more persons or
+          entities responsible for authorship of the modifications in
+          the Modified Version, together with at least five of the
+          principal authors of the Document (all of its principal
+          authors, if it has fewer than five), unless they release you
+          from this requirement.
+
+       C. State on the Title page the name of the publisher of the
+          Modified Version, as the publisher.
+
+       D. Preserve all the copyright notices of the Document.
+
+       E. Add an appropriate copyright notice for your modifications
+          adjacent to the other copyright notices.
+
+       F. Include, immediately after the copyright notices, a license
+          notice giving the public permission to use the Modified
+          Version under the terms of this License, in the form shown in
+          the Addendum below.
+
+       G. Preserve in that license notice the full lists of Invariant
+          Sections and required Cover Texts given in the Document's
+          license notice.
+
+       H. Include an unaltered copy of this License.
+
+       I. Preserve the section Entitled "History", Preserve its Title,
+          and add to it an item stating at least the title, year, new
+          authors, and publisher of the Modified Version as given on the
+          Title Page.  If there is no section Entitled "History" in the
+          Document, create one stating the title, year, authors, and
+          publisher of the Document as given on its Title Page, then add
+          an item describing the Modified Version as stated in the
+          previous sentence.
+
+       J. Preserve the network location, if any, given in the Document
+          for public access to a Transparent copy of the Document, and
+          likewise the network locations given in the Document for
+          previous versions it was based on.  These may be placed in the
+          "History" section.  You may omit a network location for a work
+          that was published at least four years before the Document
+          itself, or if the original publisher of the version it refers
+          to gives permission.
+
+       K. For any section Entitled "Acknowledgements" or "Dedications",
+          Preserve the Title of the section, and preserve in the section
+          all the substance and tone of each of the contributor
+          acknowledgements and/or dedications given therein.
+
+       L. Preserve all the Invariant Sections of the Document, unaltered
+          in their text and in their titles.  Section numbers or the
+          equivalent are not considered part of the section titles.
+
+       M. Delete any section Entitled "Endorsements".  Such a section
+          may not be included in the Modified Version.
+
+       N. Do not retitle any existing section to be Entitled
+          "Endorsements" or to conflict in title with any Invariant
+          Section.
+
+       O. Preserve any Warranty Disclaimers.
+
+     If the Modified Version includes new front-matter sections or
+     appendices that qualify as Secondary Sections and contain no
+     material copied from the Document, you may at your option designate
+     some or all of these sections as invariant.  To do this, add their
+     titles to the list of Invariant Sections in the Modified Version's
+     license notice.  These titles must be distinct from any other
+     section titles.
+
+     You may add a section Entitled "Endorsements", provided it contains
+     nothing but endorsements of your Modified Version by various
+     parties--for example, statements of peer review or that the text
+     has been approved by an organization as the authoritative
+     definition of a standard.
+
+     You may add a passage of up to five words as a Front-Cover Text,
+     and a passage of up to 25 words as a Back-Cover Text, to the end of
+     the list of Cover Texts in the Modified Version.  Only one passage
+     of Front-Cover Text and one of Back-Cover Text may be added by (or
+     through arrangements made by) any one entity.  If the Document
+     already includes a cover text for the same cover, previously added
+     by you or by arrangement made by the same entity you are acting on
+     behalf of, you may not add another; but you may replace the old
+     one, on explicit permission from the previous publisher that added
+     the old one.
+
+     The author(s) and publisher(s) of the Document do not by this
+     License give permission to use their names for publicity for or to
+     assert or imply endorsement of any Modified Version.
+
+  5. COMBINING DOCUMENTS
+
+     You may combine the Document with other documents released under
+     this License, under the terms defined in section 4 above for
+     modified versions, provided that you include in the combination all
+     of the Invariant Sections of all of the original documents,
+     unmodified, and list them all as Invariant Sections of your
+     combined work in its license notice, and that you preserve all
+     their Warranty Disclaimers.
+
+     The combined work need only contain one copy of this License, and
+     multiple identical Invariant Sections may be replaced with a single
+     copy.  If there are multiple Invariant Sections with the same name
+     but different contents, make the title of each such section unique
+     by adding at the end of it, in parentheses, the name of the
+     original author or publisher of that section if known, or else a
+     unique number.  Make the same adjustment to the section titles in
+     the list of Invariant Sections in the license notice of the
+     combined work.
+
+     In the combination, you must combine any sections Entitled
+     "History" in the various original documents, forming one section
+     Entitled "History"; likewise combine any sections Entitled
+     "Acknowledgements", and any sections Entitled "Dedications".  You
+     must delete all sections Entitled "Endorsements."
+
+  6. COLLECTIONS OF DOCUMENTS
+
+     You may make a collection consisting of the Document and other
+     documents released under this License, and replace the individual
+     copies of this License in the various documents with a single copy
+     that is included in the collection, provided that you follow the
+     rules of this License for verbatim copying of each of the documents
+     in all other respects.
+
+     You may extract a single document from such a collection, and
+     distribute it individually under this License, provided you insert
+     a copy of this License into the extracted document, and follow this
+     License in all other respects regarding verbatim copying of that
+     document.
+
+  7. AGGREGATION WITH INDEPENDENT WORKS
+
+     A compilation of the Document or its derivatives with other
+     separate and independent documents or works, in or on a volume of a
+     storage or distribution medium, is called an "aggregate" if the
+     copyright resulting from the compilation is not used to limit the
+     legal rights of the compilation's users beyond what the individual
+     works permit.  When the Document is included in an aggregate, this
+     License does not apply to the other works in the aggregate which
+     are not themselves derivative works of the Document.
+
+     If the Cover Text requirement of section 3 is applicable to these
+     copies of the Document, then if the Document is less than one half
+     of the entire aggregate, the Document's Cover Texts may be placed
+     on covers that bracket the Document within the aggregate, or the
+     electronic equivalent of covers if the Document is in electronic
+     form.  Otherwise they must appear on printed covers that bracket
+     the whole aggregate.
+
+  8. TRANSLATION
+
+     Translation is considered a kind of modification, so you may
+     distribute translations of the Document under the terms of section
+     4.  Replacing Invariant Sections with translations requires special
+     permission from their copyright holders, but you may include
+     translations of some or all Invariant Sections in addition to the
+     original versions of these Invariant Sections.  You may include a
+     translation of this License, and all the license notices in the
+     Document, and any Warranty Disclaimers, provided that you also
+     include the original English version of this License and the
+     original versions of those notices and disclaimers.  In case of a
+     disagreement between the translation and the original version of
+     this License or a notice or disclaimer, the original version will
+     prevail.
+
+     If a section in the Document is Entitled "Acknowledgements",
+     "Dedications", or "History", the requirement (section 4) to
+     Preserve its Title (section 1) will typically require changing the
+     actual title.
+
+  9. TERMINATION
+
+     You may not copy, modify, sublicense, or distribute the Document
+     except as expressly provided under this License.  Any attempt
+     otherwise to copy, modify, sublicense, or distribute it is void,
+     and will automatically terminate your rights under this License.
+
+     However, if you cease all violation of this License, then your
+     license from a particular copyright holder is reinstated (a)
+     provisionally, unless and until the copyright holder explicitly and
+     finally terminates your license, and (b) permanently, if the
+     copyright holder fails to notify you of the violation by some
+     reasonable means prior to 60 days after the cessation.
+
+     Moreover, your license from a particular copyright holder is
+     reinstated permanently if the copyright holder notifies you of the
+     violation by some reasonable means, this is the first time you have
+     received notice of violation of this License (for any work) from
+     that copyright holder, and you cure the violation prior to 30 days
+     after your receipt of the notice.
+
+     Termination of your rights under this section does not terminate
+     the licenses of parties who have received copies or rights from you
+     under this License.  If your rights have been terminated and not
+     permanently reinstated, receipt of a copy of some or all of the
+     same material does not give you any rights to use it.
+
+  10. FUTURE REVISIONS OF THIS LICENSE
+
+     The Free Software Foundation may publish new, revised versions of
+     the GNU Free Documentation License from time to time.  Such new
+     versions will be similar in spirit to the present version, but may
+     differ in detail to address new problems or concerns.  See
+     <http://www.gnu.org/copyleft/>.
+
+     Each version of the License is given a distinguishing version
+     number.  If the Document specifies that a particular numbered
+     version of this License "or any later version" applies to it, you
+     have the option of following the terms and conditions either of
+     that specified version or of any later version that has been
+     published (not as a draft) by the Free Software Foundation.  If the
+     Document does not specify a version number of this License, you may
+     choose any version ever published (not as a draft) by the Free
+     Software Foundation.  If the Document specifies that a proxy can
+     decide which future versions of this License can be used, that
+     proxy's public statement of acceptance of a version permanently
+     authorizes you to choose that version for the Document.
+
+  11. RELICENSING
+
+     "Massive Multiauthor Collaboration Site" (or "MMC Site") means any
+     World Wide Web server that publishes copyrightable works and also
+     provides prominent facilities for anybody to edit those works.  A
+     public wiki that anybody can edit is an example of such a server.
+     A "Massive Multiauthor Collaboration" (or "MMC") contained in the
+     site means any set of copyrightable works thus published on the MMC
+     site.
+
+     "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
+     license published by Creative Commons Corporation, a not-for-profit
+     corporation with a principal place of business in San Francisco,
+     California, as well as future copyleft versions of that license
+     published by that same organization.
+
+     "Incorporate" means to publish or republish a Document, in whole or
+     in part, as part of another Document.
+
+     An MMC is "eligible for relicensing" if it is licensed under this
+     License, and if all works that were first published under this
+     License somewhere other than this MMC, and subsequently
+     incorporated in whole or in part into the MMC, (1) had no cover
+     texts or invariant sections, and (2) were thus incorporated prior
+     to November 1, 2008.
+
+     The operator of an MMC Site may republish an MMC contained in the
+     site under CC-BY-SA on the same site at any time before August 1,
+     2009, provided the MMC is eligible for relicensing.
+
+ADDENDUM: How to use this License for your documents
+====================================================
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and license
+notices just after the title page:
+
+       Copyright (C)  YEAR  YOUR NAME.
+       Permission is granted to copy, distribute and/or modify this document
+       under the terms of the GNU Free Documentation License, Version 1.3
+       or any later version published by the Free Software Foundation;
+       with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+       Texts.  A copy of the license is included in the section entitled ``GNU
+       Free Documentation License''.
+
+   If you have Invariant Sections, Front-Cover Texts and Back-Cover
+Texts, replace the "with...Texts." line with this:
+
+         with the Invariant Sections being LIST THEIR TITLES, with
+         the Front-Cover Texts being LIST, and with the Back-Cover Texts
+         being LIST.
+
+   If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+   If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of free
+software license, such as the GNU General Public License, to permit
+their use in free software.
+
+
+File: groff.info,  Node: Request Index,  Next: Escape Sequence Index,  Prev: Copying This Manual,  Up: Top
+
+Appendix B Request Index
+************************
+
+Request names appear without a leading control character; the defaults
+are '.' for the regular control character and ''' for the no-break
+control character.
+
+
+* Menu:
+
+* ab:                                    Debugging.           (line  55)
+* ad:                                    Manipulating Filling and Adjustment.
+                                                              (line  83)
+* af:                                    Assigning Register Formats.
+                                                              (line  12)
+* aln:                                   Setting Registers.   (line 110)
+* als:                                   Strings.             (line 198)
+* am:                                    Writing Macros.      (line 126)
+* am1:                                   Writing Macros.      (line 127)
+* ami:                                   Writing Macros.      (line 128)
+* ami1:                                  Writing Macros.      (line 129)
+* as:                                    Strings.             (line 114)
+* as1:                                   Strings.             (line 115)
+* asciify:                               Diversions.          (line 208)
+* backtrace:                             Debugging.           (line 104)
+* bd:                                    Artificial Fonts.    (line  95)
+* blm:                                   Blank Line Traps.    (line   7)
+* box:                                   Diversions.          (line  63)
+* boxa:                                  Diversions.          (line  64)
+* bp:                                    Page Control.        (line  11)
+* br:                                    Manipulating Filling and Adjustment.
+                                                              (line  39)
+* break:                                 while.               (line  72)
+* brp:                                   Manipulating Filling and Adjustment.
+                                                              (line 156)
+* c2:                                    Control Characters.  (line  29)
+* cc:                                    Control Characters.  (line  23)
+* ce:                                    Manipulating Filling and Adjustment.
+                                                              (line 208)
+* cf:                                    I/O.                 (line  58)
+* cflags:                                Using Symbols.       (line 252)
+* ch:                                    Page Location Traps. (line 114)
+* char:                                  Using Symbols.       (line 351)
+* chop:                                  Strings.             (line 145)
+* class:                                 Character Classes.   (line  12)
+* close:                                 I/O.                 (line 240)
+* color:                                 Colors.              (line  15)
+* composite:                             Using Symbols.       (line 208)
+* continue:                              while.               (line  76)
+* cp:                                    Compatibility Mode.  (line  16)
+* cs:                                    Artificial Fonts.    (line 125)
+* cu:                                    Artificial Fonts.    (line  86)
+* da:                                    Diversions.          (line  32)
+* de:                                    Writing Macros.      (line  14)
+* de1:                                   Writing Macros.      (line  86)
+* defcolor:                              Colors.              (line  27)
+* dei:                                   Writing Macros.      (line 108)
+* dei1:                                  Writing Macros.      (line 109)
+* device:                                Postprocessor Access.
+                                                              (line  15)
+* devicem:                               Postprocessor Access.
+                                                              (line  45)
+* di:                                    Diversions.          (line  31)
+* do:                                    Compatibility Mode.  (line  27)
+* ds:                                    ms Document Control Settings.
+                                                              (line  15)
+* ds <1>:                                Strings.             (line  24)
+* ds1:                                   Strings.             (line  25)
+* dt:                                    Diversion Traps.     (line  11)
+* ec:                                    Using Escape Sequences.
+                                                              (line  76)
+* ecr:                                   Using Escape Sequences.
+                                                              (line 102)
+* ecs:                                   Using Escape Sequences.
+                                                              (line 101)
+* el:                                    if-else.             (line   8)
+* em:                                    End-of-input Traps.  (line   7)
+* eo:                                    Using Escape Sequences.
+                                                              (line  71)
+* ev:                                    Environments.        (line  46)
+* evc:                                   Environments.        (line 100)
+* ex:                                    Debugging.           (line  60)
+* fam:                                   Font Families.       (line  21)
+* fc:                                    Fields.              (line  18)
+* fchar:                                 Using Symbols.       (line 352)
+* fcolor:                                Colors.              (line  85)
+* fi:                                    Manipulating Filling and Adjustment.
+                                                              (line  66)
+* fl:                                    Debugging.           (line  95)
+* fp:                                    Font Positions.      (line  16)
+* fschar:                                Using Symbols.       (line 353)
+* fspecial:                              Special Fonts.       (line  18)
+* ft:                                    Selecting Fonts.     (line  11)
+* ftr:                                   Selecting Fonts.     (line  69)
+* fzoom:                                 Selecting Fonts.     (line  83)
+* gcolor:                                Colors.              (line  57)
+* hc:                                    Manipulating Hyphenation.
+                                                              (line  88)
+* hcode:                                 Manipulating Hyphenation.
+                                                              (line 293)
+* hla:                                   Manipulating Hyphenation.
+                                                              (line 327)
+* hlm:                                   Manipulating Hyphenation.
+                                                              (line 340)
+* hpf:                                   Manipulating Hyphenation.
+                                                              (line 233)
+* hpfa:                                  Manipulating Hyphenation.
+                                                              (line 234)
+* hpfcode:                               Manipulating Hyphenation.
+                                                              (line 235)
+* hw:                                    Manipulating Hyphenation.
+                                                              (line  22)
+* hy:                                    Manipulating Hyphenation.
+                                                              (line 120)
+* hym:                                   Manipulating Hyphenation.
+                                                              (line 354)
+* hys:                                   Manipulating Hyphenation.
+                                                              (line 369)
+* ie:                                    if-else.             (line   7)
+* if:                                    if-then.             (line   7)
+* ig:                                    Comments.            (line  54)
+* in:                                    Line Layout.         (line  86)
+* it:                                    Input Line Traps.    (line   7)
+* itc:                                   Input Line Traps.    (line   8)
+* kern:                                  Ligatures and Kerning.
+                                                              (line  41)
+* lc:                                    Leaders.             (line  22)
+* length:                                Strings.             (line 135)
+* lf:                                    Debugging.           (line  31)
+* lg:                                    Ligatures and Kerning.
+                                                              (line  23)
+* linetabs:                              Tabs and Fields.     (line 139)
+* ll:                                    Line Layout.         (line 138)
+* ls:                                    Manipulating Spacing.
+                                                              (line  57)
+* lsm:                                   Leading Space Traps. (line   7)
+* lt:                                    Page Layout.         (line  53)
+* mc:                                    Miscellaneous.       (line 110)
+* mk:                                    Page Motions.        (line  10)
+* mso:                                   I/O.                 (line  49)
+* msoquiet:                              I/O.                 (line  50)
+* na:                                    Manipulating Filling and Adjustment.
+                                                              (line 150)
+* ne:                                    Page Control.        (line  31)
+* nf:                                    Manipulating Filling and Adjustment.
+                                                              (line  74)
+* nh:                                    Manipulating Hyphenation.
+                                                              (line 228)
+* nm:                                    Miscellaneous.       (line   9)
+* nn:                                    Miscellaneous.       (line  74)
+* nop:                                   if-then.             (line  26)
+* nr:                                    ms Document Control Settings.
+                                                              (line  11)
+* nr <1>:                                Setting Registers.   (line  10)
+* nr <2>:                                Setting Registers.   (line  64)
+* nr <3>:                                Auto-increment.      (line  14)
+* nroff:                                 troff and nroff Modes.
+                                                              (line  33)
+* ns:                                    Manipulating Spacing.
+                                                              (line 116)
+* nx:                                    I/O.                 (line  90)
+* open:                                  I/O.                 (line 207)
+* opena:                                 I/O.                 (line 208)
+* os:                                    Page Control.        (line  66)
+* output:                                Diversions.          (line 195)
+* pc:                                    Page Layout.         (line  68)
+* pev:                                   Debugging.           (line  78)
+* pi:                                    I/O.                 (line 149)
+* pl:                                    Page Layout.         (line   9)
+* pm:                                    Debugging.           (line  82)
+* pn:                                    Page Layout.         (line  23)
+* pnr:                                   Debugging.           (line  86)
+* po:                                    Line Layout.         (line  60)
+* ps:                                    Changing the Type Size.
+                                                              (line   7)
+* psbb:                                  Miscellaneous.       (line 158)
+* pso:                                   I/O.                 (line  38)
+* ptr:                                   Debugging.           (line  90)
+* pvs:                                   Changing the Vertical Spacing.
+                                                              (line  48)
+* rchar:                                 Using Symbols.       (line 410)
+* rd:                                    I/O.                 (line  95)
+* return:                                Writing Macros.      (line 163)
+* rfschar:                               Using Symbols.       (line 411)
+* rj:                                    Manipulating Filling and Adjustment.
+                                                              (line 247)
+* rm:                                    Strings.             (line 193)
+* rn:                                    Strings.             (line 190)
+* rnn:                                   Setting Registers.   (line 105)
+* rr:                                    Setting Registers.   (line  99)
+* rs:                                    Manipulating Spacing.
+                                                              (line 117)
+* rt:                                    Page Motions.        (line  11)
+* schar:                                 Using Symbols.       (line 354)
+* shc:                                   Manipulating Hyphenation.
+                                                              (line  97)
+* shift:                                 Parameters.          (line  30)
+* sizes:                                 Changing the Type Size.
+                                                              (line  71)
+* so:                                    I/O.                 (line   9)
+* soquiet:                               I/O.                 (line  10)
+* sp:                                    Manipulating Spacing.
+                                                              (line  10)
+* special:                               Special Fonts.       (line  17)
+* spreadwarn:                            Debugging.           (line 135)
+* ss:                                    Manipulating Filling and Adjustment.
+                                                              (line 267)
+* stringdown:                            Strings.             (line 170)
+* stringup:                              Strings.             (line 171)
+* sty:                                   Font Families.       (line  62)
+* substring:                             Strings.             (line 153)
+* sv:                                    Page Control.        (line  65)
+* sy:                                    I/O.                 (line 171)
+* ta:                                    Tabs and Fields.     (line  13)
+* tag:                                   Postprocessor Access.
+                                                              (line  58)
+* taga:                                  Postprocessor Access.
+                                                              (line  59)
+* tc:                                    Tabs and Fields.     (line 127)
+* ti:                                    Line Layout.         (line 110)
+* tkf:                                   Ligatures and Kerning.
+                                                              (line  60)
+* tl:                                    Page Layout.         (line  39)
+* tm:                                    Debugging.           (line  43)
+* tm1:                                   Debugging.           (line  44)
+* tmc:                                   Debugging.           (line  45)
+* tr:                                    Character Translations.
+                                                              (line  13)
+* trf:                                   I/O.                 (line  57)
+* trin:                                  Character Translations.
+                                                              (line  14)
+* trnt:                                  Character Translations.
+                                                              (line  79)
+* troff:                                 troff and nroff Modes.
+                                                              (line  25)
+* uf:                                    Artificial Fonts.    (line  90)
+* ul:                                    Artificial Fonts.    (line  64)
+* unformat:                              Diversions.          (line 233)
+* vpt:                                   Vertical Position Traps.
+                                                              (line  13)
+* vs:                                    Changing the Vertical Spacing.
+                                                              (line   7)
+* warn:                                  Debugging.           (line 154)
+* warnscale:                             Debugging.           (line 131)
+* wh:                                    Page Location Traps. (line  11)
+* while:                                 while.               (line  10)
+* write:                                 I/O.                 (line 219)
+* writec:                                I/O.                 (line 220)
+* writem:                                I/O.                 (line 231)
+