groff_diff(7) — Linux manual page

Name | Description | Language | Formatter output | Debugging | Other differences | Compatibility mode | Authors | See also | COLOPHON

groff_diff(7)       Miscellaneous Information Manual       groff_diff(7)

Name         top

       groff_diff - differences between GNU roff and AT&T troff

Description         top

       The GNU roff text processing system, groff, is an extension of
       AT&T troff, the typesetting system originating in Unix systems of
       the 1970s.  groff removes many arbitrary limitations and adds
       features, both to the input language and to the page description
       language output by the troff formatter.  Differences arising from
       groff's implementation of AT&T troff features are also noted.
       See roff(7) for background.

Language         top

       GNU troff features identifiers of arbitrary length; supports
       color output, non-integral type sizes, and user-defined
       characters; adds more conditional expression operators;
       recognizes additional scaling units and numeric operators;
       enables general file I/O (in “unsafe mode” only); and exposes
       more formatter state.

   Long names
       GNU troff introduces many new requests; with three exceptions
       (cp, do, rj), they have names longer than two characters.  The
       names of registers, fonts, strings/macros/diversions,
       environments, special characters, character classes, streams, and
       colors can be of any length.  Anywhere AT&T troff supports a
       parameterized escape sequence that uses an opening parenthesis
       “(” to introduce a two-character argument, groff supports a
       square-bracketed form “[]” where the argument within can be of
       arbitrary length.

   Font families, abstract styles, and translation
       GNU troff can group text typefaces into families containing each
       of the styles “R”, “I”, “B”, and “BI”.  So that a document need
       not be coupled to a specific font family, an output device can
       associate a style in the abstract sense with a mounting position.
       Thus the default family can be combined with a style dynamically,
       producing a resolved font name.  A document can translate, or
       remap, font names with the ftr request.

       Applying the requests cs, bd, tkf, uf, or fspecial to an abstract
       style affects the member of the default family corresponding to
       that style.  The default family can be set with the fam request
       or -f command-line option.  The styles directive in the output
       device's DESC file controls which mounting positions (if any) are
       initially associated with abstract styles rather than fonts, and
       the sty request can update this association.

   Colors
       groff 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 figures are drawn, and the
       fill color, which paints the interior of filled geometric
       figures.  The color, defcolor, gcolor, and fcolor requests; \m
       and \M escape sequences; and .color, .m, and .M registers
       exercise color support.

   Hyphenation
       GNU troff uses a hyphenation algorithm and language-specific
       pattern files (based on those used in TeX) to decide which words
       can be hyphenated and where.  AT&T troff's hyphenation system
       (“suftab”) was specific to English.

       New requests permit finer control over hyphenation breaking;
       hyphenation of a word might be suppressed due to a limit on
       consecutive hyphenated lines (hlm), a minimum line length
       threshold (hym), or because the line can instead be adjusted with
       additional inter-word space (hys).  A hyphenation language is
       selected with the hla request and hyphenation patterns loaded (or
       appended) with hpf (or hpfa).  If no hyphenation language is set
       or no patterns are loaded, GNU troff will not perform automatic
       hyphenation.  The hcode request assigns values to character codes
       such that they can be handled consistently by the hyphenation
       patterns, for instance by treating accented letters the same as
       their unaccented counterparts.

       GNU troff's \: escape sequence is analogous to the \% sequence
       but produces no hyphen if the word breaks at that location.

   Fractional type sizes and new scaling units
       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 size in
       points.

       A scaled point is equal to 1/sizescale points, where sizescale is
       specified in the device description file, DESC, and defaults
       to 1; see groff_font(5).  Requests and escape sequences in GNU
       troff interpret arguments that represent a type size in 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.  In GNU troff, the register \n[.s] can interpolate
       a non-integral type size.  The register \n[.ps] interpolates the
       type size in scaled points.

       For example, if sizescale is 1000, then a scaled point is one
       thousandth of a point.  Consequently, “.ps 10.5” is synonymous
       with “.ps 10.5z”; both set the type size to 10,500 scaled points,
       or 10.5 points.

       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”, so GNU troff disallows this as well.

       Another new 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.

       Output devices may be limited in the type sizes they can employ.
       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 and .ps registers
       represent the type size selected by the formatter 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.

       A further two new measurement units available in groff are “M”,
       which indicates hundredths of an em, and “f”, which multiplies by
       65,536.  The latter provides convenient fractions for color
       definitions with the defcolor request.  For example, 0.5f equals
       32768u.

   Numeric expressions
       GNU troff permits spaces in a numeric expression within
       parentheses, and offers three new operators.

       e1>?e2 Interpolate the greater of expressions e1 and e2.

       e1<?e2 Interpolate the lesser of expressions e1 and e2.

       (c;e)  Evaluate expression e using c as the default scaling unit,
              ignoring scaling units in e if c is empty.

   Conditional expressions
       More conditions can be tested with the “if” and ie requests, as
       well as the new “while” request.

       c chr  True if a character chr is available, where chr is an
              ordinary character (Unicode basic Latin excluding control
              characters and the space), a special character, or
              \N'index'.

       d nam  True if a string, macro, diversion, or request nam is
              defined.

       F fnt  True if a font fnt is available; fnt can be an abstract
              style or a font name.  fnt is handled as if it were an
              argument to the ft request (that is, the default family is
              combined with an abstract style and font translation is
              applied), but fnt cannot be a mounting position, and no
              font is mounted.

       m col  True if a color col is defined.

       r reg  True if a register reg is defined.

       S sty  True if an abstract style sty is registered.  Font
              translations apply.

       v      Always false.  This condition is for compatibility with
              certain other troff implementations only.  (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.)

   Drawing commands
       GNU troff offers drawing commands to create filled circles and
       ellipses, and polygons.  Stroked (outlined) objects are drawn
       with the stroke color and filled (solid) ones shaded with the
       fill color.  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 a
       stroked one because the former is drawn only within its defined
       area, whereas strokes have a line thickness (set with another new
       drawing command, \D't').

   Escape sequences
       groff introduces several new escape sequences, extends the syntax
       of a few AT&T troff escape sequences (namely, \D, \f, \k, \n, \s,
       \$, and \*), and alters the behavior of \X.  In the following
       list, escape sequences are collated alphabetically at first, and
       then by symbol roughly in Unicode code point order.

       \A'anything'
              Interpolate 1 if anything is a valid identifier, and 0
              otherwise.  Because invalid input characters are removed,
              invalid identifiers are empty or contain spaces, tabs,
              newlines, or escape sequences that interpolate something
              other than a sequence of ordinary characters.  You can
              employ \A to validate a macro argument before using it to
              construct another escape sequence or identifier.

       \B'anything'
              Interpolate 1 if anything is a valid numeric expression,
              and 0 otherwise.  You might use \B along with the “if”
              request to filter out invalid macro arguments.

       \D'C d'
              Draw filled circle of diameter d with its leftmost point
              at the drawing position.

       \D'E h v'
              Draw filled ellipse with h and v as the axes and the
              leftmost point at the drawing position.

       \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; DWB and Heirloom troffs do not.  Afterward, the
              drawing position is left at (hn, vn).

       \D'P h1 v1 ... hn vn'
              As \D'p', but the polygon is filled.

       \D't n'
              Set line thickness of geometric objects to 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.

       \E     Embed an escape character that is not interpreted in copy
              mode (compare with \a and \t).  You can use it to ease the
              writing of nested macro definitions.  It 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.

       \f[fnt]
              Select typeface fnt, which may be a mounting position,
              abstract style, or font name.  \f[] and \fP are synonyms;
              we recommend the former.

       \Ff
       \F(fm
       \F[fml]
              Select default font family.  \F[] makes the previous font
              family the default.  \FP is unlike \fP; it selects font
              family “P” as the default.  See the fam request below.

       \k(rg
       \k[reg]
              Mark horizontal drawing position in two-character register
              name rg or arbitrary register name reg.

       \mc
       \m(cl
       \m[col]
              Set the stroke color.  \m[] restores the previous stroke
              color, or the default if there is none.

       \Mc
       \M(cl
       \M[col]
              Set the fill color.  \M[] restores the previous fill
              color, or the default if there is none.

       \n[reg]
              Interpolate register reg.

       \On
       \O[n]  Suppress troff output of glyphs and geometric objects.
              The sequences \O2, \O3, \O4, and \O5 are intended for
              internal use by grohtml(1).

              \O0
              \O1    Disable and enable, respectively, the emission of
                     glyphs and geometric objects to the output driver,
                     provided that this sequence occurs at the outermost
                     suppression level (see \O3 and \O4).  Horizontal
                     motions corresponding to non-overstruck glyph
                     widths still occur.  These sequences also reset the
                     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
              \O4    Begin and end a nested suppression level,
                     respectively.  grohtml uses this mechanism to
                     create images of output preprocessed with pic, eqn,
                     and tbl.  At startup, troff is at the outermost
                     suppression level.  pre-grohtml generates these
                     sequences when processing the document, using troff
                     with the ps output device, Ghostscript, and the PNM
                     tools to produce images in PNG format.  These
                     sequences start a new page if the device is not
                     html or xhtml, to reduce the number of images
                     crossing a page boundary.

              \O5[Pfile]
                     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 is a
                     name associated with the production of the next
                     image.

       \R'name ±n'
              Synonymous with “.nr name ±n”.

       \s[±n]
       \s±[n]
       \s'±n'
       \s±'n' Set the type size to, or increment or decrement it by, n
              scaled points.

       \Ve
       \V(ev
       \V[env]
              Interpolate contents of the environment variable env, as
              returned by getenv(3).  \V is interpreted even in copy
              mode.

       \X'contents'
              Within contents, the escape sequences \&, \), \%, and \:
              are ignored; \space and \~ are converted to single space
              characters; and a self-escaped escape character is output
              as a backslash \.  So that the basic Latin subset of the
              Unicode character set (that is, ISO 646:1991-IRV or,
              popularly, “US-ASCII”) can be reliably encoded in
              contents, the special character escape sequences \-,
              \[aq], \[dq], \[ga], \[ha], \[rs], and \[ti] are mapped to
              basic Latin characters; see groff_char(7).  For this
              transformation, character translations and definitions are
              ignored.  Other escape sequences are not supported.

       \Ym
       \Y(ma
       \Y[mac]
              Interpolate a macro as a device control command.  This is
              similar to \X'\*[mac]', except the contents of mac are not
              interpreted, and mac can be a macro and thus contain
              newlines, whereas the argument to \X cannot.  This
              inclusion of newlines requires an extension to the AT&T
              troff output format, and will confuse postprocessors that
              do not know about it.

       \Z'anything'
              Save the drawing position, format anything, then restore
              it.  Tabs and leaders in the argument are ignored with an
              error diagnostic.

       \#     Ignore everything up to and including the next newline.
              This escape sequence is interpreted even in copy mode.  \#
              is like \", except that \" does not ignore a newline; the
              latter therefore cannot be used by itself for a whole-line
              comment—it leaves a blank line on the input stream.

       \$0    Interpolate the name by which the macro being interpreted
              was called.  In GNU troff this name can vary; see the als
              request.

       \$(nn
       \$[nnn]
              In a macro or string definition, interpolate the nnth or
              nnnth argument.  Macros and strings can have an unlimited
              number of arguments.

       \$*    In a macro or string definition, interpolate the
              catenation of all arguments, separated by spaces.

       \$@    In a macro or string definition, interpolate the
              catenation of all arguments, with each surrounded by
              double quotes and separated by spaces.

       \$^    In a macro or string definition, interpolate the
              catenation of all arguments constructed in a form suitable
              for passage to the ds request.

       \)     Interpolate a transparent dummy character—one that is
              ignored by 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.

       \*[string [arg ...]]
              Interpolate string, passing it arg ... as arguments.

       \/     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.  Inserting
              \/ between them avoids this problem.  Use this escape
              sequence whenever an oblique glyph is immediately followed
              by an upright glyph without any intervening space.

       \,     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.  Inserting \, between
              them avoids this problem.  Use this escape sequence
              whenever an upright glyph is followed immediately by an
              oblique glyph without any intervening space.

       \:     Insert a non-printing break point.  That is, a word can
              break there, but the soft hyphen character does not mark
              the break point if it does (in contrast to “\%”).  The
              remainder of the word is subject to hyphenation as normal.

       \?anything\?
              When used in a diversion, this escape sequence
              transparently embeds input, read in copy mode, until its
              own next occurrence on the input line.  Use \! if you want
              to embed newlines in a diversion.  Unlike \!, \? is
              interpreted even in copy mode.

       \[char]
              Typeset the special character char.

       \[base-char combining-component ...]
              Typeset a composite glyph consisting of base-char overlaid
              with one or more combining-components.  For example,
              “\[A ho]” is a capital letter “A” with a “hook accent”
              (ogonek).  See the composite request below; Groff: The GNU
              Implementation of troff, the groff Texinfo manual, for
              details of composite glyph name construction; and
              groff_char(7) for a list of components used in composite
              glyph names.

       \~     Insert an unbreakable space that is adjustable like an
              ordinary space.  It is discarded from the end of an output
              line if a break is forced.

   Restricted requests
       To mitigate risks from untrusted input documents, the pi and sy
       requests are disabled by default.  troff(1)'s -U option enables
       the formatter's “unsafe mode”, restoring their function (and
       enabling additional groff extension requests, open, opena, and
       pso).

   New requests
       .aln new old
              Create alias new for existing register named old, causing
              the names to refer to the same stored value.  If old is
              undefined, a warning in category reg is generated and the
              request is ignored.  To remove a register alias, invoke rr
              on its name.  A register's contents do not become
              inaccessible until it has no more names.

       .als new old
              Create alias new for existing request, string, macro, or
              diversion 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.  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.  To remove an alias, invoke
              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.

       .am1 name [end-name]
              As “am”, but compatibility mode is disabled while the
              appendment to name is interpreted: a “compatibility save”
              token is inserted at its beginning, and a “compatibility
              restore” token at its end.  As a consequence, the requests
              “am”, am1, de, and de1 can be intermixed freely since the
              compatibility save/restore tokens affect only the parts of
              the macro populated by am1 and de1.

       .ami name [end-name]
              Append to macro indirectly.  See dei below.

       .ami1 name [end-name]
              As ami, but compatibility mode is disabled during
              interpretation of the appendment.

       .as1 name [["]contents]
              As “as”, but compatibility mode is disabled while the
              appendment to name is interpreted: a “compatibility save”
              token is inserted at the beginning of contents, and a
              “compatibility restore” token after it.  As a consequence,
              the requests “as”, as1, ds, and ds1 can be intermixed
              freely since the compatibility save/restore tokens affect
              only the portions of the strings populated by as1 and ds1.

       .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 in the diversion div are
              treated like ordinary input characters when div is
              interpolated.  Doing so can be useful in conjunction with
              the writem request.

              asciify cannot return all items in a diversion to their
              source equivalent: nodes such as those produced by \N[...]
              will remain nodes, so the result cannot be guaranteed to
              be a pure string.  See section “Copy mode” in groff(7).
              Glyph parameters such as the type face and size are not
              preserved; use unformat to achieve that.

       .backtrace
              Write backtrace of input stack to the standard error
              stream.  See the -b option of troff(1).

       .blm [name]
              Set a blank line macro (trap).  If a blank line macro is
              thus defined, groff executes name when a blank line is
              encountered in the input file, instead of the usual
              behavior.  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.

       .box [name]
       .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.

       .break Exit a “while” loop.  Do not confuse this request with a
              typographical break or the br request.  See “continue”.

       .brp   Break and adjust line; this is the AT&T troff escape
              sequence \p in request form.

       .cflags n c1 c2 ...
              Assign properties encoded by the number n to characters
              c1, c2, and so on.  Ordinary and special characters have
              certain associated properties.  (Glyphs don't: to GNU
              troff, like AT&T device-independent troff, a glyph is an
              identifier corresponding to a rectangle with some metrics;
              see groff_font(5).)  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.

              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 value in combination with
                     values 2 and 4.  Initially, no characters have this
                     property.

              The remaining values were implemented for East Asian
              language support; those who use alphabetic scripts
              exclusively can disregard them.

              128    Prohibit a break before the character, but allow a
                     break after the character.  This works only in
                     combination with values 256 and 512 and has no
                     effect otherwise.  Initially, no characters have
                     this property.

              256    Prohibit a break after the character, but allow a
                     break before the character.  This works only in
                     combination with values 128 and 512 and has no
                     effect otherwise.  Initially, no characters have
                     this property.

              512    Allow a break before or after the character.  This
                     works only in combination with values 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.

       .char c [["]contents]
              Define an ordinary or special character c as contents.  If
              contents is absent, an existing character definition made
              with the same request is deleted.

              Defining (or redefining) a character c creates an object
              in the formatter that is recognized like any other
              ordinary or special character on input, and produces
              contents on output.  Every time c is to be output,
              contents is processed in a temporary environment and the
              result encapsulated in a node.  (See section “Gtroff
              Internals” in Groff: The GNU Implementation of troff, the
              groff Texinfo manual.)  A leading neutral double quote in
              the second argument is stripped from it, allowing embedded
              leading spaces in contents, which is read in copy mode and
              continues to the end of the input line.  Further,
              compatibility mode is disabled and the escape character
              set to \ while contents is processed.  Any emboldening,
              constant spacing, or track kerning is applied to this
              object as a whole, not to each character in contents.

              A character defined by this request can be used just like
              a glyph provided by the output device.  In particular,
              other characters can be translated to it with the tr
              request; it can be made the tab or leader fill character
              with the tc and lc requests; sequences of it can be drawn
              with the \l and \L escape sequences; and, if the hcode
              request is used on c, it is subject to automatic
              hyphenation.

              To prevent infinite recursion, occurrences of c within its
              own definition are treated normally (as if it were not
              being defined with char).  The tr and trin requests take
              precedence if char also applies to c.  A character
              definition can be removed with the rchar request.

       .chop name
              Remove the last character from the macro, string, or
              diversion name.  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
              name; see section “Gtroff Internals” in Groff: The GNU
              Implementation of troff, the groff Texinfo manual, for
              discussion of nodes inserted by groff.

       .class ident c ...
              Define a character class (or simply “class”) ident
              comprising the characters or range expressions c.

              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 c is a character (or
              special character).

              Since class and special character names share the same
              name space, we recommend starting and ending the class
              name with “[” and “]”, respectively, to avoid collisions
              with existing character names defined by groff or the user
              (with char and related requests).  This practice applies
              the presence of “]” in the class name to prevent the usage
              of the special character escape form “\[...]”, thus you
              must use the \C escape sequence to access a class with
              such a name.

              You can also use a character range expression consisting
              of a start character followed by “-” and then an end
              character.  Internally, GNU troff converts these two
              character names to Unicode code points (according to the
              groff glyph list [GGL]), which determine the start and end
              values of the range.  If that fails, the class definition
              is skipped.  Furthermore, classes can be nested.

              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.

       .close stream
              Close the named stream, invalidating it as an argument to
              the write request.  See open.

       .composite c1 c2
              Map ordinary or special character c1 to c2 when c1 is a
              combining component in a composite character.  Typically,
              composite is used to map a spacing character to a
              combining one.  See groff_char(7).

       .continue
              Skip the remainder of a “while” loop's body, immediately
              starting the next iteration.  See break.

       .color [b]
              Enable or disable output of color-related device-
              independent output commands per Boolean expression b.  It
              is enabled by default, and if b is omitted.

       .cp [b]
              Enable or disable AT&T troff compatibility mode per
              Boolean expression b.  It is disabled by default, and
              enabled if b is omitted.  In compatibility mode, long
              names are not recognized, and the incompatibilities they
              cause do not arise.

       .defcolor ident scheme color-component ...
              Define a color named ident.  scheme identifies a color
              space and determines the number of required color-
              components; it must be one of “rgb” (three components),
              “cmy” (three components), “cmyk” (four components), or
              “gray” (one component).  “grey” is accepted as a synonym
              of “gray”.  Each color component can be encoded as a
              hexadecimal value starting with # or ##.  The former
              indicates that each component is in the range 0–255
              (0–FF), the latter the range 0–65535 (0–FFFF).
              Alternatively, a 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).

              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.

       .de1 ident [end-name]
              As “de”, but compatibility mode is disabled while the
              macro ident is interpreted: a “compatibility save” token
              is inserted at its beginning, and a “compatibility
              restore” token at its end.  See .am1.

       .dei name [end-name]
              Define macro indirectly, with the name of the macro to be
              defined in string name and the name of the end macro
              terminating its definition in string end-name.

       .dei1 name [end-name]
              As dei, but compatibility mode is disabled while the
              definition of the macro named in string name is
              interpreted.

       .device contents
              Write contents, read in copy mode, to troff output as a
              device control command.  A leading neutral double quote in
              anything is stripped to allow the embedding of leading
              spaces.

              A device control command issued with the device request
              will not be reflected in the output unless a partially
              collected line exists in the top-level diversion at least
              once.  When experimenting with such device controls in
              minimal documents, a br request will ensure this to be the
              case.

       .devicem name
              Write contents of macro or string name to troff output as
              a device control command.

       .do name [arg ...]
              Interpret the string, request, diversion, or macro name
              (along with any 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.

       .ds1 name [["]contents]
              As ds, but compatibility mode is disabled while name is
              interpreted: a “compatibility save” token is inserted at
              the beginning of contents, and a “compatibility restore”
              token after it.

       .ecr   Restore the escape character saved with ecs, or set escape
              character to “\” if none has been saved.

       .ecs   Save the current escape character.

       .evc env
              Copy the properties of environment env to the current
              environment, except for:

              •  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-align,
                 or to underline (with or without underlined
                 spaces)—these are set to zero;

              •  the activation status of temporary indentation;

              •  input 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).

       .fam [fml]
              Set default font family to fml.  With no argument, the
              previous font family is selected, and if none, the
              formatter's default family.  This default is “T” (Times),
              but can be overridden by the output device—see
              groff_font(5).  The default font family is associated with
              the environment.  See \F.

       .fchar c [["]contents]
              Define fallback character c as contents.  As char, but
              while that request hides a glyph with the same name in the
              selected font, fchar definitions are used only if the font
              lacks a glyph for c.  This test happens before special
              fonts are searched.

       .fcolor [color]
              Set the fill color to color, or, without an argument,
              restore the previous stroke color, or the default if there
              is none.

       .fschar f c [["]contents]
              Define fallback special character c for font f as
              contents.  As char, but a character defined by fschar is
              located after the list of fonts declared with fspecial is
              searched and before those declared with the “special”
              request.

       .fspecial f [s ...]
              When font f is selected, treat each font s as special;
              that is, search it for any glyph not found in f.  Fonts
              specified by the “special” request are searched after
              those listed in the fspecial request.  Without s
              arguments, fspecial empties the list of fonts treated as
              special when f is selected.

       .ftr f [g]
              Translate font f to g.  Whenever a font named f is
              referred to in an \f escape sequence, in the F and S
              conditional expression operators, or in the ft, ul, bd,
              cs, tkf, special, fspecial, fp, or sty requests, font g is
              used.  If g is missing or identical to f, then font f is
              not translated.

       .fzoom f [zoom]
              Set zoom factor zoom for font f.  zoom must a non-negative
              integer; it scales the magnification by thousandths with
              1000 as a basis.  If zoom is missing or equal to zero or
              1000, font f is not magnified.  f must be a resolved font
              name, not an abstract style or mounting position.

       .gcolor [color]
              Set the stroke color to color, or, without an argument,
              restore the previous stroke color, or the default if there
              is none.

       .hcode c1 code1 [c2 code2] ...
              Set the hyphenation code of character c1 to code1, that of
              c2 to code2, and so on.  A hyphenation code must be an
              ordinary character (not a special character escape
              sequence) other than a digit.

              For automatic hyphenation to work, hyphenation codes must
              be set up.  At startup, groff assigns hyphenation codes to
              the letters “a–z” (mapped to themselves), to the letters
              “A–Z” (mapped to “a–z”), and zero to all other characters.
              Normally, hyphenation patterns contain only lowercase
              letters which should be applied regardless of case.  In
              other words, they assume that the words “ABBOT” and
              “Abbot” should be hyphenated exactly as “abbot” is.  hcode
              extends this principle to letters outside the Unicode
              basic Latin alphabet; without it, words containing such
              letters won't be hyphenated properly even if the
              corresponding hyphenation patterns contain them.

       .hla [lang]
              Set the hyphenation language to lang, or clear it if there
              is no argument.  Hyphenation exceptions specified with the
              hw request and hyphenation patterns and exceptions
              specified with the hpf and hpfa requests are associated
              with the hyphenation language.  The hla request is usually
              invoked by a localization file, which is in turn loaded by
              the troffrc or troffrc-end file; see the hpf request
              below.  The hyphenation language is associated with the
              environment.

       .hlm [n]
              Set the consecutive automatically hyphenated line limit to
              n.  A negative value means “no limit”.  Omitting n implies
              a limit of -1.  This value is associated with the
              environment.  Only lines output from a given environment
              count towards the maximum associated with that
              environment.  Hyphens resulting from \% are counted;
              explicit hyphens are not.

       .hpf pattern-file
              Read hyphenation patterns from pattern-file.  This file is
              sought in the same way that macro files are with the mso
              request or the -mname command-line option to groff(1) and
              troff(1).

              The pattern-file should have the same format as (simple)
              TeX pattern files.  The following scanning rules are
              implemented.

              •  A percent sign starts a comment (up to the end of the
                 line) even if preceded by a backslash.

              •  “Digraphs” like \$ are not supported.

              •  “^^xx” (where each x is 0–9 or a–f) and ^^c
                 (character c in the code point range 0–127 decimal) are
                 recognized; other uses of ^ cause an error.

              •  No macro expansion is performed.

              •  hpf checks for the expression \patterns{...} (possibly
                 with whitespace before or after the braces).
                 Everything between the braces is taken as hyphenation
                 patterns.  Consequently, “{” and “}” are not allowed in
                 patterns.

              •  Similarly, \hyphenation{...} gives a list of
                 hyphenation exceptions.

              •  \endinput is recognized also.

              •  For backwards compatibility, if \patterns is missing,
                 the whole file is treated as a list of hyphenation
                 patterns (but the “%” character is still recognized as
                 the start of a comment).

              Use the hpfcode request (see below) to map the encoding
              used in hyphenation pattern files to groff's input
              encoding.

              The set of hyphenation patterns is associated with the
              hyphenation language set by the hla request.  The hpf
              request is usually invoked by a localization file loaded
              by the troffrc file.  By default, troffrc loads the
              localization file for English.  (As of groff 1.23.0,
              localization files for Czech (cs), German (de), English
              (en), French (fr), Japanese (ja), Swedish (sv), and
              Chinese (zh) exist.)  For Western languages, the
              localization file sets the hyphenation mode and loads
              hyphenation patterns and exceptions.

              A second call to hpf (for the same language) replaces the
              old patterns with the new ones.

              Invoking hpf causes an error if there is no hyphenation
              language.

              If no hpf request is specified (either in the document, in
              a file loaded at startup, or in a macro package), GNU
              troff won't automatically hyphenate at all.

       .hpfa pattern-file
              As hpf, except that the hyphenation patterns and
              exceptions from pattern-file are appended to the patterns
              already applied to the hyphenation language of the
              environment.

       .hpfcode a b [c d] ...
              Define mapping values for character codes in pattern
              files.  This is an older mechanism no longer used by
              groff's own macro files; for its successor, see hcode
              above.  hpf or hpfa apply the mapping after reading or
              appending to the active list of patterns.  Its arguments
              are pairs of character codes—integers from 0 to 255.  The
              request maps character code a to code b, code c to code d,
              and so on.  Character codes that would otherwise be
              invalid in groff can be used.  By default, every code maps
              to itself except those for letters “A” to “Z”, which map
              to those for “a” to “z”.

       .hydefault mode
              Set hyphenation mode default to mode.  When the hy request
              is invoked without an argument, this mode is selected.
              The hyphenation mode default is associated with the
              environment.

       .hym [length]
              Set the (right) hyphenation margin to length.  If the
              adjustment mode is not “b” or “n”, the line is not
              hyphenated if it is shorter than length.  Without an
              argument, the default hyphenation margin is reset to its
              default value, 0.  The default scaling unit is “m”.  The
              hyphenation margin is associated with the environment.  A
              negative argument resets the hyphenation margin to zero,
              emitting a warning in category “range”.

       .hys [hyphenation-space]
              Suppress hyphenation of the line in adjustment modes “b”
              or “n”, if it can be justified by adding no more than
              hyphenation-space extra space to each inter-word space.
              Without an argument, the hyphenation space adjustment
              threshold is set to its default value, 0.  The default
              scaling unit is “m”.  The hyphenation space adjustment
              threshold is associated with the current environment.  A
              negative argument resets the hyphenation space adjustment
              threshold to zero, emitting a warning in category “range”.

       .itc n name
              As “it”, but lines interrupted with the \c escape sequence
              are not applied to the line count.

       .kern n
              If n is non-zero or missing, enable pairwise kerning (the
              default), otherwise disable it.

       .length reg anything
              Compute the number of characters in anything and return
              the count in the register reg.  If reg doesn't exist, it
              is created.  anything is read in copy mode.

       .linetabs [b]
              Activate or deactivate line-tabs in the environment per
              Boolean expression b.  They are inactive by default, and
              activated if b is omitted.  When line-tabs are active, tab
              stops are computed relative to the start of the pending
              output line instead of the drawing position corresponding
              to the start of the input line.

       .lsm [name]
              Set the leading space macro (trap) to name.  If there are
              leading space characters on an input line, name is invoked
              in lieu of the usual roff behavior; the leading spaces are
              removed.  The count of leading spaces on an input line is
              stored in \n[lsn], and the amount of corresponding
              horizontal motion in \n[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.  If no argument is supplied, the
              default leading space behavior is (re-)established.

       .mso file
              As “so”, except that file is sought in the same
              directories as arguments to the groff(1) and troff(1) -m
              command-line option are (the “tmac path”).  If file does
              not exist, a warning in category “file” is emitted and the
              request has no other effect.

       .msoquiet file
              As mso, but no warning is emitted if file does not exist.

       .nop anything
              Interpret anything as if it were an input line.  nop
              resembles “.if 1”; it puts a break on the output if
              anything is empty.  Unlike “if”, it cannot govern
              conditional blocks.  Its application is to maintain
              consistent indentation within macro definitions even when
              producing text lines.

       .nroff Make the n conditional expression evaluate true and t
              false.  See troff.

       .open stream file
              Open file for writing and associate stream with it.  See
              write and close.

       .opena stream file
              As open, but if file exists, append to it instead of
              truncating it.

       .output contents
              Emit contents directly to troff's output; this usage is
              similar to that of \! in the top-level diversion.  A
              leading neutral double quote in the argument is stripped,
              allowing embedded leading spaces in contents, which is
              read in copy mode and continues to the end of the input
              line.  This request can't be used before the first page
              has started—if an error is reported, or contents fails to
              appear in troff's output, simply insert a .br line before
              the output request.

       .pev   Report the state of the current environment followed by
              that of all other environments to the standard error
              stream.

       .pcolor
              Report, to the standard error stream, the list of defined
              color names.  A device's default stroke and/or fill
              colors, “default”, are not listed since they are immutable
              and their details unknown to the formatter.

       .pcomposite
              Report, to the standard error stream, the list of defined
              composite characters.  The “from” code point is listed
              first, followed by its “to” mapping.

       .phw   Report, to the standard error stream, the list of
              hyphenation exceptions.  Each hyphenation point is marked
              with “-”.  Words that will not be hyphenated at all are
              prefixed with “-”.  Those to which the automatic
              hyphenation mode applies (meaning those defined in a
              hyphenation pattern file rather than with the hw request)
              are suffixed with a tab and asterisk (*).

       .pline Report, to the standard error stream, the list of output
              nodes corresponding to the pending output line.  The list
              is empty if there are none.

       .pnr   Write the names and values of all currently defined
              registers to the standard error stream.

       .psbb file
              Get the bounding box of a PostScript image file.  This
              file must conform to Adobe's Document Structuring
              Conventions; the request attempts to extract the bounding
              box values from a %%BoundingBox comment.  After
              invocation, the x and y coordinates (in PostScript units)
              of the lower left and upper right corners can be found in
              the registers \n[llx], \n[lly], \n[urx], and \n[ury],
              respectively.  If an error occurs, these four registers
              are set to zero.

       .pso command
              As “so”, except that input comes from the standard output
              stream of command.

       .ptr   Report the names and vertical positions of all page
              location traps to the standard error stream.  Empty slots
              in the list are shown as well, because they can affect the
              visibility of subsequently planted traps.

       .pvs ±n
              Set the post-vertical line spacing to n; default scaling
              unit is “p”.  With no argument, the post-vertical line
              space is set to its previous value.

              In GNU troff, the distance between text baselines consists
              of the extra pre-vertical line spacing set by the most
              negative \x argument on the pending output line, the
              vertical spacing (vs), the extra post-vertical line
              spacing set by the most positive \x argument on the
              pending output line, and the post-vertical line spacing
              set by this request.

       .rchar c ...
              Remove definition of each ordinary or special character c,
              undoing the effect of a char, fchar, or schar request.
              Glyphs, which are defined by font description files,
              cannot be removed.  Spaces and tabs may separate c
              arguments.

       .return [anything]
              Stop interpreting a macro, skipping to the end of its
              definition.  Do not confuse “return” with rt.  If called
              with an argument anything, the skip is performed twice—
              once within the macro being interpreted and once in an
              enclosing macro.  trace.tmac uses this feature to define a
              wrapper macro for “return”.

       .rfschar f c ...
              Remove each fallback special character c for font f.
              Spaces and tabs may separate c arguments.  See fschar.

       .rj [n]
              Right-align the next n input lines.  Without an argument,
              right-align the next input line.  rj implies “.ce 0”, and
              ce implies “.rj 0”.

       .rnn r1 r2
              Rename register r1 to r2.  If r1 doesn't exist, the
              request is ignored.

       .schar c [["]contents]
              Define global fallback character c as contents.  As char,
              but a character defined with schar is located after the
              list of fonts declared with the special request and before
              any mounted special fonts.

       .shc [c]
              Set the soft hyphen character, inserted when a word is
              hyphenated automatically or at a hyphenation character,
              to c.  If c is omitted, the soft hyphen character is set
              to the default, \[hy].  If the selected glyph does not
              exist in the font in use at a potential hyphenation point,
              then the line is not broken at that point.  Neither
              character definitions (char and similar) nor translations
              (tr and similar) are considered when assigning the soft
              hyphen character.

       .shift n
              In a macro, shift the arguments by n positions: argument i
              becomes argument i-n; arguments 1 to n are no longer
              available.  If n is missing, arguments are shifted by 1.
              No effect otherwise.

       .sizes s1 s2 ... sn [0]
              Set the available type sizes to s1, s2, ... sn scaled
              points.  The list of sizes can be terminated by an
              optional “0”.  Each si can also be a range mn.  In
              contrast to the device description file directive of the
              same name (see groff_font(5)), the argument list can't
              extend over more than one line.

       .soquiet file
              As “so”, but no warning is emitted if file does not exist.

       .special [s ...]
              Declare each font s as special, searching it for glyphs
              not found in the selected font.  Without arguments, “‐
              special" empties this list of special fonts.

       .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 3 m.

              For example, “.spreadwarn 0.2m” causes a warning if break
              warnings are not suppressed and troff must add 0.2 m or
              more for each inter-word space in a line.

       .stringdown str
       .stringup str
              Alter the string named str by replacing each of its bytes
              with its lowercase (down) or uppercase (up) version (if
              one exists).  Special characters (see groff_char(7)) 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.

       .sty pos style
              Associate abstract style with non-negative font mounting
              position pos.

       .substring string start [end]
              Replace the string named string 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
              backwards from the end of the string: the last character
              has index -1, the character before the last has index -2,
              and so on.

       .tkf f s1 n1 s2 n2
              Enable track kerning for font f.  When the current font
              is f the width of every glyph is increased by an amount
              between n1 and n2; when the current type size is less than
              or equal to s1 the width is increased by n1; when it is
              greater than or equal to s2 the width is increased by n2;
              when 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.

       .tm1 [["]contents]
              As tm, but recognizes and strips a leading neutral double
              quote, allowing embedded leading spaces in message.

       .tmc message
              As tm1 request, but does not append a newline.

       .trf file
              Transparently output the contents of file.  Each line is
              output as if preceded by \!, but is not read in copy mode.
              If file does not end with a newline, trf appends one.
              Like cf, trf breaks the line unless invoked with the no-
              break control character.  Characters in file that are
              invalid as input to GNU troff are discarded; contrast with
              cf.

       .trin abcd
              This is the same as the tr request except that the asciify
              request uses the character code (if any) before the
              character translation.

       .trnt abcd
              This is the same as the tr request except that the
              translations do not apply to text that is transparently
              throughput into a diversion with \!.

       .troff Make the t conditional expression evaluate true and n
              false.  See nroff.

       .unformat div
              Unformat the diversion div.  Unlike asciify, 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.

       .vpt [b]
              Enable or disable vertical position traps per Boolean
              expression b.  They are enabled by default, and if b is
              omitted.

              Vertical position traps are those set by the ch, wh, and
              dt requests.  Vertical position trap enablement is global.

       .warn [n]
              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 section “Warnings” of
              troff(1).  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.

       .warnscale si
              Set the scaling unit used in warnings to si.  Valid values
              for si are u, i (the default), c, p, and P.

       .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.

              troff treats the body of a while request similarly to that
              of a de request (albeit one not read in copy mode), 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.  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 (unless you redefine it).  To prevent
              infinite loops, the default number of available recursion
              levels is 1,000 or somewhat less (because things other
              than macro calls can be on the input stack).  You can
              disable this protective measure, or raise the limit, by
              setting the slimit register.  See section “Debugging”
              below.

              If a while body begins with a conditional block, its
              closing brace must end an input line.

              The break and continue requests alter a while loop's flow
              of control.

       .write stream [["]contents]
              Write contents to stream, which must previously have been
              the subject of an open request, followed by a newline.  A
              leading neutral double quote in the second argument is
              stripped, allowing embedded leading spaces in contents,
              which is read in copy mode until the end of the line.

       .writec stream [["]contents]
              As write, but does not append a newline to contents.

       .writem stream name
              Write the contents of the macro or string name to stream,
              which must previously have been the subject of an open
              request.  name is read in copy mode.

   Extended requests
       .cf file
              In a diversion, embed an object which, when interpolated,
              will cause the contents of file to be copied verbatim to
              the output.  In AT&T troff, the contents of file are
              immediately copied to the output regardless of whether a
              diversion is being written to; this behavior is so
              anomalous that it must be considered a bug.

       .de name [end-name]
       .am name [end-name]
       .ds name [["]contents]
       .as name [["]contents]
              In compatibility mode, these requests behave similarly to
              de1, am1, ds1, and as1, respectively: a “compatibility
              save” token is inserted at the beginning, and a
              “compatibility restore” token at the end, with
              compatibility mode switched on during interpolation of the
              applicable macro definition, appendment, or string
              contents.

       .hy n  New values 16 and 32 are available; the former enables
              hyphenation before the last character in a word, and the
              latter enables hyphenation after the first character in a
              word.  If invoked without an argument, the mode configured
              by the hydefault request is selected.

       .ss word-space-size [additional-sentence-space-size]
              A second argument sets the amount of additional space
              separating sentences on the same output line.  If omitted,
              this amount is set to word-space-size.  Both arguments are
              in twelfths of current font's space width (typically one-
              fourth to one-third em for Western scripts; see
              groff_font(5)).  The default for both parameters is 12.
              Negative values are erroneous.

       .ta [[n1 n2 ... nn ]T r1 r2 ... rn]
              groff supports an extended syntax to specify repeating tab
              stops after the “T” mark.  These values are always taken
              as relative distances from the previous tab stop.  This is
              the idiomatic way to specify tab stops at equal intervals
              in groff.

              The syntax summary above instructs groff to set tabs at
              positions n1, n2, ..., nn, then at nn+r1, nn+r2, ...,
              nn+rn, then at nn+rn+r1, nn+rn+r2, ..., nn+rn+rn, and so
              on.

   New registers
       GNU troff exposes more formatter state via many new read-only
       registers.  Their names often correspond to the requests that
       affect them.

       \n[.br]
              Within a macro call, interpolate 1 if the macro is called
              with the “normal” control character (“.” by default),
              and 0 otherwise.  This facility allows the reliable
              modification of requests.  Using this register outside of
              a macro definition makes no sense.

       \n[.C] Interpolate 1 if compatibility mode is in effect,
              0 otherwise.  See cp.

       \n[.cdp]
              Interpolate depth of last glyph added to the environment.
              It is positive if the glyph extends below the baseline.

       \n[.ce]
              Interpolate number of input lines remaining to be
              centered.

       \n[.cht]
              Interpolate height of last glyph added to the environment.
              It is positive if the glyph extends above the baseline.

       \n[.color]
              Interpolate 1 if colors are enabled, 0 otherwise.

       \n[.cp]
              Within a “do” request, interpolate the saved value of
              compatibility mode (see \n[.C] above).

       \n[.csk]
              Interpolate skew of last glyph added to the environment.
              The skew of a glyph is how far to the right of the center
              of a glyph the center of an accent over that glyph is to
              be placed.

       \n[.ev]
              Interpolate name of current environment.  This is a
              string-valued register.

       \n[.fam]
              Interpolate name of default font family.  This is a
              string-valued register.

       \n[.fn]
              Interpolate resolved name of the selected font.  This is a
              string-valued register.

       \n[.fp]
              Interpolate next free non-zero font mounting position.

       \n[.g] Interpolate 1.  Test with “if” or ie to check whether GNU
              troff is the formatter.

       \n[.height]
              Interpolate font height.  See \H.

       \n[.hla]
              Interpolate hyphenation language of the environment.  This
              is a string-valued register.

       \n[.hlc]
              Interpolate count of immediately preceding consecutive
              hyphenated lines in the environment.

       \n[.hlm]
              Interpolate maximum number of consecutive hyphenated lines
              allowed in the environment.

       \n[.hy]
              Interpolate automatic hyphenation mode of the environment.

       \n[.hydefault]
              Interpolate hyphenation mode default of the environment.

       \n[.hym]
              Inteprolate hyphenation margin of the environment.

       \n[.hys]
              Interpolate hyphenation space adjustment threshold of the
              environment.

       \n[.in]
              Interpolate indentation amount applicable to the pending
              output line.

       \n[.int]
              Interpolate 1 if the most recently formatted text was
              interrupted (ended with \c), 0 otherwise.

       \n[.it]
              Interpolate the count of lines remaining in any pending
              input trap.

       \n[.itc]
              Interpolate 1 if the pending input trap honors the output
              line continuation escape sequence (\c), 0 otherwise.

       \n[.itm]
              Interpolate the name of the macro associated with the
              pending input trap.  This is a string-valued register.

       \n[.kern]
              Interpolate 1 if pairwise kerning is enabled, 0 otherwise.

       \n[.lg]
              Interpolate ligature mode.

       \n[.linetabs]
              Interpolate 1 if line-tabs mode is enabled, 0 otherwise.

       \n[.ll]
              Interpolate line length applicable to the pending output
              line.

       \n[.lt]
              Interpolate title line length.

       \n[.m] Interpolate name of the selected stroke color.  This is a
              string-valued register.

       \n[.M] Interpolate name of the selected fill color.  This is a
              string-valued register.

       \n[.ne]
              Interpolate amount of space demanded by the most recent ne
              request that caused a page location trap to be sprung.
              See \n[.trunc].

       \n[.nm]
              Interpolate 1 if output line numbering is enabled (even if
              temporarily suppressed), 0 otherwise.

       \n[.nn]
              Interpolate count of output lines remaining to have
              numbering suppressed.

       \n[.ns]
              Interpolate 1 if no-space mode is enabled, 0 otherwise.

       \n[.O] Interpolate output suppression level.  See \O.

       \n[.P] Interpolate 1 if the current page is selected for output.
              See -o command-line option to troff(1).

       \n[.pe]
              Interpolate 1 during page ejection, 0 otherwise.

       \n[.pn]
              Interpolate next page number (either that set by pn, or
              that of the current page plus 1).

       \n[.ps]
              Interpolate type size in scaled points.

       \n[.psr]
              Interpolate most recently requested type size in scaled
              points.

       \n[.pvs]
              Interpolate post-vertical line spacing amount.

       \n[.rj]
              Interpolate number of input lines remaining to be right-
              aligned.

       \n[.slant]
              Interpolate font slant.  See \S.

       \n[.sr]
              Interpolate most recently requested type size in points as
              a decimal fraction.  This is a string-valued register.

       \n[.ss]
       \n[.sss]
              Interpolate values of minimal inter-word space and
              additional inter-sentence space, respectively, in twelfths
              of the space width of the selected font.

       \n[.sty]
              Interpolate selected abstract font style, if any.  This is
              a string-valued register.

       \n[.tabs]
              Interpolate representation of the tab stop settings in a
              form suitable for passage to the ta request.

       \n[.trap]
              Interpolate the name of the next vertical position trap
              that will be sprung.  This is a string-valued register.

       \n[.trunc]
              Interpolate amount of vertical space truncated by the most
              recently sprung page location 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, \n[.trunc] represents the
              difference of what the vertical position would have been
              but for the trap, and what the vertical position actually
              is.  See \n[.ne].

       \n[.U] Interpolate 1 if in unsafe mode, 0 otherwise.  See -U
              command-line option to troff(1).

       \n[.vpt]
              Interpolate 1 if vertical position traps are enabled,
              0 otherwise.

       \n[.warn]
              Interpolate warning mode.  See section “Warnings” of
              troff(1).

       \n[.x] Interpolate major version number of the running troff
              formatter.  For example, if the version number is 1.23.0,
              then \n[.x] contains 1.

       \n[.y] Interpolate minor version number of the running troff
              formatter.  For example, if the version number is 1.23.0,
              then \n[.y] contains 23.

       \n[.Y] Interpolate revision number of the running troff
              formatter.  For example, if the version number is 1.23.0,
              then \n[.Y] contains 0.

       \n[.zoom]
              Interpolate magnification of font, in thousandths, or 0 if
              magnification unused.  See fzoom.

       The following (writable) registers are set by the psbb request.

       \n[llx]
       \n[lly]
       \n[urx]
       \n[ury]
              Interpolate the (upper, lower, left, right) bounding box
              values (in PostScript units) of the most recently
              processed PostScript image.

       The following (writable) registers are set by the \w escape
       sequence.

       \n[rst]
       \n[rsb]
              Like \n[st] and \n[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 the argument formatted by the \w escape sequence, doing
              what AT&T troff documented \n[st] and \n[sb] as doing.

       \n[ssc]
              The amount of (possibly negative) horizontal space to add
              to the last glyph before a subscript.

       \n[skw]
              How far to right of the center of the last glyph in the \w
              argument, to place the center of an accent from a roman
              font over that glyph.

       Other writable registers are as follows.  Those relating to date
       and time are initialized using localtime(3) at formatter startup.

       \n[c.] Interpolate input line number.  \n[.c] is a read-only
              alias of this register.

       \n[hours]
              Interpolate number of hours elapsed since midnight.

       \n[hp] Interpolate horizontal position relative to that at the
              start of the input line.

       \n[lsn]
       \n[lss]
              Interpolate count of leading spaces on input line and
              amount of corresponding horizontal motion, respectively.

       \n[minutes]
              Interpolate number of minutes elapsed in the hour.

       \n[seconds]
              Interpolate number of seconds elapsed in the minute.

       \n[systat]
              Interpolate return value of system(3) function executed by
              most recent sy request.

       \n[slimit]
              Interpolates maximum quantity of objects on troff's
              internal input stack (default: 1000).  If non-positive,
              there is no limit: recursion can continue until program
              memory is exhausted.

       \n[year]
              Interpolate Gregorian year.  AT&T troff's \[yr]
              interpolates the Gregorian year minus 1900.

   Miscellaneous
       GNU troff predefines one string, .T, containing the argument
       given to the -T command-line option, namely the output device
       (for example, pdf or utf8).  The (read-only) register .T
       interpolates 1 if GNU troff is run with the -T command-line
       option, and 0 otherwise.

       A font not listed in the output device's DESC file's fonts
       directive is automatically mounted at the next available font
       position when it is selected.  If you mount a font explicitly
       with the fp request, you should do so on the first unused
       position, which can be found in the .fp register.

       Unparameterized string interpolation does not conceal the
       arguments to a macro being interpreted.  Thus, in a macro
       definition, the call of another macro with the existing argument
       list,
              .xx \\$@
       is more efficiently done with
              \\*[xx]\\
       (that is, with string interpolation).  The trailing backslashes
       prevent the final newline in the macro definition from being
       interpolated, potentially putting an unwanted blank line on the
       output.  See section “Punning Names” in groff(7).

       If a font description file contains pairwise kerning information,
       glyphs from that font are kerned.  Kerning between two glyphs can
       be inhibited by placing a dummy character \& between them.

       GNU troff keeps track of the nesting depth of escape sequence
       interpolations and other uses of delimiters, as in the tl request
       and the output comparison operator (that is, input like 'foo'bar'
       as a conditional expression), so the only characters you need to
       avoid using as delimiters are those that appear in the arguments
       you input, not any that result from interpolation.  Typically, '
       works fine.  Use visible characters as delimiters in GNU troff,
       not “ASCII” controls like BEL (Control+G).  The implementation of
       \$@ ensures that the double quotes surrounding an argument appear
       at an interpolation depth different from that of the arguments
       themselves.  Similarly, in bracket-form escape sequences like
       \f[ZCMI], a right bracket ] does not end the sequence unless it
       occurs at the same interpolation depth as the opening [.  In
       compatibility mode, no attention is paid to the interpolation
       depth.

       In GNU troff, the tr request can map characters to the
       unbreakable space escape sequence \~ as a special case (tr
       normally operates only on characters).  This feature replaces the
       odd-parity tr mapping trick used in AT&T troff documents, where a
       character, often ~, was “sacrificed” by mapping it to “nothing”,
       drafting it into use as an unadjustable, unbreakable space.
       (This feature was gratuitous even in early AT&T troff, which
       supported the \space escape sequence by 1976.)  Often, it makes
       more sense to use GNU troff's \~ escape sequence instead, which
       has been adopted by every other active troff implementation
       except that of Illumos, as well as by the non-troff mandoc.
       Translation of a character to \~ is unnecessary.

       GNU troff permits tabs and spaces after the first dot on a
       control line that ends a macro definition.

Formatter output         top

       The page description language output by GNU troff is modeled
       after that used by AT&T troff once the latter adopted a device-
       independent approach in the early 1980s.  Only the differences
       are documented here.  For a fuller discussion, see groff_out(5).

       Glyph and font names can be of arbitrary length; postprocessors
       should not assume that they are at most two characters.  A glyph
       to be formatted is always drawn from the current font; in
       contrast to AT&T device-independent troff, drivers need not
       search special fonts to find a glyph.

   Units
       The argument to the s command is in scaled points (units of
       points/n, where n is the argument to the sizescale command in the
       DESC file).  The argument to the “x H” command is also in scaled
       points.

   Simple commands
       If the tcommand directive is present in the output device's DESC
       file, GNU troff employs the following two commands.

       t xyz...
              Typeset word xyz; that is, set a sequence of ordinary
              glyphs named x, y, z, ..., terminated by a space or
              newline; 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.

       u n xyz...
              Typeset word xyz with track kerning.  As t, but after
              placing each glyph, the drawing position is further
              advanced horizontally by n basic units.

       New commands implement color support.

       mc cyan magenta yellow
       md
       mg gray
       mk cyan magenta yellow black
       mr red green blue
              Set the components of the stroke color with respect to
              various color spaces.  md resets the stroke color to the
              default value.  The arguments are integers in the range 0
              to 65535.

       A new device control subcommand is available.

       x u n  If n is 1, start underlining of spaces.  If n is 0, stop
              underlining of spaces.  This facility is needed for the cu
              request in nroff mode and is ignored otherwise.

   Extended drawing commands
       GNU pic does not produce troff escape sequences employing these
       extensions if its -n option is given.

       Df n   Set the shade of gray used to fill geometric objects to n,
              which must be an integer.  0 corresponds to white and 1000
              to black.  A grayscale ramp spans the two.  A value
              outside this range uses the stroke color as the fill
              color.  The fill color is opaque.  Normally the default is
              black, but some drivers may provide a way of changing
              this.  Df is obsolete since 2002, superseded by DFg below.

              The corresponding \D'f' escape sequence should not be
              used: its argument is rounded to an integer multiple of
              the horizontal motion quantum, which can limit the
              precision of n.

       DC d   Draw a filled circle of diameter d with its leftmost point
              at the drawing position.

       DE h v Draw a filled ellipse, of horizontal axis h and vertical
              axis v, with its leftmost point at the drawing position.

       Dp dx1dy1...dxndyn
              Draw a polygon with, for i=1,...,n+1, its ith vertex at
              the drawing position +ij−=Σ11(dxj,dyj).  groff output drivers
              automatically close polygons, drawing a line from
              (dxn,dyn) back to (dx1,dy1).  The drawing position is left
              at the last specified vertex, but this may change in a
              future version of GNU troff.  Heirloom Doctools troff,
              like DWB troff, by default does not close the polygon.  In
              its groff compatibility mode, Heirloom closes the polygon
              but leaves the drawing position unchanged—that is, at the
              polygon's initial drawing position.

              At the moment, GNU pic uses this command only to generate
              triangles and rectangles.

       DP dx1dy1...dxndyn
              As Dp, but draw a filled rather than a stroked polygon.

       Dt n   Set the line thickness to n basic units.  AT&T troff
              output drivers use a thickness proportional to the type
              size; this is the GNU troff default.  A negative n
              requests this explicitly.  An n of zero selects the
              smallest available line thickness.

       A difficulty arises in how the drawing position should be changed
       after the execution of these commands.  This has little
       importance to most users, since the output of GNU grn and pic
       does not depend on it.  Given a drawing command of the form Dz
       x1y1...xnyn, where z is not c or e, AT&T troff treats each xi as
       a horizontal motion, each yi as a vertical one, and therefore
       assumes that the width of the drawn object is in=Σ1xi, and its
       height is in=Σ1yi.  (Verify its assumption about height by
       examining the st and sb registers after using such a drawing
       command in a \w escape sequence).  For the sake of compatibility,
       GNU troff also follows this rule, even though it frustrates
       extensions to the D command that set drawing parameters rather
       than rendering objects, producing ugly results in the case of Dt
       and Df, or otherwise don't parameterize objects as a series of
       vertices, as with GNU troff's filled ellipse, DE.  Thus after
       executing a D command of the form Dz x1y1...xnyn, the drawing
       position should be increased by (in=Σ1xi,in=Σ1yi).  In a future
       release, GNU troff and its output drivers may abandon the
       application of this assumption to drawing commands not explicitly
       specified in the AT&T “Troff User's Manual”.

       Fill color selection is implemented with another set of
       extensions.

       DFc cyan magenta yellow
       DFd
       DFg gray
       DFk cyan magenta yellow black
       DFr red green blue
              Set the components of the fill color as described under
              the \M escape sequence above.  DFd restores the device's
              default fill color.  The drawing position is not updated,
              in contrast to Df.

   Device control syntax extension
       GNU troff introduces a line continuation convention, permitting
       the argument to the x X command to contain newlines.  A newline
       in the input is transformed to the sequence “newline+”.  When
       interpreting an x X command, a postprocessor should therefore be
       prepared for a plus sign after a newline; if it occurs, preserve
       the newline, discard the plus sign, and continue to collect the
       input into the argument of the x X command.  A newline not
       followed by a plus sign terminates the x X command.  An
       application of this feature is the embedding of PostScript or PDF
       language command streams into troff output.

       GNU troff guarantees that the first three output commands it
       emits are as follows.

              x T device
              x res n h v
              x init

Debugging         top

       In addition to AT&T troff's debugging features, GNU troff emits
       more error diagnostics when syntactical or semantic nonsense is
       encountered and supports several warning categories; the output
       of these can be selected with warn.  Also see the -E, -w, and -W
       options of troff(1).  Backtraces can be automatically produced
       when errors or warnings occur (the -b option of troff(1)) or
       generated on demand (backtrace).

       groff also adds more flexible diagnostic output requests (tmc and
       tm1).  More aspects of formatter state can be examined with
       requests that write lists of defined colors (pcolor), composite
       characters (pcomposite), environments (pev), hyphenation
       exceptions (phw), registers (pnr), page location traps (ptr), and
       a list of pending output nodes corresponding to the previous
       input line (.pline) to the standard error stream.

Other differences         top

       GNU troff's features sometimes cause incompatibilities with
       documents written assuming old implementations of troff.  Some
       GNU extensions to troff are supported by other implementations.

       AT&T troff discards trailing spaces from input lines, like GNU
       troff, but if it does so, AT&T troff also cancels end-of-sentence
       detection.  Use of the dummy character escape sequence \& is more
       portable.

       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 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 U.S. English, while GNU troff uses language-specific
       hyphenation pattern files derived from TeX.  In some versions of
       troff there was limited space to store hyphenation exceptions
       (arguments to the hw request); GNU troff has no such restriction.

       GNU troff handles the dummy character \& differently from AT&T
       troff when it is followed by the hyphenation control escape
       sequence \% at the beginning of a word.  GNU troff does not
       regard the dummy character as “starting” the word; AT&T troff
       does.  Further, Heirloom Doctools troff does not honor an
       explicit hyphenation point marked with \% after a word-initial
       one.

Compatibility mode         top

       Some implementation differences between GNU and AT&T troffs are
       thought too important to neglect; groff therefore makes available
       a compatibility mode in an effort to keep documents prepared for
       AT&T troff rendering well.

       Identifier names of arbitrary length 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, called “[”.  In GNU troff, however, the
       “[” is normally interpreted as beginning the enclosure of a long
       identifier.  In compatibility mode, GNU troff interprets names in
       the traditional way, which means that they are limited to one or
       two characters.  See the -C option in troff(1) and, above, the .C
       and .cp registers, and cp and “do” requests, for more on
       compatibility mode.

       The register \n[.cp] 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 GNU troff's more capacious name space.
       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.

       The existence of the .T string is a common feature of post-
       CSTR #54 troffs—DWB 3.3, Solaris, Heirloom Doctools, and Plan 9
       troff all support it—but valid values are specific to each
       implementation.  The behavior of the .T register in GNU troff
       differs from AT&T troff, which interpolated 1 only if nroff was
       the formatter and was called with -T.

       The lf request sets the number of the current input line in AT&T
       troff, and the next in GNU troff.

       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.

       GNU troff normally tracks the interpolation depth of escape
       sequence parameters and other delimited structures, but not in
       compatibility mode.  See section “Miscellaneous” above.

       Further, the escape sequences \f, \H, \m, \M, \R, \s, and \S are
       transparent at the beginning of an input line only in
       compatibility mode.

       GNU troff request names unrecognized by other troff
       implementations will likely be ignored; escape sequences that are
       GNU troff extensions are liable to format their function selector
       character.  For example, the adjustable, non-breaking space
       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/Illumos
       troffs, which will render it as ~.

       GNU troff does not allow the use of the escape sequences \|, \^,
       \&, \{, \}, \space, \', \`, \-, \_, \!, \%, or \c in identifiers;
       AT&T troff does.  The \A escape sequence (see subsection “Escape
       sequences” above) may be helpful in avoiding their use.

       Normally, the syntax form \sn 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 should be
       migrated to another \s form.  [Background: 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”.]

       Fractional type size support causes an 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, which may be a much smaller
       measurement.  See subsection “Fractional type sizes and new
       scaling units” above.

       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.

       In AT&T troff the pm request reports macro, string, and diversion
       sizes in units of 128-byte blocks, and an argument reduces the
       report to a sum of the above in the same units.  GNU troff
       ignores any arguments and reports the sizes in bytes.

       AT&T troff ignores the ss request if the output is a terminal
       device; GNU troff rounds down the values of minimum inter-word
       and additional inter-sentence space each 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.

       One way to format a backslash in most documents is with the \e
       escape sequence; this formats the glyph of the current escape
       character, regardless of whether it is used in a diversion; it
       also works in both GNU troff and AT&T troff.  (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.)

       The other correct way, appropriate in contexts independent of the
       backslash's common use as a roff 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.  [This escape
       sequence is not portable to AT&T troff, but is to its lineal
       descendant, Heirloom Doctools troff, as of its 060716 release
       (July 2006).]

       To store an escape sequence in a diversion that is interpreted
       when the diversion is interpolated, either use the traditional \!
       transparent output facility, or, if this is unsuitable, the new
       \? escape sequence.  See subsection “Escape sequences” above and
       sections “Diversions” and “Gtroff Internals” in Groff: The GNU
       Implementation of troff, the groff Texinfo manual.

       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 a partially collected but otherwise empty line (as if
       “\c” were in the top-level diversion) at the end of input; GNU
       troff will not.

   Formatter output incompatibilities
       Its extensions notwithstanding, GNU troff's output format has
       some incompatibilities with that of AT&T troff, but better
       compatibility is sought; problem reports and patches are welcome.
       The following incompatibilities are known.

       •  The drawing position after rendering polygons is inconsistent
          with AT&T troff practice.  Other implementations have diverged
          on this point as well.

       •  The output cannot be easily rescaled to other devices as AT&T
          troff's could.

Authors         top

       This document was written by James Clark ⟨jjc@jclark.com⟩, Werner
       Lemberg ⟨wl@gnu.org⟩, Bernd Warken ⟨groff-bernd.warken-72@web
       .de⟩, and G. Branden Robinson ⟨g.branden.robinson@gmail.com⟩.

See also         top

       Groff: The GNU Implementation of troff, by Trent A. Fisher and
       Werner Lemberg, is the primary groff manual.  You can browse it
       interactively with “info groff”.

       “Troff User's Manual” by Joseph F. Ossanna, 1976 (revised by
       Brian W. Kernighan, 1992), AT&T Bell Laboratories Computing
       Science Technical Report No. 54, widely called simply “CSTR #54”,
       documents the language, device and font description file formats,
       and output format referred to collectively in groff documentation
       as AT&T troff.

       “A Typesetter-independent TROFF” by Brian W. Kernighan, 1982,
       AT&T Bell Laboratories Computing Science Technical Report No. 97,
       provides additional insights into the device and font description
       file formats and output format.

       groff(1), groff(7), roff(7)

COLOPHON         top

       This page is part of the groff (GNU troff) project.  Information
       about the project can be found at 
       ⟨http://www.gnu.org/software/groff/⟩.  If you have a bug report
       for this manual page, see ⟨http://www.gnu.org/software/groff/⟩.
       This page was obtained from the project's upstream Git repository
       ⟨https://git.savannah.gnu.org/git/groff.git⟩ on 2024-06-14.  (At
       that time, the date of the most recent commit that was found in
       the repository was 2024-06-10.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       man-pages@man7.org

groff 1.23.0.1273-9d53-dirty   6 June 2024                 groff_diff(7)