Provided by: groff_1.23.0-5_amd64 bug

Name

       groff_diff - differences between GNU roff and AT&T troff

Description

       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

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

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

       A scaled point is equal to 1/sizescale points, where sizescale is specified in the  device
       description  file,  DESC,  and  defaults  to  1;  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.  The .s and .ps registers
       represent the type size as selected by the output driver  as  it  understands  a  device's
       capability.   The  last  requested type size is interpolated in scaled points by the read-
       only register .psr and in points as a decimal  fraction  by  the  read-only  string-valued
       register  .sr.   Both are associated with the environment.  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.

       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 e1 and e2.

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

       (c;e)  Evaluate 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 accessed with the ft request (that is, abstract styles and
              font  translation  are 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 a style sty is registered.  Font translation applies.

       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 and extends the syntax of a few  AT&T  troff
       escape  sequences (namely, \D, \f, \k, \n, \s, \$, and \*).  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,  or newlines.  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[font]
              Select  font,  which  may  be a mounting position, abstract style, or font name, to
              choose the typeface.  \f[] and \fP are synonyms; we recommend the former.

       \Ff
       \F(fm
       \F[family]
              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'anything'
              Within \X arguments, the escape sequences \&, \), \%, and \:  are  ignored;  \space
              and  \~  are converted to single space characters; and \\ is reduced to \.  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 anything, 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.

              If the use_charnames_in_special directive appears in the output device's DESC file,
              the use of special character escape sequences is not  an  error;  they  are  simply
              output  verbatim  (with  the  exception  of the seven mapped to Unicode basic Latin
              characters, discussed above).  use_charnames_in_special is currently employed  only
              by grohtml(1).

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

       \#     Everything up to and including the next newline is ignored.  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  “\%”).
              This  escape  sequence  is  an input word boundary, so the remainder of the word is
              subject to hyphenation as normal.

       \?anything\?
              When used in a diversion, this transparently  embeds  anything  in  the  diversion.
              anything  is  read  in  copy  mode.   When  the  diversion  is  reread, anything is
              interpreted.  anything may not contain newlines;  use  \!  if  you  want  to  embed
              newlines  in  a  diversion.  The escape sequence \? is also recognized in copy mode
              and becomes an internal code; it is this code that terminates anything.  Thus

                     .nr x 1
                     .nf
                     .di d
                     \?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
                     .di
                     .nr x 2
                     .di e
                     .d
                     .di
                     .nr x 3
                     .di f
                     .e
                     .di
                     .nr x 4
                     .f

              prints 4.

       \[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  reread.   Doing  so  can  be  useful in
              conjunction with the writem request.  asciify can be also used for gross hacks; for
              example, the following sets register n to 1.

                     .tr @.
                     .di x
                     @nr n 1
                     .br
                     .di
                     .tr @@
                     .asciify x
                     .x

              asciify  cannot  return  all items in a diversion to their source equivalent: nodes
              such as those produced by \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  macro  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.

                     For  example,  if  you  need  an  automatic break point after the en-dash in
                     numeric ranges like “3000–5000”, insert
                            .cflags 68 \[en]
                     into your document.  However, this can lead to bad layout  if  done  without
                     thinking;  in  most  situations,  a better solution than changing the cflags
                     value is inserting “\:” right after the hyphen at  the  places  that  really
                     need a break point.

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

              128    Prohibit a  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 the ordinary or special character c as contents, which can be  empty.   More
              precisely,  char  defines  a  groff  object  (or redefines an existing one) that is
              accessed with the name c on input, and produces contents on output.  Every  time  c
              is to be formatted, contents is processed in a temporary environment and the result
              is wrapped up into a single object.  Compatibility  mode  is  turned  off  and  the
              escape  character  is  set  to  \  while  contents  is processed.  Any emboldening,
              constant spacing, or track kerning is applied to this object as  a  whole,  not  to
              each character in contents.

              An  object  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 both apply to c.  A character definition can be
              removed with the rchar request.

       .chop object
              Remove the last character from the macro, string, or  diversion  object.   This  is
              useful  for  removing  the  newline  from  the  end  of  a  diversion that is to be
              interpolated as a string.  This request can be used repeatedly on the same  object;
              see section “gtroff Internals” in Groff: The GNU Implementation of troff, the groff
              Texinfo manual, for discussion of nodes inserted by groff.

       .class name c1 c2 ...
              Define a character class (or simply “class”)  name  comprising  the  characters  or
              range expressions c1, c2, and so on.

              A  class thus defined can then be referred to in lieu of listing all the characters
              within it.  Currently, only the cflags request can handle references  to  character
              classes.

              In the request's simplest form, each cn is a character (or special character).
                     .class [quotes] ' \[aq] \[dq] \[oq] \[cq] \[lq] \[rq]

              Since  class  and  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 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.
                     .class [prepunct] , : ; > }
                     .class [prepunctx] \C'[prepunct]' \[u2013]-\[u2016]
              The class “[prepunctx]” thus contains the contents of the  class  “[prepunct]”  and
              characters in the range U+2013–U+2016.

              If  you want to include “-” in a class, it must be the first character value in the
              argument list, otherwise it gets misinterpreted as part of the range syntax.

              It is not possible to use class names as end points of range definitions.

              A typical use of the class request is  to  control  line-breaking  and  hyphenation
              rules as defined by the cflags request.  For example, to inhibit line breaks before
              the characters belonging  to  the  “[prepunctx]”  class  defined  in  the  previous
              example, you can write the following.
                     .cflags 2 \C'[prepunctx]'

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

       .composite c1 c2
              Map character name c1 to character name c2 when c1 is a combining  component  in  a
              composite glyph.  Typically, this remaps a spacing glyph to a combining one.

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

       .color n
              If n is non-zero or missing, enable colors (the default), otherwise disable them.

       .cp n  If n is non-zero or missing, enable compatibility mode, otherwise disable  it.   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”.  The color components 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, each color component can be specified as a decimal fraction  in  the
              range  0–1,  interpreted  using a default scaling unit of “f”, which multiplies its
              value by 65,536 (but clamps it at 65,535).

              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 name [end-name]
              Define  a  macro  to be interpreted with compatibility mode disabled.  When name is
              called, compatibility mode enablement status is saved; it is restored when the call
              completes.

       .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 anything
              Write anything, read in copy mode, to troff output as a device control command.  An
              initial neutral double quote is stripped to allow the embedding of leading spaces.

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

              For example,
                     .de mac1
                     FOO
                     ..
                     .de1 mac2
                     groff
                     .mac1
                     ..
                     .de mac3
                     compatibility
                     .mac1
                     ..
                     .de ma
                     \\$1
                     ..
                     .cp 1
                     .do mac1
                     .do mac2 \" mac2, defined with .de1, calls "mac1"
                     .do mac3 \" mac3 calls "ma" with argument "c1"
                     .do mac3 \[ti] \" groff syntax accepted in .do arguments
              results in
                     FOO groff FOO compatibility c1 ~
              as output.

       .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  the
              following data.

              • a partially collected line, if present;

              • the  interruption  status of the previous input line (due to use of the \c escape
                sequence);

              • the count of remaining lines to center, to right-justify, or to  underline  (with
                or without underlined spaces)—these are set to zero;

              • the activation status of temporary indentation;

              • input 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 [family]
              Set default font family to family.  If no argument  is  given,  the  previous  font
              family  is  selected,  or  the  formatter's  default  family if there is none.  The
              formatter's default font family is “T” (Times), but it 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.  The syntax of this request is the same as
              the  char  request;  the  difference  is that a character defined with char hides a
              glyph with the same name in the selected  font,  whereas  characters  defined  with
              fchar  are  checked  only if c isn't found in the selected font.  This test happens
              before special fonts are searched.

       .fcolor color
              Set the fill color to color.  Without an  argument,  the  previous  fill  color  is
              selected.

       .fschar f c contents
              Define fallback special character c for font f as contents.  A character defined by
              fschar is located after the list of fonts declared with fspecial  is  searched  but
              before those declared with the “special” request.

       .fspecial f s1 s2 ...
              When  font  f  is selected, fonts s1, s2, ... are treated as special; that is, they
              are searched for glyphs not found in f.   Any  fonts  specified  in  the  “special”
              request are searched after s1, s2, and so on.  Without s arguments, fspecial clears
              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 multiple of
              1/1000th.  If it is missing or is equal to zero, it means the same as 1000,  namely
              no magnification.  f must be a resolved font name, not an abstract style.

       .gcolor color
              Set  the  stroke color to color.  Without an argument, the previous stroke color is
              selected.

       .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.  The request is ignored if given no arguments.

              For 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.  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  maximum  number  of consecutive hyphenated lines to n.  If n is negative,
              there is no maximum.  If omitted, n is -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”.

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

                     .ds xxx abcd\h'3i'efgh
                     .length yyy \*[xxx]
                     \n[yyy]
                     14

       .linetabs n
              If n is non-zero or missing, enable  line-tabs  mode,  otherwise  disable  it  (the
              default).   In  this  mode,  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.  Line-tabs mode is a property of the environment.

              For example, the following

                     .ds x a\t\c
                     .ds y b\t\c
                     .ds z c
                     .ta 1i 3i
                     \*x
                     \*y
                     \*z
              yields
                     a         b         c
              whereas in line-tabs mode, the same input gives
                     a         b                   c
              instead.

       .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  the  file
              name  to  be  interpolated  has the form name.tmac and it isn't found, mso tries to
              include tmac.name instead and vice versa.  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, which are read in copy  mode,  to  the  formatter  output;  this  is
              similar  to \! used in the top-level diversion.  An initial neutral double quote in
              contents is stripped to allow the embedding of leading spaces.

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

       .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
              Within a macro, return immediately.  If called  with  an  argument,  return  twice,
              namely  from  the  current  macro  and  from the macro one level higher.  No effect
              otherwise.

       .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.  See char; the distinction is  that
              a character defined with schar is located after the list of fonts declared with the
              special request but 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 f ...
              Declare each font f as special, searching it for glyphs not found in  the  selected
              font.  Without arguments, this list of special fonts is made empty.

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

                     .ds resume R\['e]sum\['e]\"
                     \*[resume]
                     .stringdown resume
                     \*[resume]
                     .stringup resume
                     \*[resume]
                     Résumé résumé RÉSUMÉ

       .sty n s
              Associate abstract style s with font mounting position n.

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

                     .ds xxx abcdefgh
                     .substring xxx 1 -4
                     \*[xxx]
                     bcde
                     .substring xxx 2
                     \*[xxx]
                     de

       .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 message
              As tm request, but strips a leading neutral double quote from message to allow  the
              embedding of leading spaces.

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

       .trf file
              Transparently output the contents of file file.  Each line is output as if preceded
              by \!; however, the lines are not subject to copy-mode interpretation.  If the file
              does  not  end  with  a  newline,  then a newline is added.  Unlike cf, file cannot
              contain characters that are invalid as input to GNU troff.

              For example, you can define a macro x containing the contents of file f, using

                     .di x
                     .trf f
                     .di

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

                     .trin ax
                     .di xxx
                     a
                     .br
                     .di
                     .xxx
                     .trin aa
                     .asciify xxx
                     .xxx

              The result is “x a”.  Using tr, the result would be “x x”.

       .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 \!.  For example,

                     .tr ab
                     .di x
                     \!.tm a
                     .di
                     .x

              prints b; if trnt is used instead of tr it prints a.

       .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 n If n is  non-zero  or  missing,  enable  vertical  position  traps  (the  default),
              otherwise  disable  them.  Vertical position traps are those set by the ch, wh, and
              dt requests.

       .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 anything
              Write  anything  to  stream, which must previously have been the subject of an open
              request, followed by a newline.  anything is read in copy mode.  An initial neutral
              double quote in anything is stripped to allow the embedding of leading spaces.

       .writec stream anything
              As write, but without a trailing newline.

       .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 reread, 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 execution.

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

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

                          .als bp*orig bp
                          .de bp
                          .tm before bp
                          .ie \\n[.br] .bp*orig
                          .el 'bp*orig
                          .tm after bp
                          ..

       \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 should 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 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 hyphenation mode 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 previous output line was  interrupted  (ended  with  \c),
                   0 otherwise.

       \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[.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[.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  horizontal  space (possibly negative) that should be added to the
               last glyph before a subscript.

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

       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 [, so input like
              \f[\*[my-family]\*[my-style]]
       works as desired.  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.
              .if t \{\
              .  de bar
              .    nop Hello, I'm 'bar'.
              .  .
              .\}

Formatter output

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

Debugging

       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 registers (pnr),
       environments (pev), and page location traps (ptr) to the standard error stream.

Implementation differences

       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.

       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.

       Long names may be GNU troff's most obvious innovation.  AT&T troff interprets “.dsabcd” as
       defining  a string “ab” with contents “cd”.  Normally, GNU troff interprets this as a call
       of a macro named “dsabcd”.  AT&T troff also interprets \*[ and \n[ as an interpolation  of
       a  string  or  register,  respectively,  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.  What you need is:
              .do nr _my_saved_C \n[.cp]
              .cp 0
       at the beginning of your file, followed by
              .cp \n[_my_saved_C]
              .do rr _my_saved_C
       at the end.  As in the C language, we all have to share one big name space,  so  choose  a
       register name that is unlikely to collide with other uses.

       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.

       In compatibility mode, the escape sequences \f, \H, \m, \M, \R, \s, and \S are transparent
       at the beginning of an input line for the purpose  of  recognizing  a  control  character,
       because  they  modify formatter state (\R) or properties of the environment (the rest) and
       therefore do not create output nodes.  For example, this code produces bold output in both
       cases, but the text differs,
              .de xx '
              Hello!
              ..
              \fB.xx\fP
       formatting “.xx” normally and “Hello!” 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 sizes cause one noteworthy incompatibility.  In AT&T troff the ps request
       ignores scaling units and thus “.ps 10u” sets the type size to 10 points, whereas  in  GNU
       troff  it sets the type size to 10 scaled points, 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.

       Unlike  AT&T  troff,  GNU troff does not ignore the ss request if the output is a terminal
       device; instead, the values of minimum inter-word and additional inter-sentence space  are
       each rounded down to the nearest multiple of 12.

       In  GNU  troff  there  is  a  fundamental  difference between (unformatted) characters and
       (formatted) glyphs.  Everything that affects how a glyph is  output  is  stored  with  the
       glyph  node;  once  a  glyph node has been constructed, it is unaffected by any subsequent
       requests that are executed, including bd, cs, tkf, tr, or fp requests.   Normally,  glyphs
       are  constructed  from characters immediately before the glyph is added to an output line.
       Macros, diversions, and strings are all, in fact, the same type of object; they contain  a
       sequence  of  intermixed character and glyph nodes.  Special characters transform from one
       to the other: before being added to the output, they behave as characters; afterward, they
       are  glyphs.  A glyph node does not behave like a character node when it is processed by a
       macro: it does not inherit any of the special properties that the character from which  it
       was constructed might have had.  For example, the input
              .di x
              \\\\
              .br
              .di
              .x
       produces  “\\”  in  GNU  troff.  Each pair of backslashes becomes one backslash glyph; the
       resulting backslashes are thus not interpreted as escape characters when they  are  reread
       as  the  diversion  is  output.  AT&T troff would interpret them as escape characters when
       rereading them and end up printing one “\”.

       One 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
       reread, 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  the partially collected line at the end of input; GNU
       troff will not.

   Formatter output incompatibilities
       Its  extensions  notwithstanding,  the  groff  intermediate   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

       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

       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)