[4maddftinfo[24m(1)                 General Commands Manual                [4maddftinfo[24m(1)

[1mName[0m
     addftinfo - add font metrics to [4mtroff[24m fonts for use with [4mgroff[0m

[1mSynopsis[0m
     [1maddftinfo [22m[[1m-asc-height [4m[22mn[24m] [[1m-body-depth [4m[22mn[24m] [[1m-body-height [4m[22mn[24m] [[1m-cap-height [4m[22mn[24m]
               [[1m-comma-depth [4m[22mn[24m] [[1m-desc-depth [4m[22mn[24m] [[1m-fig-height [4m[22mn[24m] [[1m-x-height [4m[22mn[24m]
               [4mresolution[24m [4munit‐width[24m [4mfont[0m

     [1maddftinfo --help[0m

     [1maddftinfo -v[0m
     [1maddftinfo --version[0m

[1mDescription[0m
     [4maddftinfo[24m reads an AT&T [4mtroff[24m font description file [4mfont[24m, adds further font
     metric information required by GNU ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\, and writes the combined result
     to  the  standard output stream.  The information added is derived from the
     font’s existing parameters and assumptions about  traditional  [4mtroff[24m  names
     for characters.  Among the font metrics added are the heights and depths of
     characters  (how far each extends vertically above and below the baseline).
     The [4mresolution[24m and [4munit‐width[24m arguments should be the same  as  the  corre‐
     sponding  parameters  in  the  [4mDESC[24m file.  [4mfont[24m is the name of the file de‐
     scribing the font; if [4mfont[24m ends with “[1mI[22m”, the font is assumed to be oblique
     (or italic).

[1mOptions[0m
     [1m--help [22mdisplays a usage message, while [1m-v [22mand [1m--version [22mshow version infor‐
     mation; all exit afterward.

     All other options change parameters that are used to derive the heights and
     depths.  Like the existing quantities in the font  description  file,  each
     value  [4mn[24m  is in [4mscaled[24m [4mpoints,[24m inches/[4mresolution[24m for a font whose type size
     is [4munit‐width[24m; see ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

     [1m-asc-height [4m[22mn[0m
            height of characters with ascenders, such as “b”, “d”, or “l”

     [1m-body-depth [4m[22mn[0m
            depth of characters such as parentheses

     [1m-body-height [4m[22mn[0m
            height of characters such as parentheses

     [1m-cap-height [4m[22mn[0m
            height of uppercase letters such as “A”

     [1m-comma-depth [4m[22mn[0m
            depth of a comma

     [1m-desc-depth [4m[22mn[0m
            depth of characters with descenders, such as “p”, “q”, or “y”

     [1m-fig-height[0m
            height of figures (numerals)

     [1m-x-height [4m[22mn[0m
            height of lowercase letters without ascenders such as “x”

     [4maddftinfo[24m makes no attempt to use the specified parameters to infer unspec‐
     ified parameters.  If a parameter is not specified,  the  default  will  be
     used.   The  defaults  are  chosen to produce reasonable values for a Times
     font.

[1mExit status[0m
     [4maddftinfo[24m exits with status [1m0 [22mon successful operation, and status [1m2 [22mif  the
     program cannot interpret its command‐line arguments.

[1mSee also[0m
     ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\, ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\

groff 1.24.1                       2026‐03‐20                       [4maddftinfo[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mafmtodit[24m(1)                  General Commands Manual                 [4mafmtodit[24m(1)

[1mName[0m
     afmtodit - adapt Adobe Font Metrics files for [4mgroff[24m PostScript and PDF out‐
     put

[1mSynopsis[0m
     [1mafmtodit [22m[[1m-ckmnqsx[22m] [[1m-a [4m[22mslant[24m] [[1m-d [4m[22mdevice‐description‐file[24m] [[1m-e [4m[22mencoding‐[0m
              [4mfile[24m] [[1m-f [4m[22minternal‐name[24m] [[1m-i [4m[22mitalic‐correction‐factor[24m] [[1m-o [4m[22moutput‐[0m
              [4mfile[24m] [[1m-w [4m[22mspace‐width[24m] [4mafm‐file[24m [4mmap‐file[24m [4mfont‐description‐file[0m

     [1mafmtodit --help[0m

     [1mafmtodit -v[0m
     [1mafmtodit --version[0m

[1mDescription[0m
     [4mafmtodit[24m  generates  a font description file for use with ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\’s [1mps [22mand
     [1mpdf [22moutput devices from an Adobe Font Metric file, [4mafm‐file[24m.  [4mmap‐file[24m  as‐
     sociates a [4mgroff[24m ordinary or special character name with a PostScript glyph
     name.   Output is written in ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\ format to [4mfont‐description‐file,[0m
     a file named for the intended [4mgroff[24m font name (but see the [1m-o [22moption).

     [4mmap‐file[24m should contain a sequence of lines of the form
            [4mps‐glyph[24m [4mgroff‐char[0m
     where [4mps‐glyph[24m is the PostScript glyph name and [4mgroff‐char[24m is a [4mgroff[24m ordi‐
     nary (if of unit length) or special (if longer) character identifier.   The
     same  [4mps‐glyph[24m  can  occur multiple times in the file; each [4mgroff‐char[24m must
     occur at most once.  Lines starting with “#” and blank lines  are  ignored.
     If  the  file isn’t found in the current directory, it is sought in the [4mde‐[0m
     [4mvps/generate[24m subdirectory of the default font directory.

     If a PostScript glyph is not mentioned in [4mmap‐file[24m, and a  [4mgroff[24m  character
     name  can’t  be  deduced  using  the Adobe Glyph List (AGL, built into [4mafm‐[0m
     [4mtodit[24m), then [4mafmtodit[24m puts the PostScript glyph into  the  [4mgroff[24m  font  de‐
     scription  file  as an unnamed glyph which can only be accessed by the “\N”
     escape sequence in a [4mroff[24m document.  In particular, this is true for  glyph
     variants  named  in  the  form “[4mfoo[24m.[4mbar[24m”; all glyph names containing one or
     more periods are mapped to unnamed entities.  Unless [1m-e [22mis  specified,  the
     encoding defined in the AFM file (i.e., entries with non‐negative codes) is
     used.  Refer to section “Using Symbols” in [4mGroff:[24m [4mThe[24m [4mGNU[24m [4mImplementation[24m [4mof[0m
     [4mtroff[24m, the [4mgroff[24m Texinfo manual, or ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\, which describe how [4mgroff[0m
     character identifiers are constructed.

     Glyphs  not  encoded  in  the  AFM file (i.e., entries indexed as “-1”) are
     still available in [4mgroff[24m; they get glyph index values greater than 255  (or
     greater  than  the  biggest  code used in the AFM file in the unlikely case
     that it is greater than 255) in the [4mgroff[24m font description file.  Unencoded
     glyph indices don’t have a specific order; it is best to access  them  only
     via special character identifiers.

     If  the font file proper (not just its metrics) is available, listing it in
     the files [4m/usr/share/groff/1.24.1/font/devps/download[24m and [4m/usr/share/groff/[0m
     [4m1.24.1/font/devpdf/download[24m enables it to be embedded in  the  output  pro‐
     duced by ]8;;man:grops(1)\[4mgrops[24m(1)]8;;\ and ]8;;man:gropdf(1)\[4mgropdf[24m(1)]8;;\, respectively.

     If  the  [1m-i [22moption is used, [4mafmtodit[24m automatically generates an italic cor‐
     rection, a left italic correction, and  a  subscript  correction  for  each
     glyph  (the  significance of these is explained in ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\); they can
     be specified for individual glyphs by adding to the [4mafm‐file[24m lines  of  the
     form:
            italicCorrection [4mps‐glyph[24m [4mn[0m
            leftItalicCorrection [4mps‐glyph[24m [4mn[0m
            subscriptCorrection [4mps‐glyph[24m [4mn[0m
     where  [4mps‐glyph[24m is the PostScript glyph name, and [4mn[24m is the desired value of
     the corresponding parameter in thousandths of an em.  Such  parameters  are
     normally needed only for italic (or oblique) fonts.

     The  [1m-s [22moption should be given if the font is “special”, meaning that [4mgroff[0m
     should search it whenever a glyph is not found in the current font.  To en‐
     able this search, [4mfont‐description‐file[24m can be listed as an argument to the
     [1mfonts [22mdirective in the output device’s [4mDESC[24m file; alternatively, a document
     can designate it with the [1mspecial [22mrequest.  If the  font  is  not  special,
     there  is  no need to do either, since ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ will automatically mount it
     when it is first used.

[1mOptions[0m
     [1m--help [22mdisplays a usage message, while [1m-v [22mand [1m--version [22mshow version infor‐
     mation; all exit afterward.

     [1m-a [4m[22mslant[0m
            Use [4mslant[24m as the slant (“angle”) parameter in the  font  description
            file;  this  is used by [4mgroff[24m in the positioning of accents.  By de‐
            fault [4mafmtodit[24m uses the negative of the [1mItalicAngle [22mspecified in the
            AFM file; with true italic fonts it is sometimes desirable to use  a
            slant  that  is  less  than  this.   If you find that an italic font
            places accents over base glyphs too far to the right, use [1m-a [22mto give
            it a smaller slant.

     [1m-c     [22mInclude comments in the font description file identifying the  Post‐
            Script font.

     [1m-d [4m[22mdevice‐description‐file[0m
            The  device  description  file  is [4mdesc‐file[24m rather than the default
            [4mDESC[24m.  If not found in the current directory, the [4mdevps[24m subdirectory
            of the default font directory is searched (this is true for both the
            default device description file and a file given with option [1m-d[22m).

     [1m-e [4m[22mencoding‐file[0m
            The PostScript font should be reencoded  to  use  the  encoding  de‐
            scribed  in  [4menc‐file[24m.   The  format  of  [4menc‐file[24m  is  described in
            ]8;;man:grops(1)\[4mgrops[24m(1)]8;;\.  If not found in the current directory, the  [4mdevps[24m  subdi‐
            rectory of the default font directory is searched.

     [1m-f [4m[22minternal‐name[0m
            The internal name of the [4mgroff[24m font is set to [4mname[24m.

     [1m-i [4m[22mitalic‐correction‐factor[0m
            Generate  an italic correction for each glyph so that its width plus
            its italic correction is  equal  to  [4mitalic‐correction‐factor[24m  thou‐
            sandths  of  an  em  plus  the amount by which the right edge of the
            glyph’s bounding box is to the right of its origin.  If  this  would
            result in a negative italic correction, use a zero italic correction
            instead.

            Also  generate  a  subscript  correction equal to the product of the
            tangent of the slant of the font and four fifths of the x‐height  of
            the  font.   If  this would result in a subscript correction greater
            than the italic correction, use a subscript correction equal to  the
            italic correction instead.

            Also  generate  a  left  italic  correction  for each glyph equal to
            [4mitalic‐correction‐factor[24m thousandths of an em  plus  the  amount  by
            which  the  left  edge of the glyph’s bounding box is to the left of
            its origin.  The left italic correction may be negative  unless  op‐
            tion [1m-m [22mis given.

            This  option is normally needed only with italic (or oblique) fonts.
            The font description files distributed with [4mgroff[24m were created using
            an option of [1m-i50 [22mfor italic fonts.

     [1m-o [4m[22moutput‐file[0m
            Write to [4moutput‐file[24m instead of [4mfont‐description‐file.[0m

     [1m-k     [22mOmit any kerning data from the [4mgroff[24m font; use only  for  monospaced
            (constant‐width) fonts.

     [1m-m     [22mPrevent  negative  left  italic correction values.  Font description
            files for roman styles distributed  with  [4mgroff[24m  were  created  with
            “[1m-i0 -m[22m” to improve spacing with ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\.

     [1m-n     [22mDon’t  output  a  “[1mligatures[22m”  command for this font; use with mono‐
            spaced (constant‐width) fonts.

     [1m-q     [22mQuieten duplicate mapping warnings; see section “Diagnostics” below.

     [1m-s     [22mAdd the “[1mspecial[22m” directive to the font description file.

     [1m-w [4m[22mspace‐width[0m
            Use [4mspace‐width[24m as the width of inter‐word spaces.

     [1m-x     [22mDon’t use the built‐in Adobe Glyph List.

[1mExit status[0m
     [4mafmtodit[24m exits with status [1m0 [22mon successful operation, status [1m2 [22mif the  pro‐
     gram  cannot  interpret  its command‐line arguments, and status [1m1 [22mif it en‐
     counters an error during operation.

[1mFiles[0m
     [4m/usr/share/groff/1.24.1/font/devps/DESC[0m
            describes the [1mps [22moutput device.

     [4m/usr/share/groff/1.24.1/font/devps/[24mF
            describes the font known as [4mF[24m on device [1mps[22m.

     [4m/usr/share/groff/1.24.1/font/devps/download[0m
            lists fonts available for embedding within the  PostScript  document
            (or download to the device).

     [4m/usr/share/groff/1.24.1/font/devps/generate/dingbats.map[0m
     [4m/usr/share/groff/1.24.1/font/devps/generate/dingbats-reversed.map[0m
     [4m/usr/share/groff/1.24.1/font/devps/generate/slanted-symbol.map[0m
     [4m/usr/share/groff/1.24.1/font/devps/generate/symbol.map[0m
     [4m/usr/share/groff/1.24.1/font/devps/generate/text.map[0m
            map names in the Adobe Glyph List to [4mgroff[24m special character identi‐
            fiers  for Zapf Dingbats ([1mZD[22m), reversed Zapf Dingbats ([1mZDR[22m), slanted
            symbol ([1mSS[22m), symbol ([1mS[22m), and text fonts, respectively.   These  [4mmap‐[0m
            [4mfile[24ms produce the font description files provided with [4mgroff[24m for the
            [4mgrops[24m output driver.

[1mDiagnostics[0m
     AGL name '[4mx[24m' already mapped to groff name '[4my[24m'; ignoring AGL name 'uni[4mXXXX[24m'
            You  can disregard these if they’re in the form shown, where the ig‐
            nored AGL name contains four hexadecimal  digits  [4mXXXX[24m.   The  Adobe
            Glyph  List  (AGL) has its own names for glyphs; they are often dif‐
            ferent from [4mgroff[24m’s special character names.  [4mafmtodit[24m is construct‐
            ing a mapping from [4mgroff[24m special character names to AGL names;  this
            can be a one‐to‐one or many‐to‐one mapping, but one‐to‐many will not
            work,  so  [4mafmtodit[24m discards the excess mappings.  For example, if [4mx[0m
            is [1mDelta[22m, [4my[24m is [1m*D[22m, and [4mXXXX[24m is [1m0394[22m, [4mafmtodit[24m is  telling  you  that
            the  [4mgroff[24m  font description that it is writing cannot map the [4mgroff[0m
            special character [1m\[*D] [22mto AGL glyphs [1mDelta [22mand [1muni0394 [22mat the  same
            time.

            If you get a message like this but are unhappy with which mapping is
            ignored,  a  remedy  is  to craft an alternative [4mmap‐file[24m and re‐run
            [4mafmtodit[24m using it.

            When the [1m-q [22moption is used, these messages are suppressed  in  favor
            of  a  count of how many would have been emitted were the option not
            present.

[1mSee also[0m
     [4mGroff:[24m [4mThe[24m [4mGNU[24m [4mImplementation[24m [4mof[24m [4mtroff[24m, by Trent A. Fisher and Werner  Lem‐
     berg,  is the primary [4mgroff[24m manual.  Section “Using Symbols” may be of par‐
     ticular note.  You can browse it  interactively  with  “info  '(groff)Using
     Symbols'”.

     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, ]8;;man:gropdf(1)\[4mgropdf[24m(1)]8;;\, ]8;;man:grops(1)\[4mgrops[24m(1)]8;;\, ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\

groff 1.24.1                       2026‐03‐20                        [4mafmtodit[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mchem[24m(1)                      General Commands Manual                     [4mchem[24m(1)

[1mName[0m
     chem - embed chemical structure diagrams in [4mgroff[24m documents

[1mSynopsis[0m
     [1mchem [22m[[1m--[22m] [[4mfile[24m ...]

     [1mchem -h[0m
     [1mchem --help[0m

     [1mchem -v[0m
     [1mchem --version[0m

[1mDescription[0m
     [4mchem[24m  produces chemical structure diagrams.  Today’s version is best suited
     for organic chemistry (bonds, rings).  The [4mchem[24m program  is  a  [4mgroff[24m  pre‐
     processor  like  [4meqn[24m, [4mpic[24m, [4mtbl[24m, etc.  It generates [4mpic[24m output such that all
     [4mchem[24m parts are translated into diagrams of the [4mpic[24m language.

     If no operands are given, or if [4mfile[24m is “[1m-[22m”, [4mchem[24m reads the standard  input
     stream.   [1m-h  [22mand  [1m--help [22mdisplay a usage message, whereas [1m-v [22mand [1m--version[0m
     display version information; all exit.

     The program [4mchem[24m originates from the Perl source file  [4mchem.pl[24m.   It  tells
     [4mpic[24m  to  include  a  copy  of  the macro file [4mchem.pic[24m.  Moreover the [4mgroff[0m
     source file [4mpic.tmac[24m is loaded.

     In a style reminiscent of [4meqn[24m and [4mpic[24m, the [4mchem[24m diagrams are written  in  a
     special language.

     A set of [4mchem[24m lines looks like this

            .cstart
            [4mchem[24m [4mdata[0m
            .cend

     Lines containing the keywords [1m.cstart [22mand [1m.cend [22mstart and end the input for
     [4mchem[24m,  respectively.  In [4mpic[24m context, i.e., after the call of [1m.PS[22m, [4mchem[24m in‐
     put can optionally be started by the line [1mbegin chem [22mand ended by the  line
     with the single word [1mend [22minstead.

     Anything outside these initialization lines is copied through without modi‐
     fication;  all  data between the initialization lines is converted into [4mpic[0m
     commands to draw the diagram.

     As an example,

            .cstart
            CH3
            bond
            CH3
            .cend

     prints two [1mCH3 [22mgroups with a bond between them.

     If you want to create just [4mgroff[24m output, you  must  run  [4mchem[24m  followed  by
     [4mgroff[24m with the option [1m-p [22mfor the activation of [4mpic[24m:

            [4mchem[24m [[4mfile[24m ...] [1m| groff -p [22m...

     [4mchem[24m requires the [4mMath::Trig[24m Perl module, available via ]8;;https://www.cpan.org/\CPAN]8;;\.

[1mLanguage[0m
     The  [4mchem[24m  input  language  is  rather small.  It provides rings of several
     styles and a way to glue them together as desired, bonds of several styles,
     moieties (e.g., [1mC[22m, [1mNH3[22m, ..., and strings.

   [1mSetting variables[0m
     There are some variables that can be set by commands.  Such  commands  have
     two possible forms, either

            [4mvariable[24m [4mvalue[0m

     or

            [4mvariable[24m [1m= [4m[22mvalue[0m

     This  sets the given [4mvariable[24m to the argument [4mvalue[24m.  If more arguments are
     given only the last argument is taken, all other arguments are ignored.

     There are only a few variables to be set by these commands:

     [1mtextht [4m[22marg[0m
            Set the height of the text to [4marg[24m; default is 0.16.

     [1mcwid [4m[22marg[0m
            Set the character width to [4marg[24m; default is 0.12.

     [1mdb [4m[22marg[0m
            Set the bond length to [4marg[24m; default is 0.2.

     [1msize [4m[22marg[0m
            Scale the diagram to make it look plausible at point size  [4marg[24m;  de‐
            fault is 10 point.

   [1mBonds[0m
     [1mbond [22m[[4mdirection[24m] [[4mlength[24m [4mn[24m] [[1mfrom [4m[22mName[24m|[4mpicstuff[24m]

     The  [1mbond  [22mcommand  draws a single bond in direction from nearest corner of
     [4mName[24m.  [1mbond [22mcan also be [1mdouble bond[22m, [1mfront bond[22m, [1mback bond[22m, etc.  (We  will
     get back to [4mName[24m soon.)

     [4mdirection[24m is the angle in degrees (0 up, positive clockwise) or a direction
     word  like  [1mup[22m, [1mdown[22m, [1msw [22m(= southwest), etc.  If no direction is specified,
     the bond goes in the current direction (usually that of the last bond).

     Normally the bond begins at the last object placed;  this can be changed by
     naming a [1mfrom [22mplace.  For instance, to make a simple alkyl chain:
            [1mCH3[0m
            [1mbond                [22m(this one goes right from the CH3)
            [1mC                   [22m(at the right end of the bond)
            [1mdouble bond up      [22m(from the C)
            [1mO                   [22m(at the end of the double bond)
            [1mbond right from C[0m
            [1mCH3[0m

     A length in inches may be specified to override the default length.   Other
     [4mpic[24m commands can be tacked on to the end of a bond command, to created dot‐
     ted or dashed bonds or to specify a [1mto [22mplace.

   [1mRings[0m
     There  are  lots of rings, but only five‐ and six‐sided rings get much sup‐
     port.  [1mring [22mby itself is a six‐sided ring; [1mbenzene [22mis the benzene ring with
     a circle inside.  [1maromatic [22mputs a circle into any kind of ring.

     [1mring [22m[[1mpointing [22m([1mup[22m|[1mright[22m|[1mleft[22m|[1mdown[22m)] [[1maromatic[22m] [[1mput Mol at [4m[22mn[24m]
          [[1mdouble [4m[22mi[24m,[4mj[24m [4mk[24m,[4ml[24m ... [[4mpicstuff[24m]

     The vertices of a ring are numbered 1, 2, ... from the vertex  that  points
     in  the  natural compass direction.  So for a hexagonal ring with the point
     at the top, the top vertex is 1, while if the ring has a point at the  east
     side, that is vertex 1.  This is expressed as

            R1: ring pointing up
            R2: ring pointing right

     The  ring vertices are named [1m.V1[22m, ..., [1m.V[4m[22mn[24m, with [1m.V1 [22min the pointing direc‐
     tion.  So the corners of [1mR1 [22mare [1mR1.V1 [22m(the [4mtop[24m), [1mR1.V2[22m, [1mR1.V3[22m,  [1mR1.V4  [22m(the
     [4mbottom[24m),  etc., whereas for [1mR2[22m, [1mR2.V1 [22mis the rightmost vertex and [1mR2.V4 [22mthe
     leftmost.  These vertex names are used for connecting bonds or other rings.
     For example,

            R1: benzene pointing right
            R2: benzene pointing right with .V6 at R1.V2

     creates two benzene rings connected along a side.

     Interior double bonds are specified as [1mdouble [4m[22mn1[24m[1m,[4m[22mn2[24m [4mn3[24m[1m,[4m[22mn4[24m ...[1m; [22meach  number
     pair adds an interior bond.  So the alternate form of a benzene ring is

            [1mring double 1,2 3,4 5,6[0m

     Heterocycles (rings with something other than carbon at a vertex) are writ‐
     ten as [1mput [4m[22mX[24m [1mat [4m[22mV[24m, as in

            [1mR: ring put N at 1 put O at 2[0m

     In this heterocycle, [1mR.N [22mand [1mR.O [22mbecome synonyms for [1mR.V1 [22mand [1mR.V2[22m.

     There  are  two  five‐sided  rings.   [1mring5  [22mis pentagonal with a side that
     matches the six‐sided ring; it has four natural directions.  A [1mflatring  [22mis
     a  five‐sided  ring  created  by chopping one corner of a six‐sided ring so
     that it exactly matches the six‐sided rings.

     The description of a ring has to fit on a single line.

   [1mMoieties and strings[0m
     A moiety is a string of characters beginning with a capital letter, such as
     N(C2H5)2.  Numbers are converted to subscripts (unless they  appear  to  be
     fractional  values,  as in N2.5H).  The name of a moiety is determined from
     the moiety after special characters have been stripped out: e.g., N(C2H5)2)
     has the name NC2H52.

     Moieties can be specified in two kinds.  Normally a moiety is placed  right
     after  the  last  thing  mentioned,  separated by a semicolon surrounded by
     spaces, e.g.,

            [1mB1: bond ; OH[0m

     Here the moiety is [1mOH[22m; it is set after a bond.

     As the second kind a moiety can be positioned as the first word in  a  [4mpic[24m‐
     like command, e.g.,

            [1mCH3 at C + (0.5,0.5)[0m

     Here the moiety is [1mCH3[22m.  It is placed at a position relative to [1mC[22m, a moiety
     used earlier in the chemical structure.

     So  moiety  names can be specified as [4mchem[24m positions everywhere in the [4mchem[0m
     code.  Beneath their printing moieties are names for places.

     The moiety [1mBP [22mis special.  It is not printed but just serves as a  mark  to
     be referred to in later [4mchem[24m commands.  For example,

            [1mbond ; BP[0m

     sets a mark at the end of the bond.  This can be used then for specifying a
     place.  The name [1mBP [22mis derived from [4mbranch[24m [4mpoint[24m (i.e., line crossing).

     A string within double quotes [1m" [22mis interpreted as a part of a [4mchem[24m command.
     It  represents  a string that should be printed (without the quotes).  Text
     within quotes [1m"[22m...[1m" [22mis treated more or less like a moiety  except  that  no
     changes are made to the quoted part.

   [1mNames[0m
     In  the  alkyl  chain above, notice that the carbon atom [1mC [22mwas used both to
     draw something and as the name for a place.  A moiety always defines a name
     for a place;  you can use your own names for places  instead,  and  indeed,
     for rings you will have to.  A name is just

            [4mName[24m[1m: [22m...

     [4mName[24m  is  often  the name of a moiety like [1mCH3[22m, but it need not to be.  Any
     name that begins with a capital letter and which contains only letters  and
     numbers is valid.

            First: bond
                   "bond 30 from First"

   [1mMiscellaneous[0m
     The specific construction

            [1mbond [22m... [1m; moiety[0m

     is equivalent to

            bond
            moiety

     Otherwise,  each  item  has  to  be on a separate line (and only one line).
     Note that there must be whitespace after the semicolon which separates  the
     commands.

     A period character [1m. [22mor a single quote [1m' [22min the first column of a line sig‐
     nals a [4mtroff[24m command, which is copied through as‐is.

     A  line  whose first non‐blank character is a hash character ([1m#[22m) is treated
     as a comment and thus ignored.  However, hash characters within a word  are
     kept.

     A  line  whose first word is [1mpic [22mis copied through as‐is after the word [1mpic[0m
     has been removed.

     The command

            [1msize [4m[22mn[0m

     scales the diagram to make it look plausible at point size  [4mn[24m  (default  is
     10 point).

     Anything else is assumed to be [4mpic[24m code, which is copied through with a la‐
     bel.

     Since  [4mchem[24m is a [4mpic[24m preprocessor, it is possible to include [4mpic[24m statements
     in the middle of a diagram to draw things not provided for by [4mchem[24m  itself.
     Such  [4mpic[24m  statements  should be included in [4mchem[24m code by adding [1mpic [22mas the
     first word of this line for clarity.

     The following [4mpic[24m commands are accepted as [4mchem[24m commands, so no [1mpic [22mcommand
     word is needed:

            [1mdefine [22mStart the definition of [4mpic[24m macro within [4mchem[24m.

            [1m[      [22mStart a block composite.

            [1m]      [22mEnd a block composite.

            [1m{      [22mStart a macro definition block.

            [1m}      [22mEnd a macro definition block.

     The macro names from [1mdefine [22mstatements are stored and  their  call  is  ac‐
     cepted as a [4mchem[24m command as well.

   [1mWish list[0m
     This TODO list was collected by Brian Kernighan.

     Error  checking  is minimal; errors are usually detected and reported in an
     oblique fashion by [4mpic[24m.

     There is no library or file inclusion mechanism, and there is no  shorthand
     for repetitive structures.

     The  extension  mechanism  is to create [4mpic[24m macros, but these are tricky to
     get right and don’t have all the properties of built‐in objects.

     There is no in‐line chemistry yet (e.g., analogous to the  [1m$[22m...[1m$  [22mconstruct
     of [4meqn[24m).

     There  is  no  way  to control entry point for bonds on groups.  Normally a
     bond connects to the carbon atom if entering from the  top  or  bottom  and
     otherwise to the nearest corner.

     Bonds  from  substituted  atoms  on  heterocycles do not join at the proper
     place without adding a bit of [4mpic[24m.

     There is no decent primitive for brackets.

     Text (quoted strings) doesn’t work very well.

     A squiggle bond is needed.

[1mFiles[0m
     [4m/usr/share/groff/1.24.1/pic/chem.pic[0m
            A collection of [4mpic[24m macros needed by [4mchem[24m.

     [4m/usr/share/groff/1.24.1/tmac/pic.tmac[0m
            A macro file which redefines [1m.PS[22m, [1m.PE[22m, and [1m.PF [22mto  center  [4mpic[24m  dia‐
            grams.

     [4m/usr/share/doc/groff-1.24.1/examples/chem/[24m*[4m.chem[0m
            Example files for [4mchem[24m.

     [4m/usr/share/doc/groff-1.24.1/examples/chem/122/[24m*[4m.chem[0m
            Example files from the [4mchem[24m article by its authors, “CHEM——A Program
            for   Typesetting   Chemical   Structure   Diagrams:   User  Manual”
            (CSTR #122).

[1mAuthors[0m
     The GNU version of [4mchem[24m was written by ]8;;mailto:groff-bernd.warken-72@web.de\Bernd Warken]8;;\.  It is  based  on  the
     documentation of Brian Kernighan’s original [4mawk[24m version of [4mchem[24m.

[1mSee also[0m
     “CHEM——A  Program for Typesetting Chemical Diagrams: User Manual” by Jon L.
     Bentley, Lynn W. Jelinski, and Brian W. Kernighan, 1992, AT&T Bell  Labora‐
     tories Computing Science Technical Report No. 122

     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, ]8;;man:pic(1)\[4mpic[24m(1)]8;;\

groff 1.24.1                       2026‐03‐20                            [4mchem[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4meqn[24m(1)                       General Commands Manual                      [4meqn[24m(1)

[1mName[0m
     eqn - format mathematics (equations) for [4mgroff[24m or MathML

[1mSynopsis[0m
     [1meqn [22m[[1m-CNrR[22m] [[1m-[22md [4mxy[24m] [[1m-f [4m[22mglobal‐italic‐font[24m] [[1m-m [4m[22mminimum‐type‐size[24m]
         [[1m-M [4m[22meqnrc‐directory[24m] [[1m-p [4m[22msuper/subscript‐size‐reduction[24m] [[1m-s [4m[22mglobal‐[0m
         [4mtype‐size[24m] [[1m-T [4m[22mdevice[24m] [[4mfile[24m ...]

     [1meqn --help[0m

     [1meqn -v[0m
     [1meqn --version[0m

[1mDescription[0m
     The  GNU  implementation of [4meqn[24m is part of the ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\ document formatting
     system.  [4meqn[24m is a ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ preprocessor that translates expressions in  its
     own language, embedded in ]8;;man:roff(7)\[4mroff[24m(7)]8;;\ input, into mathematical notation typeset
     by ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\.  It copies each [4mfile[24m’s contents to the standard output stream,
     translating  each  [4mequation[24m  between  lines  starting  with [1m.EQ [22mand [1m.EN[22m, or
     within a pair of user‐specified delimiters.  Normally, [4meqn[24m is not  executed
     directly  by the user, but invoked by specifying the [1m-e [22moption to ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\.
     While GNU [4meqn[24m’s input syntax is highly compatible with AT&T [4meqn[24m, the output
     [4meqn[24m produces cannot be processed by AT&T [4mtroff[24m; GNU [4mtroff[24m (or a  [4mtroff[24m  im‐
     plementing  relevant GNU extensions) must be used.  If no [4mfile[24m operands are
     present, or if [4mfile[24m is “[1m-[22m”, [4meqn[24m reads the standard input stream.

     Unless the [1m-R [22moption is used, [4meqn[24m searches for the file [4meqnrc[24m in the direc‐
     tories given with the [1m-M [22moption first, then in  [4m/usr/share/groff/site-tmac[24m,
     and  finally  in the standard macro directory [4m/usr/share/groff/1.24.1/tmac[24m.
     If it exists and is readable, [4meqn[24m processes it before any input.

     This man page primarily discusses the differences between GNU [4meqn[24m and  AT&T
     [4meqn[24m.   Most  of the new features of the GNU [4meqn[24m input language are based on
     TeX.  There are some references to the differences between TeX and GNU  [4meqn[0m
     below; these may safely be ignored if you do not know TeX.  Four points are
     worth note.

     •  GNU   [4meqn[24m  emits  Presentation  MathML  output  when  invoked  with  the
        “[1m-T MathML[22m” option.

     •  GNU [4meqn[24m does not support terminal devices well, though  it  may  suffice
        for simple inputs.

     •  GNU  [4meqn[24m sets the input token “[1m...[22m” as an ellipsis on the text baseline,
        not the three centered dots of AT&T [4meqn[24m.  Set an ellipsis  on  the  math
        axis with the GNU extension macro [1mcdots[22m.

     •  GNU  [4meqn[24m’s  [1mdelim [22mprimitive does not treat an “[1mon[22m” argument as a pair of
        equation delimiters.

   [1mAnatomy of an equation[0m
     [4meqn[24m input consists of tokens.  Consider a form of Newton’s  second  law  of
     motion for constant mass.  The input

            .EQ
            F =
            m a
            .EN

     becomes  [4mF[24m=[4mma[24m.  Each of [1mF[22m, [1m=[22m, [1mm[22m, and [1ma [22mis a token.  Spaces and newlines are
     interchangeable; they separate tokens but do not  break  lines  or  produce
     space in the output.

     Beyond their primary functions, the following input characters separate to‐
     kens as well.

     [1m{ }    [22mBraces  perform  grouping.   Whereas  “[1me  sup  a b[22m” expresses “([4me[24m to
            the [4ma[24m) times [4mb[24m”, “[1me sup { a b }[22m” means “[4me[24m to the ([4ma[24m times [4mb[24m)”.  When
            immediately preceded by a “[1mleft[22m” or “[1mright[22m” primitive, a brace loses
            its special meaning.

     [1m^ ~    [22mare the [4mhalf[24m [4mspace[24m and [4mfull[24m [4mspace,[24m respectively.  Use them  to  tune
            the appearance of the output.

     Tab  and leader characters separate tokens as well as advancing the drawing
     position to the next tab stop, but are seldom used in [4meqn[24m input.  When they
     occur, they must appear at the outermost lexical scope.  This roughly means
     that they can’t appear within braces that are necessary to disambiguate the
     input; [4meqn[24m will diagnose an error in this event.  (See subsection  “Macros”
     below for additional token separation rules.)

     Other  tokens  are primitives, macros, an argument to either of the forego‐
     ing, or components of an equation.

     [4mPrimitives[24m are fundamental keywords of the [4meqn[24m language.  They can  config‐
     ure  an aspect of the preprocessor’s state, as when setting a “global” font
     selection or type size ([1mgifont [22mand [1mgsize[22m), or declaring or deleting  macros
     (“[1mdefine[22m”  and [1mundef[22m); these are termed [4mcommands.[24m  Other primitives perform
     formatting operations on the tokens around them (as with [1mfat[22m,  [1mover[22m,  [1msqrt[22m,
     or [1mup[22m).

     Equation [4mcomponents[24m include mathematical variables, constants, numeric lit‐
     erals,  and  operators.  [4meqn[24m remaps some input character sequences to [4mgroff[0m
     special character escape sequences for economy in equation entry and to en‐
     sure that glyphs from an unstyled font are used; see ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\.

            +   \[pl]                '    \[fm]
            ‐   \[mi]                <=   \[<=]
            =   \[eq]                >=   \[>=]

     [4mMacros[24m permit primitives, components, and other macros to be collected  and
     used  together  as  a  single token.  Predefined macros make convenient the
     preparation of [4meqn[24m input in a form resembling its  spoken  expression;  for
     example, consider [1mcos[22m, [1mhat[22m, [1minf[22m, and [1mlim[22m.

   [1mSpacing and typeface[0m
     GNU  [4meqn[24m  imputes  a  type  to each equation component, adjusting the space
     around it accordingly.  Recognized types follow; most affect spacing  only,
     whereas the “[1mletter[22m” subtype of “[1mordinary[22m” also assigns a style.

       ordinary      character such as “1”, “a”, or “!”
         letter      character to be italicized by default
         digit       [4mn/a[0m
       operator      large operator such as “Σ”
       binary        binary operator such as “+”
       relation      relational operator such as “=”
       opening       opening bracket such as “(”
       closing       closing bracket such as “)”
       punctuation   punctuation character such as “,”
       inner         sub‐formula contained within brackets
       suppress      component to which automatic spacing is not applied

     Two primitives apply types to equation components.

     [1mtype [4m[22mt[24m [4me[0m
            Apply type [4mt[24m to expression [4me[24m.

     [1mchartype [4m[22mt[24m [4mtext[0m
            Assign each character in (unquoted) [4mtext[24m type [4mt[24m, persistently.

     [4meqn[24m sets up spacings and styles as if by the following commands.

            chartype "letter"      abcdefghiklmnopqrstuvwxyz
            chartype "letter"      ABCDEFGHIKLMNOPQRSTUVWXYZ
            chartype "letter"      \[*a]\[*b]\[*g]\[*d]\[*e]\[*z]
            chartype "letter"      \[*y]\[*h]\[*i]\[*k]\[*l]\[*m]
            chartype "letter"      \[*n]\[*c]\[*o]\[*p]\[*r]\[*s]
            chartype "letter"      \[*t]\[*u]\[*f]\[*x]\[*q]\[*w]
            chartype "binary"      *\[pl]\[mi]
            chartype "relation"    <>\[eq]\[<=]\[>=]
            chartype "opening"     {([
            chartype "closing"     })]
            chartype "punctuation" ,;:.
            chartype "suppress"    ^~

     [4meqn[24m  assigns  all other ordinary and special [4mroff[24m characters, including nu‐
     merals 0–9, the “[1mordinary[22m” type.  (The “[1mdigit[22m” type is  not  used,  but  is
     available for customization.)  In keeping with common practice in mathemat‐
     ical  typesetting, lowercase, but not uppercase, Greek letters are assigned
     the “[1mletter[22m” type to style them in italics.  The macros for  producing  el‐
     lipses, “[1m...[22m”, [1mcdots[22m, and [1mldots[22m, use the “[1minner[22m” type.

   [1mPrimitives[0m
     [4meqn[24m  supports  without alteration the AT&T [4meqn[24m primitives [1mabove[22m, [1mback[22m, [1mbar[22m,
     [1mbold[22m, [1mdefine[22m, [1mdown[22m, [1mfat[22m, [1mfont[22m,  [1mfrom[22m,  [1mfwd[22m,  [1mgfont[22m,  [1mgsize[22m,  [1mitalic[22m,  [1mleft[22m,
     [1mlineup[22m,  [1mmark[22m,  [1mmatrix[22m,  [1mndefine[22m, [1mover[22m, [1mright[22m, [1mroman[22m, [1msize[22m, [1msqrt[22m, [1msub[22m, [1msup[22m,
     [1mtdefine[22m, [1mto[22m, [1munder[22m, and [1mup[22m.

   [1mNew primitives[0m
     We describe the GNU extension primitives “[1mtype[22m” and [1mchartype [22min  subsection
     “Spacing  and  typeface” above; “[1mset[22m” and “[1mreset[22m” in subsection “Customiza‐
     tion” below; and [1mgbfont[22m, [1mgifont[22m, and [1mgrfont [22min  subsection  “Fonts”  below.
     In  the following synopses, [4mX[24m can be any character not appearing in the pa‐
     rameter thus bracketed.

     [4me1[24m [1maccent [4m[22me2[0m
            Set [4me2[24m as an accent over [4me1[24m.  [4meqn[24m assumes that [4me2[24m is at  the  appro‐
            priate height for a lowercase letter without an ascender, and shifts
            it vertically based on [4me1[24m’s height.  For example, [4meqn[24m defines [1mhat [22mas
            follows.

                   accent { roman "^" }

            [1mdotdot[22m,  [1mdot[22m, [1mtilde[22m, [1mvec[22m, and [1mdyad [22mare also defined using the [1maccent[0m
            primitive.

     [1mbig [4m[22me[24m  Enlarge the expression [4me[24m; semantics like those of  CSS  “large”  are
            intended.   In  [4mtroff[24m output, the type size is increased by 5 scaled
            points.  MathML output emits the following.

                   <mstyle mathsize='big'>

     [1mcopy [4m[22mfile[0m
     [1minclude [4m[22mfile[0m
            Interpolate the contents of [4mfile[24m, omitting lines beginning with  [1m.EQ[0m
            or [1m.EN[22m.  [4mfile[24m is sought relative to the current working directory.

     [1mifdef [4m[22mname[24m [4mX[24m [4manything[24m [4mX[0m
            If [4mname[24m is defined as a primitive or macro, interpret [4manything[24m.

     [1mnosplit [4m[22mtext[0m
            As  "[4mtext[24m",  but since [4mtext[24m is not quoted it is subject to macro ex‐
            pansion; it is not split up and the spacing between  characters  not
            adjusted per subsection “Spacing and typeface” above.

     [4me[24m [1mopprime[0m
            As  [1mprime[22m, but set the prime symbol as an operator on [4me[24m.  In the in‐
            put “[1mA opprime sub 1[22m”, the “1” is tucked under the prime as  a  sub‐
            script  to the “A” (as is conventional in mathematical typesetting),
            whereas when [1mprime [22mis used, the “1” is  a  subscript  to  the  prime
            character.  The precedence of [1mopprime [22mis the same as that of [1mbar [22mand
            “[1munder[22m”,  and higher than that of other primitives except [1maccent [22mand
            [1muaccent[22m.  In unquoted text, a neutral apostrophe ([1m'[22m) that is not the
            first character on the input line is treated like [1mopprime[22m.

     [1msdefine [4m[22mname[24m [4mX[24m [4manything[24m [4mX[0m
            As “[1mdefine[22m”, but [4mname[24m is not recognized as a macro  if  called  with
            arguments.

     [4me1[24m [1msmallover [4m[22me2[0m
            As  [1mover[22m, but reduce the type size of [4me1[24m and [4me2[24m, and put less verti‐
            cal space between [4me1[24m and [4me2[24m and the fraction bar.  The  [1mover  [22mprimi‐
            tive  corresponds  to  the TeX [1m\over [22mprimitive in displayed equation
            styles; [1msmallover [22mcorresponds to  [1m\over  [22min  non‐display  (“inline”)
            styles.

     [1mspace [4m[22mn[0m
            Set  extra  vertical  spacing around the equation, replacing the de‐
            fault values, where [4mn[24m is an integer in hundredths of an em.  If pos‐
            itive, [4mn[24m increases vertical spacing before the  equation;  if  nega‐
            tive, it does so after the equation.  This primitive provides an in‐
            terface  to  [4mgroff[24m’s  [1m\x [22mescape sequence, but with the opposite sign
            convention.  It has no effect if the equation is part  of  a  ]8;;man:pic(1)\[4mpic[24m(1)]8;;\
            picture.

     [1mspecial [4m[22mtroff‐macro[24m [4me[0m
            Construct  an  object by calling [4mtroff‐macro[24m on [4me[24m.  The [4mtroff[24m string
            [1m0s [22mcontains the [4meqn[24m output for [4me[24m, and  the  registers  [1m0w[22m,  [1m0h[22m,  [1m0d[22m,
            [1m0skern[22m, and [1m0skew [22mthe width, height, depth, subscript kern, and skew
            of  [4me[24m, respectively.  (The [4msubscript[24m [4mkern[24m of an object indicates how
            much a subscript on that object should be “tucked in”, or placed  to
            the  left relative to a non‐subscripted glyph of the same size.  The
            [4mskew[24m of an object is how far to the right of the center of  the  ob‐
            ject  an accent over it should be placed.)  The macro must modify [1m0s[0m
            so that it outputs the desired result, returns the drawing  position
            to  the text baseline at the beginning of [4me[24m, and updates the forego‐
            ing registers to correspond to the new dimensions of the result.

            Suppose you want a construct that “cancels” an expression by drawing
            a diagonal line through it.

                   .de Ca
                   .  ds 0s \
                   \Z'\\*(0s'\
                   \v'\\n(0du'\
                   \D'l \\n(0wu -\\n(0hu-\\n(0du'\
                   \v'\\n(0hu'
                   ..
                   .EQ
                   special Ca "x \[mi] 3 \[pl] x" ~ 3
                   .EN

            We use the [1m\[mi] [22mand [1m\[pl] [22mspecial characters instead of + and - be‐
            cause they are part of the argument to a [4mtroff[24m macro,  so  [4meqn[24m  does
            not  transform  them  to  mathematical glyphs for us.  Here’s a more
            complicated construct that draws a box  around  an  expression;  the
            bottom  of  the  box  rests on the text baseline.  We define the [4meqn[0m
            macro [1mbox [22mto wrap the call of the [4mtroff[24m macro [1mBx[22m.

                   .de Bx
                   .ds 0s \
                   \Z'\\h'1n'\\*[0s]'\
                   \v'\\n(0du+1n'\
                   \D'l \\n(0wu+2n 0'\
                   \D'l 0 -\\n(0hu-\\n(0du-2n'\
                   \D'l -\\n(0wu-2n 0'\
                   \D'l 0 \\n(0hu+\\n(0du+2n'\
                   \h'\\n(0wu+2n'
                   .nr 0w +2n
                   .nr 0d +1n
                   .nr 0h +1n
                   ..
                   .EQ
                   define box ' special Bx $1 '
                   box(foo) ~ "bar"
                   .EN

     [1msplit "[4m[22mtext[24m[1m"[0m
            As [4mtext[24m, but since [4mtext[24m is quoted, it is not subject to macro expan‐
            sion; it is split up and the spacing between characters adjusted per
            subsection “Spacing and typeface” above.

     [4me1[24m [1muaccent [4m[22me2[0m
            Set [4me2[24m as an accent under [4me1[24m.  [4me2[24m is assumed to be at the  appropri‐
            ate  height for a letter without a descender;  [4meqn[24m vertically shifts
            it depending on whether [4me1[24m has a descender.   [1mutilde  [22mis  predefined
            using [1muaccent [22mas a tilde accent below the baseline.

     [1mundef [4m[22mname[0m
            Remove definition of macro or primitive [4mname[24m, making it undefined.

     [1mvcenter [4m[22me[0m
            Vertically  center  [4me[24m  about  the  [4mmath[24m [4maxis[24m, a horizontal line upon
            which fraction bars and characters such as “+” and “−” are  aligned.
            MathML  already behaves this way, so [4meqn[24m ignores this primitive when
            producing that output format.  The built‐in [1msum [22mmacro is defined  as
            if by the following.

                   define sum ! { type "operator" vcenter size +5 \(*S } !

   [1mExtended primitives[0m
     GNU [4meqn[24m extends the syntax of some AT&T [4meqn[24m primitives, introducing one de‐
     liberate incompatibility.

     [1mdelim on[0m
            GNU  [4meqn[24m  recognizes  an  “[1mon[22m”  argument to the [1mdelim [22mprimitive spe‐
            cially, restoring any delimiters  previously  disabled  with  “[1mdelim[0m
            [1moff[22m”.  If delimiters haven’t been specified, neither command has ef‐
            fect.  Few [4meqn[24m documents are expected to use “o” and “n” as left and
            right delimiters, respectively.  If yours does, swap them, or select
            others.

     [1mcol [4m[22mn[24m [1m{ [22m... [1m}[0m
     [1mccol [4m[22mn[24m [1m{ [22m... [1m}[0m
     [1mlcol [4m[22mn[24m [1m{ [22m... [1m}[0m
     [1mrcol [4m[22mn[24m [1m{ [22m... [1m}[0m
     [1mpile [4m[22mn[24m [1m{ [22m... [1m}[0m
     [1mcpile [4m[22mn[24m [1m{ [22m... [1m}[0m
     [1mlpile [4m[22mn[24m [1m{ [22m... [1m}[0m
     [1mrpile [4m[22mn[24m [1m{ [22m... [1m}[0m
            The integer value [4mn[24m, in hundredths of an em, uses the formatter’s [1m\x[0m
            escape  sequence  to increase the vertical spacing between rows; [4meqn[0m
            ignores it when producing MathML.  Negative values are accepted  but
            have  no effect.  If more than one [4mn[24m occurs in a matrix or pile, the
            largest is used.

   [1mCustomization[0m
     When [4meqn[24m generates [4mtroff[24m input, the appearance of equations  is  controlled
     by  a  large  number  of  parameters.   They have no effect when generating
     MathML, which delegates typesetting to a MathML rendering engine.   Config‐
     ure these parameters with the “[1mset[22m” and “[1mreset[22m” primitives.

     [1mset [4m[22mp[24m [4mn[24m  assigns parameter [4mp[24m the integer value [4mn[24m; [4mn[24m is interpreted in units
              of hundredths of an em unless otherwise stated.  For example,
                     set x_height 45
              says that [4meqn[24m should assume that the font’s x‐height is 0.45 ems.

     [1mreset [4m[22mp[24m  restores the default value of parameter [4mp.[0m

     Available  parameters  [4mp[24m are as follows; defaults are shown in parentheses.
     We intend these descriptions to be expository rather than rigorous.

     [1mminimum_size            [22msets a floor for the type size (in  scaled  points)
                             at which equations are set ([1m5[22m).

     [1mfat_offset              [22mThe  [1mfat  [22mprimitive  emboldens an equation by over‐
                             printing two copies of  the  equation  horizontally
                             offset  by  this amount ([1m4[22m).  When producing MathML
                             output, components to which [1mfat_offset [22mapplies  in‐
                             stead use the following.
                                    <mstyle mathvariant='double-struck'>

     [1mover_hang               [22mA  fraction bar is longer by twice this amount than
                             the maximum of the widths of the numerator and  de‐
                             nominator; in other words, it overhangs the numera‐
                             tor and denominator by at least this amount ([1m0[22m).

     [1maccent_width            [22mWhen [1mbar [22mor [1munder [22mis applied to a single character,
                             the line is this long ([1m31[22m).  Normally, [1mbar [22mor [1munder[0m
                             produces  a  line  whose length is the width of the
                             object to which it applies; in the case of a single
                             character, this tends to produce a line that  looks
                             too long.

     [1mdelimiter_factor        [22mExtensible  delimiters  produced  with the [1mleft [22mand
                             [1mright [22mprimitives have a combined height  and  depth
                             of at least this many thousandths of twice the max‐
                             imum  amount by which the sub‐equation that the de‐
                             limiters enclose extends away from the axis ([1m900[22m).

     [1mdelimiter_shortfall     [22mExtensible delimiters produced with  the  [1mleft  [22mand
                             [1mright  [22mprimitives  have a combined height and depth
                             not less than the difference of twice  the  maximum
                             amount  by  which  the sub‐equation that the delim‐
                             iters enclose extends away from the axis  and  this
                             amount ([1m50[22m).

     [1mnull_delimiter_space    [22mThis much horizontal space is inserted on each side
                             of a fraction ([1m12[22m).

     [1mscript_space            [22mThe  width  of  subscripts  and superscripts is in‐
                             creased by this amount ([1m5[22m).

     [1mthin_space              [22mThis amount of space is automatically inserted  af‐
                             ter punctuation characters ([1m17[22m).

     [1mmedium_space            [22mThis  amount  of space is automatically inserted on
                             either side of binary operators ([1m22[22m).

     [1mthick_space             [22mThis amount of space is automatically  inserted  on
                             either side of relations ([1m28[22m).

     [1mhalf_space              [22mconfigures the width of the space produced by the [1m^[0m
                             token ([1m17[22m).

     [1mfull_space              [22mconfigures the width of the space produced by the [1m~[0m
                             token ([1m28[22m).

     [1mx_height                [22mThe  height  of lowercase letters without ascenders
                             such as “x” ([1m45[22m).

     [1maxis_height             [22mThe height above the  baseline  of  the  center  of
                             characters  such as “+” and “−” ([1m26[22m).  It is impor‐
                             tant that this value is correct for  the  font  you
                             are using.

     [1mdefault_rule_thickness  [22mThis  should  be  set to the thickness of the [1m\[ru][0m
                             character, or the  thickness  of  horizontal  lines
                             produced with the [1m\D [22mescape sequence ([1m4[22m).

     [1mnum1                    [22mThe  [1mover  [22mprimitive  shifts up the numerator by at
                             least this amount ([1m70[22m).

     [1mnum2                    [22mThe [1msmallover [22mprimitive shifts up the numerator  by
                             at least this amount ([1m36[22m).

     [1mdenom1                  [22mThe  [1mover  [22mprimitive shifts down the denominator by
                             at least this amount ([1m70[22m).

     [1mdenom2                  [22mThe [1msmallover [22mprimitive shifts down the denominator
                             by at least this amount ([1m36[22m).

     [1msup1                    [22mNormally superscripts are shifted up  by  at  least
                             this amount ([1m42[22m).

     [1msup2                    [22mSuperscripts within superscripts or upper limits or
                             numerators of [1msmallover [22mfractions are shifted up by
                             at least this amount ([1m37[22m).  Conventionally, this is
                             less than [1msup1[22m.

     [1msup3                    [22mSuperscripts within denominators or square roots or
                             subscripts  or  lower  limits  are shifted up by at
                             least this amount ([1m28[22m).   Conventionally,  this  is
                             less than [1msup2[22m.

     [1msub1                    [22mSubscripts  are  normally  shifted down by at least
                             this amount ([1m20[22m).

     [1msub2                    [22mWhen there is both a subscript and  a  superscript,
                             the  subscript  is  shifted  down  by at least this
                             amount ([1m23[22m).

     [1msup_drop                [22mThe baseline of a superscript is no more than  this
                             much  below  the top of the object on which the su‐
                             perscript is set ([1m38[22m).

     [1msub_drop                [22mThe baseline of a subscript is at least  this  much
                             below  the  bottom  of the object on which the sub‐
                             script is set ([1m5[22m).

     [1mbig_op_spacing1         [22mThe baseline of an upper limit  is  at  least  this
                             much above the top of the object on which the limit
                             is set ([1m11[22m).

     [1mbig_op_spacing2         [22mThe baseline of a lower limit is at least this much
                             below  the  bottom of the object on which the limit
                             is set ([1m17[22m).

     [1mbig_op_spacing3         [22mThe bottom of an upper limit is at least this  much
                             above  the  top of the object on which the limit is
                             set ([1m20[22m).

     [1mbig_op_spacing4         [22mThe top of a lower limit is at least this much  be‐
                             low  the bottom of the object on which the limit is
                             set ([1m60[22m).

     [1mbig_op_spacing5         [22mThis much vertical space is added above  and  below
                             limits ([1m10[22m).

     [1mbaseline_sep            [22mThe  baselines  of the rows in a pile or matrix are
                             normally this far apart ([1m140[22m).   Usually  equal  to
                             the sum of [1mnum1 [22mand [1mdenom1[22m.

     [1mshift_down              [22mThe  midpoint between the top baseline and the bot‐
                             tom baseline in a matrix or pile is shifted down by
                             this much from the axis  ([1m26[22m).   Usually  equal  to
                             [1maxis_height[22m.

     [1mcolumn_sep              [22mThis  much  space is added between columns in a ma‐
                             trix ([1m100[22m).

     [1mmatrix_side_sep         [22mThis much space is added at each side of  a  matrix
                             ([1m17[22m).

     [1mdraw_lines              [22mIf non‐zero, [4meqn[24m draws lines using the [4mtroff[24m [1m\D [22mes‐
                             cape  sequence,  rather than the [1m\l [22mescape sequence
                             and the [1m\[ru] [22mspecial character.   The  [4meqnrc[24m  file
                             sets  the  default:  [1m1 [22mon [1mps[22m, [1mhtml[22m, and the X11 de‐
                             vices, otherwise [1m0[22m.

     [1mbody_height             [22mis the presumed height of  an  equation  above  the
                             text  baseline;  [4meqn[24m  adds any excess as extra pre‐
                             vertical line spacing with [4mtroff[24m’s  [1m\x  [22mescape  se‐
                             quence ([1m85[22m).

     [1mbody_depth              [22mis the presumed depth of an equation below the text
                             baseline;  [4meqn[24m adds any excess as extra post‐verti‐
                             cal line spacing with [4mtroff[24m’s  [1m\x  [22mescape  sequence
                             ([1m35[22m).

     [1mnroff                   [22mIf  non‐zero,  then [1mndefine [22mbehaves like [1mdefine [22mand
                             [1mtdefine [22mis ignored, otherwise [1mtdefine [22mbehaves  like
                             [1mdefine [22mand [1mndefine [22mis ignored.  The [4meqnrc[24m file sets
                             the  default: [1m1 [22mon [1mascii[22m, [1mlatin1[22m, and [1mutf8 [22mdevices,
                             otherwise [1m0[22m.

   [1mMacros[0m
     In GNU [4meqn[24m, macros can take arguments.   A  word  defined  by  any  of  the
     [1mdefine[22m,  [1mndefine[22m,  or  [1mtdefine  [22mprimitives  followed  immediately by a left
     parenthesis is treated as a [4mparameterized[24m [4mmacro[24m [4mcall:[24m subsequent tokens  up
     to  a  matching right parenthesis are treated as comma‐separated arguments.
     In this context only, commas and parentheses also serve  as  token  separa‐
     tors.   A  macro  argument  is not terminated by a comma inside parentheses
     nested within it.  In a macro definition, [1m$[4m[22mn[24m, where [4mn[24m is between  1  and  9
     inclusive, is replaced by the [4mn[24mth argument; if there are fewer than [4mn[24m argu‐
     ments, it is replaced by nothing.

   [1mPredefined macros[0m
     GNU  [4meqn[24m  supports  the predefined macros offered by AT&T [4meqn[24m: [1mand[22m, [1mapprox[22m,
     [1marc[22m, [1mcos[22m, [1mcosh[22m, [1mdel[22m, [1mdet[22m, [1mdot[22m, [1mdotdot[22m, [1mdyad[22m, [1mexp[22m, [1mfor[22m, [1mgrad[22m, [1mhalf[22m, [1mhat[22m, [1mif[22m,
     [1minter[22m, [1mIm[22m, [1minf[22m, [1mint[22m, [1mlim[22m, [1mln[22m, [1mlog[22m, [1mmax[22m, [1mmin[22m, [1mnothing[22m, [1mpartial[22m, [1mprime[22m, [1mprod[22m,
     [1mRe[22m, [1msin[22m, [1msinh[22m, [1msum[22m, [1mtan[22m, [1mtanh[22m, [1mtilde[22m, [1mtimes[22m, [1munion[22m, [1mvec[22m, [1m==[22m,  [1m!=[22m,  [1m+=[22m,  [1m->[22m,
     [1m<-[22m, [1m<<[22m, [1m>>[22m, and “[1m...[22m”.  The lowercase classical Greek letters are available
     as  [1malpha[22m,  [1mbeta[22m, [1mchi[22m, [1mdelta[22m, [1mepsilon[22m, [1meta[22m, [1mgamma[22m, [1miota[22m, [1mkappa[22m, [1mlambda[22m, [1mmu[22m,
     [1mnu[22m, [1momega[22m, [1momicron[22m, [1mphi[22m, [1mpi[22m, [1mpsi[22m, [1mrho[22m, [1msigma[22m, [1mtau[22m, [1mtheta[22m, [1mupsilon[22m, [1mxi[22m,  and
     [1mzeta[22m.   Spell  them with an initial capital letter ([1mAlpha[22m) or in full capi‐
     tals ([1mALPHA[22m) to obtain uppercase forms.

     GNU [4meqn[24m further defines the macros [1mcdot[22m, [1mcdots[22m, and [1mutilde  [22m(all  discussed
     above), [1mdollar[22m, which sets a dollar sign, and [1mldots[22m, which sets an ellipsis
     on the text baseline.

   [1mFonts[0m
     [4meqn[24m  uses up to three typefaces to set an equation: italic (oblique), roman
     (upright), and bold (heavy).  Assign each a [4mgroff[24m typeface with the GNU ex‐
     tension primitives [1mgrfont[22m, [1mgifont[22m, and [1mgbfont.  [22mThe defaults are the styles
     [1mR[22m, [1mI[22m, and [1mB [22m(applied to the current font family).  The  [1mchartype  [22mprimitive
     (see  above) sets a character’s type, which determines the face used to set
     it.  The “[1mletter[22m” type is set in italics; others are set in roman.  Use the
     [1mbold [22mprimitive to select an (upright) bold style.

     [1mgbfont [4m[22mf[0m
            Select [4mf[24m as the bold font.

     [1mgifont [4m[22mf[0m
            Select [4mf[24m as the italic font.  GNU [4meqn[24m recognizes [1mgfont [22mas a  synonym
            for AT&T compatibility.

     [1mgrfont [4m[22mf[0m
            Select [4mf[24m as the roman font.

   [4m[1mroff[24m interface[0m
     The string [1m10 [22mstores the most recently formatted equation.  The register [1mMK[0m
     stores  the horizontal drawing position of the most recently assigned mark.
     Avoid using these names for any other purpose.

     GNU [4meqn[24m internally employs register, string, macro, and diversion names be‐
     ginning with the numeral [1m0[22m.  (AT&T [4meqn[24m used identifiers starting  with  the
     numeral  [1m1[22m.)  A document to be preprocessed with GNU [4meqn[24m should not use any
     such identifiers.

[1mOptions[0m
     [1m--help [22mdisplays a usage message, while [1m-v [22mand [1m--version [22mshow version infor‐
     mation; all exit afterward.

     [1m-C      [22mRecognize [1m.EQ [22mand [1m.EN [22meven when followed by a character other  than
             space or newline.

     [1m-d [4m[22mxy[24m   Specify delimiters [4mx[24m for left and [4my[24m for right ends of equations not
             bracketed  by  [1m.EQ[22m/[1m.EN[22m.   [4mx[24m and [4my[24m need not be distinct.  Any “[1mdelim[0m
             [4mxy[24m” statements in the source file override this option.

     [1m-f [4m[22mF[24m    is equivalent to “[1mgifont [4m[22mF[24m”.

     [1m-m [4m[22mn[24m    is equivalent to “[1mset minimum_size [4m[22mn[24m”.

     [1m-M [4m[22mdir[24m  Search [4mdir[24m for [4meqnrc[24m before those listed in  section  “Description”
             above.

     [1m-N      [22mProhibit newlines within delimiters, allowing [4meqn[24m to recover better
             from missing closing delimiters.

     [1m-p [4m[22mn[24m    Set  sub‐  and  superscripts  [4mn[24m points smaller than the surrounding
             text.  This option is deprecated.  [4meqn[24m normally sets sub‐  and  su‐
             perscripts at 70% of the type size of the surrounding text.

     [1m-r      [22mReduce the type size of super‐ and subscripts at most once relative
             to the base type size.

     [1m-R      [22mDon’t load [4meqnrc[24m.

     [1m-s [4m[22mn[24m    is equivalent to “[1mgsize [4m[22mn[24m”.  This option is deprecated.

     [1m-T [4m[22mdev[24m  Prepare output for the device [4mdev[24m.  This option defines a macro [4mdev[0m
             with the value [1m1[22m; [4meqnrc[24m thereby provides definitions appropriate to
             the  device.   However,  if [4mdev[24m is “[1mMathML[22m”, [4meqn[24m produces output in
             that language rather than [4mroff[24m, and does not load [4meqnrc[24m.   The  de‐
             fault device is [1mps[22m.

[1mExit status[0m
     [4meqn[24m  exits  with  status [1m0 [22mon successful operation, status [1m2 [22mif the program
     cannot interpret its command‐line arguments, and status [1m1 [22mif it  encounters
     an error during operation.

[1mFiles[0m
     [4m/usr/share/groff/1.24.1/tmac/eqnrc[0m
            initializes  the preprocessor for [4mtroff[24m output.  Any valid [4meqn[24m input
            is accepted.

[1mMathML output limitations[0m
     MathML’s design assumes that it cannot know the exact physical characteris‐
     tics of the media and devices on which it will be rendered.   It  does  not
     support control of motions and sizes to the same degree [4mtroff[24m does.

     •  GNU  [4meqn[24m’s rendering parameters (see section “Customization” above) have
        no effect on generated MathML.

     •  The [1mspecial[22m, [1mup[22m, [1mdown[22m, [1mfwd[22m, and [1mback [22mprimitives cannot  be  implemented,
        and yield a MathML “<merror>” message instead.

     •  The [1mvcenter [22mprimitive is silently ignored, as centering on the math axis
        is the MathML default.

     •  Characters  that [4meqn[24m sets extra large in [4mtroff[24m output——notably the inte‐
        gral sign——may appear too small and need to have their “<mstyle>”  wrap‐
        pers adjusted by hand.

     As  when  producing  [4mtroff[24m output, [4meqn[24m generates MathML that leaves the [1m.EQ[0m
     and [1m.EN [22mtokens in place, but emits nothing corresponding  to  [1mdelim  [22mdelim‐
     iters.   They can, however, be recognized as character sequences that begin
     with “<math>”, end with “</math>”, and do not cross line boundaries.

[1mCaveats[0m
     Tokens must be double‐quoted in [4meqn[24m input if they are not to be  recognized
     as  names  of  macros  or  primitives,  or if they are to be interpreted by
     [4mtroff[24m.  In particular, short ones, like “[1mpi[22m” and  “[1mPI[22m”,  can  collide  with
     [4mtroff[24m  identifiers.  For instance, the [4meqn[24m command “[1mgifont PI[22m” does not se‐
     lect the ]8;;man:gropdf(1)\[4mgropdf[24m(1)]8;;\ or ]8;;man:grops(1)\[4mgrops[24m(1)]8;;\ device’s Palatino italic font as the  global
     italic face; you must use “[1mgifont "PI"[22m” instead.

     Delimited  equations  are  set at the type size current at the beginning of
     the input line, not necessarily that immediately preceding the opening  de‐
     limiter.

     Unlike  TeX, [4meqn[24m does not inherently distinguish displayed and inline equa‐
     tion styles; see the [1msmallover [22mprimitive above.   However,  macro  packages
     frequently  define  [1mEQ  [22mand [1mEN [22mmacros such that the equation within is dis‐
     played.  These macros may accept arguments permitting the  equation  to  be
     labeled or captioned; see the package’s documentation.

[1mBugs[0m
     [4meqn[24m  abuses  terminology——its “equations” can be inequalities, bare expres‐
     sions, or unintelligible gibberish.  But there’s no changing it now.

     When producing terminal output, GNU [4meqn[24m renders lowercase Greek letters  in
     roman instead of italic style.

     When  producing  MathML  output,  the  [1mmark [22mand [1mlineup [22mfeatures don’t work.
     These could, in theory, be implemented with “<maligngroup>” elements.

     When producing MathML output, each digit of a numeric literal gets a  sepa‐
     rate  “<mn></mn>”  pair,  and  decimal  points are tagged with “<mo></mo>”.
     This is allowed by the specification, but inefficient.

[1mExamples[0m
     We first illustrate [4meqn[24m usage with a trigonometric identity.

            .EQ
            sin ( alpha + beta ) = sin alpha cos beta + cos alpha sin beta
            .EN

     It can be convenient to set up delimiters if mathematical content will  ap‐
     pear frequently in running text.

            .EQ
            delim $$
            .EN
            Having cached a table of logarithms,
            the property $ln ( x y ) = ln x + ln y$ sped calculations.

     The  quadratic  formula  affords an opportunity to use fractions, radicals,
     and the full space token [1m~[22m.

            .EQ
            x = { - b ~ \[+-] ~ sqrt { b sup 2 - 4 a c } } over { 2 a }
            .EN

     Alternatively, we could define the plus‐minus sign as  a  binary  operator.
     Automatic  spacing puts 0.06 em less space on either side of the plus‐minus
     than  ~  does,  this  being  the  difference  between  the  widths  of  the
     [1mmedium_space [22mparameter used by binary operators and that of the full space.
     Independently, we can define a macro “frac” for setting fractions.

            .EQ
            chartype "binary" \[+-]
            define frac ! { $1 } over { $2 } !
            x = frac(- b \[+-] sqrt { b sup 2 - 4 a c }, 2 a)
            .EN

[1mSee also[0m
     “Typesetting   Mathematics——User’s   Guide”  (2nd  edition),  by  Brian  W.
     Kernighan and Lorinda L. Cherry, 1978,  AT&T  Bell  Laboratories  Computing
     Science Technical Report No. 17.

     [4mThe[24m [4mTeXbook[24m, by Donald E. Knuth, 1984, Addison‐Wesley Professional.  Appen‐
     dix  G  discusses many of the parameters from section “Customization” above
     in greater detail.

     ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\ documents a variety of  special  character  escape  sequences
     useful  in  mathematical  typesetting.   See subsections “Logical symbols”,
     “Mathematical symbols”, and “Greek glyphs” in particular.

     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\, ]8;;man:pic(1)\[4mpic[24m(1)]8;;\, ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\

groff 1.24.1                       2026‐03‐20                             [4meqn[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4meqn2graph[24m(1)                 General Commands Manual                [4meqn2graph[24m(1)

[1mName[0m
     eqn2graph - convert an [4meqn[24m equation into a cropped image

[1mSynopsis[0m
     [1meqn2graph [22m[[1m-format [4m[22moutput‐format[24m] [[4mconvert‐argument[24m ...]

     [1meqn2graph --help[0m

     [1meqn2graph -v[0m
     [1meqn2graph --version[0m

[1mDescription[0m
     [4meqn2graph[24m reads a one‐line ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\ equation  from  the  standard  input  and
     writes an image file, by default in Portable Network Graphics (PNG) format,
     to the standard output.

     The  input  EQN  code should [4mnot[24m be preceded by the [1m.EQ [22mmacro that normally
     precedes it within ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ macros; nor do you need to have dollar‐sign  or
     other delimiters around the equation.

     Arguments  not  recognized  by  [4meqn2graph[24m  are passed to the ImageMagick or
     GraphicsMagick program ]8;;man:convert(1)\[4mconvert[24m(1)]8;;\.  By specifying these, you can give  your
     image  a  border,  set  the  image’s pixel density, or perform other useful
     transformations.

     The output image is clipped using [4mconvert[24m’s [1m-trim [22moption  to  the  smallest
     possible bounding box that contains all the black pixels.

[1mOptions[0m
     [1m--help [22mdisplays a usage message, while [1m-v [22mand [1m--version [22mshow version infor‐
     mation; all exit afterward.

     [1m-format [4m[22moutput‐format[0m
            Write  the  image  in  [4moutput‐format[24m,  which  must  be understood by
            [4mconvert[24m; the default is PNG.

[1mEnvironment[0m
     [4mGROFF_TMPDIR[0m
     [4mTMPDIR[0m
     [4mTMP[0m
     [4mTEMP[24m   These environment variables are searched in the order shown  to  de‐
            termine  the  directory  where  temporary files will be created.  If
            none are set, [4m/tmp[24m is used.

[1mAuthors[0m
     [4meqn2graph[24m  was  written  by  ]8;;mailto:esr@thyrsus.com\Eric  S.  Raymond]8;;\,  based  on  a  recipe   for
     ]8;;man:pic2graph(1)\[4mpic2graph[24m(1)]8;;\, by W. Richard Stevens.

[1mSee also[0m
     ]8;;man:pic2graph(1)\[4mpic2graph[24m(1)]8;;\, ]8;;man:grap2graph(1)\[4mgrap2graph[24m(1)]8;;\, ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\, ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, ]8;;man:convert(1)\[4mconvert[24m(1)]8;;\

groff 1.24.1                       2026‐03‐20                       [4meqn2graph[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mgdiffmk[24m(1)                   General Commands Manual                  [4mgdiffmk[24m(1)

[1mName[0m
     gdiffmk - mark differences between [4mgroff[24m/[4mnroff[24m/[4mtroff[24m files

[1mSynopsis[0m
     [1mgdiffmk [22m[[1m-a [4m[22madd‐mark[24m] [[1m-c [4m[22mchange‐mark[24m] [[1m-d [4m[22mdelete‐mark[24m] [[1m-x [4m[22mdiff‐command[24m]
             [[1m-D [22m[[1m-B[22m] [[1m-M [4m[22mmark1[24m [4mmark2[24m]] [[1m--[22m] [4mfile1[24m [4mfile2[24m [[4moutput‐file[24m]

     [1mgdiffmk --help[0m

     [1mgdiffmk --version[0m

[1mDescription[0m
     [4mgdiffmk[24m  compares  two  ]8;;man:roff(7)\[4mroff[24m(7)]8;;\  documents, [4mfile1[24m and [4mfile2[24m, and writes an‐
     other, derived from both, to the standard output stream  (or  [4moutput‐file[24m),
     adding margin character ([1mmc[22m) requests at places in the output where the in‐
     put  documents differ.  [4mgdiffmk[24m does not interpret the source documents; it
     treats [4mroff[24m comments and nilpotent changes  to  formatting  as  meaningful.
     For  example,  it does not know that [1m\h'3m'[22m, [1m\h'(1 * 3m)'[22m, and [1m\h'3m+0' [22mall
     mean the same thing.  If the [4mfile1[24m or [4mfile2[24m argument is “[1m-[22m”, [4mgdiffmk[24m  reads
     the  standard  input  stream  for  that  input.   If  the [4moutput[24m operand is
     present, [4mgdiffmk[24m writes output to a file of that name.  If it is “[1m-[22m” or ab‐
     sent, [4mgdiffmk[24m writes output to the standard output stream.  “[1m-[22m”  cannot  be
     both an input and output operand.

[1mOptions[0m
     [1m--help  [22mdisplays  a  usage message and [1m--version [22mshows version information;
     both exit afterward.

     [1m-a [4m[22madd‐mark[0m
            Annotate material absent from [4mfile1[24m but present in [4mfile2[24m  with  [4madd‐[0m
            [4mmark[24m (default: “[1m+[22m”).

     [1m-B     [22mSuppress  [1mbr [22mrequests normally inserted by [1m-D [22moption.  Use with cau‐
            tion; such requests are the only way to guarantee that deletions and
            small changes are marked.

     [1m-c [4m[22mchange‐mark[0m
            Annotate material differing between [4mfile1[24m and [4mfile2[24m with [4mchange‐mark[0m
            (default: “[1m|[22m”).

     [1m-d [4m[22mdelete‐mark[0m
            Annotate material present  in  [4mfile1[24m  but  absent  from  [4mfile2[24m  with
            [4mdelete‐mark[24m (default: “[1m*[22m”).

     [1m-D     [22mMark changed and deleted material with surrounding delimiters.

     [1m-M [4m[22mmark1[24m [4mmark2[0m
            Use  [4mmark1[24m  (default:  “[1m[[[22m”) and [4mmark2[24m (default: “[1m]][22m”) as delimiters
            when using the [1m-D [22moption.

     [1m-x [4m[22mdiff‐command[0m
            Use the [4mdiff‐command[24m program to perform the comparison of [4mfile1[24m  and
            [4mfile2[24m.   [4mdiff‐command[24m  (default:  [1mdiff[22m) must accept GNU ]8;;man:diff(1)\[4mdiff[24m(1)]8;;\’s [1m-D[0m
            extension option.

     [1m--     [22mTreat all subsequent arguments as file names,  even  if  they  begin
            with “[1m-[22m”.

[1mExit status[0m
     [4mgdiffmk[24m exits with status [1m0 [22mif the input files are the same; [1m1 [22mif they dif‐
     fer;  [1m2  [22mupon a usage error; [1m3 [22mif the system’s ]8;;man:diff(1)\[4mdiff[24m(1)]8;;\ or ]8;;man:sh(1)\[4msh[24m(1)]8;;\ commands do
     not support features [4mgdiffmk[24m requires; and [1m4 [22mif the [4moutput[24m  argument  is  a
     duplicate of [4mfile1[24m or [4mfile2[24m.

[1mCaveats[0m
     The  output  is  not necessarily compatible with all macro packages or pre‐
     processors.  A reliable workaround is to run [4mgdiffmk[24m on the output  of  the
     final preprocessor instead of the input source.

     [4mgdiffmk[24m  relies on the [1m-D [22moption of GNU [4mdiff[24m to make a merged “#ifdef” out‐
     put format.  Busybox [4mdiff[24m is  known  to  not  support  it.   Also  see  the
     [1m-x [4m[22mdiff‐command[24m option.

[1mAuthors[0m
     [4mgdiffmk[24m  was written by ]8;;mailto:MBianchi@Foveal.com\Mike Bianchi]8;;\, now retired.  It is maintained by the
     [4mgroff[24m developers.

[1mSee also[0m
     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, ]8;;man:nroff(1)\[4mnroff[24m(1)]8;;\, ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\, ]8;;man:roff(7)\[4mroff[24m(7)]8;;\, ]8;;man:diff(1)\[4mdiff[24m(1)]8;;\

groff 1.24.1                       2026‐03‐20                         [4mgdiffmk[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mglilypond[24m(1)                 General Commands Manual                [4mglilypond[24m(1)

[1mName[0m
     glilypond - embed LilyPond musical notation in [4mgroff[24m documents

[1mSynopsis[0m
     [1mglilypond [22m[[1m-k[22m] [{[1m--ly2eps[22m|[1m--pdf2eps[22m}] [[1m-e [4m[22mdirectory[24m] [[1m-o [4m[22moutput‐file[24m] [[1m-p[0m
               [4mfilename‐prefix[24m] [[1m-t [4m[22mtdir[24m] [{[1m-v[22m|[1m-V[22m}] [[1m--[22m] [[4mfile[24m ...]
     [1mglilypond [22m[{[1m--ly2eps[22m|[1m--pdf2eps[22m}] [[1m--eps_dir [4m[22mdirectory[24m] [[1m--keep_all[22m]
               [[1m--output [4m[22moutput‐file[24m] [[1m--prefix [4m[22mfilename‐prefix[24m] [[1m--temp_dir[0m
               [4mtdir[24m] [[1m--verbose[22m] [[1m--[22m] [[4mfile[24m ...]

     [1mglilypond -?[0m
     [1mglilypond -h[0m
     [1mglilypond --help[0m
     [1mglilypond --usage[0m

     [1mglilypond -l[0m
     [1mglilypond --license[0m

     [1mglilypond --version[0m

[1mDescription[0m
     [4mglilypond[24m is a ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\ preprocessor that enables the embedding of LilyPond
     music scores in [4mgroff[24m documents.  If no operands are given, or if  [4mfile[24m  is
     “[1m-[22m”,  [4mglilypond[24m  reads  the  standard input stream.  A double‐dash argument
     (“[1m--[22m”) causes all subsequent arguments to be interpreted as [4mfile[24m  operands,
     even if their names start with a dash.

     [4mglilypond[24m requires the [4mFile::HomeDir[24m Perl module, available via ]8;;https://www.cpan.org/\CPAN]8;;\.

[1mUsage[0m
     At  present,  [4mglilypond[24m  works  with the [4mgroff[24m [1mps[22m, [1mdvi[22m, [1mhtml[22m, and [1mxhtml [22mde‐
     vices.  The [1mlbp [22mand [1mlj4 [22mdevices are untested.  Unfortunately, the  [1mpdf  [22mde‐
     vice does not yet work.

[1mOption overview[0m
     [1m-?[22m|[1m-h[22m|[1m--help[22m|[1m--usage[0m
            Display usage information and exit.

     [1m--version[0m
            Display version information and exit.

     [1m-l[22m|[1m--license[0m
            Display copyright license information and exit.

   [1mOptions for building EPS files[0m
     [1m--ly2eps[0m
            Direct  ]8;;man:lilypond(1)\[4mlilypond[24m(1)]8;;\  to  create Encapsulated PostScript (EPS) files.
            This is the default.

     [1m--pdf2eps[0m
            The program [4mglilypond[24m generates a PDF file using [4mlilypond[24m.  Then the
            EPS file is generated by [4mpdf2ps[24m and [4mps2eps[24m.

   [1mDirectories and files[0m
     [1m-e[22m|[1m--eps_dir [4m[22mdirectory_name[0m
            Normally all [4mEPS[24m files are sent to the  temporary  directory.   With
            this  option, you can generate your own directory, in which all use‐
            ful [4mEPS[24m files are send.  So at last, the temporary directory can  be
            removed.

     [1m-p[22m|[1m--prefix [4m[22mbegin_of_name[0m
            Normally  all  temporary  files  get names that start with the [1mly[4m[22m...[0m
            prefix.  With this option, you can freely change this prefix.

     [1m-k[22m|[1m--keep_all[0m
            Normally all temporary files without  the  [4meps[24m  files  are  deleted.
            With this option, all generated files either by the [4mlilypond[24m program
            or other format transposers are kept.

     [1m-t[22m|[1m--temp_dir [4m[22mdir[0m
            With this option, you call a directory that is the base for the tem‐
            porary directory.  This directory name is used as is without any ex‐
            tensions.   If  this directory does not exist it is be created.  The
            temporary directory is created by  Perl’s  security  operations  di‐
            rectly  under this directory.  In this temporary directory, the tem‐
            porary files are stored.

   [1mOutput[0m
     [1m-o[22m|[1m--output [4m[22mfile_name[0m
            Normally all [4mgroff[24m output of this program is sent to  [1mSTDOUT[22m.   With
            this  option,  that  can  be changed, such that the output is stored
            into a file named in the option argument [4mfile_name[24m.

     [1m-v[22m|[1m-V[22m|[1m--verbose[0m
            A lot more of information is sent to STDERR.

   [1mShort option collections[0m
     The argument handling of options

     [4mShort[24m [4moptions[24m are arguments that start with a single dash [1m-[22m.  Such an argu‐
     ment can consist of arbitrary many options without  option  argument,  com‐
     posed as a collection of option characters following the single dash.

     Such  a collection can be terminated by an option character that expects an
     option argument.  If this option character is not the last character of the
     argument, the following final part of the argument is the option  argument.
     If  it is the last character of the argument, the next argument is taken as
     the option argument.

     This is the standard for [4mPOSIX[24m and [4mGNU[24m option management.

     For example,

     [1m-kVe [4m[22msome_dir[0m
            is a collection of the short options [1m-k [22mand [1m-V [22mwithout option  argu‐
            ment,  followed  by the short option [1m-e [22mwith option argument that is
            the following part of the argument [4msome_dir[24m.  So this argument could
            also be written as several arguments [1m-k -V -e [4m[22msome_dir[24m.

   [1mHandling of long options[0m
     Arguments that start with a double dash [1m-- [22mare so‐called [4mlong[24m [4moptions[24m  [4mR[24m  [4m.[0m
     Each double dash argument can only have a single long option.

     [4mLong[24m  [4moptions[24m  have or have not an option argument.  An option argument can
     be the next argument or can be appended with an equal sign [1m=  [22mto  the  same
     argument as the long option.

     [1m--help[0m
            is a long option without an option argument.

     [1m--eps_dir [4m[22msome_dir[0m
     [1m--eps_dir=[4m[22msome_dir[0m
            is the long option [1m--eps_dir [22mwith the option argument [4msome_dir[24m.

     Moreover  the program allows abbreviations of long options, as much as pos‐
     sible.

     The [4mlong[24m [4moption[24m [1m--keep_all [22mcan be abbreviated from [1m--keep_al [22mup to [1m--k  [22mbe‐
     cause  the program does not have another [4mlong[24m [4moption[24m whose name starts with
     the character [1mk[22m.

     On the other hand, the option [1m--version [22mcannot be abbreviated further  than
     [1m--vers [22mbecause there is also the [4mlong[24m [4moption[24m [1m--verbose [22mthat can be abbrevi‐
     ated up to [1m--verb[22m.

     An  option  argument  can  also  be  appended  to  an  abbreviation.  So is
     [1m--e=[4m[22msome_dir[24m the same as [1m--eps_dir [4m[22msome_dir[24m.

     Moreover the program allows an arbitrary usage of upper and lower  case  in
     the option name.  This is [4mPerl[24m style.

     For  example,  the  [4mlong[24m  [4moption[24m  [1m--keep_all  [22mcan  as  well  be  written as
     [1m--Keep_All [22mor even as an abbreviation like [1m--KeE[22m.

[1mLilyPond regions in [4mroff[24m input[0m
   [1mIntegrated LilyPond code[0m
     A [4mlilypond[24m part within a structure written in the  [4mgroff[24m  language  is  the
     whole part between the marks
            [1m.lilypond start[0m
     and
            [1m.lilypond end[0m
     A [4mgroff[24m input can have several of these [4mlilypond[24m parts.

     When  processing such a [4mlilypond[24m part between [1m.lilypond start [22mand [1m.lilypond[0m
     [1mend [22mwe say that the [1mglilypond [22mprogram is in [4mlilypond[24m [4mmode[24m.

     These [4mlilypond[24m parts are sent into temporary [4mlilypond[24m files with  the  file
     name extension [1m.ly[22m.  These files are transformed later on into [4mEPS[24m files.

   [1mInclusion of [4m.ly[24m files[0m
     An additional command line for file inclusion of [4mlilypond[24m files is given by
     [1m.lilypond include [4m[22mfile_name[0m
     in  [4mgroff[24m  input.  For each such [4minclude[24m command, one file of [4mlilypond[24m code
     can be included into the [4mgroff[24m code.  Arbitrarily many  of  these  commands
     can be included in the [4mgroff[24m input.

     These include commands can only be used outside the [4mlilypond[24m parts.  Within
     the  [4mlilypond[24m  [4mmode[24m,  this inclusion is not possible.  So [1m.lilypond include[0m
     may not be used in [4mlilypond[24m [4mmode[24m, i.e. between [1m.lilypond start  [22mand  [1m.lily‐[0m
     [1mpond end[22m.  These included [4mly[24m‐files are also transformed into [4mEPS[24m files.

[1mGenerated files[0m
     By  the  transformation process of [4mlilypond[24m parts into [4mEPS[24m files, there are
     many files generated.  By default, these files are  regarded  as  temporary
     files  and  as  such  stored in a temporary directory.  This process can be
     changed by command‐line options.

   [1mCommand‐line options for directories[0m
     The temporary directory for this program is either created automatically or
     can be named by the option [1m-t[22m|[1m--temp_dir [4m[22mdir[24m.

     Moreover, the [4mEPS[24m files that are later on referred by [1m.PSPIC [22mcommand in the
     final [4mgroff[24m output can be stored in a different directory that can  be  set
     by  the command‐line option [1m-e[22m|[1m--eps_dir [4m[22mdirectory_name[24m.  With this option,
     the temporary directory can be removed completely at the end  of  the  pro‐
     gram.

     The  beginning  of  the names of the temporary files can be set by the com‐
     mand‐line options [1m-p [22mor [1m--prefix[22m.

     All of the temporary files except the [4mEPS[24m files are deleted finally.   This
     can  be  changed  by  setting  the command‐line options [1m-k [22mor [1m--keep_files[22m.
     With this, all temporary files and directories are kept, not deleted.

     These [4mEPS[24m files are stored in a temporary or [4mEPS[24m directory.  But they  can‐
     not  be  deleted  by the transformation process because they are needed for
     the display which can take a long time.

[1mTransformation processes for generating EPS files[0m
   [1mMode pdf2eps[0m
     In this mode, the  current  default,  [1m.ly  [22mfiles  are  transformed  by  the
     ]8;;man:lilypond(1)\[4mlilypond[24m(1)]8;;\ program into [4mPDF[24m files, using
            [1mlilypond --pdf --output=[4m[22mfile‐name[0m
     for  each  [1m.ly  [22mfile.  The [4mfile‐name[24m must be provided without the extension
     [1m.pdf[22m.  By this process, a file [4mfile‐name[24m[1m.pdf [22mis generated.

     The next step is to transform these [4mPDF[24m files into a [4mPS[24m file.  This is done
     by the ]8;;man:pdf2ps(1)\[4mpdf2ps[24m(1)]8;;\ program using
            $ [1mpdf2ps [4m[22mfile‐name[24m[1m.pdf [4m[22mfile‐name[24m[1m.pds[0m
     The next step creates an [4mEPS[24m file from the [4mPS[24m file.  This is  done  by  the
     ]8;;man:ps2eps(1)\[4mps2eps[24m(1)]8;;\ program using
            $ [1mps2eps [4m[22mfile‐name[24m[1m.ps[0m

     By  that,  a  file  [4mfile‐name[24m[1m.eps  [22mis created for each [4mlilypond[24m part in the
     [4mgroff[24m file or standard input.

     The last step to be done is replacing all [4mlilypond[24m parts by the [4mgroff[24m  com‐
     mand
            [1m.PSPIC [4m[22mfile‐name[24m[1m.eps[0m

   [1mMode ly2eps[0m
     In  earlier  time, this mode was the default.  But now it does not work any
     more, so accept the new default [4mpdf2eps[24m.  For testing, this mode  can  also
     be chosen by the [4mglilypond[24m option [1m--ly2eps[22m.

     In  this  mode,  the [1m.ly [22mfiles are transformed by the [4mlilypond[24m program into
     many files of different formats, including [4meps[24m files, using
            $ [1mlilypond --ps -dbackend=eps -dgs-load-fonts --output=[4m[22mfile‐name[0m
     for each [1m.ly [22mfile.  The output [4mfile-name[24m must be provided without an exten‐
     sion, its directory is temporary.

     There are many [4mEPS[24m files created.  One having the complete  transformed  [1mly[0m
     file, named [4mfile-name[24m[1m.eps[22m.

     Moreover there are [4mEPS[24m files for each page, named [4mfile-name[24m[1m-[4m[22mdigit[24m[1m.eps[22m.

     The  last step to be done is replacing all [4mlilypond[24m parts by the collection
     of the corresponding [4mEPS[24m page files.  This is done by [4mgroff[24m commands
     [1m.PSPIC [4m[22mfile‐name[24m[1m-[4m[22mdigit[24m[1m.eps[0m

[1mGenerated [4mgroff[24m output[0m
     The new ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\ structure generated by [4mglilypond[24m is either

     1)     sent to standard output and can there be saved into a file or  piped
            into ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ or

     2)     stored into a file by given the option [1m-o  | [22m--output [4mfile_name[0m

[1mAuthors[0m
     [4mglilypond[24m was written by ]8;;mailto:groff-bernd.warken-72@web.de\Bernd Warken]8;;\.

[1mSee also[0m
     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\
            describes  the  usage  of the [4mgroff[24m command and contains pointers to
            further documentation of the [4mgroff[24m system.

     ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\
            describes the [1m.PSPIC [22mrequest.

     ]8;;man:lilypond(1)\[4mlilypond[24m(1)]8;;\
            briefly describes the [4mlilypond[24m command and contains pointers to fur‐
            ther documentation.

     ]8;;man:pdf2ps(1)\[4mpdf2ps[24m(1)]8;;\
            transforms a [4mPDF[24m file into a [4mPostScript[24m format.

     ]8;;man:ps2eps(1)\[4mps2eps[24m(1)]8;;\
            transforms a [4mPS[24m file into an [4mEPS[24m format.

groff 1.24.1                       2026‐03‐20                       [4mglilypond[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mgperl[24m(1)                     General Commands Manual                    [4mgperl[24m(1)

[1mName[0m
     gperl - execute Perl commands in [4mgroff[24m documents

[1mSynopsis[0m
     [1mgperl [22m[[4mfile[24m ...]

     [1mgperl -h[0m
     [1mgperl --help[0m

     [1mgperl -v[0m
     [1mgperl --version[0m

[1mDescription[0m
     This is a preprocessor for ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\.  It allows the use of ]8;;man:perl(7)\[4mperl[24m(7)]8;;\ code  in
     ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\  files.   The result of a [4mPerl[24m [4mpart[24m can be stored in groff [4mstrings[0m
     or [4mnumerical[24m [4mregisters[24m based on the arguments at a final  line  of  a  [4mPerl[0m
     [4mpart[24m.

     If no operands are given, or if [4mfile[24m is “[1m-[22m”, [4mgperl[24m reads the standard input
     stream.   A  double‐dash argument (“[1m--[22m”) causes all subsequent arguments to
     be interpreted as [4mfile[24m operands, even if their names start with a dash.  [1m-h[0m
     and [1m--help [22mdisplay a usage message, whereas [1m-v [22mand [1m--version  [22mdisplay  ver‐
     sion information; all exit afterward.

[1mPerl regions[0m
     [4mPerl[24m parts in [4mgroff[24m [4mfiles[24m are enclosed by two [1m.Perl [22mrequests with different
     arguments, a [4mstarting[24m and an [4mending[24m command.

   [1mStarting Perl mode[0m
     The  starting [4mPerl[24m [4mrequest[24m can either be without arguments, or by a request
     that has the term [1mstart [22mas its only argument.

            •      [1m.Perl[0m

            •      [1m.Perl start[0m

   [1mEnding Perl mode without storage[0m
     A [1m.Perl [22mcommand line with an argument different from [1mstart [22mfinishes a  run‐
     ning  [4mPerl[24m  [4mpart[24m.   Of  course,  it would be reasonable to add the argument
     [1mstop[22m; that’s possible, but not necessary.

            •      [1m.Perl stop[0m

            •      [1m.Perl [4m[22mother_than_start[0m
     The argument [4mother_than_start[24m can additionally be used as  a  [4mgroff[24m  string
     variable name for storage —— see next section.

   [1mEnding Perl mode with storage[0m
     A  useful  feature  of  [4mgperl[24m is to store one or more results from the [4mPerl[0m
     [4mmode[24m.

     The output of a [4mPerl[24m [4mpart[24m can be got with backticks [1m`...`[22m.

     This program collects all printing to STDOUT (normal  standard  output)  by
     the  Perl  [1mprint  [22mprogram.   This  pseudo‐printing  output can have several
     lines, due to printed line breaks with [1m\n[22m.  By that, the output of  a  Perl
     run  should  be stored into a Perl array, with a single line for each array
     member.

     This Perl array output can be stored by [4mgperl[24m in either

     [4mgroff[24m [4mstrings[0m
            by creating a groff command [1m.ds[0m

     [4mgroff[24m [4mregister[0m
            by creating a groff command [1m.rn[0m

     The storage modes can be determined by arguments of a final stopping  [1m.Perl[0m
     command.   Each  argument  [1m.ds  [22mchanges  the mode into [4mgroff[24m [4mstring[24m and [1m.nr[0m
     changes the mode into [4mgroff[24m [4mregister[24m for all following output parts.

     By default, all output is saved as strings, so [1m.ds [22mis not really needed be‐
     fore the first [1m.nr [22mcommand.  That suits to ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\, because  every  output
     can be saved as [4mgroff[24m string, but the registers can be very restrictive.

     In [4mstring[24m [4mmode[24m, [4mgperl[24m generates a [4mgroff[24m [4mstring[24m storage line
            [1m.ds [4m[22mvar_name[24m [4mcontent[0m
     In [4mregister[24m [4mmode[24m the following groff command is generated
            [1m.nr [4m[22mvar_name[24m [4mcontent[0m

     We present argument collections in the following.  You can add as first ar‐
     gument for all [1mstop[22m.  We omit this additional element.

     [1m.Perl .ds [4m[22mvar_name[0m
            This  will  store 1 output line into the groff string named [4mvar_name[0m
            by the automatically created command
                   [1m.ds [4m[22mvar_name[24m [4moutput[0m

     [1m.Perl [4m[22mvar_name[0m
            If [4mvar_name[24m is different from [1mstart [22mthis is equivalent to the former
            command, because the string mode is string with  [1m.ds  [22mcommand.   de‐
            fault.

     [1m.Perl [4m[22mvar_name1[24m [4mvar_name2[0m
            This will store 2 output lines into groff string names [4mvar_name1[24m and
            [4mvar_name2[24m,  because the default mode [1m.ds [22mis active, such that no [1m.ds[0m
            argument is needed.  Of course, this is equivalent to
                   [1m.Perl .ds [4m[22mvar_name1[24m [4mvar_name2[0m
            and
                   [1m.Perl .ds [4m[22mvar_name1[24m [1m.ds [4m[22mvar_name2[0m

     [1m.Perl .nr [4m[22mvar_name1[24m [4mvarname2[0m
            stores both variables as register variables.  [4mgperl[24m generates
            [1m.nr [4m[22mvar_name1[24m [4moutput_line1[0m
            [1m.nr [4m[22mvar_name2[24m [4moutput_line2[0m

     [1m.Perl .nr [4m[22mvar_name1[24m [1m.ds [4m[22mvar_name2[0m
            stores the 1st argument as [4mregister[24m and the second as [4mstring[24m by
            [1m.nr [4m[22mvar_name1[24m [4moutput_line1[0m
            [1m.ds [4m[22mvar_name2[24m [4moutput_line2[0m

[1mExample[0m
     A possible [4mPerl[24m [4mpart[24m in a [4mroff[24m [4mfile[24m could look like that:
            before
            .Perl start
            my $result = 'some data';
            print $result;
            .Perl stop .ds string_var
            after

     This stores the result [1m”some data” [22minto the [4mroff[24m [4mstring[24m called  [1mstring_var[22m,
     such that the following line is printed:
            .ds string_var some data
     by [4mgperl[24m as food for the coming [4mgroff[24m run.

     A [4mPerl[24m [4mpart[24m with several outputs is:
            .Perl start
            print ”first\n”;
            print ”second line\n”;
            print ”3\n”;
            .Perl var1 var2 .nr var3
     This  stores 3 printed lines into 3 [4mgroff[24m strings.  [1mvar1[22m,[1mvar2[22m,[1mvar3[22m.  So the
     following [4mgroff[24m command lines are created:
            .ds var1 first
            .ds var2 second line
            .nr var3 3

[1mAuthors[0m
     [4mgperl[24m was written by ]8;;mailto:groff-bernd.warken-72@web.de\Bernd Warken]8;;\.

[1mSee also[0m
     Man pages related to [4mgroff[24m are ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\, and ]8;;man:grog(1)\[4mgrog[24m(1)]8;;\.

     Documents related to [4mPerl[24m are ]8;;man:perl(1)\[4mperl[24m(1)]8;;\, ]8;;man:perl(7)\[4mperl[24m(7)]8;;\.

groff 1.24.1                       2026‐03‐20                           [4mgperl[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mgpinyin[24m(1)                   General Commands Manual                  [4mgpinyin[24m(1)

[1mName[0m
     gpinyin - use Hanyu Pinyin Chinese in [4mgroff[24m documents

[1mSynopsis[0m
     [1mgpinyin [22m[[4mfile[24m ...]

     [1mgpinyin -h[0m
     [1mgpinyin --help[0m

     [1mgpinyin -v[0m
     [1mgpinyin --version[0m

[1mDescription[0m
     [4mgpinyin[24m is a preprocessor for ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ that facilitates use of Hanyu Pinyin
     in ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\ files.  Pinyin is a method for  writing  the  Mandarin  Chinese
     language with the Latin alphabet.  Mandarin consists of more than four hun‐
     dred  base syllables, each spoken with one of five different tones.  Chang‐
     ing the tone applied to the syllable generally alters the  meaning  of  the
     word  it forms.  In Pinyin, a syllable is written in the Latin alphabet and
     a numeric tone indicator can be appended to each syllable.

     Each [4minput‐file[24m is a file name or the character “[1m-[22m” to  indicate  that  the
     standard  input  stream should be read.  As usual, the argument “[1m--[22m” can be
     used in order to force interpretation of all remaining  arguments  as  file
     names,  even  if  an  [4minput‐file[24m argument begins with a “[1m-[22m”.  [1m-h [22mand [1m--help[0m
     display a usage message, while [1m-v [22mand [1m--version [22mshow  version  information;
     all exit afterward.

   [1mPinyin sections[0m
     Pinyin  sections  in  [4mgroff[24m files are enclosed by two [1m.pinyin [22mrequests with
     different arguments.  The starting request is
            .pinyin start
     or
            .pinyin begin
     and the ending request is
            .pinyin stop
     or
            .pinyin end
     .

   [1mSyllables[0m
     In Pinyin, each syllable is represented by one to six  letters  drawn  from
     the fifty‐two upper‐ and lowercase letters of the Unicode basic Latin char‐
     acter  set,  plus  the  letter “U” with dieresis (umlaut) in both cases——in
     other words, the members of the set “[a–zA–ZüÜ]”.

     In [4mgroff[24m input, all basic Latin letters are written as themselves.  The  “u
     with  dieresis” can be written as “\[:u]” in lowercase or “\[:U]” in upper‐
     case.  Within [1m.pinyin [22msections, [4mgpinyin[24m supports the form “ue”  for  lower‐
     case and the forms “Ue” and “UE” for uppercase.

   [1mTones[0m
     Each syllable has exactly one of five [4mtones[24m.  The fifth tone is not explic‐
     itly  written  at  all, but each of the first through fourth tones is indi‐
     cated with a diacritic above a specific vowel within the syllable.

     In a [4mgpinyin[24m source file, these tones are written by adding  a  numeral  in
     the  range  0  to 5 after the syllable.  The tone numbers 1 to 4 are trans‐
     formed into accents above vowels in the output.  The tone numbers 0  and  5
     are synonymous.

     The tones are written as follows.

     Tone     Description      Diacritic   Example Input   Example Output
     ─────────────────────────────────────────────────────────────────────
     first    flat             ¯           ma1             mā
     second   rising           ´           ma2             má
     third    falling‐rising   ˇ           ma3             mǎ
     fourth   falling          `           ma4             mà
     fifth    neutral          (none)      ma0             ma
                                           ma5

     The  neutral tone number can be omitted from a word‐final syllable, but not
     otherwise.

[1mAuthors[0m
     [4mgpinyin[24m was written by ]8;;mailto:groff-bernd.warken-72@web.de\Bernd Warken]8;;\.

[1mSee also[0m
     Useful documents on the World Wide Web related to Pinyin include
         ]8;;http://www.foolsworkshop.com/ptou/index.html\[4mPinyin[24m [4mto[24m [4mUnicode[24m]8;;\,
         ]8;;http://www.mandarintools.com/\[4mOn‐line[24m [4mChinese[24m [4mTools[24m]8;;\,
         ]8;;http://www.pinyin.info/index.html\[4mPinyin.info:[24m [4ma[24m [4mguide[24m [4mto[24m [4mthe[24m [4mwriting[24m [4mof[24m [4mMandarin[24m [4mChinese[24m [4min[24m [4mromaniza‐[0m
         [4mtion[24m]8;;\,
         ]8;;http://www.pinyin.info/rules/where.html\“Where do the tone marks go?”]8;;\,
         ]8;;http://git.savannah.gnu.org/gitweb/?p=cjk.git;a=blob_plain;f=doc/pinyin.txt;hb=HEAD\[4mpinyin.txt[24m from the CJK macro package for TeX]8;;\,
     and
         ]8;;http://git.savannah.gnu.org/gitweb/?p=cjk.git;a=blob_plain;f=texinput/pinyin.sty;hb=HEAD\[4mpinyin.sty[24m from the CJK macro package for TeX]8;;\.

     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ and ]8;;man:grog(1)\[4mgrog[24m(1)]8;;\ explain how to view [4mroff[24m documents.

     ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\ and ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\ are comprehensive references covering  the  lan‐
     guage  elements  of  GNU  [4mtroff[24m and the available glyph repertoire, respec‐
     tively.

groff 1.24.1                       2026‐03‐20                         [4mgpinyin[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mgrap2graph[24m(1)                General Commands Manual               [4mgrap2graph[24m(1)

[1mName[0m
     grap2graph - convert a [4mgrap[24m diagram into a cropped image

[1mSynopsis[0m
     [1mgrap2graph [22m[[1m-unsafe[22m] [[1m-format [4m[22moutput‐format[24m] [[4mconvert‐argument[24m ...]

     [1mgrap2graph --help[0m

     [1mgrap2graph -v[0m
     [1mgrap2graph --version[0m

[1mDescription[0m
     [4mgrap2graph[24m reads a ]8;;man:grap(1)\[4mgrap[24m(1)]8;;\ program from the standard input  and  writes  an
     image  file,  by  default in Portable Network Graphics (PNG) format, to the
     standard output.

     The input GRAP code should [4mnot[24m be wrapped with the [1m.G1 [22mand [1m.G2 [22mmacros  that
     normally guard it within ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ documents.

     Arguments  not  recognized  by  [4mgrap2graph[24m are passed to the ImageMagick or
     GraphicsMagick program ]8;;man:convert(1)\[4mconvert[24m(1)]8;;\.  By specifying these, you can give  your
     image  a  border,  set  the  image’s pixel density, or perform other useful
     transformations.

     The output image is clipped using [4mconvert[24m’s [1m-trim [22moption  to  the  smallest
     possible bounding box that contains all the black pixels.

[1mOptions[0m
     [1m--help [22mdisplays a usage message, while [1m-v [22mand [1m--version [22mshow version infor‐
     mation; all exit afterward.

     [1m-format [4m[22moutput‐format[0m
            Write  the  image  in  [4moutput‐format[24m,  which  must  be understood by
            [4mconvert[24m; the default is PNG.

     [1m-unsafe[0m
            Run [4mgroff[24m in [4munsafe[24m mode, enabling the PIC command [1msh [22mto execute ar‐
            bitrary Unix shell commands.  The [4mgroff[24m default is to forbid this.

[1mEnvironment[0m
     [4mGROFF_TMPDIR[0m
     [4mTMPDIR[0m
     [4mTMP[0m
     [4mTEMP[24m   These environment variables are searched in the order shown  to  de‐
            termine  the  directory  where  temporary files will be created.  If
            none are set, [4m/tmp[24m is used.

[1mAuthors[0m
     [4mgrap2graph[24m  was  written  by  ]8;;mailto:esr@thyrsus.com\Eric  S.  Raymond]8;;\,  based  on  a  recipe  for
     ]8;;man:pic2graph(1)\[4mpic2graph[24m(1)]8;;\, by W. Richard Stevens.

[1mSee also[0m
     ]8;;man:pic2graph(1)\[4mpic2graph[24m(1)]8;;\, ]8;;man:eqn2graph(1)\[4meqn2graph[24m(1)]8;;\, ]8;;man:grap(1)\[4mgrap[24m(1)]8;;\, ]8;;man:pic(1)\[4mpic[24m(1)]8;;\, ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, ]8;;man:convert(1)\[4mconvert[24m(1)]8;;\

groff 1.24.1                       2026‐03‐20                      [4mgrap2graph[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mgrn[24m(1)                       General Commands Manual                      [4mgrn[24m(1)

[1mName[0m
     grn - embed Gremlin images in [4mgroff[24m documents

[1mSynopsis[0m
     [1mgrn [22m[[1m-C[22m] [[1m-T [4m[22mdev[24m] [[1m-M [4m[22mdir[24m] [[1m-F [4m[22mdir[24m] [[4mfile[24m ...]

     [1mgrn -?[0m
     [1mgrn --help[0m

     [1mgrn -v[0m
     [1mgrn --version[0m

[1mDescription[0m
     [4mgrn[24m  is  a  preprocessor  for including [4mgremlin[24m pictures in ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ input.
     [4mgrn[24m writes to standard output, processing only input lines between two that
     start with [1m.GS [22mand [1m.GE[22m.  Those lines must contain [4mgrn[24m commands (see below).
     These macros request a [4mgremlin[24m file; the picture in that file is  converted
     and  placed in the [4mtroff[24m input stream.  [1m.GS [22mmay be called with a [1mC[22m, [1mL[22m, or [1mR[0m
     argument to center, left‐, or right‐align the whole  [4mgremlin[24m  picture  (the
     default  is  to  center).   If  no [4mfile[24m is mentioned, the standard input is
     read.  At the end of the picture, the position on the page is the bottom of
     the [4mgremlin[24m picture.  If the [4mgrn[24m entry is ended with [1m.GF  [22minstead  of  [1m.GE[22m,
     the position is left at the top of the picture.

     Currently only the [4mme[24m macro package has support for [1m.GS[22m, [1m.GE[22m, and [1m.GF[22m.

     [4mgrn[24m  produces drawing escape sequences that use [4mgroff[24m’s color scheme exten‐
     sion ([1m\D'F [22m...[1m'[22m), and thus may not work with other [4mtroff[24ms.

   [4m[1mgrn[24m commands[0m
     Each input line between [1m.GS [22mand [1m.GE [22mmay have  one  [4mgrn[24m  command.   Commands
     consist of one or two strings separated by whitespace, the first string be‐
     ing the command and the second its operand.  Commands may be upper‐ or low‐
     ercase and abbreviated down to one character.

     Commands   that   affect  a  picture’s  environment  (those  listed  before
     “[1mdefault[22m”, see below) are only in effect for the current picture: the envi‐
     ronment is reinitialized to the defaults at the start of the next  picture.
     The commands are as follows.

     [1m1 [4m[22mN[0m
     [1m2 [4m[22mN[0m
     [1m3 [4m[22mN[0m
     [1m4 [4m[22mN[24m    Set  [4mgremlin[24m’s text size number 1 (2, 3, or 4) to [4mN[24m points.  The de‐
            fault is 12 (16, 24, and 36, respectively).

     [1mroman [4m[22mf[0m
     [1mitalics [4m[22mf[0m
     [1mbold [4m[22mf[0m
     [1mspecial [4m[22mf[0m
            Set the roman (italics, bold, or special) font  to  [4mtroff[24m’s  font  [4mf[0m
            (either  a  name or number).  The default is R (I, B, and S, respec‐
            tively).

     [1ml [4m[22mf[0m
     [1mstipple [4m[22mf[0m
            Set the stipple font to [4mtroff[24m’s stipple font  [4mf[24m  (name  or  number).
            The command [1mstipple [22mmay be abbreviated down as far as “[1mst[22m” (to avoid
            confusion with “[1mspecial[22m”).  There is [4mno[24m default for stipples (unless
            one is set by the “[1mdefault[22m” command), and it is invalid to include a
            [4mgremlin[24m picture with polygons without specifying a stipple font.

     [1mx [4m[22mN[0m
     [1mscale [4m[22mN[0m
            Magnify the picture (in addition to any default magnification) by [4mN[24m,
            a  floating‐point number larger than zero.  The command [1mscale [22mmay be
            abbreviated down to “[1msc[22m”.

     [1mnarrow [4m[22mN[0m
     [1mmedium [4m[22mN[0m
     [1mthick [4m[22mN[0m
            Set the thickness of [4mgremlin[24m’s narrow  (medium  and  thick,  respec‐
            tively)  lines  to [4mN[24m times 0.15pt (this value can be changed at com‐
            pile time).  The default is 1.0 (3.0 and 5.0,  respectively),  which
            corresponds  to  0.15pt (0.45pt and 0.75pt, respectively).  A thick‐
            ness value of zero selects the smallest  available  line  thickness.
            Negative  values  cause the line thickness to be proportional to the
            current point size.

     [1mpointscale [22m[[1moff[22m|[1mon[22m]
            Scale text to match the picture.  Gremlin text is usually printed in
            the point size specified with the commands [1m1[22m, [1m2[22m, [1m3[22m, or [1m4[22m, regardless
            of any scaling factors in  the  picture.   Setting  [1mpointscale  [22mwill
            cause the point sizes to scale with the picture (within [4mtroff[24m’s lim‐
            itations, of course).  An operand of anything but [1moff [22mwill turn text
            scaling on.

     [1mdefault[0m
            Reset  the  picture environment defaults to the settings in the cur‐
            rent picture.  This is meant to be used as a global  parameter  set‐
            ting  mechanism at the beginning of the [4mtroff[24m input, but can be used
            at any time to reset the default settings.

     [1mwidth [4m[22mN[0m
            Force the picture to be [4mN[24m inches wide.  This overrides  any  scaling
            factors present in the same picture.  “[1mwidth 0[22m” is ignored.

     [1mheight [4m[22mN[0m
            Force the picture to be [4mN[24m inches high, overriding other scaling fac‐
            tors.   If  both  [1mwidth  [22mand  [1mheight [22mare specified, the tighter con‐
            straint will determine the scale of the picture.  [1mheight  [22mand  [1mwidth[0m
            commands  are  not  saved with a “[1mdefault[22m” command.  They will, how‐
            ever, affect point size scaling if that option is set.

     [1mfile [4m[22mname[0m
            Get picture from [4mgremlin[24m file [4mname[24m located the current directory (or
            in the library directory; see the [1m-M  [22moption  above).   If  multiple
            [1mfile [22mcommands are given, the last one controls.  If [4mname[24m doesn’t ex‐
            ist,  an error message is reported and processing continues from the
            [1m.GE [22mline.

   [1mUsage with [4mgroff[0m
     Since [4mgrn[24m is a preprocessor, it has no  access  to  elements  of  formatter
     state,  such  as  indentation,  line length, type size, or register values.
     Consequently, no [4mtroff[24m input can be placed between the [1m.GS [22mand [1m.GE  [22mmacros.
     However, [4mgremlin[24m text elements are subsequently processed by [4mtroff[24m, so any‐
     thing  valid  in a single line of [4mtroff[24m input is valid in a line of [4mgremlin[0m
     text (barring the dot control character “.” at the beginning  of  a  line).
     Thus, it is possible to have equations within a [4mgremlin[24m figure by including
     in  the  [4mgremlin[24m file [4meqn[24m expressions enclosed by previously defined delim‐
     iters (e.g., “$$”).

     When using [4mgrn[24m along with  other  preprocessors,  run  ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\  before  [4mgrn[24m,
     ]8;;man:pic(1)\[4mpic[24m(1)]8;;\,  and/or  [4mideal[24m.  If ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\ is needed, run it as the last preproces‐
     sor.  ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ automatically runs preprocessors in the correct order.

     A picture is considered an entity, but that doesn’t stop [4mtroff[24m from  trying
     to  break it up if it falls off the end of a page.  Placing the picture be‐
     tween “keeps” in the [4mme[24m macros will ensure proper placement.

     [4mgrn[24m uses [4mtroff[24m’s registers [1mg1 [22mthrough [1mg9 [22mand sets registers [1mg1  [22mand  [1mg2  [22mto
     the  width and height of the [4mgremlin[24m figure (in device units) before enter‐
     ing the [1m.GS [22mmacro (this is for those who want to rewrite these macros).

   [1mGremlin file format[0m
     There exist two distinct [4mgremlin[24m file formats: the original format for  AED
     graphic  terminals,  and  the Sun or X11 version.  An extension used by the
     Sun/X11 version allowing reference points with negative coordinates is  [4mnot[0m
     compatible  with  the AED version.  As long as a [4mgremlin[24m file does not con‐
     tain negative coordinates, either format will be read correctly  by  either
     version  of  [4mgremlin[24m or [4mgrn[24m.  The other difference in Sun/X11 format is the
     use of names for picture objects (e.g., [1mPOLYGON[22m, [1mCURVE[22m) instead of numbers.
     Files representing the same picture are shown below.

                        sungremlinfile        gremlinfile
                        0 240.00 128.00       0 240.00 128.00
                        CENTCENT              2
                        240.00 128.00         240.00 128.00
                        185.00 120.00         185.00 120.00
                        240.00 120.00         240.00 120.00
                        296.00 120.00         296.00 120.00
                        *                     -1.00 -1.00
                        2 3                   2 3
                        10 A Triangle         10 A Triangle
                        POLYGON               6
                        224.00 416.00         224.00 416.00
                        96.00 160.00          96.00 160.00
                        384.00 160.00         384.00 160.00
                        *                     -1.00 -1.00
                        5 1                   5 1
                        0                     0
                        -1                    -1

     •  The  first  line  of  each  [4mgremlin[24m  file  contains  either  the  string
        “[1mgremlinfile[22m” (AED) or “[1msungremlinfile[22m” (Sun/X11).

     •  The  second  line of the file contains an orientation and [4mx[24m and [4my[24m values
        for a positioning point, separated by spaces.  The orientation, either [1m0[0m
        or [1m1[22m, is ignored by the Sun/X11 version.  [1m0 [22mmeans that [4mgremlin[24m will dis‐
        play things in horizontal format (a drawing area wider than it is  tall,
        with  a  menu across the top).  [1m1 [22mmeans that [4mgremlin[24m will display things
        in vertical format (a drawing area taller than it is wide, with  a  menu
        on the left side).  [4mx[24m and [4my[24m are floating‐point values giving a position‐
        ing  point  to  be  used  when this file is read into another file.  The
        stuff on this line really isn’t all that important; a value of  “[1m1  0.00[0m
        [1m0.00[22m” is suggested.

     •  The  rest  of  the file consists of zero or more element specifications.
        After the last element specification is a  line  containing  the  string
        “[1m-1[22m”.

     •  Lines longer than 127 characters are truncated to that length.

   [1mElement specifications[0m
     •  The  first  line of each element contains a single decimal number giving
        the type of the element (AED) or its name (Sun/X11).

                    [4mgremlin[24m File Format: Object Type Specification
               ──────────────────────────────────────────────────────────
               AED Number   Sun/X11 Name            Description
                    [1m0       BOTLEFT        [22mtext aligned to bottom left
                    [1m1       BOTRIGHT       [22mtext aligned to bottom right
                    [1m2       CENTCENT       [22mcenter object
                    [1m3       VECTOR         [22mvector
                    [1m4       ARC            [22marc
                    [1m5       CURVE          [22mcurve
                    [1m6       POLYGON        [22mpolygon
                    [1m7       BSPLINE        [22mb‐spline
                    [1m8       BEZIER         [22mBézier
                   [1m10       TOPLEFT        [22mtext aligned to top left
                   [1m11       TOPCENT        [22mtext aligned to top center
                   [1m12       TOPRIGHT       [22mtext aligned to top right
                   [1m13       CENTLEFT       [22mtext aligned to center left
                   [1m14       CENTRIGHT      [22mtext aligned to center right
                   [1m15       BOTCENT        [22mtext aligned to bottom center

     •  Each line after the object type specifies a point used  to  display  the
        element.   It contains an [4mx[24m and a [4my[24m coordinate in floating‐point format,
        separated by spaces.  The list of points is terminated by  a  line  con‐
        taining  the  string  “[1m-1.0  -1.0[22m”  (AED)  or  a  single  asterisk,  “[1m*[22m”
        (Sun/X11).

     •  After the points comes a line containing two decimal values, giving  the
        brush and size for the element.  The brush determines the style in which
        things  are  drawn.   For  vectors, arcs, and curves there are six valid
        brush values.

                               [1m1   [22mthin dotted lines
                               [1m2   [22mthin dot‐dashed lines
                               [1m3   [22mthick solid lines
                               [1m4   [22mthin dashed lines
                               [1m5   [22mthin solid lines
                               [1m6   [22mmedium solid lines

        For polygons, 0 is also valid: it specifies an  invisible  border.   For
        text, the brush selects a font as follows.

                             [1m1   [22mroman (R font in [4mtroff[24m)
                             [1m2   [22mitalics (I font in [4mtroff[24m)
                             [1m3   [22mbold (B font in [4mtroff[24m)
                             [1m4   [22mspecial (S font in [4mtroff[24m)

        If  you’re using [4mgrn[24m to run your pictures through [4mgroff[24m, the font is re‐
        ally just a starting font.  The text string can contain  formatting  se‐
        quences like “\fI” or “\d” which may change the font (as well as do many
        other  things).   For  text, the size field is a decimal value between 1
        and 4.  It selects the size of the font in which the text will be drawn.
        For polygons, this size field is interpreted as a stipple number to fill
        the polygon with.  The number is used to index into a  stipple  font  at
        print time.

     •  The  last line of each element contains a decimal number and a string of
        characters, separated by a single space.  The number is a count  of  the
        number  of  characters in the string.  This information is used only for
        text elements, and contains the text string.  There can be spaces inside
        the text.  For arcs, curves, and vectors, the character  count  is  zero
        ([1m0[22m), followed by exactly one space before the newline.

   [1mCoordinates[0m
     [4mgremlin[24m was designed for AED terminals, and its coordinates reflect the AED
     coordinate  space.   For  vertical pictures, [4mx[24m values range 116 to 511, and
     [4my[24m values from 0 to 483.  For horizontal pictures, [4mx[24m values range from 0  to
     511,  and [4my[24m values from 0 to 367.  Although you needn’t absolutely stick to
     this range, you’ll get better results if you at least stay in  this  vicin‐
     ity.   Also,  point  lists  are  terminated  by a point of (-1, -1), so you
     shouldn’t ever use negative coordinates.  [4mgremlin[24m  writes  out  coordinates
     using  the  ]8;;man:printf(3)\[4mprintf[24m(3)]8;;\  format “%f1.2”; it’s probably a good idea to use the
     same format if you want to modify the [4mgrn[24m code.

   [1mSun/X11 coordinates[0m
     There is no restriction on the range of coordinates used to create  objects
     in  the  Sun/X11  version of [4mgremlin[24m.  However, files with negative coordi‐
     nates [4mwill[24m cause problems if displayed on the AED.

[1mOptions[0m
     [1m-? [22mand [1m--help [22mdisplay a usage message, while [1m-v [22mand [1m--version [22mshow  version
     information; all exit afterward.

     [1m-C      [22mRecognize  [1m.GS  [22mand [1m.GE [22m(and [1m.GF[22m) even when followed by a character
             other than space or newline.

     [1m-F [4m[22mdir[24m  Search [4mdir[24m for subdirectories [4mdev[24mname ([4mname[24m is the name of the out‐
             put driver) for the [4mDESC[24m file before the default  font  directories
             [4m/usr/share/groff/site-font[24m, [4m/usr/share/groff/1.24.1/font[24m, and [4m/usr/[0m
             [4mlib/font[24m.

     [1m-M [4m[22mdir[24m  Prepend  [4mdir[24m  to  the  search  path for [4mgremlin[24m files.  The default
             search path is the current directory,  the  home  directory,  [4m/usr/[0m
             [4mshare/groff/site-tmac[24m,  and  [4m/usr/share/groff/1.24.1/tmac[24m,  in that
             order.

     [1m-T [4m[22mdev[24m  Prepare device output using output driver [4mdev[24m.  The default is  [1mps[22m.
             See ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ for a list of valid devices.

[1mExit status[0m
     [4mgrn[24m  exits  with  status [1m0 [22mon successful operation, status [1m2 [22mif the program
     cannot interpret its command‐line arguments, and status [1m1 [22mif it  encounters
     an error during operation.

[1mFiles[0m
     [4m/usr/share/groff/1.24.1/font/dev[24mname[4m/DESC[0m
            describes the output device [4mname[24m.

[1mAuthors[0m
     David  Slattengren  and  Barry  Roitblat  wrote  the original Berkeley [4mgrn[24m.
     Daniel Senderowicz and ]8;;mailto:wl@gnu.org\Werner Lemberg]8;;\ modified it for [4mgroff[24m.

[1mSee also[0m
     ]8;;man:gremlin(1)\[4mgremlin[24m(1)]8;;\, ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, ]8;;man:pic(1)\[4mpic[24m(1)]8;;\, ]8;;man:ideal(1)\[4mideal[24m(1)]8;;\

groff 1.24.1                       2026‐03‐20                             [4mgrn[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mgrodvi[24m(1)                    General Commands Manual                   [4mgrodvi[24m(1)

[1mName[0m
     grodvi - [4mgroff[24m output driver for TeX DVI format

[1mSynopsis[0m
     [1mgrodvi [22m[[1m-dl[22m] [[1m-F [4m[22mdir[24m] [[1m-p [4m[22mpaper‐format[24m] [[1m-w [4m[22mn[24m] [[4mfile[24m ...]

     [1mgrodvi --help[0m

     [1mgrodvi -v[0m
     [1mgrodvi --version[0m

[1mDescription[0m
     The GNU [4mroff[24m DVI output driver translates the output of ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\  into  TeX
     DVI  format.   Normally,  [4mgrodvi[24m  is invoked by ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ when the latter is
     given the “[1m-T dvi[22m” option.  (In this installation, [1mps [22mis the default output
     device.)  Use [4mgroff[24m’s [1m-P [22moption to pass any options shown above to  [4mgrodvi[24m.
     If  no  [4mfile[24m arguments are given, or if [4mfile[24m is “-”, [4mgrodvi[24m reads the stan‐
     dard input stream.  It writes to the standard output stream.

     The DVI file generated by [4mgrodvi[24m can be interpreted by any correctly  writ‐
     ten  DVI  driver.  [4mtroff[24m drawing primitives are implemented using [4mtpic[24m ver‐
     sion 2 specials.  If the driver does not support these, [1m\D [22mescape sequences
     will not produce any output.

     Encapsulated PostScript (EPS) files can be easily included; use  the  [1mPSPIC[0m
     macro.  [4mpspic.tmac[24m is loaded automatically by [4mdvi.tmac[24m.  See ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\.

     The  default  color  used by the [1m\m [22mand [1m\M [22mescape sequences is black.  Cur‐
     rently, the stroke color for [1m\D [22mdrawing escape  sequences  is  black;  fill
     color values are translated to gray.

     In  [4mgroff[24m,  as  in AT&T [4mtroff[24m, the [1m\N [22mescape sequence can be used to access
     any glyph in the current font by its  position  in  the  corresponding  TFM
     file.

     By design, the DVI format doesn’t care about the physical dimensions of the
     output medium.  See subsection “Device extension commands” below.

   [1mTypefaces[0m
     [4mgrodvi[24m  supports the standard four styles: [1mR [22m(roman), [1mI [22m([4mitalic[24m), [1mB [22m([1mbold[22m),
     and [1mBI [22m([4m[1mbold‐italic[24m[22m).  Fonts are grouped into families [1mT [22mand [1mH [22mhaving  mem‐
     bers in each style.  “CM” abbreviates “Computer Modern”.

            [1mTR     [22mCM Roman (cmr10)
            [1mTI     [22mCM Text Italic (cmti10)
            [1mTB     [22mCM Bold Extended Roman (cmbx10)
            [1mTBI    [22mCM Bold Extended Text Italic (cmbxti10)
            [1mHR     [22mCM Sans Serif (cmss10)
            [1mHI     [22mCM Slanted Sans Serif (cmssi10)
            [1mHB     [22mCM Sans Serif Bold Extended (cmssbx10)
            [1mHBI    [22mCM Slanted Sans Serif Bold Extended (cmssbxo10)

     The following fonts are not members of a family.

            [1mCW     [22mCM Typewriter Text (cmtt10)
            [1mCWI    [22mCM Italic Typewriter Text (cmitt10)

     Special  fonts  include  [1mMI [22m(cmmi10), [1mS [22m(cmsy10), [1mEX [22m(cmex10), [1mSC [22m(cmtex10,
     only for [1mCW[22m), and, perhaps surprisingly, [1mTR[22m, [1mTI[22m, and [1mCW[22m, because TeX places
     some glyphs in text fonts that [4mtroff[24m generally does not.  For italic fonts,
     [1mCWI [22mis used instead of [1mCW[22m.

     Finally, the symbol fonts of the American Mathematical Society  are  avail‐
     able as special fonts [1mSA [22m(msam10) and [1mSB [22m(msbm10).  They are not mounted by
     default.

     You  can  load the [4mec.tmac[24m macro file to employ the EC and TC fonts instead
     of CM, which they resemble.  They also provide Euro  [1m\[Eu]  [22mand  per  mille
     [1m\[%0]  [22mglyphs.   Do  so  before  loading  localization macro files, because
     [4mec.tmac[24m does not set up automatic hyphenation codes.

   [1mDevice extension commands[0m
     [4mgrodvi[24m emits the equivalent to  TeX’s  [1m\special{papersize=[4m[22mwidth[24m[1m,[4m[22mlength[24m[1m}  [22mon
     the  first  page; [4mdvips[24m (or another DVI driver) then sets the page size ac‐
     cordingly.  If either  the  page  width  or  length  is  not  positive,  no
     [1mpapersize [22mspecial is output.

     [4mgrodvi[24m  supports  one  device  extension,  accessed  with the [4mgroff[24m request
     [1mdevice [22mor [4mroff[24m [1m\X [22mescape sequence.

     [1m\X'papersize=[4m[22mwidth[24m[1m,[4m[22mlength[24m[1m'[0m
            Set the page dimensions in centimeters to [4mwidth[24m by [4mlength.[24m   If  the
            [1m-l  [22moption  was specified, these dimensions are swapped.  Changes to
            the paper dimensions should occur prior to the first page, or during
            page ejection before starting a subsequent one.

            [4mCaution:[24m the ordering of dimensions differs from that used by [4mpaper‐[0m
            [4msize.tmac[24m and ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\’s “[1m-d paper[22m” option.

     The parameter(s) to [1mdevice [22mand [1m\X [22mare translated to the same DVI  file  in‐
     structions as would be produced by [1m\special{[4m[22manything[24m[1m} [22min TeX; [4manything[24m can‐
     not contain a newline.

   [1mFont description files[0m
     Use  ]8;;man:tfmtodit(1)\[4mtfmtodit[24m(1)]8;;\  to create [4mgroff[24m font description files from TFM (TeX font
     metrics) files.  The font description file should contain the following ad‐
     ditional directives, which [4mtfmtodit[24m generates automatically.

     [1minternalname [4m[22mname[0m
            The name of the TFM file (without the [4m.tfm[24m extension) is [4mname[24m.

     [1mchecksum [4m[22mn[0m
            The checksum in the TFM file is [4mn[24m.

     [1mdesignsize [4m[22mn[0m
            The design size in the TFM file is [4mn[24m.

   [1mDrawing commands[0m
     [4mgrodvi[24m supports an additional drawing command.

     [1m\D'R [4m[22mdh[24m [4mdv[24m[1m'[0m
            Draw a rule (solid black rectangle) with one corner at  the  drawing
            position, and the diagonally opposite corner at the drawing position
            +([4mdh[24m,[4mdv[24m),  which  becomes  the new drawing position afterward.  This
            command produces a rule in the DVI file and so can be  printed  even
            with  a driver that does not support [4mtpic[24m specials, unlike the other
            [1m\D [22mcommands.

[1mOptions[0m
     [1m--help [22mdisplays a usage message, while [1m-v [22mand [1m--version [22mshow version infor‐
     mation; all exit afterward.

     [1m-d      [22mDo not use [4mtpic[24m specials to implement drawing commands.  Horizontal
             and vertical lines are implemented by rules.   Other  drawing  com‐
             mands are ignored.

     [1m-F [4m[22mdir[24m  Prepend  directory  dir[4m/dev[24mname to the search path for font and de‐
             vice description files; [4mname[24m is the name  of  the  device,  usually
             [1mdvi[22m.

     [1m-l      [22mUse landscape orientation rather than portrait.

     [1m-p [4m[22mpaper‐format[0m
             Set physical dimensions of output medium, overriding the [1mpapersize[22m,
             [1mpaperlength[22m,  and  [1mpaperwidth  [22mdirectives in the [4mDESC[24m file.  [4mpaper‐[0m
             [4mformat[24m can be any argument accepted by the [1mpapersize [22mdirective; see
             ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

     [1m-w [4m[22mn[24m    Draw rules (lines) with a thickness of [4mn[24m thousandths of an em.  The
             default thickness is [1m40 [22m(0.04 em).

[1mExit status[0m
     [4mgrodvi[24m exits with status [1m0 [22mon successful operation, status [1m2 [22mif the program
     cannot interpret its command‐line arguments, and status [1m1 [22mif it  encounters
     an error during operation.

[1mEnvironment[0m
     [4mGROFF_FONT_PATH[0m
            lists  directories in which to search for [4mdevdvi[24m, [4mgrodvi[24m’s directory
            of  device  and  font   description   files.    See   ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\   and
            ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

[1mFiles[0m
     [4m/usr/share/groff/1.24.1/font/devdvi/DESC[0m
            describes the [1mdvi [22moutput device.

     [4m/usr/share/groff/1.24.1/font/devdvi/[24mF
            describes the font known as [4mF[24m on device [1mdvi[22m.

     [4m/usr/share/groff/1.24.1/tmac/dvi.tmac[0m
            defines  font  mappings, special characters, and colors for use with
            the [1mdvi [22moutput device.  It is automatically loaded by  [4mtroffrc[24m  when
            the [1mdvi [22moutput device is selected.

     [4m/usr/share/groff/1.24.1/tmac/ec.tmac[0m
            configures  the [1mdvi [22moutput device to use the EC and TC font families
            instead of CM (Computer Modern).

[1mBugs[0m
     DVI files produced by [4mgrodvi[24m use a different resolution (57,816  units  per
     inch) from those produced by TeX.  Incorrectly written drivers which assume
     the  resolution  used by TeX, rather than using the resolution specified in
     the DVI file, will not work with [4mgrodvi[24m.

     When using the [1m-d [22moption with boxed tables, vertical and  horizontal  lines
     can  sometimes protrude by one pixel.  This is a consequence of the way TeX
     requires that the heights and widths of rules be rounded.

[1mSee also[0m
     ]8;;https://texfaq.org/FAQ-ECfonts\“What are the EC fonts?”]8;;\; TeX FAQ: Frequently Asked Question List for TeX

     ]8;;man:tfmtodit(1)\[4mtfmtodit[24m(1)]8;;\,    ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\,    ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\,     ]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\,     ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\,
     ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\, ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\

groff 1.24.1                       2026‐03‐20                          [4mgrodvi[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mgroff[24m(1)                     General Commands Manual                    [4mgroff[24m(1)

[1mName[0m
     groff - front end to the GNU [4mroff[24m document formatting system

[1mSynopsis[0m
     [1mgroff [22m[[1m-abcCeEgGijklNpRsStUVXzZ[22m] [[1m-d [4m[22mctext[24m] [[1m-d [4m[22mstring[24m[1m=[4m[22mtext[24m] [[1m-D [4m[22mfallback‐[0m
           [4mencoding[24m] [[1m-f [4m[22mfont‐family[24m] [[1m-F [4m[22mfont‐directory[24m] [[1m-I [4m[22minclusion‐[0m
           [4mdirectory[24m] [[1m-K [4m[22minput‐encoding[24m] [[1m-L [4m[22mspooler‐argument[24m] [[1m-m [4m[22mmacro‐[0m
           [4mpackage[24m] [[1m-M [4m[22mmacro‐directory[24m] [[1m-n [4m[22mpage‐number[24m] [[1m-o [4m[22mpage‐list[24m]
           [[1m-P [4m[22mpostprocessor‐argument[24m] [[1m-r [4m[22mcnumeric‐expression[24m]
           [[1m-r [4m[22mregister[24m[1m=[4m[22mnumeric‐expression[24m] [[1m-T [4m[22moutput‐device[24m] [[1m-w [4m[22mwarning‐[0m
           [4mcategory[24m] [[1m-W [4m[22mwarning‐category[24m] [[4mfile[24m ...]

     [1mgroff -h[0m
     [1mgroff --help[0m

     [1mgroff -v [22m[[4moption[24m ...] [[4mfile[24m ...]
     [1mgroff --version [22m[[4moption[24m ...] [[4mfile[24m ...]

[1mDescription[0m
     [4mgroff[24m  is the primary front end to the GNU [4mroff[24m document formatting system.
     GNU [4mroff[24m is a typesetting system that reads plain text input that  includes
     formatting  commands  to  produce output in PostScript, PDF, HTML, or other
     formats, or for display to a terminal.  Formatting  commands  can  be  low‐
     level  typesetting  primitives, macros from a supplied package, or user‐de‐
     fined macros.  All three approaches can be combined.  If no  [4mfile[24m  operands
     are specified, or if [4mfile[24m is “[1m-[22m”, [4mgroff[24m reads the standard input stream.

     A  reimplementation  and  extension  of  [4mtroff[24m and other programs from AT&T
     Unix, [4mgroff[24m is widely available on POSIX and other  systems  owing  to  its
     long association with Unix manuals, including man pages.  It and its prede‐
     cessor  have  produced  several  best‐selling  software  engineering texts.
     [4mgroff[24m can create typographically sophisticated  documents  while  consuming
     minimal system resources.

     Like  its predecessor “troff”, the term “groff” affords two popular pronun‐
     ciations: as one syllable (like the surname), rhyming with “trough”, or  as
     “jee‐roff”,  in  analogy to the Bell Labs pronunciation “tee‐roff”.  Little
     risk of confusion exists; use whichever suits you.

     The [4mgroff[24m command orchestrates the execution of preprocessors,  the  trans‐
     formation  of  input  documents  into a device‐independent page description
     language, and the production of output from that language.

[1mOptions[0m
     [1m-h [22mand [1m--help [22mdisplay a usage message and exit.

     Because [4mgroff[24m is intended to subsume most users’ direct invocations of  the
     ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\  formatter,  the  two  programs  share a set of options.  However,
     [4mgroff[24m has some options that [4mtroff[24m does not share, and  others  which  [4mgroff[0m
     interprets  differently.  At the same time, not all valid [4mtroff[24m options can
     be given to [4mgroff[24m.

   [4m[1mgroff[24m‐specific options[0m
     The following options either do not exist in GNU [4mtroff[24m or  are  interpreted
     differently by [4mgroff[24m.

     [1m-D [4m[22menc[24m   Use [4menc[24m as ]8;;man:preconv(1)\[4mpreconv[24m(1)]8;;\’s fallback input encoding; implies [1m-k[22m.

     [1m-e       [22mRun ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\ preprocessor.

     [1m-g       [22mRun ]8;;man:grn(1)\[4mgrn[24m(1)]8;;\ preprocessor.

     [1m-G       [22mRun ]8;;man:grap(1)\[4mgrap[24m(1)]8;;\ preprocessor; implies [1m-p[22m.

     [1m-I [4m[22mdir[24m   Works  as  [4mtroff[24m’s option (see below), but also implies [1m-g [22mand [1m-s[22m.
              [4mgroff[24m  passes  [1m-I  [22moptions  and  their  arguments  to   ]8;;man:soelim(1)\[4msoelim[24m(1)]8;;\,
              ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\,  and  output  drivers; with the option letter changed to
              [1m-M[22m, it passes the same arguments to ]8;;man:grn(1)\[4mgrn[24m(1)]8;;\.

     [1m-j       [22mRun ]8;;man:chem(1)\[4mchem[24m(1)]8;;\ preprocessor; implies [1m-p[22m.

     [1m-k       [22mRun ]8;;man:preconv(1)\[4mpreconv[24m(1)]8;;\ preprocessor.  Refer to its man page for its behav‐
              ior if neither of [4mgroff[24m’s [1m-K [22mor [1m-D [22moptions is also specified.

     [1m-K [4m[22menc[24m   Set input encoding used by ]8;;man:preconv(1)\[4mpreconv[24m(1)]8;;\ to [4menc[24m; implies [1m-k[22m.

     [1m-l       [22mSend the output to a spooler program for  printing.   The  “[1mprint[22m”
              directive  in  the  device  description file specifies the default
              command to be used; see ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.  If no  such  directive  is
              present  for  the  output device, this option is ignored.  See op‐
              tions [1m-L [22mand [1m-X[22m.

     [1m-L [4m[22marg[24m   Pass [4marg[24m to the print spooler.  If  multiple  [4marg[24ms  are  required,
              pass each with a separate [1m-L [22moption.  [4mgroff[24m does not prefix an op‐
              tion dash to [4marg[24m before passing it to the spooler.

     [1m-M       [22mWorks as [4mtroff[24m’s option (see below), but is also passed to ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\,
              ]8;;man:grap(1)\[4mgrap[24m(1)]8;;\, and ]8;;man:grn(1)\[4mgrn[24m(1)]8;;\.

     [1m-N       [22mProhibit newlines between [4meqn[24m delimiters: pass [1m-N [22mto ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\.

     [1m-p       [22mRun ]8;;man:pic(1)\[4mpic[24m(1)]8;;\ preprocessor.

     [1m-P [4m[22marg[24m   Pass  [4marg[24m  to  the  postprocessor.  If multiple [4marg[24ms are required,
              pass each with a separate [1m-P [22moption.  [4mgroff[24m does not prefix an op‐
              tion dash to [4marg[24m before passing it to the postprocessor.

     [1m-R       [22mRun ]8;;man:refer(1)\[4mrefer[24m(1)]8;;\ preprocessor.  No mechanism is provided  for  passing
              arguments  to it; most [4mrefer[24m options have equivalent language ele‐
              ments that can be specified within the document.

     [1m-s       [22mRun ]8;;man:soelim(1)\[4msoelim[24m(1)]8;;\ preprocessor.

     [1m-S       [22mEnable safer mode and ignore  any  subsequent  [1m-U  [22moption.   [4mgroff[0m
              passes the [1m-S [22moption to ]8;;man:pic(1)\[4mpic[24m(1)]8;;\ and ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\.

     [1m-t       [22mRun ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\ preprocessor.

     [1m-T [4m[22mdev[24m   Prepare output for device [4mdev.[24m  [4mgroff[24m passes the [1m-T [22moption and its
              argument  to  [4mtroff[24m,  then  (unless the [1m-Z [22moption is used) runs an
              output driver to convert [4mtroff[24m’s output to a form appropriate  for
              [4mdev[24m; see subsection “Output devices” below.

     [1m-U       [22mOperate  in unsafe mode.  [4mgroff[24m passes the [1m-U [22moption to ]8;;man:pic(1)\[4mpic[24m(1)]8;;\ and
              ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\.

     [1m--version[0m
     [1m-v       [22mWrite version information for [4mgroff[24m and all programs run by it  to
              the  standard  output  stream;  that is, the given command line is
              processed in the usual way, passing [1m-v [22mto the  formatter  and  any
              pre‐ or postprocessors invoked.

     [1m-V       [22mOutput  the  pipeline  that [4mgroff[24m would run to the standard output
              stream and exit.  If given more than once, [4mgroff[24m both  writes  the
              pipeline to the standard error stream and runs it.

     [1m-X       [22mUse ]8;;man:gxditview(1)\[4mgxditview[24m(1)]8;;\ instead of the usual postprocessor to (pre)view a
              document  on  an  X11 display.  Combining this option with “[1m-T ps[22m”
              uses the font metrics of the PostScript device,  whereas  the  “[1m-T[0m
              [1mX75[22m”, “[1m-T X75-12[22m” “[1m-T X100[22m”, and “[1m-T X100-12[22m” options use the met‐
              rics of X11 fonts.

     [1m-Z       [22mDisable postprocessing.  [4mtroff[24m output appears on the standard out‐
              put stream (unless suppressed with [1m-z[22m); see ]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\ for a de‐
              scription of this format.

   [1mTransparent options[0m
     The  following  options  are passed as‐is to the formatter program ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\
     and described in more detail in its man page.

     [1m-a       [22mGenerate a plain text approximation of the typeset output.

     [1m-b       [22mWrite a backtrace to the standard error stream on  each  error  or
              warning.

     [1m-c       [22mStart with color output disabled.

     [1m-C       [22mEnable AT&T [4mtroff[24m compatibility mode; implies [1m-c[22m.

     [1m-d [4m[22mctext[0m
     [1m-d [4m[22mstring[24m[1m=[4m[22mtext[0m
              Define string.

     [1m-E       [22mInhibit [4mtroff[24m error messages; implies [1m-Ww[22m.

     [1m-f [4m[22mfam[24m   Set default font family.

     [1m-F [4m[22mdir[24m   Search in directory [4mdir[24m for the selected output device’s directory
              of device and font description files.

     [1m-i       [22mProcess standard input after the specified input files.

     [1m-I [4m[22mdir[24m   Search [4mdir[24m for input files.

     [1m-m [4m[22mmac[24m   Read  macro package [4mmac[24m before input.  [4mgroff[24m passes [1m-m [22moptions and
              their arguments to ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\, ]8;;man:grap(1)\[4mgrap[24m(1)]8;;\, and ]8;;man:grn(1)\[4mgrn[24m(1)]8;;\.

     [1m-M [4m[22mdir[24m   Search directory [4mdir[24m for macro files.  [4mgroff[24m passes [1m-M [22moptions and
              their arguments to ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\, ]8;;man:grap(1)\[4mgrap[24m(1)]8;;\, and ]8;;man:grn(1)\[4mgrn[24m(1)]8;;\.

     [1m-n [4m[22mnum[24m   Begin numbering pages at [4mnum.[0m

     [1m-o [4m[22mlist[24m  Output only pages in [4mlist[24m.

     [1m-r [4m[22mcnumeric‐expression[0m
     [1m-r [4m[22mregister[24m[1m=[4m[22mnumeric‐expression[0m
              Define register.

     [1m-S       [22mEnable safer mode and ignore any subsequent [1m-U [22moption.

     [1m-U       [22mOperate in unsafe mode.

     [1m-w [4m[22mcat[0m
     [1m-W [4m[22mcat[24m   Enable and inhibit, respectively, warnings in category [4mcat.[0m

     [1m-z       [22mSuppress formatted device‐independent output of [4mtroff[24m.

[1mUsage[0m
     The architecture of the GNU [4mroff[24m system follows that of other  device‐inde‐
     pendent  [4mroff[24m  implementations,  comprising  preprocessors, macro packages,
     output drivers (or “postprocessors”), and a suite of  utilities,  with  the
     formatter program ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ at its heart.  See ]8;;man:roff(7)\[4mroff[24m(7)]8;;\ for a survey of how a
     [4mroff[24m system works.

     The  front  end programs available in the GNU [4mroff[24m system make it easier to
     use than traditional [4mroff[24ms that required the construction of  pipelines  or
     use of temporary files to carry a source document from maintainable form to
     device‐ready output.  The discussion below summarizes the constituent parts
     of  the GNU [4mroff[24m system.  It complements ]8;;man:roff(7)\[4mroff[24m(7)]8;;\ with [4mgroff[24m‐specific infor‐
     mation.

   [1mGetting started[0m
     Those who prefer to learn by experimenting or are desirous of  rapid  feed‐
     back from the system may wish to start with a “Hello, world!” document.

     $ [1mecho "Hello, world!" | groff -Tascii | sed '/^$/d'[0m
     Hello, world!

     We  used  a  ]8;;man:sed(1)\[4msed[24m(1)]8;;\ command only to eliminate the 65 blank lines that would
     otherwise flood the terminal screen.  ([4mroff[24m systems were developed  in  the
     days of paper‐based terminals with 66 lines to a page.)

     Today’s users may prefer output to a UTF‐8‐capable terminal.

     $ [1mecho "Hello, world!" | groff -Tutf8 | sed '/^$/d'[0m

     Producing  PDF,  HTML, or TeX’s DVI is also straightforward.  The hard part
     may be selecting a viewer program for the output.

     $ [1mecho "Hello, world!" | groff -Tpdf > hello.pdf[0m
     $ [1mevince hello.pdf[0m
     $ [1mecho "Hello, world!" | groff -Thtml > hello.html[0m
     $ [1mfirefox hello.html[0m
     $ [1mecho "Hello, world!" | groff -Tdvi > hello.dvi[0m
     $ [1mxdvi hello.dvi[0m

   [1mUsing [4mgroff[24m as a REPL[0m
     Those with a programmer’s bent may be pleased to know  that  they  can  use
     [4mgroff[24m  in a read‐evaluate‐print loop (REPL).  Doing so can be handy to ver‐
     ify one’s understanding of the formatter’s behavior and/or  the  syntax  it
     accepts.  Turning on all warnings with [1m-ww [22mcan aid this goal.

     $ [1mgroff -ww -Tutf8[0m
     [1m\# This is a comment. Let's define a register.[0m
     [1m.nr a 1[0m
     [1m\# Do integer arithmetic with operators evaluated left‐to‐right.[0m
     [1m.nr b \n[a]+5/2[0m
     [1m\# Let's get the result on the standard error stream.[0m
     [1m.tm \n[b][0m
     3
     [1m\# Now we'll define a string.[0m
     [1m.ds name Leslie\" This is another form of comment.[0m
     [1m.nr b (\n[a] + (7/2))[0m
     [1m\# Center the next two text input lines.[0m
     [1m.ce 2[0m
     [1mHi, \*[name].[0m
     [1mYour secret number is \n[b].[0m
     [1m\# We will see that the division rounded toward zero.[0m
     [1mIt is[0m
     [1m\# Here's an if‐else control structure.[0m
     [1m.ie (\n[b] % 2) odd.[0m
     [1m.el even.[0m
     [1m\# This trick sets the page length to the current vertical[0m
     [1m\# position, so that blank lines don't spew when we're done.[0m
     [1m.pl \n[nl]u[0m
     [4m<Control‐D>[0m
                                Hi, Leslie.
                         Your secret number is 4.
     It is even.

   [1mPaper format[0m
     The  formatter reads the device description file [4mDESC[24m for the selected out‐
     put device when it starts; page  dimensions  declared  there  are  used  if
     present.  [4mgroff[24m’s build process configures a default page format and writes
     it to typesetters’ [4mDESC[24m files.  This installation defaults to “[1mletter[22m”.  If
     the [4mDESC[24m file lacks this information, the formatter and output driver use a
     page  length  of  [1m“[22m11i[1m”  [22m(eleven inches) for compatibility with AT&T [4mtroff[24m.
     See ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

     In the formatter, the [1mpl [22mrequest changes the page length, but  macro  pack‐
     ages often do not support alteration of the paper format within a document.
     One might, for instance, want to switch between portrait and landscape ori‐
     entations.   Macro  packages lack a consistent approach to configuration of
     parameters dependent on the paper format; some, like  [4mms[24m,  benefit  from  a
     preamble  in the document prior to the first macro call, while others, like
     [4mmm[24m, instead require the specification of registers on the command line,  or
     otherwise  before  its  macro file is interpreted, to configure page dimen‐
     sions.

     Output drivers for typesetters also recognize command‐line  options  [1m-p  [22mto
     override  the  default page dimensions and [1m-l [22mto use landscape orientation.
     The output driver’s man page, such as ]8;;man:grops(1)\[4mgrops[24m(1)]8;;\, may be helpful.

     [4mgroff[24m’s “[1m-d paper[22m” command‐line option is a convenient means of setting the
     paper format; see ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\.  Combine it with  appropriate  [1m-P  [22moptions
     for the output driver, overriding its defaults.  The following command for‐
     mats for PostScript on A4 paper in landscape orientation.

            $ [1mgroff -T ps -d paper=a4l -P -pa4 -P -l -ms my.ms >my.ps[0m

   [1mFront end[0m
     The [4mgroff[24m program wraps ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\, allowing one to specify preprocessors via
     command‐line  options and running the appropriate output driver for the se‐
     lected output device.  This convenience avoids the manual  construction  of
     pipelines or management of temporary files required of users of traditional
     ]8;;man:roff(7)\[4mroff[24m(7)]8;;\ systems.  Use ]8;;man:grog(1)\[4mgrog[24m(1)]8;;\ to infer an appropriate [4mgroff[24m command line to
     format a document.

   [1mLanguage[0m
     Input  to a [4mroff[24m system is in plain text interleaved with control lines and
     escape sequences.  The combination constitutes a document in one of a  fam‐
     ily  of  languages  we  also  call  [4mroff[24m;  see  ]8;;man:roff(7)\[4mroff[24m(7)]8;;\ for background.  An
     overview of GNU [4mroff[24m language syntax and features, including lists  of  all
     supported  escape  sequences,  requests,  and  predefined registers, can be
     found in ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\.  GNU [4mroff[24m extensions to the AT&T [4mtroff[24m language, a  com‐
     mon subset of [4mroff[24m dialects extant today, are detailed in ]8;;man:groff_diff(7)\[4mgroff_diff[24m(7)]8;;\.

   [1mPreprocessors[0m
     A  preprocessor  interprets  a  domain‐specific language that produces [4mroff[0m
     language output.  Frequently, such input is confined to sections or regions
     of [4mroff[24m input (bracketed with macro calls specific to  each  preprocessor),
     which  it  replaces.   Preprocessors  therefore often interpret a subset of
     [4mroff[24m syntax along with their own language.  GNU [4mroff[24m provides reimplementa‐
     tions of most preprocessors familiar to users of  AT&T  [4mtroff[24m;  these  rou‐
     tinely have extended features and/or require GNU [4mtroff[24m to format their out‐
     put.

            [4mtbl[24m         lays out tables;
            [4meqn[24m         typesets mathematics;
            [4mpic[24m         draws diagrams;
            [4mrefer[24m       processes bibliographic references;
            [4msoelim[24m      preprocesses “sourced” input files;
            [4mgrn[24m         renders ]8;;man:gremlin(1)\[4mgremlin[24m(1)]8;;\ diagrams;
            [4mchem[24m        draws chemical structural formulæ using [4mpic[24m;
            [4mgperl[24m       populates [4mgroff[24m registers and strings using ]8;;man:perl(1)\[4mperl[24m(1)]8;;\;
            [4mglilypond[24m   embeds [4mLilyPond[24m sheet music; and
            [4mgpinyin[24m     eases Mandarin Chinese input using Hanyu Pinyin.

     A preprocessor unique to GNU [4mroff[24m is ]8;;man:preconv(1)\[4mpreconv[24m(1)]8;;\, which converts various in‐
     put  encodings to something GNU [4mtroff[24m can understand.  When used, it is run
     before any other preprocessors.

     Most preprocessors enclose content between a pair of characteristic tokens.
     Such a token must occur at the beginning of an input line and use  the  dot
     control  character.   Spaces and tabs must not follow the control character
     or precede the end of the input line.  Deviating from these rules defeats a
     token’s recognition by the preprocessor.  Tokens are generally preserved in
     preprocessor output and interpreted as macro calls subsequently  by  [4mtroff[24m.
     The [4mideal[24m preprocessor is not yet available in [4mgroff[24m.

                ┌──────────────┬─────────────────┬────────────────┐
                │ preprocessor │ starting token  │  ending token  │
                ├──────────────┼─────────────────┼────────────────┤
                │     [4mchem[24m     │     .cstart     │     .cend      │
                │     [4meqn[24m      │       .EQ       │      .EN       │
                │     [4mgrap[24m     │       .G1       │      .G2       │
                │     [4mgrn[24m      │       .GS       │      .GE       │
                │    [4mideal[24m     │       .IS       │      .IE       │
                │              │                 │      .IF       │
                │     [4mpic[24m      │       .PS       │      .PE       │
                │              │                 │      .PF       │
                │              │                 │      .PY       │
                │    [4mrefer[24m     │       .R1       │      .R2       │
                │     [4mtbl[24m      │       .TS       │      .TE       │
                ├──────────────┼─────────────────┼────────────────┤
                │  [4mglilypond[24m   │ .lilypond start │ .lilypond stop │
                │    [4mgperl[24m     │   .Perl start   │   .Perl stop   │
                │   [4mgpinyin[24m    │  .pinyin start  │  .pinyin stop  │
                └──────────────┴─────────────────┴────────────────┘

   [1mMacro packages[0m
     Macro  files  are [4mroff[24m input files designed to produce no output themselves
     but instead ease the preparation of other [4mroff[24m  documents.   When  a  macro
     file  is installed at a standard location and suitable for use by a general
     audience, it is termed a [4mmacro[24m [4mpackage[24m.

     The [1m-m [22moption loads a macro package prior to any [4mroff[24m input documents,  and
     after  performing any string and register assignments directed by [1m-d [22mand [1m-r[0m
     options.  The GNU [4mroff[24m system implements most well‐known macro packages for
     AT&T [4mtroff[24m in a compatible way and extends them.  These have one‐  or  two‐
     letter names arising from intense practices of naming economy in early Unix
     culture,  a laconic approach that led to many of the packages being identi‐
     fied in general usage with the [4mnroff[24m and [4mtroff[24m option letter used to invoke
     them, sometimes to punning effect, as with “man” (short for “manual”),  and
     even  with  the  option  dash, as in the case of the [4ms[24m package, much better
     known as [4mms[24m or even [4m-ms[24m.

     Macro packages serve a variety of purposes.  Some are “full‐service”  pack‐
     ages,  adopting  responsibility  for  page  layout  among other fundamental
     tasks, and defining their own lexicon of macros for  document  composition;
     each such package stands alone and a given document can use at most one.

     [4man[24m     is  used to compose man pages in the format originating in Version 7
            Unix (1979); see ]8;;man:groff_man(7)\[4mgroff_man[24m(7)]8;;\.  It can be specified on  the  command
            line as [1m-man[22m.

     [4mdoc[24m    is  used  to  compose man pages in the format originating in 4.3BSD‐
            Reno (1990); see ]8;;man:groff_mdoc(7)\[4mgroff_mdoc[24m(7)]8;;\.  It can be specified on the  command
            line as [1m-mdoc[22m.

     [4me[24m      is  the Berkeley general‐purpose macro suite, developed as an alter‐
            native to AT&T’s [4ms[24m; see ]8;;man:groff_me(7)\[4mgroff_me[24m(7)]8;;\.  It can  be  specified  on  the
            command line as [1m-me[22m.

     [4mm[24m      implements the format used by the second‐generation AT&T macro suite
            for general documents, a successor to [4ms[24m; see ]8;;man:groff_mm(7)\[4mgroff_mm[24m(7)]8;;\.  It can be
            specified on the command line as [1m-mm[22m.

     [4mom[24m     (invariably  called  “mom”)  is  a  modern  package written by Peter
            Schaffter specifically for GNU [4mroff[24m.  Consult the  ]8;;file:///usr/share/doc/groff-1.24.1/html/mom/toc.html\[4mmom[24m  HTML  manual]8;;\
            for  extensive  documentation.   She——for  [4mmom[24m takes the female pro‐
            noun——can be specified on the command line as [1m-mom[22m.

     [4ms[24m      is  the  original  AT&T   general‐purpose   document   format;   see
            ]8;;man:groff_ms(7)\[4mgroff_ms[24m(7)]8;;\.  It can be specified on the command line as [1m-ms[22m.

     Others are supplemental.  For instance, [4mandoc[24m is a wrapper package specific
     to  GNU [4mroff[24m that recognizes whether a document uses [4mman[24m or [4mmdoc[24m format and
     loads the corresponding macro package.  It can be specified on the  command
     line  as  [1m-mandoc[22m.   A ]8;;man:man(1)\[4mman[24m(1)]8;;\ librarian may use this macro file to delegate
     loading of the correct macro package; it is thus unnecessary for [4mman[24m itself
     to scan the contents of a document to decide the issue.

     Many macro files augment the function of the full‐service packages,  or  of
     [4mroff[24m  documents that do not employ such a package——the latter are sometimes
     characterized as “raw”.  These auxiliary packages are described, along with
     details of macro file naming and placement, in ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\.

   [1mFormatters[0m
     The  formatter,  the  program  that  interprets  [4mroff[24m  language  input,  is
     ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\.  It provides the features of the AT&T [4mtroff[24m and [4mnroff[24m programs as
     well  as  many  extensions.  The command‐line option [1m-C [22mswitches [4mtroff[24m into
     [4mcompatibility[24m [4mmode[24m, which tries to emulate AT&T  [4mtroff[24m  as  closely  as  is
     practical  to enable the formatting of documents written for the older sys‐
     tem.

     A shell script, ]8;;man:nroff(1)\[4mnroff[24m(1)]8;;\, emulates the behavior of AT&T [4mnroff[24m.  It attempts
     to correctly encode the output based on the locale, relieving the  user  of
     the  need  to  specify an output device with the [1m-T [22moption and is therefore
     convenient for use with terminal output devices, described in the next sub‐
     section.

     GNU [4mtroff[24m generates output in a device‐independent, but  not  device‐agnos‐
     tic, page description language detailed in ]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\.

   [1mOutput devices[0m
     [4mtroff[24m  output is formatted for a particular [4moutput[24m [4mdevice[24m, typically speci‐
     fied by the [1m-T [22moption to the formatter or a front end.  If neither this op‐
     tion nor the [4mGROFF_TYPESETTER[24m environment variable  is  used,  the  default
     output device is [1mps[22m.  An output device may be any of the following.

     [1mascii     [22mfor terminals using the ISO 646 1991:IRV character set and encod‐
               ing, also known as US‐ASCII.

     [1mdvi       [22mfor TeX DVI format.

     [1mhtml[0m
     [1mxhtml     [22mfor HTML and XHTML output, respectively.

     [1mlatin1    [22mfor  terminals  using  the ISO Latin‐1 (8859‐1) character set and
               encoding.

     [1mlbp       [22mfor Canon CaPSL printers (LBP‐4 and LBP‐8 series laser printers).

     [1mlj4       [22mfor HP LaserJet4‐compatible (or other PCL5‐compatible) printers.

     [1mpdf       [22mfor PDF output.

     [1mps        [22mfor PostScript output.

     [1mutf8      [22mfor terminals using the ISO 10646 (“Unicode”)  character  set  in
               UTF‐8 encoding.

     [1mX75       [22mfor  previewing  with  [4mgxditview[24m  using  75  dpi resolution and a
               10‐point base type size.

     [1mX75-12    [22mfor previewing with [4mgxditview[24m  using  75  dpi  resolution  and  a
               12‐point base type size.

     [1mX100      [22mfor  previewing  with  [4mgxditview[24m  using  100 dpi resolution and a
               10‐point base type size.

     [1mX100-12   [22mfor previewing with [4mgxditview[24m using  100  dpi  resolution  and  a
               12‐point base type size.

   [1mPostprocessors[0m
     Any  program  that  interprets  the output of GNU [4mtroff[24m is a postprocessor.
     The postprocessors provided by GNU [4mroff[24m are [4moutput[24m [4mdrivers[24m, which prepare a
     document for viewing or printing.  Postprocessors for other purposes,  such
     as page resequencing or statistical measurement of a document, are conceiv‐
     able.

     An output driver supports one or more output devices, each with its own de‐
     vice  description  file.   A  device  determines its postprocessor with the
     [1mpostpro [22mdirective in its device description file; see  ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.   The
     [1m-X  [22moption overrides this selection, causing [4mgxditview[24m to serve as the out‐
     put driver.

     ]8;;man:grodvi(1)\[4mgrodvi[24m(1)]8;;\
            provides [1mdvi[22m.

     ]8;;man:grohtml(1)\[4mgrohtml[24m(1)]8;;\
            provides [1mhtml [22mand [1mxhtml[22m.

     ]8;;man:grolbp(1)\[4mgrolbp[24m(1)]8;;\
            provides [1mlbp[22m.

     ]8;;man:grolj4(1)\[4mgrolj4[24m(1)]8;;\
            provides [1mlj4[22m.

     ]8;;man:gropdf(1)\[4mgropdf[24m(1)]8;;\
            provides [1mpdf[22m.

     ]8;;man:grops(1)\[4mgrops[24m(1)]8;;\
            provides [1mps[22m.

     ]8;;man:grotty(1)\[4mgrotty[24m(1)]8;;\
            provides [1mascii[22m, [1mlatin1[22m, and [1mutf8[22m.

     ]8;;man:gxditview(1)\[4mgxditview[24m(1)]8;;\
            provides [1mX75[22m, [1mX75-12[22m, [1mX100[22m, and [1mX100-12[22m, and additionally  can  pre‐
            view [1mps[22m.

   [1mUtilities[0m
     GNU [4mroff[24m includes a suite of utilities.

     ]8;;man:gdiffmk(1)\[4mgdiffmk[24m(1)]8;;\
            marks differences between a pair of [4mroff[24m input files.

     ]8;;man:grog(1)\[4mgrog[24m(1)]8;;\
            infers the [4mgroff[24m command a document requires.

     Several  utilities prepare descriptions of fonts, enabling the formatter to
     use them when producing output for a given device.

     ]8;;man:addftinfo(1)\[4maddftinfo[24m(1)]8;;\
            adds information to AT&T [4mtroff[24m  font  description  files  to  enable
            their use with GNU [4mtroff[24m.

     ]8;;man:afmtodit(1)\[4mafmtodit[24m(1)]8;;\
            creates font description files for PostScript Type 1 fonts.

     ]8;;man:pfbtops(1)\[4mpfbtops[24m(1)]8;;\
            translates  a  PostScript  Type  1 font in PFB (Printer Font Binary)
            format to PFA (Printer Font ASCII), which can then be interpreted by
            [4mafmtodit[24m.

     ]8;;man:hpftodit(1)\[4mhpftodit[24m(1)]8;;\
            creates font description files for  the  HP  LaserJet  4  family  of
            printers.

     ]8;;man:tfmtodit(1)\[4mtfmtodit[24m(1)]8;;\
            creates font description files for the TeX DVI device.

     ]8;;man:xtotroff(1)\[4mxtotroff[24m(1)]8;;\
            creates font description files for X Window System core fonts.

     A trio of tools transform material constructed using [4mroff[24m preprocessor lan‐
     guages into graphical image files.

     ]8;;man:eqn2graph(1)\[4meqn2graph[24m(1)]8;;\
            converts an [4meqn[24m equation into a cropped image.

     ]8;;man:grap2graph(1)\[4mgrap2graph[24m(1)]8;;\
            converts a [4mgrap[24m diagram into a cropped image.

     ]8;;man:pic2graph(1)\[4mpic2graph[24m(1)]8;;\
            converts a [4mpic[24m diagram into a cropped image.

     Another set of programs works with the bibliographic data files used by the
     ]8;;man:refer(1)\[4mrefer[24m(1)]8;;\ preprocessor.

     ]8;;man:indxbib(1)\[4mindxbib[24m(1)]8;;\
            makes  inverted indices for bibliographic databases, speeding lookup
            operations on them.

     ]8;;man:lkbib(1)\[4mlkbib[24m(1)]8;;\
            searches the databases.

     ]8;;man:lookbib(1)\[4mlookbib[24m(1)]8;;\
            interactively searches the databases.

[1mExit status[0m
     [4mgroff[24m exits successfully (with status [1m0[22m) if either of  the  options  [1m-h  [22mor
     [1m--help  [22mis specified, status [1m2 [22mif the program cannot interpret its command‐
     line arguments, and status [1m1 [22mif it encounters an  error  during  operation.
     Otherwise,  [4mgroff[24m  runs  a  pipeline  to process its input; if all commands
     within the pipeline  exit  successfully,  [4mgroff[24m  does  likewise.   If  not,
     [4mgroff[24m’s  exit  status  encodes  a  summary of problems encountered, setting
     bit 2 if a command exited with a failure status, bit 3  if  a  command  was
     terminated  with  a  signal,  and bit 4 if a command could not be executed.
     (Thus, if all three misfortunes befall one’s  pipeline,  [4mgroff[24m  exits  with
     status  2^2 + 2^3 + 2^4 = 4+8+16 = 28.)  To troubleshoot pipeline problems,
     re‐run the [4mgroff[24m command with the [1m-V [22moption and break the reported pipeline
     down into separate stages, inspecting the exit status  of,  and  diagnostic
     messages emitted by, each command.

[1mEnvironment[0m
     Environment  variables  in  the host system affect the behavior of programs
     supplied by [4mgroff[24m as follows.  Normally, the path separator in  environment
     variables ending with [4mPATH[24m is the colon; this may vary depending on the op‐
     erating system.  For example, Windows uses a semicolon instead.

     [4mGROFF_BIN_PATH[0m
            Locate  [4mgroff[24m  commands  in  these directories, followed by those in
            [4mPATH[24m.  If not set, the installation directory of GNU  [4mroff[24m  executa‐
            bles, [4m/usr/bin[24m, is searched before [4mPATH[24m.

     [4mGROFF_COMMAND_PREFIX[0m
            Apply  a  prefix to certain GNU [4mroff[24m commands.  [4mgroff[24m can be config‐
            ured at compile time to apply a prefix to the names of  programs  it
            provides  that  had  counterparts in AT&T [4mtroff[24m, so that name colli‐
            sions are avoided at run time.  The default prefix is empty.

            When used, this prefix is conventionally the letter “g”.  For  exam‐
            ple,  GNU  [4mtroff[24m  would  be installed as [4mgtroff[24m.  Besides [4mtroff[24m, the
            prefix applies to the formatter  wrapper  [4mnroff[24m;  the  preprocessors
            [4meqn[24m, [4mgrn[24m, [4mpic[24m, [4mrefer[24m, [4mtbl[24m, and [4msoelim[24m; and the utilities [4mindxbib[24m and
            [4mlookbib[24m.

     [4mGROFF_ENCODING[0m
            Specify  the  assumed character encoding of the input.  [4mgroff[24m passes
            its value as an argument to  [4mpreconv[24m(1)  preprocessor’s  [1m-e  [22moption.
            This  variable’s  existence implies the [4mgroff[24m option [1m-k[22m.  If set but
            empty, [4mgroff[24m runs [4mpreconv[24m without an [1m-e [22moption.  [4mgroff[24m’s  [1m-K  [22moption
            overrides [4mGROFF_ENCODING[24m.

     [4mGROFF_FONT_PATH[0m
            Seek  the  selected output device’s directory of device and font de‐
            scription files in this  list  of  directories.   See  ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\  and
            ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

     [4mGROFF_TMAC_PATH[0m
            Seek  macro  packages in this list of directories.  See ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ and
            ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\.

     [4mGROFF_TMPDIR[0m
            Create temporary files in this directory.  If not  set,  but  [4mTMPDIR[0m
            is,  the  latter is used instead.  On Windows systems, if neither of
            the foregoing are set, the environment variables [4mTMP[24m  and  [4mTEMP[24m  (in
            that  order)  are checked also.  Otherwise, temporary files are cre‐
            ated in [4m/tmp[24m.  The ]8;;man:refer(1)\[4mrefer[24m(1)]8;;\, ]8;;man:grohtml(1)\[4mgrohtml[24m(1)]8;;\, and ]8;;man:grops(1)\[4mgrops[24m(1)]8;;\  commands  use
            temporary files.

     [4mGROFF_TYPESETTER[0m
            Set  the  default  output  device.  If empty or not set, [1mps [22mis used.
            The [1m-T [22moption overrides [4mGROFF_TYPESETTER[24m.

     [4mSOURCE_DATE_EPOCH[0m
            Declare a time stamp (expressed as seconds since the Unix epoch)  to
            use  as the output creation time stamp in place of the current time.
            The time is converted to human‐readable  form  using  ]8;;man:gmtime(3)\[4mgmtime[24m(3)]8;;\  and
            ]8;;man:asctime(3)\[4masctime[24m(3)]8;;\  when the formatter starts up and stored in registers us‐
            able by documents and macro packages.

     [4mTZ[24m     Declare the time zone to use when converting the current time to hu‐
            man‐readable form; see ]8;;man:tzset(3)\[4mtzset[24m(3)]8;;\.  If [4mSOURCE_DATE_EPOCH[24m is  used,  it
            is always converted to human‐readable form using UTC.

[1mExamples[0m
     [4mroff[24m  systems  are best known for formatting man pages.  A ]8;;man:man(1)\[4mman[24m(1)]8;;\ librarian
     program, having located a page, might render it with a [4mgroff[24m command.
            groff -t -man -Tutf8 /usr/share/man/man1/groff.1
     The librarian will also pipe the output through a pager,  which  might  not
     interpret  terminal escape sequences [4mgroff[24m emits for boldface, underlining,
     italics, or hyperlinking; see section “Limitations” below.

     To process a [4mroff[24m input file using the preprocessors [4mtbl[24m and [4mpic[24m and the [4mme[0m
     macro package in the way to which AT&T [4mtroff[24m  users  were  accustomed,  one
     would type (or script) a pipeline.

            pic foo.me | tbl | troff -me -Tutf8 | grotty

     Shorten this pipeline to an equivalent command using [4mgroff[24m.

            groff -p -t -me -T utf8 foo.me

     An  even  easier way to do this is to use ]8;;man:grog(1)\[4mgrog[24m(1)]8;;\ to guess the preprocessor
     and macro options and execute the result by using the command  substitution
     feature of the shell.

            $(grog -Tutf8 foo.me)

     Each  command‐line option to a postprocessor must be specified with any re‐
     quired leading dashes “[1m-[22m” because [4mgroff[24m passes the arguments as‐is  to  the
     postprocessor; this permits arbitrary arguments to be transmitted.  For ex‐
     ample, to pass a title to the [4mgxditview[24m postprocessor, the shell commands
            groff -X -P -title -P 'trial run' mydoc.t
     and
            groff -X -Z mydoc.t | gxditview -title 'trial run' -
     are equivalent.

[1mLimitations[0m
     When  paging  output for the [1mascii[22m, [1mlatin1[22m, and [1mutf8 [22mdevices, programs like
     ]8;;man:more(1)\[4mmore[24m(1)]8;;\ and ]8;;man:less(1)\[4mless[24m(1)]8;;\ may require command‐line options  to  correctly  handle
     some terminal escape sequences; see ]8;;man:grotty(1)\[4mgrotty[24m(1)]8;;\.

[1mInstallation directories[0m
     GNU  [4mroff[24m installs files in varying locations depending on its compile‐time
     configuration.  On this installation, the following locations are used.

     [4m/usr/bin[0m
            Directory containing [4mgroff[24m’s executable commands.

     [4m/usr/share/groff/1.24.1/eign[0m
            List of common words for ]8;;man:indxbib(1)\[4mindxbib[24m(1)]8;;\.

     [4m/usr/share/groff/1.24.1[0m
            Directory for data files.

     [4m/usr/dict/papers/Ind[0m
            Default index for ]8;;man:lkbib(1)\[4mlkbib[24m(1)]8;;\ and ]8;;man:refer(1)\[4mrefer[24m(1)]8;;\.

     [4m/usr/share/doc/groff-1.24.1[0m
            Documentation directory.

     [4m/usr/share/doc/groff-1.24.1/examples[0m
            Example directory.

     [4m/usr/share/groff/1.24.1/font[0m
            Font directory.

     [4m/usr/share/doc/groff-1.24.1/html[0m
            HTML documentation directory.

     [4m/usr/lib/font[0m
            Legacy font directory.

     [4m/usr/share/groff/site-font[0m
            Local font directory.

     [4m/usr/share/groff/site-tmac[0m
            Local macro package ([4mtmac[24m file) directory.

     [4m/usr/share/groff/1.24.1/tmac[0m
            Macro package ([4mtmac[24m file) directory.

     [4m/usr/share/groff/1.24.1/oldfont[0m
            Font directory for compatibility with old  versions  of  [4mgroff[24m;  see
            ]8;;man:grops(1)\[4mgrops[24m(1)]8;;\.

     [4m/usr/share/doc/groff-1.24.1/pdf[0m
            PDF documentation directory.

   [4m[1mgroff[24m macro directory[0m
     Most  macro  files  supplied  with GNU [4mroff[24m are stored in [4m/usr/share/groff/[0m
     [4m1.24.1/tmac[24m for the installation corresponding  to  this  document.   As  a
     rule, multiple directories are searched for macro files; see ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\.  For
     a catalog of macro files GNU [4mroff[24m provides, see ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\.

   [4m[1mgroff[24m device and font description directory[0m
     Device  and  font  description  files  supplied with GNU [4mroff[24m are stored in
     [4m/usr/share/groff/1.24.1/font[24m for the  installation  corresponding  to  this
     document.  As a rule, multiple directories are searched for device and font
     description  files;  see  ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\.   For  the  formats of these files, see
     ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

[1mAvailability[0m
     Obtain links to [4mgroff[24m releases for download, its source repository, discus‐
     sion mailing lists, a support ticket tracker, and further information  from
     the ]8;;http://www.gnu.org/software/groff\[4mgroff[24m page of the GNU website]8;;\.

     A  free  implementation of the [4mgrap[24m preprocessor, written by ]8;;mailto:faber@lunabase.org\Ted Faber]8;;\, can
     be found at the ]8;;http://www.lunabase.org/~faber/Vault/software/grap/\[4mgrap[24m website]8;;\.  [4mgroff[24m supports only this [4mgrap[24m.

[1mAuthors[0m
     [4mgroff[24m (both the front‐end command and the  overall  system)  was  primarily
     written by ]8;;mailto:jjc@jclark.com\James Clark]8;;\.  Contributors to this document include Clark, Trent
     A. Fisher, ]8;;mailto:wl@gnu.org\Werner Lemberg]8;;\, ]8;;mailto:groff-bernd.warken-72@web.de\Bernd Warken]8;;\, and ]8;;mailto:g.branden.robinson@gmail.com\G. Branden Robinson]8;;\.

[1mSee also[0m
     [4mGroff:[24m  [4mThe[24m [4mGNU[24m [4mImplementation[24m [4mof[24m [4mtroff[24m, by Trent A. Fisher and Werner Lem‐
     berg, is the primary [4mgroff[24m manual.  You can browse  it  interactively  with
     “info groff”.

     A  list of all [4mgroff[24m man pages follows.  A few ([4mgrohtml[24m, [4mgropdf[24m, [4mgxditview[24m,
     and [4mxtotroff[24m) will be unavailable if their corresponding programs were dis‐
     abled during compilation.

     Introduction, history, and further reading:
            ]8;;man:roff(7)\[4mroff[24m(7)]8;;\

     Viewer for [4mgroff[24m (and AT&T device‐independent [4mtroff[24m) documents:
            ]8;;man:gxditview(1)\[4mgxditview[24m(1)]8;;\

     Preprocessors:
            ]8;;man:chem(1)\[4mchem[24m(1)]8;;\,  ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\,   ]8;;man:neqn(1)\[4mneqn[24m(1)]8;;\,   ]8;;man:glilypond(1)\[4mglilypond[24m(1)]8;;\,   ]8;;man:grn(1)\[4mgrn[24m(1)]8;;\,   ]8;;man:preconv(1)\[4mpreconv[24m(1)]8;;\,
            ]8;;man:gperl(1)\[4mgperl[24m(1)]8;;\, ]8;;man:pic(1)\[4mpic[24m(1)]8;;\, ]8;;man:gpinyin(1)\[4mgpinyin[24m(1)]8;;\, ]8;;man:refer(1)\[4mrefer[24m(1)]8;;\, ]8;;man:soelim(1)\[4msoelim[24m(1)]8;;\, ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\

     Macro packages:
            ]8;;man:groff_hdtbl(7)\[4mgroff_hdtbl[24m(7)]8;;\,   ]8;;man:groff_man(7)\[4mgroff_man[24m(7)]8;;\,  ]8;;man:groff_man_style(7)\[4mgroff_man_style[24m(7)]8;;\,  ]8;;man:groff_mdoc(7)\[4mgroff_mdoc[24m(7)]8;;\,
            ]8;;man:groff_me(7)\[4mgroff_me[24m(7)]8;;\, ]8;;man:groff_mm(7)\[4mgroff_mm[24m(7)]8;;\, ]8;;man:groff_mmse(7)\[4mgroff_mmse[24m(7)]8;;\, ]8;;man:groff_mom(7)\[4mgroff_mom[24m(7)]8;;\,  ]8;;man:groff_ms(7)\[4mgroff_ms[24m(7)]8;;\,
            ]8;;man:groff_rfc1345(7)\[4mgroff_rfc1345[24m(7)]8;;\, ]8;;man:groff_trace(7)\[4mgroff_trace[24m(7)]8;;\, ]8;;man:groff_www(7)\[4mgroff_www[24m(7)]8;;\

     Bibliographic database management tools:
            ]8;;man:indxbib(1)\[4mindxbib[24m(1)]8;;\, ]8;;man:lkbib(1)\[4mlkbib[24m(1)]8;;\, ]8;;man:lookbib(1)\[4mlookbib[24m(1)]8;;\

     Language, conventions, and GNU extensions:
            ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\, ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\, ]8;;man:groff_diff(7)\[4mgroff_diff[24m(7)]8;;\, ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\, ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\

     Device‐independent page description language:
            ]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\

     Formatter program:
            ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\

     Formatter wrappers:
            ]8;;man:nroff(1)\[4mnroff[24m(1)]8;;\, ]8;;man:mmroff(1)\[4mmmroff[24m(1)]8;;\, ]8;;man:pdfmom(1)\[4mpdfmom[24m(1)]8;;\

     Postprocessors for output devices:
            ]8;;man:grodvi(1)\[4mgrodvi[24m(1)]8;;\,  ]8;;man:grohtml(1)\[4mgrohtml[24m(1)]8;;\,  ]8;;man:grolbp(1)\[4mgrolbp[24m(1)]8;;\,  ]8;;man:grolj4(1)\[4mgrolj4[24m(1)]8;;\, ]8;;man:gropdf(1)\[4mgropdf[24m(1)]8;;\, ]8;;man:grops(1)\[4mgrops[24m(1)]8;;\,
            ]8;;man:grotty(1)\[4mgrotty[24m(1)]8;;\

     Font support utilities:
            ]8;;man:addftinfo(1)\[4maddftinfo[24m(1)]8;;\,  ]8;;man:afmtodit(1)\[4mafmtodit[24m(1)]8;;\,  ]8;;man:hpftodit(1)\[4mhpftodit[24m(1)]8;;\,  ]8;;man:pfbtops(1)\[4mpfbtops[24m(1)]8;;\,  ]8;;man:tfmtodit(1)\[4mtfmtodit[24m(1)]8;;\,
            ]8;;man:xtotroff(1)\[4mxtotroff[24m(1)]8;;\

     Graphics conversion utilities:
            ]8;;man:eqn2graph(1)\[4meqn2graph[24m(1)]8;;\, ]8;;man:grap2graph(1)\[4mgrap2graph[24m(1)]8;;\, ]8;;man:pic2graph(1)\[4mpic2graph[24m(1)]8;;\

     Difference‐marking utility:
            ]8;;man:gdiffmk(1)\[4mgdiffmk[24m(1)]8;;\

     “groff guess” utility:
            ]8;;man:grog(1)\[4mgrog[24m(1)]8;;\

groff 1.24.1                       2026‐03‐20                           [4mgroff[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mgrog[24m(1)                      General Commands Manual                     [4mgrog[24m(1)

[1mName[0m
     grog - “groff guess”——infer the [4mgroff[24m command a document requires

[1mSynopsis[0m
     [1mgrog [22m[[4mgroff‐option[24m ...] [[1m--[22m] [[4mfile[24m ...]

     [1mgrog -h[0m
     [1mgrog --help[0m

     [1mgrog -v[0m
     [1mgrog --version[0m

[1mDescription[0m
     [4mgrog[24m  reads its input and guesses which ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ options are needed to ren‐
     der it.  If no operands are given, or if [4mfile[24m is “[1m-[22m”, [4mgrog[24m reads the  stan‐
     dard  input stream.  The corresponding [4mgroff[24m command is normally written to
     the standard output stream.

[1mOptions[0m
     [1m-h [22mand [1m--help [22mdisplay a usage message, whereas  [1m-v  [22mand  [1m--version  [22mdisplay
     version information; all exit afterward.

     All  other specified short options (that is, arguments beginning with a mi‐
     nus sign “[1m-[22m” followed by a letter) are interpreted as [4mgroff[24m options or  op‐
     tion  clusters  with  or  without an option argument.  Such options are in‐
     cluded in the constructed [4mgroff[24m command line.

[1mDetails[0m
     [4mgrog[24m reads each [4mfile[24m operand, pattern‐matching strings that  are  statisti‐
     cally  likely to be characteristic of ]8;;man:roff(7)\[4mroff[24m(7)]8;;\ documents.  It tries to guess
     which of the following [4mgroff[24m options are required to correctly  render  the
     input:  [1m-e[22m,  [1m-g[22m,  [1m-G[22m,  [1m-j[22m,  [1m-p[22m,  [1m-R[22m,  [1m-t  [22m(preprocessors); and [1m-man[22m, [1m-mdoc[22m,
     [1m-mdoc-old[22m, [1m-me[22m, [1m-mm[22m, [1m-mom[22m, and [1m-ms [22m(macro packages).   The  inferred  [4mgroff[0m
     command  including  these options and any [4mfile[24m parameters is written to the
     standard output stream.

     It is possible to specify arbitrary [4mgroff[24m  options  on  the  command  line.
     These  are  included  in  the  inferred command without change.  Choices of
     [4mgroff[24m options include [1m-C [22mto enable AT&T [4mtroff[24m compatibility mode and [1m-T  [22mto
     select  a  non‐default  output  device.   If  the  input  is not encoded in
     ISO 646:1991 IRV (US‐ASCII) or ISO Latin‐1 (8859‐1), we advise specifying a
     [4mgroff[24m option to run ]8;;man:preconv(1)\[4mpreconv[24m(1)]8;;\; see the [1m-D[22m, [1m-k[22m, and [1m-K [22moptions of ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\.
     For UTF‐8 input, [1m-k [22mis a good choice.

     [4mgroff[24m may issue diagnostic messages when an  inappropriate  [1m-m  [22moption,  or
     multiple  conflicting  ones,  are  specified.   Consequently, it is best to
     specify no [1m-m [22moptions to [4mgrog[24m unless it cannot correctly infer all  of  the
     [1m-m  [22marguments  a  document  requires.   A [4mroff[24m document can also be written
     without recourse to any macro package.  In such cases, [4mgrog[24m infers a  [4mgroff[0m
     command without an [1m-m [22moption.

   [1mLimitations[0m
     [4mgrog[24m  presumes  that  the input does not change the escape, control, or no‐
     break control characters.  [4mgrog[24m does not parse [4mroff[24m input line continuation
     or control structures (brace escape sequences and the “[1mif[22m”, “[1mie[22m”, and  “[1mel[22m”
     requests) nor [4mgroff[24m’s “[1mwhile[22m”.  Thus the input
            .if \
            t .NH 1
            .if n .SH
            Introduction
     conceals  the use of the [4mms[24m macros [1mNH [22mand [1mSH [22mfrom [4mgrog[24m.  Such constructions
     are regarded by [4mgrog[24m’s implementors as insufficiently common to cause  many
     inference problems.  Preprocessors can be even stricter when matching macro
     calls that bracket the regions of an input file they replace.  [4mpic[24m, for ex‐
     ample, requires [1mPS[22m, [1mPE[22m, and [1mPF [22mcalls to immediately follow the default con‐
     trol character at the beginning of a line.

     Detection  of the [1m-s [22moption (the ]8;;man:soelim(1)\[4msoelim[24m(1)]8;;\ preprocessor) is tricky; to cor‐
     rectly infer its necessity would require [4mgrog[24m to recursively open all files
     given as arguments to the [1m.so [22mrequest under the same conditions that [4msoelim[0m
     itself does so; see its man page.  Recall that [4msoelim[24m is necessary only  if
     sourced files need to be preprocessed.  Therefore, as a workaround, you may
     want  to run the input through [4msoelim[24m manually, piping it to [4mgrog[24m, and com‐
     pare the output to running [4mgrog[24m on the input directly.  If  the  “[4msoelim[24m”ed
     input  causes  [4mgrog[24m  to  infer  additional preprocessor options, then [1m-s [22mis
     likely necessary.

            $ [1mprintf ".TS\nl.\nI'm a table.\n.TE\n" > 3.roff[0m
            $ [1mprintf ".so 3.roff\n" > 2.roff[0m
            $ [1mprintf ".XP\n.so 2.roff\n" > 1.roff[0m
            $ [1mgrog 1.roff[0m
            groff -ms 1.roff
            $ [1msoelim 1.roff | grog[0m
            groff -t -ms -

     In the foregoing example, we see that this procedure enabled [4mgrog[24m to detect
     ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\ macros, so we would add [1m-s [22mas well as the detected [1m-t  [22moption  to  a
     revised [4mgrog[24m or [4mgroff[24m command.

            $ [1mgrog -st 1.roff[0m
            groff -st -ms 1.roff

[1mExit status[0m
     [4mgrog[24m exits with status [1m1 [22mif a macro package appears to be in use by the in‐
     put  document,  but  [4mgrog[24m was unable to infer which one, or [1m2 [22mif there were
     problems handling an option or operand.  It otherwise exits with status  [1m0[22m.
     Inferring  no  preprocessors or macro packages is not an error condition; a
     valid [4mroff[24m document need not use either.  Even plain text is  valid  input,
     if one is mindful of the syntax of the control and escape characters.

[1mExamples[0m
     Running
            [1mgrog /usr/share/doc/groff-1.24.1/meintro.me[0m
     at the command line results in
            groff -me /usr/share/doc/groff-1.24.1/meintro.me
     because  [4mgrog[24m  recognizes  that the file [4mmeintro.me[24m is written using macros
     from the [4mme[24m package.  The command
            [1mgrog /usr/share/doc/groff-1.24.1/pic.ms[0m
     outputs
            groff -e -p -t -ms /usr/share/doc/groff-1.24.1/pic.ms
     on the other hand.  Besides discerning the [4mms[24m macro  package,  [4mgrog[24m  recog‐
     nizes  that  the  file  [4mpic.ms[24m additionally needs the combination of [1m-t [22mfor
     [4mtbl[24m, [1m-e [22mfor [4meqn[24m, and [1m-p [22mfor [4mpic[24m.

     Consider a file [4mdoc/grnexampl.me[24m, which uses the [4mgrn[24m  preprocessor  to  in‐
     clude  a  ]8;;man:gremlin(1)\[4mgremlin[24m(1)]8;;\  picture file in an [4mme[24m document.  Let’s say we want to
     suppress color output, produce a DVI file, and get backtraces for  any  er‐
     rors that [4mtroff[24m encounters.  The command
            [1mgrog -bc -Idoc -Tdvi doc/grnexmpl.me[0m
     is processed by [4mgrog[24m into
            groff -bc -Idoc -Tdvi -e -g -me doc/grnexmpl.me
     where we can see that [4mgrog[24m has inferred the [4mme[24m macro package along with the
     [4meqn[24m  and  [4mgrn[24m preprocessors.  (The input file is located in [4m/usr/share/doc/[0m
     [4mgroff-1.24.1[24m if you’d like to try this example yourself.)

[1mAuthors[0m
     [4mgrog[24m was originally written in Bourne shell by James  Clark.   The  current
     implementation  in  Perl was written by ]8;;mailto:groff-bernd.warken-72@web.de\Bernd Warken]8;;\ and heavily revised by
     ]8;;mailto:g.branden.robinson@gmail.com\G. Branden Robinson]8;;\.

[1mSee also[0m
     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\

groff 1.24.1                       2026‐03‐20                            [4mgrog[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mgrohtml[24m(1)                   General Commands Manual                  [4mgrohtml[24m(1)

[1mName[0m
     grohtml, post-grohtml, pre-grohtml - [4mgroff[24m output driver for HTML

[1mSynopsis[0m
     [1mpre-grohtml [22m[[1m-epV[22m] [[1m-a [4m[22manti‐aliasing‐text‐bits[24m] [[1m-D [4m[22mimage‐directory[24m]
                 [[1m-F [4m[22mfont‐directory[24m] [[1m-g [4m[22manti‐aliasing‐graphic‐bits[24m]
                 [[1m-i [4m[22mresolution[24m] [[1m-I [4m[22mimage‐stem[24m] [[1m-o [4m[22mimage‐vertical‐offset[24m]
                 [[1m-x [4m[22mhtml‐dialect[24m] [4mtroff‐command[24m [4mtroff‐argument[24m ...

     [1mpre-grohtml --help[0m

     [1mpre-grohtml -v[0m
     [1mpre-grohtml --version[0m

     [1mpost-grohtml [22m[[1m-bCGhlnrVy[22m] [[1m-F [4m[22mfont‐directory[24m] [[1m-j [4m[22moutput‐stem[24m]
                  [[1m-k [4m[22mencoding[24m] [[1m-s [4m[22mbase‐point‐size[24m] [[1m-S [4m[22mheading‐level[24m]
                  [[1m-x [4m[22mhtml‐dialect[24m] [[4mfile[24m ...]

     [1mpost-grohtml --help[0m

     [1mpost-grohtml -v[0m
     [1mpost-grohtml --version[0m

[1mDescription[0m
     The GNU [4mroff[24m system’s HTML support consists of a preprocessor, [4mpre-grohtml[24m,
     and an output driver, [4mpost-grohtml[24m; together, they translate ]8;;man:roff(7)\[4mroff[24m(7)]8;;\  docu‐
     ments to HTML.  Because a preprocessor is (uniquely) required for this out‐
     put  driver,  users should invoke [4mgrohtml[24m via the ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ command with the
     [1m-Thtml [22mor [1m-Txhtml [22moptions.  (In this installation, [1mps [22mis the default output
     device.)  Use [4mgroff[24m’s [1m-P [22moption to pass any options shown above to [4mgrohtml[24m.
     If no operands are given, or if [4mfile[24m is “[1m-[22m”, [4mgrohtml[24m reads the standard in‐
     put stream.  It writes to the standard output stream.

     [4mgrohtml[24m  invokes  [4mgroff[24m  twice.   In  the  first  pass,  the   preprocessor
     [4mpre-grohtml[24m renders pictures, equations, and tables as images in PostScript
     format  using  the [1mps [22moutput device.  In the second pass, the output driver
     [4mpost-grohtml[24m translates the output of ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ to HTML.

     [4mgrohtml[24m writes UTF‐8‐encoded output (but see the [1m-k  [22moption)  and  produces
     HTML  character  references for most non‐composite, non‐basic Latin Unicode
     characters.  In spite of this, [4mgroff[24m may issue warnings about unknown  spe‐
     cial  characters if they can’t be found during the first pass.  You can ig‐
     nore these warnings unless the special characters appear inside a table  or
     equation.

   [1mTypefaces[0m
     [4mgrohtml[24m supports the standard four styles: [1mR [22m(roman), [1mI [22m([4mitalic[24m), [1mB [22m([1mbold[22m),
     and  [1mBI [22m([4m[1mbold‐italic[24m[22m).  Fonts are grouped into families [1mT [22mand [1mC [22mhaving mem‐
     bers in each style.

            [1mTR     [22mTimes roman
            [1mTI     [22mTimes italic
            [1mTB     [22mTimes bold
            [1mTBI    [22mTimes bold‐italic
            [1mCR     [22mCourier roman
            [1mCI     [22mCourier italic
            [1mCB     [22mCourier bold
            [1mCBI    [22mCourier bold‐italic

     A special font, [1mS[22m, is also provided to accommodate [4mroff[24m documents that  ex‐
     pect it to always be available.

     [4mgrohtml[24m  furthermore  supports  a  naming  scheme  for East Asian typefaces
     shared with ]8;;man:gropdf(1)\[4mgropdf[24m(1)]8;;\, ]8;;man:grops(1)\[4mgrops[24m(1)]8;;\, and ]8;;man:grotty(1)\[4mgrotty[24m(1)]8;;\.

            [1mCSH    [22mSimplified Chinese, Hei style
            [1mCSS    [22mSimplified Chinese, Song style
            [1mCTH    [22mTraditional Chinese, Hei style
            [1mCTS    [22mTraditional Chinese, Song style
            [1mJPG    [22mJapanese, Gothic style
            [1mJPM    [22mJapanese, Mincho style
            [1mKOG    [22mKorean, Gothic style
            [1mKOM    [22mKorean, Mincho style

   [1mFont description files[0m
     The font description files used with [4mgrohtml[24m expose the same  glyph  reper‐
     toire in their [1mcharset [22msections.  See ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

   [1mDependencies[0m
     [4mpre-grohtml[24m  generates an image whenever an [4meqn[24m equation, [4mtbl[24m table, or [4mpic[0m
     picture is encountered in the input.  [4mgrohtml[24m  therefore  may  run  several
     commands  as part of its operation.  These include the Netpbm tools [4mpamcut[24m,
     [4mpnmcrop[24m, and [4mpnmtopng[24m, as well as Ghostscript’s [4mgs[24m and [4mps2ps[24m.

[1mOptions[0m
     [1m--help [22mdisplays a usage message, while [1m-v [22mand [1m--version [22mshow version infor‐
     mation; all exit afterward.

     [1m-a [4m[22manti‐aliasing‐text‐bits[0m
            Number of bits of antialiasing information to be used by  text  when
            generating  PNG  images.   The default is [1m4 [22mbut [1m0[22m, [1m1[22m, and [1m2 [22mare also
            valid.  Your system’s version of [4mgs[24m must support the [1m-dTextAlphaBits[0m
            option in order to exploit antialiasing.  A value of [1m0 [22mstops [4mgrohtml[0m
            from issuing antialiasing commands to [4mgs[24m.

     [1m-b     [22mInitialize the background color to white.

     [1m-C     [22mSuppress output of “CreationDate:” HTML comment.

     [1m-D [4m[22mimage‐directory[0m
            Instruct [4mgrohtml[24m to place all image files into  directory  [4mimage‐di‐[0m
            [4mrectory[24m.

     [1m-e     [22mDirect [4meqn[24m to produce MathML.

            This  option  should not be manually specified; it is synthesized by
            [4mgroff[24m depending on whether it was given the [1m-Thtml  [22mor  [1m-Txhtml  [22mop‐
            tion.

     [1m-F [4m[22mfont‐directory[0m
            Prepend directory font‐directory[4m/dev[24mname to the search path for font
            and  device  description files; [4mname[24m is the name of the device, usu‐
            ally [1mhtml[22m.

     [1m-g [4m[22manti‐aliasing‐graphic‐bits[0m
            Number of bits of antialiasing information to be  used  by  graphics
            when  generating  PNG  images.  The default is [1m4 [22mbut [1m0[22m, [1m1[22m, and [1m2 [22mare
            also  valid.   Your  system’s  version  of  [4mgs[24m  must   support   the
            [1m-dGraphicAlphaBits [22moption in order to exploit antialiasing.  A value
            of [1m0 [22mstops [4mgrohtml[24m from issuing antialiasing commands to [4mgs[24m.

     [1m-G     [22mSuppress output of “Creator:” HTML comment.

     [1m-h     [22mGenerate  section  headings  by using HTML [1mB [22melements and increasing
            the font size, rather than HTML [1mH [22melements.

     [1m-i [4m[22mresolution[0m
            Set the image resolution in pixels per inch; the default is [1m100[22m.

     [1m-I [4m[22mimage‐stem[0m
            Determine the image  file  name  stem.   If  omitted,  [4mgrohtml[24m  uses
            [4mgrohtml-[24mXXXXX  (where  [4mXXXXX[24m is the process ID).  A dash is appended
            to the stem to separate it from the following image number.

     [1m-j [4m[22moutput‐stem[0m
            Instruct [4mgrohtml[24m to split the HTML output into multiple files.  Out‐
            put is written to a new file at each section heading (but see option
            [1m-S [22mbelow) named [4moutput‐stem-[24mn[4m.html[24m.

     [1m-k [4m[22mencoding[0m
            Select the character encoding used in the  generated  document,  af‐
            fecting  the declared encoding in the preamble and the form of char‐
            acter entity references.  Valid values are “ASCII” and “UTF-8”.  The
            default is “UTF‐8”.

     [1m-l     [22mTurn off the production of automatic section links at the top of the
            document.

     [1m-n     [22mGenerate simple heading anchors whenever a section/number heading is
            found.  Without the option the anchor value is the textual  heading.
            This  can cause problems when a heading contains a “?” on older ver‐
            sions of some browsers.  This feature is automatically enabled if  a
            heading contains an image.

     [1m-o [4m[22mimage‐vertical‐offset[0m
            Specify the vertical offset of images in points.

     [1m-p     [22mDisplay  page  rendering  progress  to  the  standard  error stream.
            [4mgrohtml[24m displays a page number only when an image is required.

     [1m-r     [22mTurn off the automatic header and footer line (HTML rule).

     [1m-s [4m[22mbase‐type‐size[0m
            Set the document’s base type size in points.  When this size is used
            in the source, it corresponds to the HTML base type size.  Every in‐
            crease of two points in the source will produce a “[1mbig[22m” element, and
            conversely when a decrease of two points is seen, a “[1msmall[22m”  element
            is emitted.

     [1m-S [4m[22mheading‐level[0m
            When  splitting  HTML  output  (see  option [1m-j [22mabove), split at each
            nested heading level defined by [4mheading‐level[24m, or higher).  The  de‐
            fault is [1m1[22m.

     [1m-V     [22mCreate  an XHTML or HTML validator button at the bottom of each page
            of the document.

     [1m-x [4m[22mhtml‐dialect[0m
            Select HTML dialect.  Currently, [4mhtml‐dialect[24m should be  either  the
            digit [1m4 [22mor the letter [1mx[22m, which indicates whether [4mgrohtml[24m should gen‐
            erate HTML 4 or XHTML, respectively.

            This  option  should not be manually specified; it is synthesized by
            [4mgroff[24m depending on whether it was given the [1m-Thtml  [22mor  [1m-Txhtml  [22mop‐
            tion.

     [1m-y     [22mProduce  a  right‐aligned [4mgroff[24m signature at the end of the document
            (only if [1m-V [22mis also specified).

[1mExit status[0m
     [4mpre-grohtml[24m and [4mpost-grohtml[24m each exit with status [1m0 [22mon  successful  opera‐
     tion,  status [1m2 [22mif the program cannot interpret its command‐line arguments,
     and status [1m1 [22mif it encounters an error during operation.

[1mEnvironment[0m
     [4mGROFF_FONT_PATH[0m
            lists directories in which to search for [4mdevhtml[24m,  [4mgrohtml[24m’s  direc‐
            tory  of  device  and  font  description  files.   See  ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ and
            ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

     [4mSOURCE_DATE_EPOCH[0m
            A timestamp (expressed as seconds since the Unix epoch)  to  use  as
            the  output  creation  timestamp  in place of the current time.  The
            time  is  converted  to  human‐readable  form  using  ]8;;man:gmtime(3)\[4mgmtime[24m(3)]8;;\  and
            ]8;;man:asctime(3)\[4masctime[24m(3)]8;;\, and recorded in an HTML comment.

     [4mTZ[24m     The time zone to use when converting the current time to human‐read‐
            able form; see ]8;;man:tzset(3)\[4mtzset[24m(3)]8;;\.  If [4mSOURCE_DATE_EPOCH[24m is used, it is always
            converted to human‐readable form using UTC.

[1mFiles[0m
     [4m/usr/share/groff/1.24.1/font/devhtml/DESC[0m
            describes the [1mhtml [22moutput device.

     [4m/usr/share/groff/1.24.1/font/devhtml/[24mF
            describes the font known as [4mF[24m on device [1mhtml[22m.

     [4m/usr/share/groff/1.24.1/tmac/html.tmac[0m
            defines  font  mappings, special characters, and colors for use with
            the [1mhtml [22moutput device.  It is automatically loaded by [4mtroffrc[24m  when
            either of the [1mhtml [22mor [1mxhtml [22moutput devices is selected.

     [4m/usr/share/groff/1.24.1/tmac/html-end.tmac[0m
            finalizes  setup  of  the  [1mhtml  [22moutput device.  It is automatically
            loaded by [4mtroffrc-end[24m when either of the [1mhtml [22mor  [1mxhtml  [22moutput  de‐
            vices is selected.

     [4mgrohtml[24m  uses  temporary  files.  See ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ for details about where such
     files are created.

[1mBugs[0m
     [4mgrohtml[24m is still beta code.

     [4mgrohtml[24m does not truly support hyphenation, but you can fool  it  into  hy‐
     phenating  long input lines, which can appear in HTML output with a hyphen‐
     ated word followed by a space but no line break.

[1mSee also[0m
     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\, ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\

groff 1.24.1                       2026‐03‐20                         [4mgrohtml[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mgrolbp[24m(1)                    General Commands Manual                   [4mgrolbp[24m(1)

[1mName[0m
     grolbp - [4mgroff[24m output driver for Canon CaPSL printers

[1mSynopsis[0m
     [1mgrolbp [22m[[1m-l[22m] [[1m-c [4m[22mnum‐copies[24m] [[1m-F [4m[22mfont‐directory[24m] [[1m-o [4m[22morientation[24m] [[1m-p [4m[22mpaper‐[0m
            [4mformat[24m] [[1m-w [4m[22mwidth[24m] [[4mfile[24m ...]
     [1mgrolbp [22m[[1m--copies=[4m[22mnum‐copies[24m] [[1m--fontdir=[4m[22mfont‐directory[24m] [[1m--landscape[22m]
            [[1m--linewidth=[4m[22mwidth[24m] [[1m--orientation=[4m[22morientation[24m] [[1m--papersize=[4m[22mpaper‐[0m
            [4mformat[24m] [[4mfile[24m ...]

     [1mgrolbp -h[0m
     [1mgrolbp --help[0m

     [1mgrolbp -v[0m
     [1mgrolbp --version[0m

[1mDescription[0m
     This GNU [4mroff[24m output driver translates the output of ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ into a  CaPSL
     and  VDM  format  suitable  for  Canon LBP‐4 and LBP‐8 printers.  Normally,
     [4mgrolbp[24m is invoked by ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ when the latter is given the “[1m-T lbp[22m” option.
     (In this installation, [1mps [22mis the default output device.)   Use  [4mgroff[24m’s  [1m-P[0m
     option to pass any options shown above to [4mgrolbp[24m.  If no [4mfile[24m arguments are
     given,  or  if  [4mfile[24m  is  “-”,  [4mgrolbp[24m reads the standard input stream.  It
     writes to the standard output stream.

   [1mTypefaces[0m
     The driver supports the Dutch, Swiss, and Swiss‐Narrow scalable  typefaces,
     each  in  the regular, bold, italic, and bold‐italic styles.  Additionally,
     the bitmapped, monospaced Courier and Elite typefaces are available in reg‐
     ular, bold, and italic styles; Courier at 8 and 12 points, Elite at  8  and
     10 points.  The following chart summarizes the [4mgroff[24m font names used to ac‐
     cess them.

           ┌───────────────┬─────────┬────────┬──────────┬──────────────┐
           │   [1mTypeface    [22m│  [1mRoman  [22m│  [1mBold  [22m│  [1mItalic  [22m│  [1mBold‐Italic [22m│
           ├───────────────┼─────────┼────────┼──────────┼──────────────┤
           │ Dutch         │  TR     │  TB    │  TI      │  TBI         │
           ├───────────────┼─────────┼────────┼──────────┼──────────────┤
           │ Swiss         │  HR     │  HB    │  HI      │  HBI         │
           ├───────────────┼─────────┼────────┼──────────┼──────────────┤
           │ Swiss Narrow  │  HNR    │  HNB   │  HNI     │  HNBI        │
           ├───────────────┼─────────┼────────┼──────────┼──────────────┤
           │ Courier       │  CR     │  CB    │  CI      │              │
           ├───────────────┼─────────┼────────┼──────────┼──────────────┤
           │ Elite         │  ER     │  EB    │  EI      │              │
           └───────────────┴─────────┴────────┴──────────┴──────────────┘

   [1mPaper format, orientation, and device description file[0m
     [4mgrolbp[24m  supports  paper  formats  “[1mA4[22m”, “[1mletter[22m”, “[1mlegal[22m”, and “[1mexecutive[22m”.
     These are matched case‐insensitively.  The [1m-p[22m, [1m--papersize [22moption overrides
     any setting in the device description file [4mDESC[24m.  If  neither  specifies  a
     paper format, A4 is assumed.

     In its [4mDESC[24m file, [4mgrolbp[24m (case‐insensitively) recognizes an [1morientation [22mdi‐
     rective accepting one mandatory argument, [1mportrait [22mor [1mlandscape[22m.  The first
     valid orientation directive encountered controls.  The [1m-l[22m, [1m-o[22m, and [1m--orien‐[0m
     [1mtation  [22mcommand‐line  options override any setting in [4mDESC[24m.  If none of the
     foregoing specify the orientation, portrait is assumed.

   [1mFont description files[0m
     In  addition  to  the  font  description  file  directives  documented   in
     ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\, [4mgrolbp[24m recognizes [1mlbpname[22m, which maps the [4mgroff[24m font name to
     the font name used internally by the printer.  Its syntax is as follows.
            lbpname [4mprinter‐font‐name[0m
     [1mlbpname[22m’s argument is case‐sensitive.  The printer’s font names are encoded
     as follows.

     For bitmapped fonts, [4mprinter‐font_name[24m has the form [1mN[22m⟨[4mbase‐font‐name[24m⟩⟨[4mfont‐[0m
     [4mstyle[24m⟩.   [4mbase‐font‐name[24m  is  the  font name as it appears in the printer’s
     font listings without the first letter, up to (but not including) the  font
     size.   [4mfont‐style[24m can be one of the letters [1mR[22m, [1mI[22m, or [1mB[22m, indicating the ro‐
     man, italic, and bold styles, respectively.  For instance, if the printer’s
     “font listing A” shows “Nelite12I.ISO_USA”, the corresponding entry in  the
     [4mgroff[24m  font  description file is “[1mlbpname NeliteI[22m”.  You may need to modify
     [4mgrolbp[24m to add support for new bitmapped fonts,  since  the  available  font
     names  and  font  sizes  of bitmapped fonts (as documented above) are hard‐
     coded into the program.

     For scalable fonts, [4mprinter‐font‐name[24m is identical to the font name  as  it
     appears  in  the  printer’s  “font listing A”.  For instance, to select the
     “Swiss” font in bold‐italic style, which appears in  the  font  listing  as
     “Swiss-BoldOblique”, “[1mlbpname Swiss-BoldOblique[22m” is the required directive,
     and this is what we find in the [4mgroff[24m font description file [4mHBI[24m for the [1mlbp[0m
     device.

   [1mDrawing commands[0m
     For  compatibility  with ]8;;man:grolj4(1)\[4mgrolj4[24m(1)]8;;\, an additional drawing command is avail‐
     able.

     [1m\D'R [4m[22mdh[24m [4mdv[24m[1m'[0m
            Draw a rule (solid black rectangle) with one corner at  the  drawing
            position, and the diagonally opposite corner at the drawing position
            +([4mdh[24m,[4mdv[24m).

[1mOptions[0m
     [1m-h  [22mand [1m--help [22mdisplay a usage message, while [1m-v [22mand [1m--version [22mshow version
     information; all exit afterward.

     [1m-c [4m[22mnum‐copies[0m
     [1m--copies=[4m[22mnum‐copies[0m
            Produce [4mnum‐copies[24m copies of each page.

     [1m-F [4m[22mfont‐directory[0m
     [1m--fontdir=[4m[22mfont‐directory[0m
            Prepend directory font‐directory[4m/dev[24mname to the search path for font
            and device description files; [4mname[24m is the name of the  device,  usu‐
            ally [1mlbp[22m.

     [1m-l[0m
     [1m--landscape[0m
            Format the document in landscape orientation.

     [1m-o [4m[22morientation[0m
     [1m--orientation=[4m[22morientation[0m
            Format  the  document  in  the  given  [4morientation[24m,  which  must  be
            “[1mportrait[22m” or “[1mlandscape[22m”.

     [1m-p [4m[22mpaper‐format[0m
     [1m--papersize=[4m[22mpaper‐format[0m
            Set the paper format to [4mpaper‐format[24m, which must be  a  valid  paper
            format as described above.

     [1m-w [4m[22mwidth[0m
     [1m--linewidth=[4m[22mwidth[0m
            Set  the  default  line thickness to [4mwidth[24m thousandths of an em; the
            default is [1m40 [22m(0.04 em).

[1mExit status[0m
     [4mgrolbp[24m exits with status [1m0 [22mon successful operation, status [1m2 [22mif the program
     cannot interpret its command‐line arguments, and status [1m1 [22mif it  encounters
     an error during operation.

[1mEnvironment[0m
     [4mGROFF_FONT_PATH[0m
            lists  directories in which to seek the selected output device’s di‐
            rectory of device and font  description  files.   See  ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\  and
            ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

[1mFiles[0m
     [4m/usr/share/groff/1.24.1/font/devlbp/DESC[0m
            describes the [1mlbp [22moutput device.

     [4m/usr/share/groff/1.24.1/font/devlbp/[24mF
            describes the font known as [4mF[24m on device [1mlbp[22m.

     [4m/usr/share/groff/1.24.1/tmac/lbp.tmac[0m
            defines  macros for use with the [1mlbp [22moutput device.  It is automati‐
            cally loaded by [4mtroffrc[24m when the [1mlbp [22moutput device is selected.

[1mSee also[0m
     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\, ]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\, ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\, ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\

groff 1.24.1                       2026‐03‐20                          [4mgrolbp[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mgrolj4[24m(1)                    General Commands Manual                   [4mgrolj4[24m(1)

[1mName[0m
     grolj4 - [4mgroff[24m output driver for HP LaserJet 4 and compatible printers

[1mSynopsis[0m
     [1mgrolj4 [22m[[1m-l[22m] [[1m-c [4m[22mnum‐copies[24m] [[1m-d [22m[[4mn[24m]] [[1m-F [4m[22mfont‐directory[24m] [[1m-p [4m[22mpaper‐format[24m]
            [[1m-w [4m[22mline‐width[24m] [[4mfile[24m ...]

     [1mgrolj4 --help[0m

     [1mgrolj4 -v[0m
     [1mgrolj4 --version[0m

[1mDescription[0m
     This GNU [4mroff[24m output driver translates the output of ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ into  a  PCL5
     format suitable for a Hewlett‐Packard LaserJet 4 printer.  Normally, [4mgrolj4[0m
     is  invoked  by ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ when the latter is given the “[1m-T lj4[22m” option.  (In
     this installation, [1mps [22mis the default output device.)  Use [4mgroff[24m’s [1m-P [22moption
     to pass any options shown above to [4mgrolj4[24m.  If no [4mfile[24m arguments are given,
     or if [4mfile[24m is “-”, [4mgrolj4[24m reads the standard input stream.   It  writes  to
     the standard output stream.

   [1mTypefaces[0m
     [4mgrolj4[24m  supports the standard four styles: [1mR [22m(roman), [1mI [22m([4mitalic[24m), [1mB [22m([1mbold[22m),
     and [1mBI [22m([4m[1mbold‐italic[24m[22m).  Fonts are grouped into families [1mA[22m, [1mC[22m, [1mG[22m, [1mO[22m,  [1mT[22m,  [1mTN[22m,
     [1mU[22m,  and  [1mUC [22mhaving members in each style.  For the convenience of a consis‐
     tent font repertoire in [4mgroff[24m, [4mlj4.tmac[24m (see section  “Files”  below)  uses
     [1mftr  [22mrequests  to remap [1mH [22m(“Helvetica”) font names to the [1mU [22mnames shown be‐
     low.

            [1mAB       [22mArial Bold
            [1mABI      [22mArial Bold Italic
            [1mAI       [22mArial Italic
            [1mAR       [22mArial Roman
            [1mCB       [22mCourier Bold
            [1mCBI      [22mCourier Bold Italic
            [1mCI       [22mCourier Italic
            [1mCR       [22mCourier Roman
            [1mGB       [22mGaramond Halbfett
            [1mGBI      [22mGaramond Kursiv Halbfett
            [1mGI       [22mGaramond Kursiv
            [1mGR       [22mGaramond Antiqua
            [1mOB       [22mCG Omega Bold
            [1mOBI      [22mCG Omega Bold Italic
            [1mOI       [22mCG Omega Italic
            [1mOR       [22mCG Omega Roman
            [1mOB       [22mCG Omega Bold
            [1mOBI      [22mCG Omega Bold Italic
            [1mOI       [22mCG Omega Italic
            [1mOR       [22mCG Omega Roman
            [1mTB       [22mCG Times Bold
            [1mTBI      [22mCG Times Bold Italic
            [1mTI       [22mCG Times Italic
            [1mTR       [22mCG Times Roman
            [1mTNRB     [22mM Times Bold
            [1mTNRBI    [22mM Times Bold Italic
            [1mTNRI     [22mM Times Italic
            [1mTNRR     [22mM Times Roman
            [1mUB       [22mUnivers Bold
            [1mUBI      [22mUnivers Bold Italic
            [1mUI       [22mUnivers Medium Italic
            [1mUR       [22mUnivers Medium
            [1mUCB      [22mUnivers Condensed Bold
            [1mUCBI     [22mUnivers Condensed Bold Italic
            [1mUCI      [22mUnivers Condensed Medium Italic
            [1mUCR      [22mUnivers Condensed Medium

     The following fonts are not members of a family.

            [1mALBB           [22mAlbertus Extra Bold
            [1mALBR           [22mAlbertus Medium
            [1mAOB            [22mAntique Olive Bold
            [1mAOI            [22mAntique Olive Italic
            [1mAOR            [22mAntique Olive Roman
            [1mCLARENDON      [22mClarendon
            [1mCORONET        [22mCoronet
            [1mLGB            [22mLetter Gothic Bold
            [1mLGI            [22mLetter Gothic Italic
            [1mLGR            [22mLetter Gothic Roman
            [1mMARIGOLD       [22mMarigold

     The special font is [1mS [22m(PostScript Symbol); [1mSYMBOL [22m(M Symbol), and [1mWINGDINGS[0m
     (Wingdings) are also available but not mounted by default.

   [1mPaper format and device description file[0m
     [4mgrolj4[24m supports paper formats “[1mA4[22m”, “[1mB5[22m”, “[1mC5[22m”, “[1mcom10[22m”, “[1mDL[22m”, “[1mexecutive[22m”,
     “[1mlegal[22m”, “[1mletter[22m”, and “[1mmonarch[22m”.  These  are  matched  case‐insensitively.
     The  [1m-p  [22moption  overrides any setting in the device description file [4mDESC[24m.
     If neither specifies a paper format, “letter” is assumed.

   [1mFont description files[0m
     [4mgrolj4[24m recognizes four font description  file  directives  in  addition  to
     those documented in ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

     [1mpclweight [4m[22mn[0m
            Set  the  stroke  weight to [4mn[24m, an integer in the range -7 to +7; the
            default is 0.

     [1mpclstyle [4m[22mn[0m
            Set the style to [4mn[24m, an integer in the range 0 to 32767; the  default
            is 0.

     [1mpclproportional [4m[22mn[0m
            Set  the proportional spacing Boolean flag to [4mn[24m, which can be either
            0 or 1; the default is 0.

     [1mpcltypeface [4m[22mn[0m
            Set the typeface family to [4mn[24m, an integer in the range  0  to  65535;
            the default is 0.

   [1mDrawing commands[0m
     An  additional drawing command is recognized as an extension to those docu‐
     mented in ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\.

     [1m\D'R [4m[22mdh[24m [4mdv[24m[1m'[0m
            Draw a rule (solid black rectangle) with one corner at  the  drawing
            position, and the diagonally opposite corner at the drawing position
            +([4mdh[24m,[4mdv[24m),  at  which  the  drawing position will be afterward.  This
            generates a PCL fill rectangle command, and so will work on printers
            that do not support HP‐GL/2, unlike the other [1m\D [22mcommands.

   [1mFonts[0m
     Nominally, HP LaserJet 4‐series and newer printers have the  same  internal
     fonts.   45 fonts are scalable from 0.25 to 999.75 points in 0.25‐point in‐
     crements.  A Lineprinter font is available only at 8.5 points.

     The LaserJet font files included with [4mgroff[24m assume that all printers  since
     the  LaserJet 4 are identical.  There are some differences between fonts in
     the earlier and more recent printers, however.  The LaserJet 4 printer used
     Agfa Intellifont technology for 35 of the internal scalable fonts; the  re‐
     maining   10   scalable   fonts   were   TrueType.    Beginning   with  the
     LaserJet 4000‐series printers introduced in  1997,  all  scalable  internal
     fonts  have been TrueType.  The number of printable glyphs differs slightly
     between Intellifont and TrueType fonts (generally, the TrueType  fonts  in‐
     clude  more glyphs), and there are some minor differences in glyph metrics.
     Differences among printer models are described  in  the  [4mPCL[24m  [4m5[24m  [4mComparison[0m
     [4mGuide[24m  and  the  [4mPCL[24m  [4m5[24m  [4mComparison[24m [4mGuide[24m [4mAddendum[24m (for printers introduced
     since approximately 2001).

     LaserJet printers reference a glyph by a combination of a 256‐glyph  symbol
     set  and  an index within that symbol set.  Many glyphs appear in more than
     one symbol set; all combinations of symbol set and index that reference the
     same glyph are equivalent.  For each glyph, ]8;;man:hpftodit(1)\[4mhpftodit[24m(1)]8;;\ searches a list  of
     symbol sets, and selects the first set that contains the glyph.  The print‐
     ing code generated by [4mhpftodit[24m is an integer that encodes a numerical value
     for the symbol set in the high byte(s), and the index in the low byte.  See
     ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\  for  a  complete description of the font file format; symbol
     sets are described in greater detail in the [4mPCL[24m [4m5[24m [4mPrinter[24m [4mLanguage[24m  [4mTechni‐[0m
     [4mcal[24m [4mReference[24m [4mManual[24m.

     Two  of  the  scalable  fonts, Symbol and Wingdings, are bound to 256‐glyph
     symbol sets; the remaining scalable fonts, as well as the Lineprinter font,
     support numerous symbol sets, sufficient to enable printing  of  more  than
     600 glyphs.

     The metrics generated by [4mhpftodit[24m assume that the [4mDESC[24m file contains values
     of  1200 for [4mres[24m and 6350 for [4munitwidth[24m, or any combination (e.g., 2400 and
     3175) for which [4mres[24m × [4munitwidth[24m = 7620000.   Although  HP  PCL  5  LaserJet
     printers  support an internal resolution of 7200 units per inch, they use a
     16‐bit signed integer for positioning; if [1mdevlj4 [22mis to support U.S.  ledger
     paper  (11  in  ×  17  in;  in  =  inch),  the maximum usable resolution is
     32767 ÷ 17, or 1927 units per inch, which rounds down  to  1200  units  per
     inch.    If   the   largest   required   paper  dimension  is  less  (e.g.,
     8.5 in × 11 in, or A5), a greater [4mres[24m (and lesser [4munitwidth[24m) can be  speci‐
     fied.

     Font  metrics  for  Intellifont  fonts  were provided by Tagged Font Metric
     (TFM) files originally developed by Agfa/Compugraphic.  The TFM files  pro‐
     vided  for  these fonts supported 600+ glyphs and contained extensive lists
     of kerning pairs.

     To accommodate developers who had become accustomed to TFM files,  HP  also
     provided  TFM  files  for the 10 TrueType fonts included in the LaserJet 4.
     The TFM files for TrueType fonts generally included less  information  than
     the Intellifont TFMs, supporting fewer glyphs, and in most cases, providing
     no  kerning  information.  By the time the LaserJet 4000 printer was intro‐
     duced, most developers had migrated to other means of obtaining  font  met‐
     rics,  and  support for new TFM files was very limited.  The TFM files pro‐
     vided for the  TrueType  fonts  in  the  LaserJet  4000  support  only  the
     ISO Latin‐2 (8859‐2) symbol set, and include no kerning information; conse‐
     quently,  they  are  of little value for any but the most rudimentary docu‐
     ments.

     Because the Intellifont TFM files contain  considerably  more  information,
     they  generally  are preferable to the TrueType TFM files even for use with
     the TrueType fonts in the newer printers.  The  metrics  for  the  TrueType
     fonts are very close, though not identical, to those for the earlier Intel‐
     lifont fonts of the same names.  Although most output using the Intellifont
     metrics  with the newer printers is quite acceptable, a few glyphs may fail
     to print as expected.  The differences in glyph metrics may be particularly
     noticeable with composite parentheses, brackets, and braces used by ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\.
     A script, located in [4m/usr/share/groff/1.24.1/font/devlj4/generate[24m,  can  be
     used to adjust the metrics for these glyphs in the special font “S” for use
     with printers that have all TrueType fonts.

     At  the  time  HP last supported TFM files, only version 1.0 of the Unicode
     standard was available.  Consequently, many glyphs  lacking  assigned  code
     points  were  assigned by HP to the Private Use Area (PUA).  Later versions
     of the Unicode standard included code points outside the PUA  for  many  of
     these  glyphs.  The HP‐supplied TrueType TFM files use the PUA assignments;
     TFM files generated from more recent TrueType font files require the  later
     Unicode values to access the same glyphs.  Consequently, two different map‐
     ping  files may be required: one for the HP‐supplied TFM files, and one for
     more recent TFM files.

[1mOptions[0m
     [1m--help [22mdisplays a usage message, while [1m-v [22mand [1m--version [22mshow version infor‐
     mation; all exit afterward.

     [1m-c [4m[22mnum‐copies[0m
             Format [4mnum‐copies[24m copies of each page.

     [1m-d [22m[[4mn[24m]  Use duplex mode [4mn[24m: 1 is  long‐side  binding  (default),  and  2  is
             short‐side binding.

     [1m-F [4m[22mfont‐directory[0m
             Prepend  directory  [4mfont‐directory[24m/dev[4mname[24m  to  the search path for
             font and device description files; [4mname[24m is the name of the  device,
             usually [1mlj4[22m.

     [1m-l      [22mFormat the document in landscape orientation.

     [1m-p [4m[22mpaper‐format[0m
             Set  the  paper format to [4mpaper‐format[24m, which must be a valid paper
             format as described above.

     [1m-w [4m[22mline‐width[0m
             Set the default line thickness to [4mline‐width[24m thousandths of an  em;
             the default is [1m40 [22m(0.04 em).

[1mExit status[0m
     [4mgrolj4[24m exits with status [1m0 [22mon successful operation, status [1m2 [22mif the program
     cannot  interpret its command‐line arguments, and status [1m1 [22mif it encounters
     an error during operation.

[1mEnvironment[0m
     [4mGROFF_FONT_PATH[0m
            lists directories in which to seek the selected output device’s  di‐
            rectory  of  device  and  font  description files.  See ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ and
            ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

[1mFiles[0m
     [4m/usr/share/groff/1.24.1/font/devlj4/DESC[0m
            describes the [1mlj4 [22moutput device.

     [4m/usr/share/groff/1.24.1/font/devlj4/[24mF
            describes the font known as [4mF[24m on device [1mlj4[22m.

     [4m/usr/share/groff/1.24.1/tmac/lj4.tmac[0m
            defines macros for use with the [1mlj4 [22moutput device.  It is  automati‐
            cally loaded by [4mtroffrc[24m when the [1mlj4 [22moutput device is selected.

[1mBugs[0m
     Small dots.

[1mSee also[0m
     ]8;;http://www.hp.com/ctg/Manual/bpl13210.pdf\[4mHP[24m [4mPCL/PJL[24m [4mReference:[24m [4mPCL[24m [4m5[24m [4mPrinter[24m [4mLanguage[24m  [4mTechnical[24m  [4mReference[24m  [4mManual,[0m
     [4mPart[24m [4mI[24m]8;;\

     ]8;;man:hpftodit(1)\[4mhpftodit[24m(1)]8;;\, ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\, ]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\, ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\, ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\

groff 1.24.1                       2026‐03‐20                          [4mgrolj4[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mgropdf[24m(1)                    General Commands Manual                   [4mgropdf[24m(1)

[1mName[0m
     gropdf - [4mgroff[24m output driver for Portable Document Format

[1mSynopsis[0m
     [1mgropdf [22m[[1m-delsW[22m] [{[1m-f[22m|[1m--format‐options[22m} [4mbit‐vector[24m] [[1m-F [4m[22mfont‐directory[24m]
            [[1m-I [4m[22minclusion‐directory[24m] [[1m-p [4m[22mpaper‐format[24m] [[1m--pdfver [22m{[1m1.4[22m|[1m1.7[22m}]
            [[1m-u [22m[[4mcmap‐file[24m]] [[1m-y [4m[22mfoundry[24m] [[4mfile[24m ...]

     [1mgropdf --help[0m

     [1mgropdf -v[0m
     [1mgropdf --version[0m

[1mDescription[0m
     The  GNU  [4mroff[24m  PDF  output  driver  translates the output of ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ into
     Portable Document Format.  Normally, [4mgropdf[24m is invoked by ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ when the
     latter is given the “[1m-T pdf[22m” option.  (In this installation, [1mps [22mis the  de‐
     fault  output  device.)   Use  [4mgroff[24m’s  [1m-P [22moption to pass any options shown
     above to [4mgropdf[24m.  If no [4mfile[24m arguments are given, or if [4mfile[24m is “-”, [4mgropdf[0m
     reads the standard input stream.  It writes to the standard output stream.

     See section “Font installation” below for a guide to installing  fonts  for
     [4mgropdf[24m.

[1mOptions[0m
     [1m--help [22mdisplays a usage message, while [1m-v [22mand [1m--version [22mshow version infor‐
     mation; all exit afterward.

     [1m-d      [22mInclude  debug  information  as comments within the PDF.  Also pro‐
             duces an uncompressed PDF.

     [1m-e      [22mForces [4mgropdf[24m to embed [4mall[24m fonts (even the 14 base PDF fonts).

     [1m--format-options [4m[22mbit‐vector[0m
     [1m-f [4m[22mbit‐vector[0m
             Specify  advanced  options  for  [4mgropdf.[24m   Familiarity   with   the
             ]8;;https://www.pdfa-inc.org/product/iso-32000-2-pdf-2-0-bundle-sponsored-access/\ISO 32000  PDF  standard]8;;\ is helpful.  The [4mbit‐vector[24m argument is an
             integer that configures characteristics of the generated PDF.   Add
             the following values to combine them.

                    Value   Meaning
                    ────────────────────────────────────────────────────────────
                    [1m1       [22mSubset included Type 1 fonts.
                    [1m2       [22mUse more compact format for text by including space
                            as a character.  Fonts that do not include space as
                            a glyph may conflict with this feature.
                    [1m4       [22mCompress all data streams.
                    [1m8       [22mDon’t  embed  font  files.  (A font required by the
                            document is not embedded; usually not useful.)

             The default feature combination is 7.  To mimic  what  [4mgropdf[24m  from
             [4mgroff[24m 1.23 produced, specify “6” to turn off subsetting.

     [1m-F [4m[22mdir[24m  Prepend  directory [4mdir[24m/dev[4mname[24m to the search path for font, and de‐
             vice description files; [4mname[24m is the name  of  the  device,  usually
             [1mpdf[22m.

     [1m-I [4m[22mdir[24m  Search  the directory [4mdir[24m for files named in [1m\X'pdf: pdfpic' [22mdevice
             extension commands.  [1m-I [22mmay be specified more than once;  each  [4mdir[0m
             is  searched in the given order.  To search the current working di‐
             rectory before others, add “[1m-I .[22m” at the desired place; it is  oth‐
             erwise searched last.

     [1m-l      [22mOrient the document in landscape format.

     [1m-p [4m[22mpaper‐format[0m
             Set  the  physical dimensions of the output medium.  This overrides
             the [1mpapersize[22m, [1mpaperlength[22m, and [1mpaperwidth [22mdirectives in  the  [4mDESC[0m
             file;  it  accepts  the  same arguments as the [1mpapersize [22mdirective.
             See ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\ for details.

     [1m--pdfver [22m{[1m1.4[22m|[1m1.7[22m}
             PDF version 1.7 introduced a more compact object  format;  this  is
             now  the  default.  If you require the original format (as produced
             by [4mgropdf[24m 1.23) set the version to [1m1.4[22m.

     [1m-s      [22mAppend a comment line to end of PDF showing statistics, i.e. number
             of pages in document.  Ghostscript’s [1mps2pdf  [22mcomplains  about  this
             line if it is included, but works anyway.

     [1m-u [22m[[4mcmap‐file[24m]
             [4mgropdf[24m normally includes a ToUnicode CMap with any font created us‐
             ing  [4mtext.enc[24m  as the encoding file, this makes it easier to search
             for words which contain ligatures.  You can include your  own  CMap
             by  specifying  a  [4mcmap‐file[24m or have no CMap at all by omitting the
             argument.

     [1m-W      [22mExit with failure status if any warnings are issued.

     [1m-y [4m[22mfoundry[0m
             Set the foundry to use for selecting fonts of the same name.

[1mUsage[0m
     [4mgropdf[24m’s input must be in the format produced by ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ and described  in
     ]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\.   Further,  its  device  and font description files must meet
     certain requirements.  The device [1mresolution [22mmust be  an  integer  multiple
     of 72 times [1msizescale[22m.  By default, [4mgropdf[24m uses a [1mresolution [22mof 72000 and a
     [1msizescale  [22mof  1000.  A valid paper format is mandatory; see ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.
     While the PDF standard allows several font file formats (like TrueType), at
     present [4mgropdf[24m accepts only the same Type  1  Adobe  PostScript  format  as
     ]8;;man:grops(1)\[4mgrops[24m(1)]8;;\.   Fewer Type 1 fonts are supported natively in PDF documents than
     the standard 35 fonts supported by [4mgrops[24m and PostScript printers,  but  all
     are  available  since [4mgropdf[24m automatically embeds any that aren’t specified
     by the PDF standard.

     [4mgropdf[24m supports [4mfoundries[24m that permit multiple providers to supply the same
     [4mgroff[24m font names.  [4mgroff[24m’s compilation process attempts to  locate  Type  1
     fonts  on  the  system,  populates a [4mFoundry[24m file with their locations, and
     generates font description files corresponding to them.   Font  description
     files  can also be added after installation.  Each such file must contain a
     directive
            [1minternalname [4m[22mpsname[0m
     that maps the [4mgroff[24m font name (such as “TR”) to a PostScript name (such  as
     “Times-Roman”).   Lines  starting  with [1m# [22mand blank lines are ignored.  The
     code for each character given in the font file must correspond to the  code
     in  the  default  encoding for the font.  This code can be used with the [1m\N[0m
     escape sequence in [4mtroff[24m to select the character even if it lacks a special
     character name.  Every character in the font description must exist in  the
     font file, and the widths given in the description must match those used in
     the font file.  See ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

     [4mgropdf[24m  can  automatically  [4membed[24m any downloadable fonts necessary to print
     the document.  Any fonts thus required must be listed  in  the  file  [4m/usr/[0m
     [4mshare/groff/1.24.1/font/devpdf/download[24m, which should comprise lines of the
     form
            [4mfoundry[24m [4mfont[24m [4mfile‐name[0m
     where  [4mfoundry[24m  is the foundry name, or blank for the default foundry; [4mfont[0m
     is the PostScript name of the font, and [4mfile‐name[24m is the name of the PFA or
     PFB font file, and can be a pathname (can contain slashes).  Any lines  be‐
     ginning  with  [1m#  [22mand  blank lines are ignored; fields must be separated by
     tabs (spaces are [1mnot [22mallowed); if [4mfile‐name[24m is not a pathname, it is sought
     using the same mechanism as that used for font metric files.  The  [4mdownload[0m
     file itself is also sought using this mechanism.  Foundry names are usually
     a  single  character (such as ‘U’ for the URW foundry) or empty for the de‐
     fault foundry.  This default uses the same fonts as [4mGhostscript[24m  uses  when
     it embeds fonts in a PDF file.

     The default stroke and fill colors are black.

   [1mTypefaces[0m
     Styles called [1mR[22m, [1mI[22m, [1mB[22m, and [1mBI [22mmounted at font positions 1 to 4.  Text fonts
     are grouped into families [1mA[22m, [1mBM[22m, [1mC[22m, [1mH[22m, [1mHN[22m, [1mN[22m, [1mP[22m, and [1mT[22m, each having members
     in each of these styles.

            [1mAR      [22mAvantGarde‐Book
            [1mAI      [22mAvantGarde‐BookOblique
            [1mAB      [22mAvantGarde‐Demi
            [1mABI     [22mAvantGarde‐DemiOblique
            [1mBMR     [22mBookman‐Light
            [1mBMI     [22mBookman‐LightItalic
            [1mBMB     [22mBookman‐Demi
            [1mBMBI    [22mBookman‐DemiItalic
            [1mCR      [22mCourier
            [1mCI      [22mCourier‐Oblique
            [1mCB      [22mCourier‐Bold
            [1mCBI     [22mCourier‐BoldOblique
            [1mHR      [22mHelvetica
            [1mHI      [22mHelvetica‐Oblique
            [1mHB      [22mHelvetica‐Bold
            [1mHBI     [22mHelvetica‐BoldOblique
            [1mHNR     [22mHelvetica‐Narrow
            [1mHNI     [22mHelvetica‐Narrow‐Oblique
            [1mHNB     [22mHelvetica‐Narrow‐Bold
            [1mHNBI    [22mHelvetica‐Narrow‐BoldOblique
            [1mNR      [22mNewCenturySchlbk‐Roman
            [1mNI      [22mNewCenturySchlbk‐Italic
            [1mNB      [22mNewCenturySchlbk‐Bold
            [1mNBI     [22mNewCenturySchlbk‐BoldItalic
            [1mPR      [22mPalatino‐Roman
            [1mPI      [22mPalatino‐Italic
            [1mPB      [22mPalatino‐Bold
            [1mPBI     [22mPalatino‐BoldItalic
            [1mTR      [22mTimes‐Roman
            [1mTI      [22mTimes‐Italic
            [1mTB      [22mTimes‐Bold
            [1mTBI     [22mTimes‐BoldItalic

     Another text font is not a member of a family.

            [1mZCMI    [22mZapfChancery‐MediumItalic

     Special fonts include [1mS[22m, the PostScript Symbol font; [1mSS[22m, a subset of [1mS [22mwith
     slanted lowercase Greek letters; [1mEURO[22m, which offers a Euro glyph in several
     styles for use with old devices lacking it; and [1mZD[22m, Zapf Dingbats.  In con‐
     trast to [4mgrops[24m, [4mgropdf[24m does not require a reversed variant of it ([1mZDR[22m); the
     “hand  pointing  left”  glyph  ([1m\[lh][22m)  is  available  nevertheless,  since
     [4mpdf.tmac[24m defines it using the [1m\X'pdf: xrev' [22mdevice extension  command  (see
     below).  Some glyphs in these fonts are unnamed and must be accessed as in‐
     dexed characters, using the [1m\N [22mescape sequence.

     The  fonts  corresponding  to  [1mEURO [22mand [1mSS [22mare unknown to the PDF standard;
     [4mgroff[24m therefore provides their AFM files (font  metrics)  and  PFA  or  PFB
     files so that they can be used with other software and embedded in PDF out‐
     put.

   [1mFeature service levels and URW font support[0m
     The  traditional  PostScript Type 1 fonts are limited in their glyph reper‐
     toire, and the original versions from the Adobe foundry are not free  soft‐
     ware.   Historically, because their presence was mandated by the PostScript
     standard, one could expect to find support for them in any  conforming  de‐
     vice  or  software  PostScript  renderer.  PostScript (“Level 1”) initially
     standardized 14 typefaces: Times,  Helvetica,  and  Courier  each  in  four
     styles  (which [4mgroff[24m groups into “families”); a symbol font; and a dingbats
     font.  PostScript Level 2 increased the number to 35, adding  the  families
     Avant  Garde,  Bookman,  Helvetica  Narrow,  New  Century  Schoolbook,  and
     Palatino; and a text font in one style, Zapf  Chancery  medium  italic.   A
     document could be small because it did not need to embed font resources un‐
     less  it  had  unusual (for the time) glyph or typeface requirements.  This
     situation carried over into the early years of PostScript’s successor  page
     description  language, PDF.  Nowadays, it is common to embed fonts in PDFs,
     and authorities widely recommend this practice, which increases the  relia‐
     bility  of  document  rendering, and many free software fonts are available
     with much greater glyph coverage than Adobe’s Type 1 fonts for PostScript.

     [4mgropdf[24m attempts to work in variety of scenarios, and  delivers  better  re‐
     sults  when  configured  with supporting digital font files (for embedding)
     and font metrics files describing those fonts to the formatter.

     •  [4mFull[24m [4mservice[24m is available when [4mgropdf[24m can locate all  35  fonts  of  the
        PostScript  Level  2 standard on the file system along with their corre‐
        sponding font metrics (AFM) files.  The  Adobe‐compatible  unnamed  (de‐
        fault)  foundry  supports up to 256 glyphs in each typeface.  Fonts from
        the URW foundry (“U”) are compatible extensions of the Adobe fonts  with
        extended glyph coverage, including support for Cyrillic script.  [4mgroff[24m’s
        build  process  uses ]8;;man:afmtodit(1)\[4mafmtodit[24m(1)]8;;\ to generate font description files from
        the URW foundry’s AFM files; see section “Files” below.

     •  [4mIntermediate[24m [4mservice[24m is available when [4mgropdf[24m can locate all 35 fonts of
        the PostScript Level 2 standard but not their corresponding font metrics
        (AFM) files.  [4mgroff[24m’s build process copies the  font  description  files
        from  those  for  the ]8;;man:grops(1)\[4mgrops[24m(1)]8;;\ driver, reusing them for [4mgropdf[24m; this re‐
        duces glyph coverage to 256 glyphs maximum from each face, and  the  “U”
        foundry is unavailable.

     •  [4mBasic[24m  [4mservice[24m  results  when  [4mgropdf[24m  cannot locate all 35 fonts of the
        PostScript Level 2 standard.  Only the base 14 fonts of the PDF standard
        are available, and only in the sense that the formatter  can  use  their
        metrics  (copied  from [4mgrops[24m font descriptions as described above).  Use
        of the [1m-e [22moption to embed fonts in the generated PDF results in  an  er‐
        ror.

   [1mDevice extension commands[0m
     [4mgropdf[24m  supports  many  device  extensions, accessed with the [4mgroff[24m request
     [1mdevice [22mor [4mroff[24m [1m\X [22mescape sequence.  First, it understands many of  the  de‐
     vice extensions supported by ]8;;man:grops(1)\[4mgrops[24m(1)]8;;\.

     [1m\X'ps: invis'[0m
            Suppress output.

     [1m\X'ps: endinvis'[0m
            Stop suppressing output.

     [1m\X'ps: exec gsave currentpoint 2 copy translate [4m[22mn[24m [1mrotate neg exch neg exch[0m
     [1mtranslate'[0m
            where [4mn[24m is the angle of rotation.  This is to support the [1malign [22mcom‐
            mand in ]8;;man:pic(1)\[4mpic[24m(1)]8;;\.

     [1m\X'ps: exec grestore'[0m
            Used by ]8;;man:pic(1)\[4mpic[24m(1)]8;;\ to restore state after rotation.

     [1m\X'ps: exec [4m[22mn[24m [1msetlinejoin'[0m
            where [4mn[24m can be one of the following values.

            0 = Miter join
            1 = Round join
            2 = Bevel join

     [1m\X'ps: exec [4m[22mn[24m [1msetlinecap'[0m
            where [4mn[24m can be one of the following values.

            0 = Butt cap
            1 = Round cap, and
            2 = Projecting square cap

     [4mgropdf[24m  also  supports  a  subset  of the commands introduced in [4mgpresent[24m’s
     [4mpresent.tmac[24m.

            [1mPAUSE[0m
            [1mBLOCKS[0m
            [1mBLOCKE[0m

     These allow you to create presentation PDFs.  Many of  the  other  commands
     are already available in other macro packages.

     These commands are implemented with [4mgroff[24m X commands:‐

     [1m\X'ps: exec %%%%PAUSE'[0m
            The  section before this is treated as a block and is introduced us‐
            ing the current [1mBLOCK [22mtransition setting (see “[1m\X'pdf:  transition'[22m”
            below).  Equivalently, [1m.pdfpause [22mis available as a macro.

     [1m\X'ps: exec %%%%BEGINONCE'[0m
            Any  text  following  this command (up to %%%%ENDONCE) is shown only
            once, the next %%%%PAUSE will remove it.  If producing a non‐presen‐
            tation PDF, i.e. ignoring the pauses, see [4mGROPDF_NOSLIDE[24m below, this
            text is ignored.

     [1m\X'ps: exec %%%%ENDONCE'[0m
            This terminates the block defined by %%%%BEGINONCE.   This  pair  of
            commands  is  what  implements  the .BLOCKS Once/.BLOCKE commands in
            [4mpresent.tmac[24m.

     The [4mmom[24m macro package already integrates these extensions, so you can build
     slides with [4mmom[24m.

     If you use [4mpresent.tmac[24m with [4mgropdf[24m there is no need  to  run  the  program
     ]8;;man:presentps(1)\[4mpresentps[24m(1)]8;;\ since the output will already be a presentation PDF.

     All other [1mps: [22mtags are silently ignored.

     [4mgropdf[24m also recognizes a device extension used by the DVI driver.

     [1m\X'papersize=[4m[22mwidth[24m[1m,[4m[22mlength[24m[1m'[0m
            Set  the  page dimensions in centimeters to [4mwidth[24m by [4mlength.[24m  If the
            [1m-l [22moption was specified, these dimensions are swapped.   Changes  to
            the paper dimensions should occur prior to the first page, or during
            page ejection before starting a subsequent one.

            [4mCaution:[24m the ordering of dimensions differs from that used by [4mpaper‐[0m
            [4msize.tmac[24m and ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\’s “[1m-d paper[22m” option.

     [1m\X'pdf: markstart [4m[22m/ANN‐definition[24m[1m'[0m
     [1m\X'pdf: markend'[0m
            Macros that support PDF features use these extension commands inter‐
            nally  to bracket [4mhotspot[24m text (a hyperlink).  User documents should
            call the [1m.pdfhref [22mmacro instead.   Their  application  is  found  in
            other  macro packages (like ]8;;man:groff_man(7)\[4mgroff_man[24m(7)]8;;\ or ]8;;man:groff_mdoc(7)\[4mgroff_mdoc[24m(7)]8;;\) that call
            [1m.pdfhref [22mwith a [1m-S [22margument, then indicate the end of  hotspot  text
            with [1m\X'pdf: markend'\m[\*[pdf:curcol]][22m.

     [1m\X'pdf: xrev'[0m
            Toggle  the  reversal of glyph direction.  This feature works by re‐
            versing all following text.  Each separate letter is also  mirrored.
            One application is the reversal of glyphs in the Zapf Dingbats font.
            To restore the normal glyph orientation, repeat the command.

     [4mgropdf[24m  supports  several  more  device extensions using the [1mpdf: [22mtag.  The
     following have counterpart [4mconvenience[24m [4mmacros[24m that take the same  arguments
     and behave equivalently.

     [1m.pdfbackground [4m[22mcmd[24m [4mleft[24m [4mtop[24m [4mright[24m [4mbottom[24m [4mweight[0m
     [1m.pdfbackground off[0m
     [1m.pdfbackground footnote [4m[22mbottom[0m
     [1m\X'pdf: background [4m[22mcmd[24m [4mleft[24m [4mtop[24m [4mright[24m [4mbottom[24m [4mweight[24m[1m'[0m
     [1m\X'pdf: background off'[0m
     [1m\X'pdf: background footnote [4m[22mbottom[24m[1m'[0m
            Produce a background rectangle on the page.

            [4mcmd[24m     is  the command, which can be any of “[1mpage[22m|[1mfill[22m|[1mbox[22m” in com‐
                    bination.  Thus, “[1mpagefill[22m” would  draw  a  rectangle  which
                    covers  the  whole current page size (in which case the rest
                    of the parameters can be omitted because the box  dimensions
                    are  taken  from the current media size).  “[1mboxfill[22m”, on the
                    other hand, requires the given dimensions to place the  box.
                    Including  “[1mfill[22m”  in  the command paints the rectangle with
                    the current fill colour (as with [1m\M[][22m) and  including  “[1mbox[22m”
                    gives  the  rectangle  a border in the current stroke colour
                    (as with [1m\m[][22m).

                    [4mcmd[24m may also be “[1moff[22m” on its own, which  terminates  drawing
                    the  current  box.  If you have specified a page colour with
                    “[1mpagefill[22m”, it is always the first box in the stack, and  if
                    you specify it again, it replaces the first entry.  Be aware
                    that  the  “[1mpagefill[22m”  box renders the page opaque, so tools
                    that “watermark” PDF pages are unlikely  to  be  successful.
                    To return the background to transparent, issue an “[1moff[22m” com‐
                    mand with no other boxes open.

                    Finally,  [4mcmd[24m  may be “[1mfootnote[22m” followed by a new value for
                    [4mbottom[24m, which is used for all  open  boxes  on  the  current
                    page.   This  is  to allow room for footnote areas that grow
                    while a page is processed  (to  accommodate  multiple  foot‐
                    notes, for instance).  (If the value is negative, it is used
                    as an offset from the bottom of the page.)

            [4mleft[0m
            [4mtop[0m
            [4mright[0m
            [4mbottom[24m  are  the coordinates of the box.  The [4mtop[24m and [4mbottom[24m coordi‐
                    nates are the minimum and maximum for the box, since the ac‐
                    tual start of the box is [4mgroff[24m’s drawing position  when  you
                    issue  the  command,  and the bottom of the box is the point
                    where you turn the box “[1moff[22m”.  The top  and  bottom  coordi‐
                    nates are used only if the box drawing extends onto the next
                    page; ordinarily, they would be set to the header and footer
                    margins.

            [4mweight[24m  provides  the line width for the border if “[1mbox[22m” is included
                    in the command.

            An [4msboxes[24m macro file is also available; see ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\.

     [1m.pdfmarksuspend[0m
     [1m.pdfmarkrestart[0m
     [1m\X'pdf: marksuspend'[0m
     [1m\X'pdf: markrestart'[0m
            If you use a page location trap to produce a header  or  footer,  or
            otherwise  interrupt  a  document’s text, you need to use these com‐
            mands if a PDF [4mhotspot[24m crosses a trap boundary; otherwise  any  text
            output  by  the trap will be marked as part of the hotspot.  To pre‐
            vent this error, place these device extension  escape  sequences  or
            their   corresponding   convenience   macros   [1m.pdfmarksuspend   [22mand
            [1m.pdfmarkrestart [22mat the start and end  of  the  trap  macro,  respec‐
            tively.

     [1m.pdfpagename [4m[22mname[0m
     [1m\X'pdf: pagename [4m[22mname[24m[1m'[0m
            Assign  the  current  page  a  [4mname[24m.  All documents bear two default
            names, ‘[1mtop[22m’ and ‘[1mbottom[22m’.

     [1m.pdfpagenumbering [4m[22mtype[24m [4mprefix[24m [4mstart[0m
     [1m\X'pdf: pagenumbering [4m[22mtype[24m [4mprefix[24m [4mstart[24m[1m'[0m
            Control the page numbering shown in a PDF  reader’s  outline  (which
            also contains bookmarks).  Normally, the page number associated with
            each bookmark is its sequence number in the file, but this might not
            match  the  desired  numbering  scheme.  A document may bear a cover
            sheet (which has no page number); front matter (possibly including a
            table of contents) that uses lowercase roman numerals; the main mat‐
            ter, which uses arabic numerals; and back matter, which may  include
            appendices  that  are  each prefixed with a letter and independently
            numbered.  Place this command prior to breaking the  page  to  which
            the  new  numbering  scheme  is  to  apply.   It then persists until
            changed again.

            [4mtype[24m    specifies the numbering system to use. It should be  one  of
                    “[1mDecimal[22m”,  “[1mRoman[22m”, “[1mroman[22m”, “[1mAlpha[22m”, or “[1malpha[22m”.  This pa‐
                    rameter may be abbreviated to the first letter,  whose  let‐
                    tercase  determines that used for the numbers where applica‐
                    ble.  The ordering used by the alphabetic numbering  systems
                    is A‐Z ... AA‐AZ ... ZA‐ZZ.  [4mtype[24m can also be “[1m.[22m”, which se‐
                    lects no numbering system; you may still provide a [4mprefix.[0m

            [4mprefix[24m  specifies  text to precede the page number.  For example, to
                    number the pages of an appendix “A‐1”, “A‐2”, and so  forth,
                    use a [4mprefix[24m of “[1mA‐[22m” and a [4mtype[24m of “[1mDecimal[22m”.

            [4mstart[24m   determines the page number.  It defaults to 1.

     [1m.pdfpic [4m[22mfile[24m [4malignment[24m [4mwidth[24m [4mheight[24m [4mline‐length[0m
     [1m\X'pdf: pdfpic [4m[22mfile[24m [4malignment[24m [4mwidth[24m [4mheight[24m [4mline‐length[24m[1m'[0m
            Place an image from file [4mfile[24m of desired [4mwidth[24m and [4mheight[24m (if [4mheight[0m
            is  missing or zero then it is scaled proportionally).  If [4malignment[0m
            is [1m-L [22mthe drawing is left‐aligned.  If it is [1m-C [22mor [1m-R [22ma  [4mline‐length[0m
            greater than the width of the drawing is required as well.  If [4mwidth[0m
            is  specified  as zero then the width is scaled in proportion to the
            height.  If both [4mwidth[24m and [4mheight[24m are non‐zero the image  is  scaled
            to ‘best fit’.

            The  availability  of other software on the system, such as [4mPerlMag‐[0m
            [4mick[24m, influences the types of image files [4mgropdf[24m  can  embed  in  its
            output.

               ┌───────┬──────┬─────────┬─────────────┬────────────────────┐
               │       │ none │ [4mfile[24m(1) │ [4midentify[24m(1) │ [4mImage::Magick[24m(3pm) │
               ├───────┼──────┼─────────┼─────────────┼────────────────────┤
               │ [4m.pdf[24m  │  ✓   │    ✓    │      ✓      │         ✓          │
               ├───────┼──────┼─────────┼─────────────┼────────────────────┤
               │ [4m.jpg[24m  │  ✗   │    ✓    │      ✓      │         ✓          │
               ├───────┼──────┼─────────┼─────────────┼────────────────────┤
               │ [4m.jp2[24m  │  ✗   │    ✗    │      ✓      │         ✓          │
               ├───────┼──────┼─────────┼─────────────┼────────────────────┤
               │ other │  ✗   │    ✗    │      ✗      │         ✓          │
               └───────┴──────┴─────────┴─────────────┴────────────────────┘

            See  ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\ for a description of the [1mPDFPIC [22mmacro, which pro‐
            vides a convenient high‐level interface  for  inclusion  of  various
            graphic file formats.

     [1m.pdfswitchtopage [4m[22mwhen[24m [4mname[0m
     [1m\X'pdf: switchtopage [4m[22mwhen[24m [4mname[24m[1m'[0m
            Normally  each new page is appended to the end of the document, this
            command allows following pages to be inserted at a [4m‘named’[24m  position
            within the document (see pagename command above).  [4m‘when’[24m can be ei‐
            ther ‘[4mafter[24m’ or ‘[4mbefore[24m’.  If it is omitted it defaults to ‘[4mbefore[24m’.
            It  should be used at the end of the page before you want the switch
            to happen.  This allows pages such as a TOC to be moved to elsewhere
            in the document, but more esoteric uses are possible.

     [1m.pdftransition [4m[22mscope[24m [4mmode[24m [4mduration[24m [4mdimension[24m [4mmotion[24m [4mdirection[24m [4mscale[24m [4mbool[0m
     [1m\X'pdf: transition [4m[22mscope[24m [4mmode[24m [4mduration[24m [4mdimension[24m [4mmotion[24m [4mdirection[24m [4mscale[0m
     [4mbool[24m[1m'[0m
            Configure the style of page transitions, as  used  in  “slides”  (or
            “foils”).   [4mscope[24m  can  be either [1mSLIDE [22mor [1mBLOCK[22m.  [1mSLIDE [22mapplies the
            transition when a new slide is introduced to the screen;  [1mBLOCK  [22map‐
            plies it to the individual blocks making up the slide.

            [4mmode[24m is the transition type between slides:‐

                   [1mSplit  [22m‐ Two lines sweep across the screen, revealing the new
                   page.  The lines may be either horizontal or vertical and may
                   move inward from the edges of the page or  outward  from  the
                   center, as specified by the [4mdimension[24m and [4mmotion[24m entries, re‐
                   spectively.
                   [1mBlinds  [22m‐  Multiple  lines,  evenly spaced across the screen,
                   synchronously sweep in the same direction to reveal  the  new
                   page.   The  lines  may  be either horizontal or vertical, as
                   specified by the  [4mdimension[24m  entry.   Horizontal  lines  move
                   downward; vertical lines move to the right.
                   [1mBox  [22m‐  A rectangular box sweeps inward from the edges of the
                   page or outward from the center, as specified by  the  [4mmotion[0m
                   entry, revealing the new page.
                   [1mWipe  [22m‐  A single line sweeps across the screen from one edge
                   to the other in the direction specified by the [4mdirection[24m  en‐
                   try, revealing the new page.
                   [1mDissolve [22m‐ The old page dissolves gradually to reveal the new
                   one.
                   [1mGlitter  [22m‐  As Dissolve, except that the effect sweeps across
                   the page in a wide band moving from one side of the screen to
                   the other in the direction specified by the [4mdirection[24m entry.
                   [1mR [22m‐ The new page simply replaces the old one with no  special
                   transition effect; the [4mdirection[24m entry shall be ignored.
                   [1mFly  [22m‐ (PDF 1.5) Changes are flown out or in (as specified by
                   [4mmotion[24m), in the direction specified by [4mdirection[24m, to or  from
                   a location that is offscreen except when [4mdirection[24m is [1mNone[22m.
                   [1mPush [22m‐ (PDF 1.5) The old page slides off the screen while the
                   new page slides in, pushing the old page out in the direction
                   specified by [4mdirection[24m.
                   [1mCover [22m‐ (PDF 1.5) The new page slides on to the screen in the
                   direction specified by [4mdirection[24m, covering the old page.
                   [1mUncover [22m‐ (PDF 1.5) The old page slides off the screen in the
                   direction  specified by [4mdirection[24m, uncovering the new page in
                   the direction specified by [4mdirection[24m.
                   [1mFade [22m‐ (PDF 1.5)  The  new  page  gradually  becomes  visible
                   through the old one.

            [4mduration[24m is the length of the transition in seconds (default 1).

            [4mdimension[24m  (Optional;  [1mSplit  [22mand [1mBlinds [22mtransition styles only) The
            dimension in which the specified transition effect  shall  occur:  [1mH[0m
            Horizontal, or [1mV [22mVertical.

            [4mmotion[24m (Optional; [1mSplit[22m, [1mBox [22mand [1mFly [22mtransition styles only) The di‐
            rection of motion for the specified transition effect: [1mI [22mInward from
            the edges of the page, or [1mO [22mOutward from the center of the page.

            [4mdirection[24m  (Optional;  [1mWipe[22m,  [1mGlitter[22m,  [1mFly[22m, [1mCover[22m, [1mUncover [22mand [1mPush[0m
            transition styles only) The direction in which the specified transi‐
            tion effect  shall  moves,  expressed  in  degrees  counterclockwise
            starting  from a left‐to‐right direction.  If the value is a number,
            it shall be one of: [1m0 [22m= Left to right, [1m90  [22m=  Bottom  to  top  (Wipe
            only),  [1m180  [22m= Right to left (Wipe only), [1m270 [22m= Top to bottom, [1m315 [22m=
            Top‐left to bottom‐right (Glitter only) The value can be [1mNone[22m, which
            is relevant only for the [1mFly [22mtransition when the value of  [4mscale[24m  is
            not 1.0.

            [4mscale[24m (Optional; PDF 1.5; [1mFly [22mtransition style only) The starting or
            ending  scale at which the changes shall be drawn.  If [4mmotion[24m speci‐
            fies an inward transition, the scale  of  the  changes  drawn  shall
            progress  from  [4mscale[24m  to 1.0 over the course of the transition.  If
            [4mmotion[24m specifies an outward transition, the  scale  of  the  changes
            drawn  shall progress from 1.0 to [4mscale[24m over the course of the tran‐
            sition

            [4mbool[24m (Optional; PDF 1.5; [1mFly [22mtransition style  only)  If  [1mtrue[22m,  the
            area that shall be flown in is rectangular and opaque.

            Any of the parameters may be replaced with a "." which signifies the
            parameter  retains its previous value, also any trailing missing pa‐
            rameters are ignored.

            [1mNote: [22mnot all PDF Readers support any or all these transitions.

   [1mMacros[0m
     [4mgropdf[24m’s support macros in [4mpdf.tmac[24m define the convenience macros described
     above.  Some features have no direct device extension escape sequence coun‐
     terpart.

     [1m.pdfbookmark [22m[[1m-T [4m[22mtag‐name[24m] [4mlevel[24m [4mtext[0m
            Mark the nearest page location as a bookmark, and optionally a named
            destination as well.  [4mBookmarks[24m populate the  outline  pane  of  the
            reader.   They are organized into a hierarchical tree; each level of
            the tree is numbered, starting at 1, and named as [4mtext[24m in  the  out‐
            line.   [4mNamed[24m  [4mdestinations[24m permit hyperlink‐style navigation within
            the document.  Specifying [1m-T [22mfollowed by [4mtag‐name[24m  creates  a  named
            destination  making  the page location eligible as a target named by
            “[1m.pdfhref L [22m...”.

     [1m.pdfhref L -D [4m[22mdest[24m [[1m-S[22m] [[1m-P [4m[22mprefix‐text[24m] [[1m-A [4m[22msuffix‐text[24m] [[4mlink‐text[24m]
            Create a hotspot link to [4mdest,[24m (the  [4mtag‐name[24m)  which  a  “[1m.pdfbook‐[0m
            [1mmark  [22m...” or “[1m.pdfhref M [22m...” call elsewhere in the document should
            define.  (If the document employs forward  references,  it  must  be
            processed  twice;  see ]8;;man:pdfmom(1)\[4mpdfmom[24m(1)]8;;\.)  If [4mlink‐text[24m is omitted the text
            associated with [4mdest[24m, when it was created, is formatted as the  link
            text.   The  [1m-P [22mand [1m-A [22marguments format their successors as text be‐
            fore and after the  link  text,  respectively,  without  intervening
            space.   Specifying  [1m-S [22mprevents [1mpdfhref [22mfrom “closing” the hotspot,
            requiring the document (or macro package wrapping [1mpdfhref[22m) to do  so
            itself with “[1m\X'pdf: markend'\m[\*[pdf:curcol]][22m”.

     [1m.pdfhref M [22m[[1m-E[22m] [[1m-N [4m[22mtag‐name[24m] [4mdest[0m
            Mark  the  nearest  page  location as a destination named (the first
            word of) [4mdest,[24m which should be unique within a document.  Specifying
            [1m-T [22mfollowed by [4mtag‐name[24m overrides this default.  Specifying [1m-E  [22mfor‐
            mats [4mdest[24m as text in the document as well.

     [1m.pdfhref W -D [4m[22muri[24m [[1m-S[22m] [[1m-P [4m[22mprefix‐text[24m] [[1m-A [4m[22msuffix‐text[24m] [4mlink‐text[0m
            Create  a  hotspot  link to [4muri,[24m a World Wide Web Universal Resource
            Identifier (URI).  The [1m-P [22mand [1m-A [22marguments format  their  successors
            as text before and after the link text, respectively, without inter‐
            vening  space.   Specifying  [1m-S  [22mprevents [1mpdfhref [22mfrom “closing” the
            hotspot, requiring the document (or macro package wrapping  [1mpdfhref[22m)
            to do so itself with “[1m\X'pdf: markend'\m[\*[pdf:curcol]][22m”.

     [1m.pdfinfo /[4m[22mfield[24m [4mcontent[24m ...
            Define  PDF  metadata.   [4mfield[24m may be one of [1mTitle[22m, [1mAuthor[22m, [1mSubject[22m,
            [1mKeywords[22m, or another datum supported by the  PDF  standard  or  your
            reader.  [4mfield[24m must be prefixed with a slash.

     [1m.pdfnote [22m[[1m-T [4m[22mtitle[24m] [4mtext[0m
            Create  an annotation in the document.  Reader support for this fea‐
            ture varies.  Some place an icon at  the  current  position  on  the
            page;  hovering  over  the icon reveals any [4mtitle[24m, while clicking on
            the icon pops up a window containing [4mtext[24m.

   [1mParameters[0m
     The following parameters, shown as [4mroff[24m control lines, affect the operation
     of [4mgropdf[24m.

     ┌─────────────────────────────────────────────────────────────────────────┐
     │        [1mParameter                     Purpose                Default     [22m│
     ├─────────────────────────────────────────────────────────────────────────┤
     │ .nr PDFNOTE.WIDTH          Set width of annotation       1c             │
     │                            icon.                                        │
     │ .nr PDFNOTE.HEIGHT         Set height of annotation      1c             │
     │                            icon.                                        │
     │ .ds PDFNOTE.COLOR          Set RGB color of annotation   1.00 1.00 0.00 │
     │                            icon (RGB)                                   │
     │ .ds PDFNOTE.OPACITY        Set opacity of annotation     0.6            │
     │                            icon (decimal value in [0,                   │
     │                            1]).                                         │
     │ .nr PDFOUTLINE.FOLDLEVEL   Set depth of visible book‐    10000          │
     │                            mark hierarchy.                              │
     │ .nr PDFHREF.VIEW.LEADING   Set position adjustment       5p             │
     │                            when clicking bookmark or                    │
     │                            internal hotspot.                            │
     │ .nr PDFHREF.LEADING        Configure size of increased   2.0p           │
     │                            clickable area around a                      │
     │                            hotspot.                                     │
     │ .ds PDFHREF.BORDER         Configure the border width    0 0 0          │
     │                            around a hotspot by speci‐                   │
     │                            fying two zeroes followed                    │
     │                            by the desired width in                      │
     │                            points.  Do not use a scal‐                  │
     │                            ing unit.                                    │
     │ .ds PDFHREF.COLOR          Set RGB color of link text.   0.00 0.35 0.60 │
     └─────────────────────────────────────────────────────────────────────────┘

     In the foregoing, you can also spell “COLOR” in string names as “COLOUR”.

   [1mImporting PDF graphics[0m
     If you are importing an image as a PDF file, it must be a single  page  and
     the  drawing  must  just  fit  inside  the  media size of the PDF file.  In
     ]8;;man:inkscape(1)\[4minkscape[24m(1)]8;;\ or ]8;;man:gimp(1)\[4mgimp[24m(1)]8;;\, for example, make sure the canvas  size  just  fits
     the image.

     The  PDF  parser  [4mgropdf[24m implements has not been rigorously tested with all
     applications that produce PDF.  If you find a single‐page PDF  which  fails
     to import properly, try processing it with the ]8;;man:pdftk(1)\[4mpdftk[24m(1)]8;;\ program.
            pdftk [4mexisting‐file[24m output [4mnew‐file[0m
     You may find that [4mnew‐file[24m imports successfully.

   [1mTrueType and other font formats[0m
     [4mgropdf[24m  does  not yet support any font formats besides Adobe Type 1 (PFA or
     PFB).

[1mFont installation[0m
     For your convenience, [4mgroff[24m offers [4minstall-font.bash[24m, a shell  script  that
     interactively assists the configuration of fonts for use with the GNU [4mtroff[0m
     formatter and the [4mgropdf[24m output driver.  See section “Files” below.

     The following is a step‐by‐step font installation guide for [4mgropdf.[0m

     •  Convert  your font to something [4mgroff[24m understands.  This is a PostScript
        Type 1 font in PFA or PFB format, together with an AFM file.  A PFA file
        begins as follows.
               %!PS-AdobeFont-1.0:
        A PFB file contains this string as well, preceded by  some  non‐printing
        bytes.   In  the  following  steps,  we  will consider the use of CTAN’s
        ]8;;https://ctan.org/tex-archive/fonts/brushscr\BrushScriptX‐Italic]8;;\ font in PFA format.

     •  Convert the  AFM  file  to  a  [4mgroff[24m  font  description  file  with  the
        ]8;;man:afmtodit(1)\[4mafmtodit[24m(1)]8;;\ program.  For instance,
               $ [1mafmtodit BrushScriptX-Italic.afm text.map BSI[0m
        converts the Adobe Font Metric file [4mBrushScriptX-Italic.afm[24m to the [4mgroff[0m
        font description file [4mBSI[24m.

        If  you have a font family which provides regular upright (roman), bold,
        italic, and bold‐italic styles, (where  “italic”  may  be  “oblique”  or
        “slanted”),  we  recommend  using [1mR[22m, [1mB[22m, [1mI[22m, and [1mBI[22m, respectively, as suf‐
        fixes to the [4mgroff[24m font family name to enable [4mgroff[24m’s  font  family  and
        style  selection  features.   An example is [4mgroff[24m’s built‐in support for
        Times: the font family name is abbreviated as  [1mT[22m,  and  the  [4mgroff[24m  font
        names  are  therefore [1mTR[22m, [1mTB[22m, [1mTI[22m, and [1mTBI[22m.  In our example, however, the
        BrushScriptX font is available in a single style only, italic.

     •  Install the [4mgroff[24m font description file(s) in a [4mdevpdf[24m  subdirectory  in
        the  search  path that [4mgroff[24m uses for device and font file descriptions.
        See the [4mGROFF_FONT_PATH[24m entry in section “Environment” of  ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\  for
        the current value of the font search path.  While [4mgroff[24m doesn’t directly
        use  AFM  files,  it is a good idea to store them alongside its font de‐
        scription files.

     •  Register fonts in the [4mdevpdf/download[24m file so they can  be  located  for
        embedding  in  PDF files [4mgropdf[24m generates.  Only the first [4mdownload[24m file
        encountered in the font search path is read.  If in doubt, copy the  de‐
        fault  [4mdownload[24m  file (see section “Files” below) to the first directory
        in the font search path and add your fonts there.  The  PostScript  font
        name  used  by  [4mgropdf[24m  is stored in the [1minternalname [22mfield in the [4mgroff[0m
        font description file.  (This name does  not  necessarily  resemble  the
        font’s  file  name.)   If  the font in our example had originated from a
        foundry named [1mZ[22m, we would add the following line to [4mdownload[24m.
               Z→BrushScriptX-Italic→BrushScriptX-Italic.pfa
        A tab character, depicted as  →,  separates  the  fields.   The  default
        foundry  has no name: its field is empty and entries corresponding to it
        start with a tab character, as will the one in our example.

     •  Test the selection and embedding of the new font.
               printf "\\f[BSI]Hello, world!\n" | groff -T pdf -P -e >hello.pdf
               see hello.pdf

[1mExit status[0m
     0      [4mgropdf[24m successfully produced a PDF document.

     1      [4mgropdf[24m experienced a critical error, or warnings  were  emitted  and
            the [1m-W [22moption was specified.

     2      [4mgropdf[24m could not interpret its command‐line arguments.

[1mEnvironment[0m
     [4mGROFF_FONT_PATH[0m
            A  list of directories in which to seek the selected output device’s
            directory of device and font description files.  If, in the [4mdownload[0m
            file, the font file has been specified with a full path, no directo‐
            ries are searched.  See ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ and ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

     [4mGROPDF_NOSLIDE[0m
            If set and evaluates to a true value (to Perl), [4mgropdf[24m ignores  com‐
            mands specific to presentation PDFs, producing a normal PDF instead.

     [4mGROPDF_OPTIONS[0m
            [4mgropdf[24m  interprets  the  contents  of this environment variable as a
            space‐separated list of command‐line options.  Explicit command‐line
            options override any settings from this environment variable.

     [4mSOURCE_DATE_EPOCH[0m
            A timestamp (expressed as seconds since the Unix epoch)  to  use  as
            the  output  creation  timestamp  in place of the current time.  The
            time is converted to human‐readable form using Perl’s [4mgmtime()[24m func‐
            tion and recorded in a PDF comment.

     [4mTZ[24m     The time zone to use when converting the current time to human‐read‐
            able form; see ]8;;man:tzset(3)\[4mtzset[24m(3)]8;;\.  If [4mSOURCE_DATE_EPOCH[24m is used, it is always
            converted to human‐readable form using UTC.

[1mFiles[0m
     [4m/usr/share/groff/1.24.1/font/devpdf/DESC[0m
            describes the [1mpdf [22moutput device.

     [4m/usr/share/groff/1.24.1/font/devpdf/[24mF
            describes the font known as [4mF[24m on device [1mpdf[22m.

     [4m/usr/share/groff/1.24.1/font/devpdf/U-[24mF
            describes the font from the URW foundry (versus the  Adobe  default)
            known as [4mF[24m on device [1mpdf[22m.

     [4m/usr/share/groff/1.24.1/font/devpdf/download[0m
            lists  fonts  available  for  embedding  within the PDF document (by
            analogy to the [1mps [22mdevice’s downloadable font support).

     [4m/usr/share/groff/1.24.1/font/devpdf/Foundry[0m
            is a data file used by the [4mgroff[24m build system to  locate  PostScript
            Type 1 fonts.

     [4m/usr/share/groff/1.24.1/font/devpdf/symbolsl.afm[0m
            provides  metrics  for the slanted symbol font known to [4mgroff[24m as [1mSS[22m.
            These data facilitate use of the font with non‐[4mgroff[24m software.

     [4m/usr/share/groff/1.24.1/font/devpdf/symbolsl.pfb[0m
            supplies the slanted symbol font known to [4mgroff[24m as [1mSS[22m.

     [4m/usr/share/groff/1.24.1/font/devpdf/enc/text.enc[0m
            describes the encoding scheme used by most PostScript Type 1  fonts;
            the  [1mencoding [22mdirective of font description files for the [1mpdf [22mdevice
            refers to it.

     [4m/usr/share/groff/1.24.1/font/devpdf/generate/symbolsl.sfd[0m
            is the source form of the [4msymbolsl.pfb[24m font, in spline font database
            (SFD) format.

     [4m/usr/share/groff/1.24.1/tmac/pdf.tmac[0m
            defines macros for use with the [1mpdf [22moutput device.  It is  automati‐
            cally loaded by [4mtroffrc[24m when the [1mpdf [22moutput device is selected.

     [4m/usr/share/groff/1.24.1/tmac/pdfpic.tmac[0m
            defines  the  [1mPDFPIC  [22mmacro  for embedding images in a document; see
            ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\.  It is automatically loaded by [4mtroffrc.[0m

     [4m/usr/share/doc/groff-1.24.1/examples/install-font.bash[0m
            This script, contributed by [4mmom[24m macro package author Peter Schaffter
            and long available at his web site,  assists  with  making  TrueType
            ([4m.ttf[24m),  OpenType  ([4m.otf[24m),  and PostScript Type 1 ([4m.pfa[24m, [4m.pfb[24m) fonts
            available to [4mgroff[24m.

            Change to its directory and run “[1mbash install-font.bash  -H[22m”  for  a
            man page‐like description of its features and operation.

[1mAuthors[0m
     [4mgropdf[24m was written and is maintained by ]8;;mailto:deri@chuzzlewit.myzen.co.uk\Deri James]8;;\.

[1mSee also[0m
     [4m/usr/share/doc/groff-1.24.1/sboxes/msboxes.ms[0m
     [4m/usr/share/doc/groff-1.24.1/sboxes/msboxes.pdf[0m
            “Using PDF boxes with [4mgroff[24m and the [4mms[24m macros”, by Deri James.

     [4mpresent.tmac[0m
            is  part  of ]8;;https://bob.diertens.org/corner/useful/gpresent/\[4mgpresent[24m]8;;\, a software package by Bob Diertens that works
            with [4mgroff[24m to produce presentations (“foils”, or “slide decks”).

     ]8;;man:afmtodit(1)\[4mafmtodit[24m(1)]8;;\, ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\, ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\, ]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\

groff 1.24.1                       2026‐03‐20                          [4mgropdf[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mgrops[24m(1)                     General Commands Manual                    [4mgrops[24m(1)

[1mName[0m
     grops - [4mgroff[24m output driver for PostScript

[1mSynopsis[0m
     [1mgrops [22m[[1m-glm[22m] [[1m-b [4m[22mbrokenness‐flags[24m] [[1m-c [4m[22mnum‐copies[24m] [[1m-F [4m[22mfont‐directory[24m]
           [[1m-I [4m[22minclusion‐directory[24m] [[1m-p [4m[22mpaper‐format[24m] [[1m-P [4m[22mprologue‐file[24m]
           [[1m-w [4m[22mrule‐thickness[24m] [[4mfile[24m ...]

     [1mgrops --help[0m

     [1mgrops -v[0m
     [1mgrops --version[0m

[1mDescription[0m
     The GNU [4mroff[24m PostScript output driver translates  the  output  of  ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\
     into PostScript.  Normally, [4mgrops[24m is invoked by ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ when the latter is
     given  the “[1m-T ps[22m” option.  (In this installation, [1mps [22mis the default output
     device.)  Use [4mgroff[24m’s [1m-P [22moption to pass any options shown above  to  [4mgrops[24m.
     If  no  [4mfile[24m arguments are given, or if [4mfile[24m is “-”, [4mgrotty[24m reads the stan‐
     dard input stream.  It writes to the standard output stream.

     When called with multiple [4mfile[24m arguments, [4mgrops[24m  doesn’t  produce  a  valid
     document  structure  (one  conforming  to  the Document Structuring Conven‐
     tions).  To print such catenated output, it is necessary to deactivate  DSC
     handling in the printing program or previewer.

     See  section  “Font installation” below for a guide to installing fonts for
     [4mgrops[24m.

[1mOptions[0m
     [1m--help [22mdisplays a usage message, while [1m-v [22mand [1m--version [22mshow version infor‐
     mation; all exit afterward.

     [1m-b [4m[22mn[24m    Work around problems with spoolers, previewers, and older printers.
             Normally, [4mgrops[24m produces output at PostScript LanguageLevel 2  that
             conforms  to  version  3.0 of the Document Structuring Conventions.
             Some software and devices can’t handle such  a  data  stream.   The
             value of [4mn[24m determines what [4mgrops[24m does to make its output acceptable
             to  such consumers.  If [4mn[24m is [1m0[22m, [4mgrops[24m employs no workarounds, which
             is the default; it can be changed by modifying the [1mbroken [22mdirective
             in [4mgrops[24m’s [4mDESC[24m file.

             Add 1 to suppress generation  of  [1m%%BeginDocumentSetup  [22mand  [1m%%End‐[0m
             [1mDocumentSetup  [22mcomments; this is needed for early versions of Tran‐
             Script that get confused by anything between the  [1m%%EndProlog  [22mcom‐
             ment and the first [1m%%Page [22mcomment.

             Add 2 to omit lines in included files beginning with [1m%![22m, which con‐
             fuse Sun’s [4mpageview[24m previewer.

             Add  4  to  omit  lines  in  included  files beginning with [1m%%Page[22m,
             [1m%%Trailer [22mand [1m%%EndProlog[22m; this is needed for spoolers  that  don’t
             understand [1m%%BeginDocument [22mand [1m%%EndDocument [22mcomments.

             Add  8  to  write  [1m%!PS-Adobe-2.0 [22mrather than [1m%!PS-Adobe-3.0 [22mas the
             first line of the PostScript output;  this  is  needed  when  using
             Sun’s Newsprint with a printer that requires page reversal.

             Add  16  to  omit media size information (that is, output neither a
             [1m%%DocumentMedia [22mcomment nor the [1msetpagedevice [22mPostScript  command).
             This was the behavior of [4mgroff[24m 1.18.1 and earlier; it is needed for
             older  printers  that  don’t understand PostScript LanguageLevel 2,
             and is also necessary if the output is further processed to produce
             an EPS file; see subsection “Escapsulated PostScript” below.

     [1m-c [4m[22mn[24m    Output [4mn[24m copies of each page.

     [1m-F [4m[22mdir[24m  Prepend directory dir[4m/dev[24mname to the search path for font  and  de‐
             vice description and PostScript prologue files; [4mname[24m is the name of
             the device, usually [1mps[22m.

     [1m-g      [22mGenerate  PostScript  code  to guess the page length.  The guess is
             correct only if the imageable area is vertically  centered  on  the
             page.   This  option  allows  you to generate documents that can be
             printed on both U.S. letter and A4 paper formats without change.

     [1m-I [4m[22mdir[24m  Search the directory [4mdir[24m for files named in [1m\X'ps: file' [22mand [1m\X'ps:[0m
             [1mimport' [22mescape sequences.  [1m-I [22mmay be specified more than once; each
             [4mdir[24m is searched in the given order.  To search the current  working
             directory  before  others,  add  “[1m-I .[22m” at the desired place; it is
             otherwise searched last.

     [1m-l      [22mUse landscape orientation rather than portrait.

     [1m-m      [22mTurn on manual feed for the document.

     [1m-p [4m[22mfmt[24m  Set physical dimensions of output medium, overriding the [1mpapersize[22m,
             [1mpaperlength[22m, and [1mpaperwidth [22mdirectives in the [4mDESC[24m file.   [4mfmt[24m  can
             be   any   argument   accepted  by  the  [1mpapersize  [22mdirective;  see
             ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

     [1m-P [4m[22mprologue[0m
             Use the file [4mprologue[24m, sought in the [4mgroff[24m font search path, as the
             PostScript prologue, overriding the default  (see  section  “Files”
             below) and the environment variable [4mGROPS_PROLOGUE.[0m

     [1m-w [4m[22mn[24m    Draw rules (lines) with a thickness of [4mn[24m thousandths of an em.  The
             default thickness is [1m40 [22m(0.04 em).

[1mUsage[0m
     The  input  to [4mgrops[24m must be in the format output by ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\, described in
     ]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\.  In addition, the device and font description files  for  the
     device  used must meet certain requirements.  The device resolution must be
     an integer multiple of 72 times the [1msizescale[22m.  The device description file
     must contain a valid paper format; see ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.  Each  font  descrip‐
     tion file must contain a directive
            internalname [4mpsname[0m
     which says that the PostScript name of the font is [4mpsname[24m.

     A font description file may also contain a directive
            encoding [4menc‐file[0m
     which  says that the PostScript font should be reencoded using the encoding
     described in [4menc‐file[24m; this file should consist of a sequence of  lines  of
     the form
            [4mpschar[24m [4mcode[0m
     where [4mpschar[24m is the PostScript name of the character, and [4mcode[24m is its posi‐
     tion  in  the  encoding expressed as a decimal integer; valid values are in
     the range 0 to 255.  Lines starting with [1m# [22mand  blank  lines  are  ignored.
     The  code for each character given in the font description file must corre‐
     spond to the code for the character in encoding file, or to the code in the
     default encoding for the font if the PostScript font is  not  to  be  reen‐
     coded.   This  code can be used with the [1m\N [22mescape sequence in [4mtroff[24m to se‐
     lect the character, even if it does not have a  [4mgroff[24m  glyph  name.   Every
     character  in  the font description file must exist in the PostScript font,
     and the widths given in the font description file  must  match  the  widths
     used  in  the PostScript font.  [4mgrops[24m assumes that a character with a [4mgroff[0m
     name of [1mspace [22mis blank (makes no marks on the page); it  can  make  use  of
     such a character to generate more efficient and compact PostScript output.

     [4mgrops[24m is able to display all glyphs in a PostScript font; it is not limited
     to  256  of them.  [4menc‐file[24m (or the default encoding if no encoding file is
     specified) just defines the order of glyphs for the first  256  characters;
     all  other glyphs are accessed with additional encoding vectors which [4mgrops[0m
     produces on the fly.

     [4mgrops[24m can embed fonts in a document that are necessary to render  it;  this
     is called “downloading”.  Such fonts must be in PFA format.  Use ]8;;man:pfbtops(1)\[4mpfbtops[24m(1)]8;;\
     to  convert a Type 1 font in PFB format.  Downloadable fonts must be listed
     a [4mdownload[24m file containing lines of the form
            [4mpsname[24m [4mfile[0m
     where [4mpsname[24m is the PostScript name of the font, and [4mfile[24m is  the  name  of
     the  file  containing  it.   Blank lines and those beginning with [1m# [22mare ig‐
     nored; fields are separated by tabs.  [4mfile[24m is sought using the same  mecha‐
     nism  as  for [4mgroff[24m font description files.  The [4mdownload[24m file itself is as
     well; currently, the first matching file found in the device and  font  de‐
     scription search path is used.

     If the file containing a downloadable font or imported document conforms to
     the  Adobe Document Structuring Conventions, then [4mgrops[24m interprets any com‐
     ments in the files sufficiently to ensure that its own output  is  conform‐
     ing.   It  also  supplies  any needed font resources that are listed in the
     [4mdownload[24m file as well as any needed file resources.  It  is  also  able  to
     handle  inter‐resource  dependencies.  For example, suppose that you have a
     downloadable font called Garamond, and  also  a  downloadable  font  called
     Garamond‐Outline  which  depends on Garamond (typically it would be defined
     to copy Garamond’s font dictionary, and change the PaintType), then  it  is
     necessary  for Garamond to appear before Garamond‐Outline in the PostScript
     document.  [4mgrops[24m handles this automatically provided that the  downloadable
     font  file  for  Garamond‐Outline  indicates  its dependence on Garamond by
     means of the Document Structuring Conventions,  for  example  by  beginning
     with the following lines.
            %!PS-Adobe-3.0 Resource-Font
            %%DocumentNeededResources: font Garamond
            %%EndComments
            %%IncludeResource: font Garamond
     In this case, both Garamond and Garamond‐Outline would need to be listed in
     the  [4mdownload[24m file.  A downloadable font should not include its own name in
     a [1m%%DocumentSuppliedResources [22mcomment.

     [4mgrops[24m does not interpret [1m%%DocumentFonts [22mcomments.   The  [1m%%DocumentNeeded‐[0m
     [1mResources[22m, [1m%%DocumentSuppliedResources[22m, [1m%%IncludeResource[22m, [1m%%BeginResource[22m,
     and  [1m%%EndResource  [22mcomments  (or  possibly  the old [1m%%DocumentNeededFonts[22m,
     [1m%%DocumentSuppliedFonts[22m, [1m%%IncludeFont[22m,  [1m%%BeginFont[22m,  and  [1m%%EndFont  [22mcom‐
     ments) should be used.

     The  default  stroke  and fill colors are black.  For colors defined in the
     “rgb” color space, [1msetrgbcolor [22mis used; for “cmy” and “cmyk”, [1msetcmykcolor[22m;
     and for “gray”, [1msetgray[22m.  [1msetcmykcolor [22mis a PostScript LanguageLevel 2 com‐
     mand and thus not available on some older printers.

   [1mTypefaces[0m
     Styles called [1mR[22m, [1mI[22m, [1mB[22m, and [1mBI [22mmounted at font positions 1 to 4.  Text fonts
     are grouped into families [1mA[22m, [1mBM[22m, [1mC[22m, [1mH[22m, [1mHN[22m, [1mN[22m, [1mP[22m, and [1mT[22m, each having members
     in each of these styles.

            [1mAR      [22mAvantGarde‐Book
            [1mAI      [22mAvantGarde‐BookOblique
            [1mAB      [22mAvantGarde‐Demi
            [1mABI     [22mAvantGarde‐DemiOblique
            [1mBMR     [22mBookman‐Light
            [1mBMI     [22mBookman‐LightItalic
            [1mBMB     [22mBookman‐Demi
            [1mBMBI    [22mBookman‐DemiItalic
            [1mCR      [22mCourier
            [1mCI      [22mCourier‐Oblique
            [1mCB      [22mCourier‐Bold
            [1mCBI     [22mCourier‐BoldOblique
            [1mHR      [22mHelvetica
            [1mHI      [22mHelvetica‐Oblique
            [1mHB      [22mHelvetica‐Bold
            [1mHBI     [22mHelvetica‐BoldOblique
            [1mHNR     [22mHelvetica‐Narrow
            [1mHNI     [22mHelvetica‐Narrow‐Oblique
            [1mHNB     [22mHelvetica‐Narrow‐Bold
            [1mHNBI    [22mHelvetica‐Narrow‐BoldOblique
            [1mNR      [22mNewCenturySchlbk‐Roman
            [1mNI      [22mNewCenturySchlbk‐Italic
            [1mNB      [22mNewCenturySchlbk‐Bold
            [1mNBI     [22mNewCenturySchlbk‐BoldItalic
            [1mPR      [22mPalatino‐Roman
            [1mPI      [22mPalatino‐Italic
            [1mPB      [22mPalatino‐Bold
            [1mPBI     [22mPalatino‐BoldItalic
            [1mTR      [22mTimes‐Roman
            [1mTI      [22mTimes‐Italic
            [1mTB      [22mTimes‐Bold
            [1mTBI     [22mTimes‐BoldItalic

     Another text font is not a member of a family.

            [1mZCMI    [22mZapfChancery‐MediumItalic

     Special fonts include [1mS[22m, the PostScript Symbol font; [1mZD[22m, Zapf Dingbats;  [1mSS[0m
     (slanted  symbol),  which contains oblique forms of lowercase Greek letters
     derived from Symbol; [1mEURO[22m, which offers a Euro glyph for use with  old  de‐
     vices  lacking  it; and [1mZDR[22m, a reversed version of Zapf Dingbats (with sym‐
     bols flipped about the vertical axis).  Most glyphs in these fonts are  un‐
     named and must be accessed using [1m\N[22m.  The last three are not standard Post‐
     Script  fonts,  but supplied by [4mgroff[24m and therefore included in the default
     [4mdownload[24m file.

     [4mgrops[24m furthermore supports a naming scheme for East Asian typefaces  shared
     with ]8;;man:grohtml(1)\[4mgrohtml[24m(1)]8;;\, ]8;;man:gropdf(1)\[4mgropdf[24m(1)]8;;\, and ]8;;man:grotty(1)\[4mgrotty[24m(1)]8;;\.

            [1mCSH    [22mSimplified Chinese, Hei style
            [1mCSS    [22mSimplified Chinese, Song style
            [1mCTH    [22mTraditional Chinese, Hei style
            [1mCTS    [22mTraditional Chinese, Song style
            [1mJPG    [22mJapanese, Gothic style
            [1mJPM    [22mJapanese, Mincho style
            [1mKOG    [22mKorean, Gothic style
            [1mKOM    [22mKorean, Mincho style

   [1mDevice extension commands[0m
     [4mgrops[24m  recognizes  device  extension commands produced by the [4mgroff[24m request
     [1mdevice [22mor [4mroff[24m [1m\X [22mescape sequence, but interprets  only  those  that  begin
     with a “[1mps:[22m” tag.

     [1m\X'ps: exec [4m[22mcode[24m[1m'[0m
            Execute  the  arbitrary  PostScript  commands  [4mcode[24m.  The PostScript
            [4mcurrentpoint[24m is set to the [4mgroff[24m drawing position when the [1m\X [22mescape
            sequence is interpreted before executing [4mcode[24m.  The origin is at the
            top left corner of the page; [4mx[24m coordinates increase  to  the  right,
            and [4my[24m coordinates down the page.  A procedure [1mu [22mis defined that con‐
            verts [4mgroff[24m basic units to the coordinate system in effect (provided
            the user doesn’t change the scale).  For example,
                   .nr x 1i
                   \X'ps: exec \nx u 0 rlineto stroke'
            draws a horizontal line one inch long.  [4mcode[24m may make changes to the
            graphics state, but any changes persist only to the end of the page.
            A  dictionary  containing  the  definitions specified by the [1mdef [22mand
            [1mmdef [22mcommands is on top of the dictionary stack.  If your code  adds
            definitions  to  this dictionary, you should allocate space for them
            using “[1m\X'ps: mdef [4m[22mn[24m[1m'[22m”.  Any definitions persist only until the  end
            of  the  page.   If  you use the [1m\Y [22mescape sequence with an argument
            that names a macro, [4mcode[24m can extend over multiple lines.  For  exam‐
            ple,
                   .nr x 1i
                   .de y
                   ps: exec
                   \nx u 0 rlineto
                   stroke
                   ..
                   \Yy
            is  another way to draw a horizontal line one inch long.  The single
            backslash before “[1mnx[22m”——the only  reason  to  use  a  register  while
            defining  the  macro  “[1my[22m”——is  to convert a user‐specified dimension
            “[1m1i[22m” to [4mgroff[24m basic units which are in turn converted to  PostScript
            units with the [1mu [22mprocedure.

            [4mgrops[24m  wraps user‐specified PostScript code into a dictionary, noth‐
            ing more.  In particular, it doesn’t start and end the inserted code
            with [1msave [22mand [1mrestore[22m, respectively.  This must be supplied  by  the
            user, if necessary.

     [1m\X'ps: file [4m[22mname[24m[1m'[0m
            This is the same as the [1mexec [22mcommand except that the PostScript code
            is read from file [4mname[24m.

     [1m\X'ps: def [4m[22mcode[24m[1m'[0m
            Place  a  PostScript  definition  contained in [4mcode[24m in the prologue.
            There should be at most one definition per [1m\X [22mcommand.  Long defini‐
            tions can be split over several [1m\X [22mcommands; all the [4mcode[24m  arguments
            are  simply  joined together separated by newlines.  The definitions
            are placed in a dictionary which is automatically pushed on the dic‐
            tionary stack when an [1mexec [22mcommand is executed.  If you use  the  [1m\Y[0m
            escape sequence with an argument that names a macro, [4mcode[24m can extend
            over multiple lines.

     [1m\X'ps: mdef [4m[22mn[24m [4mcode[24m[1m'[0m
            Like  [1mdef[22m,  except that [4mcode[24m may contain up to [4mn[24m definitions.  [4mgrops[0m
            needs to know how many definitions [4mcode[24m contains so that it can cre‐
            ate an appropriately sized PostScript dictionary to contain them.

     [1m\X'ps: import [4m[22mfile[24m [4mllx[24m [4mlly[24m [4murx[24m [4mury[24m [4mwidth[24m [[4mheight[24m][1m'[0m
            Import a PostScript graphic from [4mfile[24m.  The arguments [4mllx[24m, [4mlly[24m, [4murx[24m,
            and [4mury[24m give the bounding box of the graphic in  the  default  Post‐
            Script  coordinate system.  They should all be integers: [4mllx[24m and [4mlly[0m
            are the [4mx[24m and [4my[24m coordinates of the lower left corner of the graphic;
            [4murx[24m and [4mury[24m are the [4mx[24m and [4my[24m coordinates of the upper right corner of
            the graphic; [4mwidth[24m and [4mheight[24m are integers  that  give  the  desired
            width and height in [4mgroff[24m basic units of the graphic.

            The  graphic  is  scaled  so  that  it has this width and height and
            translated so that the lower left corner of the graphic  is  located
            at  the position associated with [1m\X [22mcommand.  If the height argument
            is omitted it is scaled uniformly in the [4mx[24m and [4my[24m axes so that it has
            the specified width.

            The contents of the [1m\X [22mcommand are not interpreted by [4mtroff[24m, so ver‐
            tical space for the graphic is  not  automatically  added,  and  the
            [4mwidth[24m  and [4mheight[24m arguments are not allowed to have attached scaling
            indicators.

            If the PostScript file complies with the Adobe Document  Structuring
            Conventions  and contains a [1m%%BoundingBox [22mcomment, then the bounding
            box can be automatically extracted from within [4mgroff[24m input by  using
            the [1mpsbb [22mrequest.

            See  ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\  for  a description of the [1mPSPIC [22mmacro which pro‐
            vides a convenient high‐level interface for inclusion of  PostScript
            graphics.

     [1m\X'ps: invis'[0m
     [1m\X'ps: endinvis'[0m
            No output is generated for text and drawing commands that are brack‐
            eted  with  these  [1m\X [22mcommands.  These commands are intended for use
            when output from [4mtroff[24m is  previewed  before  being  processed  with
            [4mgrops[24m;  if  the previewer is unable to display certain characters or
            other constructs, then other substitute characters or constructs can
            be used for previewing by bracketing them with these [1m\X [22mcommands.

            For example, [4mgxditview[24m is not able to display a proper [1m\[em] [22mcharac‐
            ter because the standard X11 fonts do not provide it;  this  problem
            can be overcome with the following request.

                   .char \[em] \X'ps: invis'\
                   \Z'\v'‐.25m'\h'.05m'\D'l .9m 0'\h'.05m''\
                   \X'ps: endinvis'\[em]

            In this case, [4mgxditview[24m is unable to display the [1m\[em] [22mcharacter and
            draws the line, whereas [4mgrops[24m prints the [1m\[em] [22mcharacter and ignores
            the  line (this code is already in file [4mXps.tmac[24m, which is loaded if
            a document intended for [4mgrops[24m is previewed with [4mgxditview[24m).

     If a PostScript procedure [1mBPhook [22mhas  been  defined  via  a  “[1mps:  def[22m”  or
     “[1mps:  mdef[22m”  device  extension  command, it is executed at the beginning of
     every page (before anything is drawn or written by [4mgroff[24m).  For example, to
     underlay the page contents with the word “DRAFT” in light gray,  you  might
     use the following.
            .de XX
            ps: def
            /BPhook
            { gsave .9 setgray clippath pathbbox exch 2 copy
              .5 mul exch .5 mul translate atan rotate pop pop
              /NewCenturySchlbk‐Roman findfont 200 scalefont setfont
              (DRAFT) dup stringwidth pop -.5 mul -70 moveto show
              grestore }
            def
            ..
            .devicem XX

     Or,  to  cause  lines  and  polygons  to  be drawn with square linecaps and
     mitered linejoins instead of the round linecaps and linejoins normally used
     by [4mgrops[24m, use the following.
            .de XX
            ps: def
            /BPhook { 2 setlinecap 0 setlinejoin } def
            ..
            .devicem XX
     (Square linecaps, as opposed to butt linecaps (“[1m0 setlinecap[22m”),  give  true
     corners in boxed tables even though the lines are drawn unconnected.)

   [1mEncapsulated PostScript[0m
     [4mgrops[24m  itself doesn’t emit bounding box information.  The following script,
     [4mgroff2eps[24m, produces an EPS file.

            #!/bin/sh
            groff -P-b16 "$1" > "$1".ps
            gs -dNOPAUSE -sDEVICE=bbox -- "$1".ps 2> "$1".bbox
            sed -e "/^%%Orientation/r $1.bbox" \
                -e "/^%!PS-Adobe-3.0/s/$/ EPSF-3.0/" "$1".ps > "$1".eps
            rm "$1".ps "$1".bbox

     You can then use “[1mgroff2eps foo[22m” to convert file [4mfoo[24m to [4mfoo.eps[24m.

   [1mTrueType and other font formats[0m
     To use TrueType fonts with [4mgrops[24m, convert them first to Type 42  format,  a
     PostScript  wrapper  equivalent  to the PFA format described in ]8;;man:pfbtops(1)\[4mpfbtops[24m(1)]8;;\.
     Several methods exist to generate a Type 42 wrapper; some of  them  involve
     the use of a PostScript interpreter such as Ghostscript——see ]8;;man:gs(1)\[4mgs[24m(1)]8;;\.

     ]8;;https://fontforge.org/\FontForge]8;;\  converts  most outline font formats.  Here’s how we’d set up Ro‐
     boto Slab Serif for use with [4mgroff[24m.

         MAP=/usr/share/groff/1.24.1/font/devps/generate/text.map
         TTF=/usr/share/fonts/truetype/roboto/slab/RobotoSlab-Regular.ttf
         BASE=$(basename "$TTF")
         INT=${BASE%.ttf}
         PFA=$INT.pfa
         AFM=$INT.afm
         GFN=RSR
         DIR=$HOME/.local/groff/font
         mkdir -p "$DIR"/devps
         fontforge -lang=ff -c "Open(\"$TTF\");\
         Generate(\"$DIR/devps/$PFA\");"
         afmtodit "$DIR/devps/$AFM" "$MAP" "$DIR/devps/$GFN"
         printf "$BASE\t$PFA\n" >> "$DIR/devps/download"

     [4mfontforge[24m and [4mafmtodit[24m may produce warnings depending on font file  attrib‐
     utes.  Test the font as follows.

         printf ".ft RSR\nHello, world!\n" | groff -F "$DIR" > hello.ps

     Once  you’re  satisfied  that  the font works, you may want to generate any
     available related styles  (for  instance,  Roboto  Slab  also  has  “Bold”,
     “Light”,  and “Thin” styles) and set up [4mGROFF_FONT_PATH[24m in your environment
     to include the directory you keep the generated fonts in so that you  don’t
     have to use the [1m-F [22moption.

[1mFont installation[0m
     For  your  convenience, [4mgroff[24m offers [4minstall-font.bash[24m, a shell script that
     interactively assists the configuration of fonts for use with the GNU [4mtroff[0m
     formatter and the [4mgrops[24m output driver.  See section “Files” below.

     The following is a step‐by‐step font installation guide for [4mgrops.[0m

     •  Convert your font to something [4mgroff[24m understands.  This is a  PostScript
        Type 1 font in PFA format or a PostScript Type 42 font, together with an
        AFM file.  A PFA file begins as follows.
               %!PS-AdobeFont-1.0:
        A  PFB  file contains this string as well, preceded by some non‐printing
        bytes.  If your font is in PFB format, use [4mgroff[24m’s ]8;;man:pfbtops(1)\[4mpfbtops[24m(1)]8;;\ program to
        convert it to PFA.  For TrueType and other font  formats,  we  recommend
        [4mfontforge[24m,  which can convert most outline font formats.  A Type 42 font
        file begins as follows.
               %!PS-TrueTypeFont
        This is a wrapper format for TrueType fonts.   Old  PostScript  printers
        might not support them (that is, they might not have a built‐in TrueType
        font  interpreter).  In the following steps, we will consider the use of
        CTAN’s ]8;;https://ctan.org/tex-archive/fonts/brushscr\BrushScriptX‐Italic]8;;\ font in PFA format.

     •  Convert the  AFM  file  to  a  [4mgroff[24m  font  description  file  with  the
        ]8;;man:afmtodit(1)\[4mafmtodit[24m(1)]8;;\ program.  For instance,
               $ [1mafmtodit BrushScriptX-Italic.afm text.map BSI[0m
        converts the Adobe Font Metric file [4mBrushScriptX-Italic.afm[24m to the [4mgroff[0m
        font description file [4mBSI[24m.

        If  you have a font family which provides regular upright (roman), bold,
        italic, and bold‐italic styles  (where  “italic”  may  be  “oblique”  or
        “slanted”),  we  recommend  using  the  letters [1mR[22m, [1mB[22m, [1mI[22m, and [1mBI[22m, respec‐
        tively, as suffixes to the [4mgroff[24m font family name to enable [4mgroff[24m’s font
        family and style selection features.  An  example  is  [4mgroff[24m’s  built‐in
        support  for  Times:  the  font family name is abbreviated as [1mT[22m, and the
        [4mgroff[24m font names are therefore [1mTR[22m, [1mTB[22m, [1mTI[22m, and  [1mTBI[22m.   In  our  example,
        however,  the  BrushScriptX  font  is  available in a single style only,
        italic.

     •  Install the [4mgroff[24m font description file(s) in a  [4mdevps[24m  subdirectory  in
        the  search  path that [4mgroff[24m uses for device and font file descriptions.
        See the [4mGROFF_FONT_PATH[24m entry in section “Environment” of  ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\  for
        the current value of the font search path.  While [4mgroff[24m doesn’t directly
        use  AFM  files,  it is a good idea to store them alongside its font de‐
        scription files.

     •  Register fonts in the [4mdevps/download[24m file so they can be located for em‐
        bedding in PostScript files [4mgrops[24m generates.  Only  the  first  [4mdownload[0m
        file encountered in the font search path is read.  If in doubt, copy the
        default [4mdownload[24m file (see section “Files” below) to the first directory
        in  the  font search path and add your fonts there.  The PostScript font
        name used by [4mgrops[24m is stored in the [1minternalname [22mfield in the [4mgroff[24m font
        description file.  (This name does not necessarily resemble  the  font’s
        file name.)  We add the following line to [4mdownload[24m.
               BrushScriptX-Italic→BrushScriptX-Italic.pfa
        A tab character, depicted as →, separates the fields.

     •  Test the selection and embedding of the new font.
               printf "\\f[BSI]Hello, world!\n" | groff -T ps >hello.ps
               see hello.pdf

[1mOld fonts[0m
     [4mgroff[24m versions 1.19.2 and earlier contained descriptions of a slightly dif‐
     ferent  set  of the base 35 PostScript level 2 fonts defined by Adobe.  The
     older set has 314 glyphs and a larger set of kerning pairs; the  newer  one
     has  only 229 glyphs, but includes the Euro sign.  For backward compatibil‐
     ity, these old font descriptions are  also  installed  in  the  [4m/usr/share/[0m
     [4mgroff/1.24.1/oldfont/devps[24m directory.

     To use them, make sure that [4mgrops[24m finds the fonts before the default system
     fonts (with the same names): either give [4mgrops[24m the [1m-F [22mcommand‐line option,
            $ [1mgroff -Tps -P-F -P/usr/share/groff/1.24.1/oldfont [22m...
     or add the directory to [4mgroff[24m’s font and device description search path en‐
     vironment variable,
            $ [1mGROFF_FONT_PATH=/usr/share/groff/1.24.1/oldfont \[0m
                   [1mgroff -Tps [22m...
     when the command runs.

[1mExit status[0m
     [4mgrops[24m  exits with status [1m0 [22mon successful operation, status [1m2 [22mif the program
     cannot interpret its command‐line arguments, and status [1m1 [22mif it  encounters
     an error during operation.

[1mEnvironment[0m
     [4mGROFF_FONT_PATH[0m
            A  list of directories in which to seek the selected output device’s
            directory of device and font description files.   See  ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\  and
            ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

     [4mGROPS_PROLOGUE[0m
            If  this  is  set  to [4mfoo[24m, then [4mgrops[24m uses the file [4mfoo[24m (in the font
            path) instead of the default prologue file [4mprologue[24m.  The option  [1m-P[0m
            overrides this environment variable.

     [4mSOURCE_DATE_EPOCH[0m
            A  timestamp  (expressed  as seconds since the Unix epoch) to use as
            the output creation timestamp in place of  the  current  time.   The
            time  is  converted  to  human‐readable  form  using  ]8;;man:gmtime(3)\[4mgmtime[24m(3)]8;;\  and
            ]8;;man:asctime(3)\[4masctime[24m(3)]8;;\, and recorded in a PostScript comment.

     [4mTZ[24m     The time zone to use when converting the current time to human‐read‐
            able form; see ]8;;man:tzset(3)\[4mtzset[24m(3)]8;;\.  If [4mSOURCE_DATE_EPOCH[24m is used, it is always
            converted to human‐readable form using UTC.

[1mFiles[0m
     [4m/usr/share/groff/1.24.1/font/devps/DESC[0m
            describes the [1mps [22moutput device.

     [4m/usr/share/groff/1.24.1/font/devps/[24mF
            describes the font known as [4mF[24m on device [1mps[22m.

     [4m/usr/share/groff/1.24.1/font/devps/download[0m
            lists fonts available for embedding within the  PostScript  document
            (or download to the device).

     [4m/usr/share/groff/1.24.1/font/devps/prologue[0m
            is the default PostScript prologue prefixed to every output file.

     [4m/usr/share/groff/1.24.1/font/devps/text.enc[0m
            describes  the encoding scheme used by most PostScript Type 1 fonts;
            the [1mencoding [22mdirective of font description files for the  [1mps  [22mdevice
            refers to it.

     [4m/usr/share/groff/1.24.1/tmac/ps.tmac[0m
            defines  macros  for use with the [1mps [22moutput device.  It is automati‐
            cally loaded by [4mtroffrc[24m when the [1mps [22moutput device is selected.

     [4m/usr/share/groff/1.24.1/tmac/pspic.tmac[0m
            defines the [1mPSPIC [22mmacro for embedding  images  in  a  document;  see
            ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\.  It is automatically loaded by [4mtroffrc.[0m

     [4m/usr/share/groff/1.24.1/tmac/psold.tmac[0m
            provides replacement glyphs for text fonts that lack complete cover‐
            age  of  the  ISO Latin‐1 character set; using it, [4mgroff[24m can produce
            glyphs like eth (ð) and thorn (þ) that older PostScript printers  do
            not natively support.

     [4m/usr/share/doc/groff-1.24.1/examples/install-font.bash[0m
            This script, contributed by [4mmom[24m macro package author Peter Schaffter
            and  long  available  at  his web site, assists with making TrueType
            ([4m.ttf[24m), OpenType ([4m.otf[24m), and PostScript Type 1  ([4m.pfa[24m,  [4m.pfb[24m)  fonts
            available to [4mgroff[24m.

            Change  to  its  directory and run “[1mbash install-font.bash -H[22m” for a
            man page‐like description of its features and operation.

     [4mgrops[24m  creates  temporary  files  using  the  template  “[4mgrops[24mXXXXXX”;  see
     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\.

[1mSee also[0m
     ]8;;http://partners.adobe.com/public/developer/en/ps/5001.DSC_Spec.pdf\PostScript Language Document Structuring Conventions Specification]8;;\

     ]8;;man:afmtodit(1)\[4mafmtodit[24m(1)]8;;\,  ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\, ]8;;man:pfbtops(1)\[4mpfbtops[24m(1)]8;;\, ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\, ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\,
     ]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\, ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\

groff 1.24.1                       2026‐03‐20                           [4mgrops[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mgrotty[24m(1)                    General Commands Manual                   [4mgrotty[24m(1)

[1mName[0m
     grotty - [4mgroff[24m output driver for typewriter‐like (terminal) devices

[1mSynopsis[0m
     [1mgrotty [22m[[1m-dfhot[22m] [[1m-i[22m|[1m-r[22m] [[1m-F [4m[22mfont‐directory[24m] [[4mfile[24m ...]

     [1mgrotty -c [22m[[1m-bBdfhouU[22m] [[1m-F [4m[22mfont‐directory[24m] [[4mfile[24m ...]

     [1mgrotty --help[0m

     [1mgrotty -v[0m
     [1mgrotty --version[0m

[1mDescription[0m
     The GNU [4mroff[24m TTY  (“Teletype”)  output  driver  translates  the  output  of
     ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\  into a form suitable for typewriter‐like devices, including video
     terminal emulators.  Normally, [4mgrotty[24m is invoked by ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ when the  lat‐
     ter is given one of the “[1m-T ascii[22m”, “[1m-T latin1[22m”, or “[1m-T utf8[22m” options.  (In
     this installation, [1mps [22mis the default output device.)  Use [4mgroff[24m’s [1m-P [22moption
     to pass any options shown above to [4mgrotty[24m.  If no [4mfile[24m arguments are given,
     or  if  [4mfile[24m  is “-”, [4mgrotty[24m reads the standard input stream.  It writes to
     the standard output stream.

     By default, [4mgrotty[24m emits SGR escape sequences  (from  ISO  6429,  popularly
     called  “ANSI escapes”) to change text attributes (bold, italic, underline,
     reverse video [“negative image”] and colors).  Devices supporting SGR 30–37
     and 40–47 sequences can view [4mroff[24m documents  using  eight  different  back‐
     ground  and  foreground  colors.   [4mgrotty[24m’s [4mtty.tmac[24m file defines the eight
     color names of ISO 6429: black, white, red, green, blue,  yellow,  magenta,
     and cyan.  Unrecognized colors map to the default color, the value of which
     depends on the settings of the terminal.  Also see the [1m-t [22moption below.

     By  default,  [4mgrotty[24m produces OSC 8 hyperlinks on devices employing SGR es‐
     cape sequences.

     In accord with long‐standing practice and terminals (emulators)  that  lack
     support  for  slanted  (oblique  or  italic) faces, [4mgrotty[24m marks italicized
     character cells with underlines instead by default——but see the  [1m-i  [22moption
     below.

   [1mSGR and OSC support in pagers[0m
     When  paging  [4mgrotty[24m’s  output with ]8;;man:less(1)\[4mless[24m(1)]8;;\, the latter program must be in‐
     structed to pass SGR and OSC sequences through to the device; its [1m-R [22moption
     is one way to achieve this ([4mless[24m version 566 or later is required for OSC 8
     support).  Consequently, programs like ]8;;man:man(1)\[4mman[24m(1)]8;;\ that page [4mroff[24m documents with
     [4mless[24m must call it with an appropriate option.

   [1mLegacy output format[0m
     The [1m-c [22moption tells [4mgrotty[24m to use an output format  compatible  with  paper
     terminals,  like  the Teletype machines for which [4mroff[24m and [4mnroff[24m were first
     developed but which are no longer in wide use.  SGR  escape  sequences  are
     not  emitted;  bold,  italic, and underlining character attributes are thus
     not manipulated.  Instead, [4mgrotty[24m overstrikes, representing a bold  charac‐
     ter [4mc[24m with the sequence “[4mc[24m BACKSPACE [4mc[24m”, an italic character [4mc[24m with the se‐
     quence  “[1m_ [22mBACKSPACE [4mc[24m”, and bold italics with “[1m_ [22mBACKSPACE [4mc[24m BACKSPACE [4mc[24m”.
     This rendering is inherently ambiguous when the character [4mc[24m is  itself  the
     underscore.

     The  legacy output format can be rendered on a video terminal (or emulator)
     by piping [4mgrotty[24m’s output through ]8;;man:ul(1)\[4mul[24m(1)]8;;\, which may render bold  italics  as
     reverse  video.   Some  implementations of ]8;;man:more(1)\[4mmore[24m(1)]8;;\ also are able to display
     these sequences; you may wish to experiment with that command’s [1m-b  [22moption.
     [4mless[24m  renders  legacy  bold and italics without requiring options.  In con‐
     trast to the terminal output drivers of some  other  [4mroff[24m  implementations,
     [4mgrotty[24m  never  outputs  reverse line feeds.  You need not filter its output
     through ]8;;man:col(1)\[4mcol[24m(1)]8;;\ to remove them.

   [1mDevice extension commands[0m
     [4mgrotty[24m recognizes a device extension command produced by the [4mgroff[24m  request
     [1mdevice [22mor [4mroff[24m [1m\X [22mescape sequence.

     [1m\X'tty: link [22m[[4muri[24m [[4mkey[24m[1m=[4m[22mvalue[24m] ...][1m'[0m
            Embed  a hyperlink using the OSC 8 terminal escape sequence.  Speci‐
            fying [4muri[24m starts hyperlinked text, and omitting it ends  the  hyper‐
            link.  When [4muri[24m is present, any number of additional key/value pairs
            can  be specified; their interpretation is the responsibility of the
            pager or terminal.  Spaces or tabs cannot appear literally  in  [4muri[24m,
            [4mkey[24m, or [4mvalue[24m; they must be represented in an alternate form.

   [1mDevice description files[0m
     If  the  [4mDESC[24m file for the character encoding contains the “[1municode[22m” direc‐
     tive, [4mgrotty[24m emits Unicode characters in  UTF‐8  encoding.   Otherwise,  it
     emits  characters  in  a  single‐byte encoding depending on the data in the
     font description files.  See ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

     A font description file may contain a directive “[1minternalname [4m[22mn[24m” where [4mn[24m is
     a decimal integer.  If the 01 bit in [4mn[24m is set, [4mgrotty[24m treats  the  font  as
     slanted; if the 02 bit is set, [4mgrotty[24m treats the font as bold.

   [1mTypefaces[0m
     [4mgrotty[24m  supports the standard four styles: [1mR [22m(roman), [1mI [22m([4mitalic[24m), [1mB [22m([1mbold[22m),
     and [1mBI [22m([4m[1mbold‐italic[24m[22m).  Because the output driver operates  in  [4mnroff[24m  mode,
     attempts to set or change the font family or type size are ignored.

     [4mgrotty[24m  shares  a  naming  scheme for East Asian typefaces with ]8;;man:grohtml(1)\[4mgrohtml[24m(1)]8;;\,
     ]8;;man:gropdf(1)\[4mgropdf[24m(1)]8;;\, and ]8;;man:grops(1)\[4mgrops[24m(1)]8;;\.

            [1mCSH    [22mSimplified Chinese, Hei style
            [1mCSS    [22mSimplified Chinese, Song style
            [1mCTH    [22mTraditional Chinese, Hei style
            [1mCTS    [22mTraditional Chinese, Song style
            [1mJPG    [22mJapanese, Gothic style
            [1mJPM    [22mJapanese, Mincho style
            [1mKOG    [22mKorean, Gothic style
            [1mKOM    [22mKorean, Mincho style

[1mOptions[0m
     [1m--help [22mdisplays a usage message, while [1m-v [22mand [1m--version [22mshow version infor‐
     mation; all exit afterward.

     [1m-b      [22mSuppress the use of overstriking for bold characters in legacy out‐
             put format.

     [1m-B      [22mUse only overstriking for bold‐italic characters in  legacy  output
             format.

     [1m-c      [22mUse  [4mgrotty[24m’s  legacy  output format (see subsection “Legacy output
             format” above).  SGR and OSC escape sequences are not emitted.

     [1m-d      [22mIgnore all drawing commands in the input.  By default, [4mgrotty[24m  ren‐
             ders  “[1mD  l[22m”  commands that have at least one zero argument (and so
             are either horizontal or vertical) using Unicode box drawing  char‐
             acters (for the [1mutf8 [22mdevice) or the [1m-[22m, [1m|[22m, and [1m+ [22mcharacters (for all
             other  devices).   [4mgrotty[24m  handles  “[1mD p[22m” commands that consist en‐
             tirely  of  horizontal   and   vertical   lines   similarly.    See
             ]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\.

     [1m-f      [22mEmit  a  form  feed at the end of each page having no output on its
             last line.

     [1m-F [4m[22mdir[24m  Prepend directory dir[4m/dev[24mname to the search path for font  and  de‐
             vice  description files; [4mname[24m describes the output device’s charac‐
             ter encoding, one of [1mascii[22m, [1mlatin1[22m, or [1mutf8[22m.

     [1m-h      [22mUse literal horizontal tab characters in the output.  Tabs are  as‐
             sumed to be set every 8 columns.

     [1m-i      [22mRender  fonts  marked  as slanted with the SGR attribute for italic
             text rather than underlined text.   Many  terminals  don’t  support
             this  attribute;  however, ]8;;man:xterm(1)\[4mxterm[24m(1)]8;;\, since patch #314 (2014‐12‐28),
             does.  Ignored if [1m-c [22mis also specified.

     [1m-o      [22mSuppress overstriking (other than for bold and/or underlined  char‐
             acters  when the legacy output format is in use; see options [1m-b [22mand
             [1m-u[22m).

     [1m-r      [22mRender fonts marked as slanted with the SGR attribute  for  reverse
             video  text  rather  than  underlined text.  Ignored if [1m-c [22mor [1m-i [22mis
             also specified.

     [1m-t      [22mAssume that the output device supports SGR 38  and  48  escape  se‐
             quences,  which  permit  specification of character cell foreground
             and background colors in the RGB color space with 8 bits per  chan‐
             nel.

     [1m-u      [22mSuppress  the  use  of  underlining for italic characters in legacy
             output format.

     [1m-U      [22mUse only underlining for bold‐italic characters  in  legacy  output
             format.

[1mExit status[0m
     [4mgrotty[24m exits with status [1m0 [22mon successful operation, status [1m2 [22mif the program
     cannot  interpret its command‐line arguments, and status [1m1 [22mif it encounters
     an error during operation.

[1mEnvironment[0m
     [4mGROFF_FONT_PATH[0m
            A list of directories in which to seek the selected output  device’s
            directory  of  device  and font description files.  See ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ and
            ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

     [4mGROFF_NO_SGR[0m
            If set, [4mgrotty[24m’s legacy output format is used just as if the [1m-c  [22mop‐
            tion were specified; see subsection “Legacy output format” above.

[1mFiles[0m
     [4m/usr/share/groff/1.24.1/font/devascii/DESC[0m
            describes the [1mascii [22moutput device.

     [4m/usr/share/groff/1.24.1/font/devascii/[24mF
            describes the font known as [4mF[24m on device [1mascii[22m.

     [4m/usr/share/groff/1.24.1/font/devlatin1/DESC[0m
            describes the [1mlatin1 [22moutput device.

     [4m/usr/share/groff/1.24.1/font/devlatin1/[24mF
            describes the font known as [4mF[24m on device [1mlatin1[22m.

     [4m/usr/share/groff/1.24.1/font/devutf8/DESC[0m
            describes the [1mutf8 [22moutput device.

     [4m/usr/share/groff/1.24.1/font/devutf8/[24mF
            describes the font known as [4mF[24m on device [1mutf8[22m.

     [4m/usr/share/groff/1.24.1/tmac/tty.tmac[0m
            defines  macros  for use with the [1mascii[22m, [1mlatin1[22m, and [1mutf8 [22moutput de‐
            vices.  It is automatically loaded by [4mtroffrc[24m when any of those out‐
            put devices is selected.

     [4m/usr/share/groff/1.24.1/tmac/tty-char.tmac[0m
            defines fallback characters for use with [4mgrotty.[24m  See ]8;;man:nroff(1)\[4mnroff[24m(1)]8;;\.

[1mLimitations[0m
     [4mgrotty[24m is intended only for simple documents.

     •  There is no support for horizontal or vertical motions  smaller  than  a
        character cell.

     •  Drawing  commands  producing anything other than horizontal and vertical
        lines are not supported.

     •  Color handling differs from other output drivers.  The GNU [4mtroff[24m  output
        commands  produced  by requests and escape sequences that set the stroke
        and fill colors instead set the foreground and background character cell
        colors, respectively.

     The commands generated by the [1m\l [22mand [1m\L [22mescape sequences on one  hand,  and
     the [1m\D'l' [22mline‐drawing escape sequence on the other, make different compro‐
     mises  due to the first two factors.  Specifically, (1) [1m\l [22mdraws horizontal
     lines with underscore characters; [1m\D'l' [22muses ACS  or  Unicode  line‐drawing
     characters  if  possible,  and  hyphen‐minus signs if not.  (2) [1m\D'l' [22mdraws
     vertical lines an extra character cell high, and horizontal lines an  extra
     cell  to  the right.  [4mgrotty[24m does this to detect intersecting lines so that
     it can replace them with glyphs of appropriate appearance (like “+”).   Ob‐
     serve the difference below.

     The input

            Hello,\L'1v'
            world.\l'1n'
            .sp 2v
            Hello,\D'l 0 1v'
            world.\D'l 1n 0'
            .pl \n(nlu \" truncate page for convenience

     rendered with “[1mnroff -T ascii[22m” produces the following output.

            Hello,
                  | world._

            Hello,|
                  |world.--

[1mExamples[0m
     The  following  [4mgroff[24m  document exercises several features for which output
     device support varies:  (1)  bold  style;  (2)  italic  (underline)  style;
     (3)  bold‐italic style; (4) character composition by overstriking (“coöper‐
     ate”); (5) foreground color; (6) background color; and (7)  horizontal  and
     vertical line drawing.

            You might see \f[B]bold\f[] and \f[I]italic\f[].
            Some people see \f[BI]both at once\f[].
            If the output device does (not) co\z\[ad]operate,
            you might see \m[red]red\m[].
            Black on cyan can have a \M[cyan]\m[black]prominent\m[]\M[]
            \D'l 1i 0'\D'l 0 2i'\D'l 1i 0' look.
            .\" If in nroff mode, end page now.
            .if n .pl \n[nl]u

     Given  the  foregoing input, compare and contrast the output of the follow‐
     ing.

            $ [1mgroff -T ascii [4m[22mfile[0m
            $ [1mgroff -T utf8 -P -i [4m[22mfile[0m
            $ [1mgroff -T utf8 -P -c [4m[22mfile[24m [1m| ul[0m

[1mSee also[0m
     ]8;;https://ecma-international.org/wp-content/uploads/ECMA-48_5th_edition_june_1991.pdf\“Control  Functions  for Coded Character Sets” (ECMA‐48) 5th  edition, Ecma
     International, June 1991.]8;;\ A gratis version of ISO 6429, this  document  in‐
     cludes a normative description of SGR escape sequences.

     ]8;;https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda\“Hyperlinks in Terminal Emulators”]8;;\, Egmont Koblinger.

     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\,  ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\,  ]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\,  ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\,  ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\,  ]8;;man:ul(1)\[4mul[24m(1)]8;;\,
     ]8;;man:more(1)\[4mmore[24m(1)]8;;\, ]8;;man:less(1)\[4mless[24m(1)]8;;\, ]8;;man:man(1)\[4mman[24m(1)]8;;\

groff 1.24.1                       2026‐03‐20                          [4mgrotty[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mhpftodit[24m(1)                  General Commands Manual                 [4mhpftodit[24m(1)

[1mName[0m
     hpftodit - create font description files for use with [4mgroff[24m and [4mgrolj4[0m

[1mSynopsis[0m
     [1mhpftodit [22m[[1m-aqs[22m] [[1m-i [4m[22mn[24m] [4mtfm‐file[24m [4mmap‐file[24m [4mfont‐description[0m

     [1mhpftodit -d [4m[22mtfm‐file[24m [[4mmap‐file[24m]

     [1mhpftodit --help[0m

     [1mhpftodit -v[0m
     [1mhpftodit --version[0m

[1mDescription[0m
     [4mhpftodit[24m creates a font description file for  use  with  a  Hewlett‐Packard
     LaserJet  4‐series  (or  newer)  printer and the ]8;;man:grolj4(1)\[4mgrolj4[24m(1)]8;;\ output driver of
     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, using data from an HP tagged font metric (TFM) file.  [4mtfm‐file[24m is
     the name of the font’s TFM file; Intellifont and  TrueType  TFM  files  are
     supported, but symbol set TFM files are not.  [4mmap‐file[24m is a file giving the
     [4mgroff[24m  special  character  identifiers  for  glyphs  in the font; this file
     should consist of a sequence of lines of the form
            [4mm[24m [4mu[24m [4mc1[24m [4mc2[24m ... [# [4mcomment[24m]
     where [4mm[24m is a decimal integer giving the glyph’s MSL  (Master  Symbol  List)
     number,  [4mu[24m  is a hexadecimal integer giving its Unicode character code, and
     [4mc1[24m, [4mc2[24m, ...  are its [4mgroff[24m glyph names (see ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\ for a list).  The
     values can be separated by any number of spaces and/or tabs.   The  Unicode
     value  must  use  uppercase hexadecimal digits A–F, and must lack a leading
     “[1m0x[22m”, “[1mu[22m”, or “[1mU+[22m”.  Unicode values corresponding to composite  glyphs  are
     decomposed;  that is “[1mu00C0[22m” becomes “[1mu0041_0300[22m”.  A glyph without a [4mgroff[0m
     special character identifier may be named [1mu[4m[22mXXXX[24m if the glyph corresponds to
     a Unicode value, or as an unnamed glyph “[1m---[22m”.  If the given Unicode  value
     is  in the Private Use Area (PUA) (0xE000–0xF8FF), the glyph is included as
     an unnamed glyph.  Refer to ]8;;man:groff_diff(1)\[4mgroff_diff[24m(1)]8;;\ for additional information  about
     unnamed glyphs and how to access them.

     Blank  lines and lines beginning with “[1m#[22m” are ignored.  A “[1m#[22m” following one
     or more [4mgroff[24m names begins a comment.  Because “[1m#[22m” is a valid  [4mgroff[24m  name,
     it  must appear first in a list of [4mgroff[24m names if a comment is included, as
     in
            3   0023   #   # number sign
     or
            3   0023   # sh   # number sign
     whereas in
            3   0023   sh #   # number sign
     the first “[1m#[22m” is interpreted as the beginning of the comment.

     [4mhpftodit[24m writes output to [4mfont‐description,[24m a file named for  the  intended
     [4mgroff[24m  font  name;  if this operand is “[1m-[22m”, [4mhpftodit[24m writes to the standard
     output stream.  The [1m-i [22moption directs [4mhpftodit[24m to automatically generate an
     italic correction, a left italic correction, and a subscript correction for
     each glyph.  See ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

[1mOptions[0m
     [1m--help [22mdisplays a usage message, while [1m-v [22mand [1m--version [22mshow version infor‐
     mation; all exit afterward.

     [1m-a     [22mInclude glyphs in the TFM file that are not included in [4mmap‐file[24m.  A
            glyph with corresponding Unicode value is given the  name  u[4mXXXX[24m;  a
            glyph without a Unicode value is included as an unnamed glyph “---”.
            A glyph with a Unicode value in the Private Use Area (0xE000–0xF8FF)
            is also included as an unnamed glyph.

            This  option provides a simple means of adding Unicode‐named and un‐
            named glyphs to a font without including them in the map  file,  but
            it  affords little control over which glyphs are placed in a regular
            font and which are placed in a special font.  The  presence  or  ab‐
            sence of the [1m-s [22moption has some effect on which glyphs are included:
            without  it,  only  the “text” symbol sets are searched for matching
            glyphs; with it, only the “mathematical” symbol sets  are  searched.
            Nonetheless,  restricting the symbol sets searched isn’t very selec‐
            tive——many glyphs are placed in  both  regular  and  special  fonts.
            Normally, [1m-a [22mshould be used only as a last resort.

     [1m-d     [22mDump  information  about the TFM file to the standard output stream;
            use this to ensure that a TFM file is a proper match for a font, and
            that its contents are suitable.  The information includes the values
            of important TFM tags and a listing (by MSL number  for  Intellifont
            TFM  files or by Unicode value for TrueType TFM files) of the glyphs
            included in the TFM file.  The unit of measure “DU”  for  some  tags
            indicates  design  units; there are 8782 design units per em for In‐
            tellifont fonts, and 2048 design units per em  for  TrueType  fonts.
            Note that the accessibility of a glyph depends on its inclusion in a
            symbol  set;  some  TFM files list many glyphs but only a few symbol
            sets.

            The glyph listing includes the glyph index within the TFM file,  the
            MSL  or  Unicode  value,  and the symbol set and character code that
            will be used to print the glyph.  If [4mmap‐file[24m is given, [4mgroff[24m  names
            are  given  for matching glyphs.  If only the glyph index and MSL or
            Unicode value are given, the glyph does not appear in any  supported
            symbol set and cannot be printed.

            With the [1m-d [22moption, [4mmap‐file[24m is optional, and [4moutput‐font[24m is ignored
            if given.

     [1m-i [4m[22mn[24m   Generate  an italic correction for each glyph so that its width plus
            its italic correction is equal to [4mn[24m thousandths of an  em  plus  the
            amount  by  which  the right edge of the glyphs’s bounding box is to
            the right of its origin.  The minimum value [4mhpftodit[24m will  write  is
            zero.

            Also  generate  a  subscript  correction equal to the product of the
            tangent of the slant of the font and four fifths of the x‐height  of
            the font.  If a subscript correction greater than the italic correc‐
            tion  would  result,  use a subscript correction equal to the italic
            correction instead.

            Also generate a left italic correction for each  glyph  equal  to  [4mn[0m
            thousandths  of  an em plus the amount by which the left edge of the
            glyphs’s bounding box is to the left of its origin.  The left italic
            correction may be negative.

            This option normally is needed only with italic or oblique fonts;  a
            value of 50 (0.05 em) usually is a reasonable choice.

     [1m-q     [22mSuppress  warnings  about glyphs in the map file that were not found
            in the TFM file.  Warnings never are given for unnamed glyphs or  by
            glyphs  named  by  their Unicode values.  This option is useful when
            sending the output of [4mhpftodit[24m to the standard output stream.

     [1m-s     [22mAdd the [1mspecial [22mdirective to the font  description  file,  affecting
            the  order  in  which  HP  symbol  sets are searched for each glyph.
            Without this option, the “text” sets are searched before the “mathe‐
            matical” symbol sets.  With it, the search order is reversed.

[1mExit status[0m
     [4mhpftodit[24m exits with status [1m0 [22mon successful operation, status [1m2 [22mif the  pro‐
     gram  cannot  interpret  its command‐line arguments, and status [1m1 [22mif it en‐
     counters an error during operation.

[1mFiles[0m
     [4m/usr/share/groff/1.24.1/font/devlj4/DESC[0m
            describes the [1mlj4 [22moutput device.

     [4m/usr/share/groff/1.24.1/font/devlj4/[24mF
            describes the font known as [4mF[24m on device [1mlj4[22m.

     [4m/usr/share/groff/1.24.1/font/devlj4/generate/Makefile[0m
            is a ]8;;man:make(1)\[4mmake[24m(1)]8;;\ script that uses ]8;;man:hpftodit(1)\[4mhpftodit[24m(1)]8;;\ to prepare the [4mgroff[24m  font
            description files above from HP TFM data; it can be used to regener‐
            ate them in the event the TFM files are updated.

     [4m/usr/share/groff/1.24.1/font/devlj4/generate/special.awk[0m
            is  an ]8;;man:awk(1)\[4mawk[24m(1)]8;;\ script that corrects the Intellifont‐based height met‐
            rics for several glyphs in the [1mS  [22m(special)  font  for  TrueType  CG
            Times used in the HP LaserJet 4000 and later.

     [4m/usr/share/groff/1.24.1/font/devlj4/generate/special.map[0m
     [4m/usr/share/groff/1.24.1/font/devlj4/generate/symbol.map[0m
     [4m/usr/share/groff/1.24.1/font/devlj4/generate/text.map[0m
     [4m/usr/share/groff/1.24.1/font/devlj4/generate/wingdings.map[0m
            map  MSL  indices  and  HP  Unicode PUA assignments to [4mgroff[24m special
            character identifiers.

[1mSee also[0m
     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, ]8;;man:groff_diff(1)\[4mgroff_diff[24m(1)]8;;\, ]8;;man:grolj4(1)\[4mgrolj4[24m(1)]8;;\, ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\

groff 1.24.1                       2026‐03‐20                        [4mhpftodit[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mindxbib[24m(1)                   General Commands Manual                  [4mindxbib[24m(1)

[1mName[0m
     indxbib - make inverted index of bibliographic databases

[1mSynopsis[0m
     [1mindxbib [22m[[1m-w[22m] [[1m-c [4m[22mcommon‐words‐file[24m] [[1m-d [4m[22mdir[24m] [[1m-f [4m[22mlist‐file[24m]
             [[1m-h [4m[22mmin‐hash‐table‐size[24m] [[1m-i [4m[22mexcluded‐fields[24m]
             [[1m-k [4m[22mmax‐keys‐per‐record[24m] [[1m-l [4m[22mmin‐key‐length[24m] [[1m-n [4m[22mthreshold[24m]
             [[1m-o [4m[22mfile[24m] [[1m-t [4m[22mmax‐key‐length[24m] [[4mfile[24m ...]

     [1mindxbib --help[0m

     [1mindxbib -v[0m
     [1mindxbib --version[0m

[1mDescription[0m
     [4mindxbib[24m makes an inverted index of the bibliographic databases in each [4mfile[0m
     to speed their access by ]8;;man:refer(1)\[4mrefer[24m(1)]8;;\, ]8;;man:lookbib(1)\[4mlookbib[24m(1)]8;;\, and ]8;;man:lkbib(1)\[4mlkbib[24m(1)]8;;\.   The  program
     writes  to  a  temporary  file that it later renames to file[4m.i[24m.  If no [4mfile[0m
     operands are present and no [1m-o [22moption is given,  [4mindxbib[24m  names  the  index
     [4mInd.i[24m.

     Bibliographic  databases are divided into records by blank lines.  Within a
     record, each field starts with a [1m% [22mcharacter at the beginning  of  a  line.
     Fields have a one‐letter name that follows the [1m% [22mcharacter.

     [4mindxbib[24m  stores the values set by the [1m-c[22m, [1m-l[22m, [1m-n[22m, and [1m-t [22moptions in the in‐
     dex: programs that search the index interpret them, discarding and truncat‐
     ing keys appropriately, and using the original  keys  to  verify  that  any
     record found using the index actually contains the keys.  This means that a
     user  of an index need not know whether these options were used in the cre‐
     ation of the index, provided that not all the keys to be searched for would
     have been discarded during indexing and that the user supplies at least the
     part of each key that would have remained after being truncated during  in‐
     dexing.   [4mindxbib[24m  also  stores the value set by the [1m-i [22moption in the index
     for use in verifying records found using it.

[1mOptions[0m
     [1m--help [22mdisplays a usage message, while [1m-v [22mand [1m--version [22mshow version infor‐
     mation; all exit afterward.

     [1m-c [4m[22mcommon‐words‐file[0m
             Read the list of common words  from  [4mcommon‐words‐file[24m  instead  of
             [4m/usr/share/groff/1.24.1/eign[24m.

     [1m-d [4m[22mdir[24m  Use [4mdir[24m as the name of the directory to store in the index, instead
             of  that  returned by ]8;;man:getcwd(2)\[4mgetcwd[24m(2)]8;;\.  Typically, [4mdir[24m will be a symbolic
             link whose target is the current working directory.

     [1m-f [4m[22mlist‐file[0m
             Read the files to be indexed from [4mlist‐file[24m.  If  [4mlist‐file[24m  is  [1m-[22m,
             files  will  be read from the standard input stream.  The [1m-f [22moption
             can be given at most once.

     [1m-h [4m[22mmin‐hash‐table‐size[0m
             Use the first prime number greater than or equal  to  the  argument
             for  the  size  of the hash table.  Larger values will usually make
             searching faster, but will make the index  file  larger  and  cause
             [4mindxbib[24m to use more memory.  The default hash table size is 997.

     [1m-i [4m[22mexcluded‐fields[0m
             Don’t  index  the  contents  of fields whose names are in [4mexcluded‐[0m
             [4mfields[24m.  Field names are one character each.  If this option is not
             present, [4mindxbib[24m excludes fields [1mX[22m, [1mY[22m, and [1mZ[22m.

     [1m-k [4m[22mmax‐keys‐per‐record[0m
             Use no more keys per input record than specified in  the  argument.
             If this option is not present, the maximum is 100.

     [1m-l [4m[22mmin‐key‐length[0m
             Discard  any  key  whose  length  in characters is shorter than the
             value of the argument.  If this option is not present, the  minimum
             key length is 3.

     [1m-n [4m[22mthreshold[0m
             Discard the [4mthreshold[24m most common words from the common words file.
             If  this  option is not present, the 100 most common words are dis‐
             carded.

     [1m-o [4m[22mbasename[0m
             Name the index basename[4m.i[24m.

     [1m-t [4m[22mmax‐key‐length[0m
             Truncate keys to [4mmax‐key‐length[24m in characters.  If this  option  is
             not present, keys are truncated to 6 characters.

     [1m-w      [22mIndex whole files.  Each file is a separate record.

[1mExit status[0m
     [4mindxbib[24m  exits  with status [1m0 [22mon successful operation, status [1m2 [22mif the pro‐
     gram cannot interpret its command‐line arguments, and status [1m1  [22mif  it  en‐
     counters an error during operation.

[1mFiles[0m
     file[4m.i[0m
            index for [4mfile[0m

     [4mInd.i[24m  default index name

     [4m/usr/share/groff/1.24.1/eign[0m
            contains the list of common words.  The traditional name, “[4meign[24m”, is
            an abbreviation of “English ignored [word list]”.

     [4mindxbib[24mXXXXXX
            temporary file

[1mSee also[0m
     “Some  Applications of Inverted Indexes on the Unix System”, by M. E. Lesk,
     1978, AT&T Bell Laboratories Computing Science Technical Report No. 69.

     ]8;;man:refer(1)\[4mrefer[24m(1)]8;;\, ]8;;man:lkbib(1)\[4mlkbib[24m(1)]8;;\, ]8;;man:lookbib(1)\[4mlookbib[24m(1)]8;;\

groff 1.24.1                       2026‐03‐20                         [4mindxbib[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mlkbib[24m(1)                     General Commands Manual                    [4mlkbib[24m(1)

[1mName[0m
     lkbib - search bibliographic databases

[1mSynopsis[0m
     [1mlkbib [22m[[1m-n[22m] [[1m-i [4m[22mfields[24m] [[1m-p [4m[22mfile[24m] ... [[1m-t [4m[22mn[24m] [4mkey[24m ...

     [1mlkbib --help[0m

     [1mlkbib -v[0m
     [1mlkbib --version[0m

[1mDescription[0m
     [4mlkbib[24m searches bibliographic databases for references matching all keywords
     [4mkey[24m and writes any references found to  the  standard  output  stream.   It
     reads databases given by [1m-p [22moptions and then (unless [1m-n [22mis given) a default
     database.   The  default database is taken from the [4mREFER[24m environment vari‐
     able if it is set, otherwise it is [4m/usr/dict/papers/Ind[24m.  For each database
     [4mfile[24m to be searched, if an index file[4m.i[24m created by ]8;;man:indxbib(1)\[4mindxbib[24m(1)]8;;\ exists,  then
     it will be searched instead; each index can cover multiple databases.

[1mOptions[0m
     [1m--help [22mdisplays a usage message, while [1m-v [22mand [1m--version [22mshow version infor‐
     mation; all exit afterward.

     [1m-i [4m[22mstring[0m
            When  searching files for which no index exists, ignore the contents
            of fields whose names are in [4mstring[24m.

     [1m-n     [22mSuppress search of default database.

     [1m-p [4m[22mfile[0m
            Search [4mfile[24m.  Multiple [1m-p [22moptions can be used.

     [1m-t [4m[22mn[24m   Require only the first [4mn[24m characters of keys to be  given.   The  de‐
            fault is 6.

[1mExit status[0m
     [4mlkbib[24m  exits with status [1m0 [22mon successful operation, status [1m2 [22mif the program
     cannot interpret its command‐line arguments, and status [1m1 [22mif it  encounters
     an error during operation.

[1mEnvironment[0m
     [4mREFER[24m  Assign this variable a file name to override the default database.

[1mFiles[0m
     [4m/usr/dict/papers/Ind[0m
            Default database to be used if the [4mREFER[24m environment variable is not
            set.

     file[4m.i[0m
            Index files.

[1mSee also[0m
     “Some  Applications of Inverted Indexes on the Unix System”, by M. E. Lesk,
     1978, AT&T Bell Laboratories Computing Science Technical Report No. 69.

     ]8;;man:refer(1)\[4mrefer[24m(1)]8;;\, ]8;;man:lookbib(1)\[4mlookbib[24m(1)]8;;\, ]8;;man:indxbib(1)\[4mindxbib[24m(1)]8;;\

groff 1.24.1                       2026‐03‐20                           [4mlkbib[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mlookbib[24m(1)                   General Commands Manual                  [4mlookbib[24m(1)

[1mName[0m
     lookbib - search bibliographic databases interactively

[1mSynopsis[0m
     [1mlookbib [22m[[1m-i [4m[22mstring[24m] [[1m-t [4m[22mn[24m] [4mfile[24m ...

     [1mlookbib --help[0m

     [1mlookbib -v[0m
     [1mlookbib --version[0m

[1mDescription[0m
     [4mlookbib[24m writes a prompt to the standard error stream (unless  the  standard
     input  stream is not a terminal), reads from the standard input a line con‐
     taining a set of keywords, searches each bibliographic  database  [4mfile[24m  for
     references  containing  those  keywords, writes any references found to the
     standard output stream, and repeats this process until the  end  of  input.
     For  each  database  [4mfile[24m  to  be  searched,  if an index file[4m.i[24m created by
     ]8;;man:indxbib(1)\[4mindxbib[24m(1)]8;;\ exists, then it will be searched instead; each index  can  cover
     multiple databases.

[1mOptions[0m
     [1m--help [22mdisplays a usage message, while [1m-v [22mand [1m--version [22mshow version infor‐
     mation; all exit afterward.

     [1m-i [4m[22mstring[0m
            When  searching files for which no index exists, ignore the contents
            of fields whose names are in [4mstring[24m.

     [1m-t [4m[22mn[24m   Require only the first [4mn[24m characters of keys to be  given.   The  de‐
            fault is 6.

[1mExit status[0m
     [4mlookbib[24m  exits  with status [1m0 [22mon successful operation, status [1m2 [22mif the pro‐
     gram cannot interpret its command‐line arguments, and status [1m1  [22mif  it  en‐
     counters an error during operation.

[1mFiles[0m
     file[4m.i[0m
            Index files.

[1mSee also[0m
     “Some  Applications of Inverted Indexes on the Unix System”, by M. E. Lesk,
     1978, AT&T Bell Laboratories Computing Science Technical Report No. 69.

     ]8;;man:refer(1)\[4mrefer[24m(1)]8;;\, ]8;;man:lkbib(1)\[4mlkbib[24m(1)]8;;\, ]8;;man:indxbib(1)\[4mindxbib[24m(1)]8;;\

groff 1.24.1                       2026‐03‐20                         [4mlookbib[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mmmroff[24m(1)                    General Commands Manual                   [4mmmroff[24m(1)

[1mName[0m
     mmroff - reference‐ and PostScript inclusion‐handling  front  end  for  GNU
     [4mroff[24m [4mmm[24m macro package

[1mSynopsis[0m
     [1mmmroff [22m[[1m-x[22m] [4mgroff‐argument[24m ...

     [1mmmroff --help[0m

     [1mmmroff --version[0m

[1mDescription[0m
     [4mmmroff[24m is a simple wrapper for [4mgroff[24m, used to expand internal references in
     [4mmm[24m  documents;  see  ]8;;man:groff_mm(7)\[4mgroff_mm[24m(7)]8;;\.  It runs [4mgroff[24m with the [1m-mm [22moption twice,
     first with [1m-z [22mand [1m-rRef=1 [22mto populate reference and index files with  their
     corresponding  entries,  and then without to produce the document.  It also
     handles the inclusion of PostScript images with the [1mPIC  [22mmacro.   Documents
     that  do  not  use these features of [4mgroff[24m [4mmm[24m (the [1mINITI[22m, [1mIND[22m, [1mINDP[22m, [1mINITR[22m,
     [1mSETR[22m, [1mGETHN[22m, [1mGETPN[22m, [1mGETR[22m, [1mGETST[22m, and [1mPIC [22mmacros) do not require [4mmmroff[24m.

[1mOptions[0m
     [1m--help [22mdisplays a usage message, while [1m--version [22mshows version information;
     both exit afterward.

     [1m-x     [22mCreate or update the reference list file and exit.

[1mEnvironment[0m
     Normally, the path separator in environment variables ending with  [4mPATH[24m  is
     the  colon;  this may vary depending on the operating system.  For example,
     Windows uses a semicolon instead.

     [4mGROFF_BIN_PATH[0m
            Locate [4mgroff[24m commands in these directories,  followed  by  those  in
            [4mPATH[24m.   If  not set, the installation directory of GNU [4mroff[24m executa‐
            bles, [4m/usr/bin[24m, is searched before [4mPATH[24m.

[1mExit status[0m
     [4mmmroff[24m exits with status [1m0 [22mif the [1m--help [22mor [1m--version [22moptions  were  speci‐
     fied,  or  if  [1m-x [22mwas specified and the program successfully created or up‐
     dated the reference list file.  It exits with status [1m1 [22mif it was unable  to
     create necessary files.  Otherwise, it exits with the status of [4mgroff[24m.

[1mAuthors[0m
     [4mmmroff[24m was written by ]8;;mailto:jh@axis.se\Jörgen Hägg]8;;\ of Lund, Sweden.

[1mSee also[0m
     ]8;;man:groff_mm(7)\[4mgroff_mm[24m(7)]8;;\, ]8;;man:groff_mmse(7)\[4mgroff_mmse[24m(7)]8;;\, ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\, ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\, ]8;;man:pic(1)\[4mpic[24m(1)]8;;\, ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\

groff 1.24.1                       2026‐03‐20                          [4mmmroff[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mneqn[24m(1)                      General Commands Manual                     [4mneqn[24m(1)

[1mName[0m
     neqn - format equations for character‐cell terminal output

[1mSynopsis[0m
     [1mneqn [22m[[4meqn‐argument[24m ...]

[1mDescription[0m
     [4mneqn[24m invokes the ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\ command with the [1mascii [22moutput device.

     GNU  [4meqn[24m does not support low‐resolution, typewriter‐like devices, although
     it may work adequately for very simple input.

[1mSee also[0m
     ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\

groff 1.24.1                       2026‐03‐20                            [4mneqn[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mnroff[24m(1)                     General Commands Manual                    [4mnroff[24m(1)

[1mName[0m
     nroff - format documents with [4mgroff[24m for terminal (“TTY”) devices

[1mSynopsis[0m
     [1mnroff [22m[[1m-abcCEhikpRStUVzZ[22m] [[1m-d [4m[22mctext[24m] [[1m-d [4m[22mstring[24m[1m=[4m[22mtext[24m] [[1m-D [4m[22mfallback‐input‐[0m
           [4mencoding[24m] [[1m-I [4m[22minclusion‐directory[24m] [[1m-K [4m[22minput‐encoding[24m] [[1m-m [4m[22mmacro‐[0m
           [4mpackage[24m] [[1m-M [4m[22mmacro‐directory[24m] [[1m-n [4m[22mpage‐number[24m] [[1m-o [4m[22mpage‐list[24m]
           [[1m-P [4m[22mpostprocessor‐argument[24m] [[1m-r [4m[22mcnumeric‐expression[24m]
           [[1m-r [4m[22mregister[24m[1m=[4m[22mnumeric‐expression[24m] [[1m-T [4m[22moutput‐device[24m] [[1m-w [4m[22mwarning‐[0m
           [4mcategory[24m] [[1m-W [4m[22mwarning‐category[24m] [[4mfile[24m ...]

     [1mnroff --help[0m

     [1mnroff -v [22m[[4mother‐nroff‐option[24m ...]
     [1mnroff --version [22m[[4mother‐nroff‐option[24m ...]

[1mDescription[0m
     [4mnroff[24m formats documents written in the ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\  language  for  typewriter‐
     like devices such as terminal emulators.  GNU [4mnroff[24m emulates the AT&T [4mnroff[0m
     command using ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\.  [4mnroff[24m generates output via ]8;;man:grotty(1)\[4mgrotty[24m(1)]8;;\, [4mgroff[24m’s ter‐
     minal output driver, which needs to know the character encoding scheme used
     by  the  device.   Consequently,  acceptable arguments to the [1m-T [22moption are
     [1mascii[22m,  [1mlatin1[22m,  and  [1mutf8[22m;  any  others  are  ignored.   If  neither   the
     [4mGROFF_TYPESETTER[24m environment variable nor the [1m-T [22mcommand‐line option (which
     overrides  the environment variable) specifies a (valid) device, [4mnroff[24m con‐
     sults the locale to select an appropriate output device.   It  first  tries
     the ]8;;man:locale(1)\[4mlocale[24m(1)]8;;\ program, then checks several locale‐related environment vari‐
     ables;  see  section  “Environment”  below.   If all of the foregoing fail,
     [4mnroff[24m assumes “[1m-T ascii[22m”.

     The [1m-a[22m, [1m-b[22m, [1m-c[22m, [1m-C[22m, [1m-d[22m, [1m-E[22m, [1m-i[22m, [1m-I[22m, [1m-m[22m, [1m-M[22m, [1m-n[22m, [1m-o[22m, [1m-r[22m, [1m-U[22m, [1m-w[22m, [1m-W[22m, and  [1m-z[0m
     options  have  the  effects described in ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\.  [1m-c [22mand [1m-h [22mimply “[1m-P -c[22m”
     and “[1m-P -h[22m”, respectively; [1m-c [22mis also meaningful to [4mtroff[24m itself.  Further,
     GNU [4mnroff[24m ignores the AT&T [4mnroff[24m options [1m-e[22m, [1m-q[22m, and  [1m-s[22m.   ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\  docu‐
     ments  options  [1m-D[22m, [1m-k[22m, [1m-K[22m, [1m-p[22m, [1m-P[22m, [1m-R[22m, [1m-t[22m, [1m-S[22m, and [1m-Z[22m.  [1m-V [22mcauses [4mnroff[24m to
     display the constructed [4mgroff[24m command on the standard  output  stream,  but
     does not execute it.  [1m-v [22mand [1m--version [22mshow version information about [4mnroff[0m
     and  the  programs it runs, while [1m--help [22mdisplays a usage message; all exit
     afterward.

[1mExit status[0m
     [4mnroff[24m exits with status [1m2 [22mif there was a  problem  parsing  its  arguments,
     with status [1m0 [22mif any of the options [1m-V[22m, [1m-v[22m, [1m--version[22m, or [1m--help [22mwere spec‐
     ified, and with the status of [4mgroff[24m otherwise.

[1mEnvironment[0m
     Normally,  the  path separator in environment variables ending with [4mPATH[24m is
     the colon; this may vary depending on the operating system.   For  example,
     Windows uses a semicolon instead.

     [4mGROFF_BIN_PATH[0m
            Locate  [4mgroff[24m  commands  in  these directories, followed by those in
            [4mPATH[24m.  If not set, the installation directory of GNU  [4mroff[24m  executa‐
            bles, [4m/usr/bin[24m, is searched before [4mPATH[24m.

     [4mGROFF_TYPESETTER[0m
            specifies the default output device for [4mgroff[24m.

     [4mLC_ALL[0m
     [4mLC_CTYPE[0m
     [4mLANG[0m
     [4mLESSCHARSET[0m
            are  pattern‐matched  in  this  order for contents matching standard
            character encodings supported by [4mgroff[24m in the event no [1m-T [22moption  is
            given and [4mGROFF_TYPESETTER[24m is unset, or the values specified are in‐
            valid.

[1mFiles[0m
     [4m/usr/share/groff/1.24.1/tmac/tty-char.tmac[0m
            defines fallback definitions of [4mroff[24m special characters.  These def‐
            initions more poorly optically approximate typeset output than those
            of  [4mtty.tmac[24m  in favor of communicating semantic information.  [4mnroff[0m
            loads it automatically.

[1mNotes[0m
     Pager programs like ]8;;man:more(1)\[4mmore[24m(1)]8;;\ and ]8;;man:less(1)\[4mless[24m(1)]8;;\ may require command‐line options to
     correctly handle some output sequences; see ]8;;man:grotty(1)\[4mgrotty[24m(1)]8;;\.

[1mSee also[0m
     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\, ]8;;man:grotty(1)\[4mgrotty[24m(1)]8;;\, ]8;;man:locale(1)\[4mlocale[24m(1)]8;;\, ]8;;man:roff(7)\[4mroff[24m(7)]8;;\

groff 1.24.1                       2026‐03‐20                           [4mnroff[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mpdfmom[24m(1)                    General Commands Manual                   [4mpdfmom[24m(1)

[1mName[0m
     pdfmom - produce PDF documents using the [4mmom[24m macro package for [4mgroff[0m

[1mSynopsis[0m
     [1mpdfmom [22m[[1m--roff[22m] [[1m-Tpdf[22m] [[4mgroff‐options[24m] [[4mfile[24m ...]

     [1mpdfmom [22m[[1m--roff[22m] [1m-Tps [22m[[4mpdfroff‐options[24m] [[4mgroff‐options[24m] [[4mfile[24m ...]

     [1mpdfmom -v[0m
     [1mpdfmom --version[0m

[1mDescription[0m
     [4mpdfmom[24m is a wrapper around ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ that facilitates the production of  PDF
     documents from files formatted with the [4mmom[24m macros.

     If  the  [1m--roff [22moption is used, the wrapper can be used with macro packages
     other than ]8;;man:groff_mom(7)\[4mgroff_mom[24m(7)]8;;\.  This is also true if the wrapper  is  renamed  or
     linked  as  a pseudonym; for example, creating a [4mpdfms[24m link pointing to the
     [4mpdfmom[24m executable makes a wrapper for producing PDFs with the [4mms[24m package.

     [4mpdfmom[24m prints to the standard output, so output must usually be  redirected
     to  a destination file.  The size of the final PDF can be reduced by piping
     the output through ]8;;man:ps2pdf(1)\[4mps2pdf[24m(1)]8;;\.

     If called with the [1m-Tpdf [22moption (which is the  default),  [4mpdfmom[24m  processes
     files  using  [4mgroff[24m’s native PDF driver, ]8;;man:gropdf(1)\[4mgropdf[24m(1)]8;;\.  If [1m-Tps [22mis given, pro‐
     cessing is passed over to [4mpdfroff[24m, which uses  [4mgroff[24m’s  PostScript  driver.
     In  either case, multiple runs of the source file are performed in order to
     satisfy any forward references in the document.

     [4mpdfmom[24m accepts all the same options as [4mgroff[24m.  If [1m-Tps [22mis  given,  the  op‐
     tions  associated  with  [4mpdfroff[24m  are  accepted as well.  When [4mpdfmom[24m calls
     [4mpdfroff[24m, the options “[1m-mpdfmark -mom  --no-toc[22m”  options  are  implied  and
     should  not  be given on the command line.  Equally, it is not necessary to
     supply the [1m-mom [22mor [1m-m mom [22moptions when [1m-Tps [22mis absent.

     PDF integration with the [4mmom[24m macros is discussed  in  full  in  the  manual
     “Producing PDFs with [4mgroff[24m and [4mmom[24m”, which was itself produced with [4mpdfmom[24m.

     If called with the [1m-v [22mor [1m--version [22moptions, [4mpdfmom[24m displays its version in‐
     formation  and exits.  Using the [1m--help [22moption displays a usage message and
     exits.

[1mAuthors[0m
     [4mpdfmom[24m was written by ]8;;mailto:deri@chuzzlewit.myzen.co.uk\Deri James]8;;\ and ]8;;mailto:peter@schaffter.ca\Peter Schaffter]8;;\, and is maintained  by
     James.

[1mSee also[0m
     [4m/usr/share/doc/groff-1.24.1/pdf/mom-pdf.pdf[0m
            “Producing  PDFs  with  [4mgroff[24m  and  [4mmom[24m”,  by  Deri  James and Peter
            Schaffter.  This file, together with  its  source,  [4mmom-pdf.mom[24m,  is
            part of the [4mgroff[24m distribution.

     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, ]8;;man:gropdf(1)\[4mgropdf[24m(1)]8;;\, ]8;;man:pdfroff(1)\[4mpdfroff[24m(1)]8;;\, ]8;;man:ps2pdf(1)\[4mps2pdf[24m(1)]8;;\

groff 1.24.1                       2026‐03‐20                          [4mpdfmom[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mpfbtops[24m(1)                   General Commands Manual                  [4mpfbtops[24m(1)

[1mName[0m
     pfbtops  -  translate  PostScript Printer Font Binary files to Printer Font
     ASCII

[1mSynopsis[0m
     [1mpfbtops [22m[[4mpfb‐file[24m]

     [1mpfbtops --help[0m

     [1mpfbtops -v[0m
     [1mpfbtops --version[0m

[1mDescription[0m
     [4mpfbtops[24m translates a PostScript Type 1 font in Printer  Font  Binary  (PFB)
     format to Printer Font ASCII (PFA) format, splitting overlong lines in text
     packets  into smaller chunks.  If [4mpfb‐file[24m is omitted, the PFB file will be
     read from the standard input stream.  The PFA font will be written  on  the
     standard output stream.  PostScript fonts for MS‐DOS were historically sup‐
     plied  in  PFB format.  Use of a PostScript Type 1 font with [4mgroff[24m requires
     conversion of its metrics (AFM file) to a [4mgroff[24m font description file;  see
     ]8;;man:afmtodit(1)\[4mafmtodit[24m(1)]8;;\.

     The  [1m--help  [22moption  displays  a usage message, while [1m-v [22mand [1m--version [22mshow
     version information; all exit afterward.

[1mSee also[0m
     ]8;;man:grops(1)\[4mgrops[24m(1)]8;;\, ]8;;man:gropdf(1)\[4mgropdf[24m(1)]8;;\

groff 1.24.1                       2026‐03‐20                         [4mpfbtops[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mpic[24m(1)                       General Commands Manual                      [4mpic[24m(1)

[1mName[0m
     pic - compile pictures for [4mtroff[24m or TeX

[1mSynopsis[0m
     [1mpic [22m[[1m-CnSU[22m] [[4mfile[24m ...]

     [1mpic -t [22m[[1m-cCSUz[22m] [[4mfile[24m ...]

     [1mpic --help[0m

     [1mpic -v[0m
     [1mpic --version[0m

[1mDescription[0m
     The GNU implementation of [4mpic[24m is part of the ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\  document  formatting
     system.  [4mpic[24m is a ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ preprocessor that translates descriptions of di‐
     agrammatic  pictures embedded in ]8;;man:roff(7)\[4mroff[24m(7)]8;;\ or TeX input into the language un‐
     derstood by TeX or [4mtroff[24m.  It copies each [4mfile[24m’s contents to  the  standard
     output stream, translating each [4mpicture[24m between lines starting with [1m.PS [22mand
     any  of  [1m.PE[22m, [1m.PF[22m, or [1m.PY[22m.  End a [4mpic[24m picture with [1m.PE [22mto leave the drawing
     position at the bottom of the picture, and with [1m.PF [22mor [1m.PY [22mto leave  it  at
     the  top.   Normally, [4mpic[24m is not executed directly by the user, but invoked
     by specifying the [1m-p [22moption to ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\.  If no [4mfile[24m operands are  present,
     or if [4mfile[24m is “[1m-[22m”, [4mpic[24m reads the standard input stream.

     It  is  the user’s responsibility to provide appropriate definitions of the
     [1mPS[22m, [1mPE[22m, and one or both of the [1mPF [22mand [1mPY [22mmacros.  When a macro package does
     not supply these, obtain simple definitions with the  [4mgroff[24m  option  [1m-mpic[22m;
     these horizontally center each picture.

     GNU  [4mpic[24m  supports [1mPY [22mas a synonym of [1mPF [22mto work around a name space colli‐
     sion with the [4mmm[24m macro package, which defines [1mPF [22mas a page  footer  manage‐
     ment macro.  Use [1mPF [22mpreferentially unless a similar problem faces your doc‐
     ument.

[1mOptions[0m
     [1m--help [22mdisplays a usage message, while [1m-v [22mand [1m--version [22mshow version infor‐
     mation; all exit afterward.

     [1m-c     [22mBe  more  compatible  with [4mtpic[24m; implies [1m-t[22m.  Lines beginning with [1m\[0m
            are not passed through transparently.  Lines beginning  with  [1m.  [22mare
            passed  through  with  the  initial [1m. [22mchanged to [1m\[22m.  GNU [4mpic[24m gives a
            line beginning with [1m.ps [22mspecial treatment: it takes an optional  in‐
            teger  argument  specifying  the line thickness (pen size) in milli‐
            inches, a missing argument restores the previous line thickness, and
            the default line thickness is 8  milliinches.   The  line  thickness
            thus  specified takes effect only when a non‐negative line thickness
            has not been specified by use of the [1mthickness [22mattribute or by  set‐
            ting the [1mlinethick [22mvariable.

     [1m-C     [22mRecognize  [1m.PS[22m,  [1m.PE[22m, [1m.PF[22m, and [1m.PY [22meven when followed by a character
            other than space or newline.

     [1m-n     [22mDon’t use [4mgroff[24m extensions to the [4mtroff[24m drawing  commands.   Specify
            this  option  if  a postprocessor you’re using doesn’t support these
            extensions, described in ]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\.  This option also causes  [4mpic[0m
            not to use zero‐length lines to draw dots in [4mtroff[24m mode.

     [1m-S     [22mEnable  safer  mode  and  ignore any subsequent [1m-U [22moption.  In [4msafer[0m
            [4mmode,[24m [4mpic[24m ignores [1msh [22mcommands, which can be useful when operating on
            untrustworthy input.  [4mpic[24m operates in safer mode by default.

     [1m-t     [22mProduce TeX output.

     [1m-U     [22mOperate in [4munsafe[24m [4mmode;[24m [1msh [22mcommands are interpreted.

     [1m-z     [22mIn TeX mode, draw dots using zero‐length lines.

     The following options supported by other versions of [4mpic[24m are ignored.

     [1m-D      [22mDraw all lines using the \D escape sequence.  GNU [4mpic[24m  always  does
             this.

     [1m-T [4m[22mdev[24m  Generate  output for the [4mtroff[24m device [4mdev[24m.  This option is unneces‐
             sary in GNU [4mpic[24m because the [4mtroff[24m it generates  is  device‐indepen‐
             dent.

[1mUsage[0m
     This  section  primarily  discusses the differences between GNU [4mpic[24m and the
     Eighth Edition Unix version of AT&T [4mpic[24m (1985).  Many of these  differences
     also apply to later versions of AT&T [4mpic[24m.

   [1mTeX mode[0m
     TeX‐compatible  output  is  produced  when the [1m-t [22moption is specified.  You
     must use a TeX driver that supports [4mtpic[24m version 2 specials.  ([4mtpic[24m  was  a
     fork  of  AT&T  [4mpic[24m by Tim Morgan of the University of California at Irvine
     that diverged from its source around 1984.  It  is  best  known  today  for
     lending its name to a group of [1m\special [22mcommands it produced for TeX.)

     Lines  beginning  with [1m\ [22mare passed through unaltered except for a [1m% [22msuffix
     to avoid unwanted spaces.  Use this feature to change fonts or the value of
     [1m\baselineskip[22m.  Other applications may produce undesirable results; use  at
     your own risk.  By default, lines beginning with a dot are not treated spe‐
     cially——but see the [1m-c [22moption.

     In  TeX  mode,  [4mpic[24m defines a vbox called [1m\graph [22mfor each picture.  Use GNU
     [4mpic[24m’s [1mfigname [22mcommand to change the name of the vbox.  You must print  that
     vbox yourself using the command
            \centerline{\box\graph}
     for  instance.   Since  the  vbox  has a height of zero——it is defined with
     [1m\vtop[22m——this produces slightly more vertical space above  the  picture  than
     below it;
            \centerline{\raise 1em\box\graph}
     would  avoid  this.  To give the vbox a positive height and a depth of zero
     (as used by LaTeX’s [4mgraphics.sty[24m, for example), define the following  macro
     in your document.
            \def\gpicbox#1{%
              \vbox{\unvbox\csname #1\endcsname\kern 0pt}}
     You can then simply say [1m\gpicbox{graph} [22minstead of [1m\box\graph[22m.

   [1mCommands[0m
     Several  commands new to GNU [4mpic[24m accept delimiters, shown in their synopses
     as braces [1m{ }[22m.  Nesting of braces is supported.  Any other characters  (ex‐
     cept  a  space,  tab, or newline) may be used as alternative delimiters, in
     which case the members of a given pair must be identical.  GNU  [4mpic[24m  recog‐
     nizes  double‐quoted strings within delimiters of either kind; such strings
     may contain the delimiter character or unbalanced braces.

     [1mfor [4m[22mvariable[24m [1m= [4m[22mexpr1[24m [1mto [4m[22mexpr2[24m [[1mby [22m[[1m*[22m][4mexpr3[24m] [1mdo [4m[22mX[24m [4mbody[24m [4mX[0m
            Set [4mvariable[24m to [4mexpr1[24m.  While the value of [4mvariable[24m is less than  or
            equal  to  [4mexpr2[24m,  do [4mbody[24m and increment [4mvariable[24m by [4mexpr3[24m; if [1mby [22mis
            not given, increment [4mvariable[24m by 1.  [4mexpr3[24m can be negative, in which
            case [4mvariable[24m is then tested whether it is greater than or equal  to
            [4mexpr2[24m.  A [1m* [22mprefix on [4mvariable[24m multiplies it by [4mexpr3[24m (which must be
            greater  than  zero)  at each iteration rather than incrementing it.
            If the range constraint on [4mexpr3[24m isn’t met, the loop does  not  exe‐
            cute.  [4mX[24m can be any character not in [4mbody[24m.

     [1mif [4m[22mexpr[24m [1mthen [4m[22mX[24m [4mif‐true[24m [4mX[24m [[1melse [4m[22mY[24m [4mif‐false[24m [4mY[24m]
            Evaluate  [4mexpr[24m;  if it is non‐zero then do [4mif‐true[24m, otherwise do [4mif‐[0m
            [4mfalse[24m.  [4mX[24m can be any character not in [4mif‐true[24m.  [4mY[24m can be any charac‐
            ter not in [4mif‐false[24m.

     [1mprint [4m[22marg[24m ...
            Catenate and write arguments to the standard error  stream  followed
            by  a newline.  Each [4marg[24m must be an expression, a position, or text.
            This feature is useful for debugging.

     [1mcommand [4m[22marg[24m ...
            Catenate arguments and pass them as a line to [4mtroff[24m  or  TeX.   Each
            [4marg[24m  must be an expression, a position, or text.  [1mcommand [22mallows the
            values of [4mpic[24m variables to be passed to the formatter.  Thus,
                   .PS
                   x = 14
                   command ".ds string x is " x "."
                   .PE
                   \*[string]
            produces
                   x is 14.
            when formatted with [4mtroff[24m.

     [1msh [4m[22mX[24m [4mcommand[24m [4mX[0m
            Pass [4mcommand[24m to a shell via ]8;;man:system(3)\[4msystem[24m(3)]8;;\.  Ignored  if  [1m-U  [22moption  not
            specified.

     [1mcopy "[4m[22mfilename[24m[1m"[0m
            Include [4mfilename[24m at this point in the file.

     [1mcopy [22m[[1m"[4m[22mfilename[24m[1m"[22m] [1mthru [4m[22mX[24m [4mbody[24m [4mX[24m [[1muntil [22m"[4mword[24m[1m"[22m]
     [1mcopy [22m[[1m"[4m[22mfilename[24m[1m"[22m] [1mthru [4m[22mmacro[24m [[1muntil [22m"[4mword[24m[1m"[22m]
            This construct does [4mbody[24m once for each line of [4mfilename[24m; the line is
            split into blank‐delimited words, and occurrences of [1m$[4m[22mi[24m in [4mbody[24m, for
            [4mi[24m  between  1  and 9, are replaced by the [4mi[24m‐th word of the line.  If
            [4mfilename[24m is not given, lines are taken from the current input up  to
            [1m.PE[22m.   If an [1muntil [22mclause is specified, GNU [4mpic[24m reads lines only un‐
            til encountering one beginning with [4mword[24m; which it then discards.  [4mX[0m
            can be any character not in [4mbody[24m.  For example,
                   .PS
                   copy thru % circle at ($1,$2) % until "END"
                   1 2
                   3 4
                   5 6
                   END
                   box
                   .PE
            and
                   .PS
                   circle at (1,2)
                   circle at (3,4)
                   circle at (5,6)
                   box
                   .PE
            are equivalent.  The commands to be performed for each line can also
            be taken from a macro defined earlier by  giving  the  name  of  the
            macro as the argument to [1mthru[22m.  The argument after [1mthru [22mis looked up
            as a macro name first; if not defined, its first character is inter‐
            preted as a delimiter.

     [1mreset[0m
     [1mreset [4m[22mpvar1[24m[[1m,[22m] [4mpvar2[24m ...
            Reset predefined variables [4mpvar1[24m, [4mpvar2[24m ... to their default values;
            if  no  arguments are given, reset all predefined variables to their
            default values.  Variable names may be separated by commas,  spaces,
            or  both.   Assigning  a  value  to [1mscale [22malso causes all predefined
            variables that control dimensions to be reset to their default  val‐
            ues times the new value of [1mscale[22m.

     [1mplot [4m[22mexpr[24m ["[4mtext[24m"]
            Create a text object by using [4mtext[24m as a format string for ]8;;man:sprintf(3)\[4msprintf[24m(3)]8;;\
            with an argument of [4mexpr[24m.  If [4mtext[24m is omitted, [1m"%g" [22mis implied.  At‐
            tributes  can  be specified in the same way as for a normal text ob‐
            ject.  [4mCaution:[24m be very careful that you specify an appropriate for‐
            mat string in [4mtext;[24m [4mpic[24m’s validation of it is limited.  [1mplot [22mis dep‐
            recated in favour of [1msprintf[22m.

     [4mvar[24m [1m:= [4m[22mexpr[0m
            Update an existing variable.  [4mvar[24m must already be defined, and  [4mexpr[0m
            is  assigned to [4mvar[24m without creating a variable local to the current
            block.  (By contrast, [1m= [22mdefines [4mvar[24m in the current block  if  it  is
            not already defined there, and then changes the value in the current
            block only.)  For example,
                   [1m.PS[0m
                   [1mx = 3[0m
                   [1my = 3[0m
                   [1m[[0m
                   [1mx := 5[0m
                   [1my = 5[0m
                   [1m][0m
                   [1mprint x   y[0m
                   [1m.PE[0m
            writes
                   5 3
            to the standard error stream.

   [1mExpressions[0m
     The syntax for expressions has been significantly extended.

     [4mx[24m [1m^ [4m[22my[24m (exponentiation)
     [1msin([4m[22mx[24m[1m)[0m
     [1mcos([4m[22mx[24m[1m)[0m
     [1matan2([4m[22my[24m[1m, [4m[22mx[24m[1m)[0m
     [1mlog([4m[22mx[24m[1m) [22m(base 10)
     [1mexp([4m[22mx[24m[1m) [22m(base 10, i.e. 10^[4mx[24m)
     [1msqrt([4m[22mx[24m[1m)[0m
     [1mint([4m[22mx[24m[1m)[0m
     [1mrand() [22m(return a random number between 0 and 1)
     [1mrand([4m[22mx[24m[1m) [22m(return a random number between 1 and [4mx[24m; deprecated)
     [1msrand([4m[22mx[24m[1m) [22m(set the random number seed)
     [1mmax([4m[22me1[24m[1m, [4m[22me2[24m[1m)[0m
     [1mmin([4m[22me1[24m[1m, [4m[22me2[24m[1m)[0m
     [1m![4m[22me[0m
     [4me1[24m [1m&& [4m[22me2[0m
     [4me1[24m [1m|| [4m[22me2[0m
     [4me1[24m [1m== [4m[22me2[0m
     [4me1[24m [1m!= [4m[22me2[0m
     [4me1[24m [1m>= [4m[22me2[0m
     [4me1[24m [1m> [4m[22me2[0m
     [4me1[24m [1m<= [4m[22me2[0m
     [4me1[24m [1m< [4m[22me2[0m
     [1m"[4m[22mstr1[24m[1m" == "[4m[22mstr2[24m[1m"[0m
     [1m"[4m[22mstr1[24m[1m" != "[4m[22mstr2[24m[1m"[0m

     String  comparison  expressions  must  be parenthesised in some contexts to
     avoid ambiguity.

   [1mOther changes[0m
     A bare expression, [4mexpr[24m, is acceptable as an attribute; it is equivalent to
     “[4mdir[24m [4mexpr[24m”, where [4mdir[24m is the current direction.   For  example,  “[1mline  2i[22m”
     draws  a  line  2  inches  long in the current direction.  The ‘i’ (or ‘I’)
     character is ignored; to use another measurement unit, set the [1mscale  [22mvari‐
     able to an appropriate value.

     The  maximum  width  and height of the picture are taken from the variables
     [1mmaxpswid [22mand [1mmaxpsht[22m.  Initially, these have values  8.5  and  11,  respec‐
     tively.

     Scientific notation is allowed for numbers, as with “[1mx = 5e-2[22m”.

     Text  attributes  can  be  compounded.  For example, “[1m"foo" above ljust[22m” is
     valid.

     There is no limit to the depth to which blocks can be nested.  For example,
            [A: [B: [C: box ]]] with .A.B.C.sw at 1,2
            circle at last [].A.B.C
     is acceptable.

     Arcs have compass points determined by the circle of which  the  arc  is  a
     part.

     Circles,  ellipses, and arcs can be dotted or dashed.  In TeX mode, splines
     can be dotted or dashed as well.

     Boxes can have rounded corners.  The [1mrad [22mattribute specifies the radius  of
     the  quarter‐circles at each corner.  If no [1mrad [22mor [1mdiam [22mattribute is given,
     a radius of [1mboxrad [22mis used.  Initially, [1mboxrad [22mhas a value  of  0.   A  box
     with rounded corners can be dotted or dashed.

     Boxes  can  have slanted sides, generalizing them from rectangles to paral‐
     lelograms.  The [1mxslanted [22mand [1myslanted [22mattributes specify the [4mx[24m and  [4my[24m  off‐
     sets of the box’s upper right corner from its default position.

     The  [1m.PS [22mline accepts a second argument specifying a maximum height for the
     picture.  If a width of zero is specified, it is ignored when computing the
     scaling factor for the picture.  GNU [4mpic[24m always scales  a  picture  by  the
     same  amount  vertically  and horizontally.  This differs from DWB 2.0 [4mpic[24m,
     which may change the picture’s aspect ratio if a height is specified.

     Each text object has an associated invisible box that determines  its  com‐
     pass  points and implicit motion.  The dimensions of the box are taken from
     its width and height attributes.  If the width attribute is  not  supplied,
     the  value of [1mtextwid [22mis assumed.  If the height attribute is not supplied,
     the height defaults to the number of text strings associated with  the  ob‐
     ject times [1mtextht[22m.  Initially, [1mtextwid [22mand [1mtextht [22mhave values of 0.

     In  (almost  all) places where a quoted text string can be used, an expres‐
     sion of the form

            [1msprintf("[4m[22mformat[24m[1m", [4m[22marg[24m[1m, [22m...[1m)[0m

     can be used instead; it transforms its arguments per [4mformat[24m,  which  should
     be  a  string as described in ]8;;man:printf(3)\[4mprintf[24m(3)]8;;\, and appropriate to the quantity of
     arguments supplied.  GNU [4mpic[24m supports only the conversion specifiers [1me[22m,  [1mE[22m,
     [1mf[22m,  [1mg[22m, [1mG[22m, and [1m%[22m, modifiers “[1m#[22m”, “[1m-[22m”, “[1m+[22m”, and “ ” [space]), a minimum field
     width, and an optional precision.

     The thickness of the lines used  to  draw  objects  is  controlled  by  the
     [1mlinethick  [22mvariable,  which  is measured in points.  A negative value indi‐
     cates the default thickness.  In TeX output mode when the [1m-c [22moption is  not
     given, this means 8 milliinches.  In [4mtroff[24m and TeX [1m-c [22moutput modes, the de‐
     fault  thickness  corresponds to the type size.  (Thus, if the type size is
     10 points, a line is 10 points thick.)  A [1mlinethick [22mvalue of zero draws the
     thinnest  possible  line  supported  by  the  output  device.    Initially,
     [1mlinethick  [22mhas  a  value of -1.  A [1mthick[22m[[1mness[22m] attribute is also available.
     For example, “[1mcircle thickness 1.5[22m” draws a circle with a line thickness of
     1.5 points.  The thickness of lines is not affected by  the  value  of  the
     [1mscale [22mvariable, nor by the width or height given in the [1m.PS [22mline.

     Boxes (including boxes with rounded corners or slanted sides), circles, and
     ellipses can be filled by giving them an attribute of [1mfill[22m[[1med[22m], which takes
     an  optional  expression  argument with a value between 0 and 1; 0 fills it
     with white, 1 with black, and values in between with a proportionally  gray
     shade.   A value greater than 1 is interpreted as the shade of gray that is
     being used for text and lines.  Normally this is black, but output  devices
     may  provide a mechanism for changing this.  Without an argument, the value
     of the variable [1mfillval [22mis used.  Initially, [1mfillval [22mhas a  value  of  0.5.
     The [1minvisible [22mattribute does not affect the filling of objects.  Text asso‐
     ciated  with  a  filled object is added after the object is filled, so that
     the text is not obscured by the filling.

     Additional modifiers are available to draw colored objects: [1moutline[22m[[1md[22m] sets
     the color of the outline, [1mshaded [22mthe  fill  color,  and  [1mcolo[22m[[1mu[22m][1mr[22m[[1med[22m]  sets
     both.  All expect a subsequent string argument specifying the color.
            circle shaded "green" outline "black"
     Color  is  not  yet supported in TeX mode.  Device macro files like [4mps.tmac[0m
     declare color names; you can define additional ones with the  [1mdefcolor  [22mre‐
     quest  (see  ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\).   [4mpic[24m assumes at the beginning of each picture that
     the stroke and fill colors are set to the device defaults.

     To change the name of the vbox in TeX mode, set the pseudo‐variable [1mfigname[0m
     (which is actually a specially parsed command) within a picture.  For exam‐
     ple,
            .PS
            figname = foobar;
            circle "dig here";
            .PE
     makes the picture available in the box [1m\foobar[22m.

     Arrow heads are drawn as solid triangles if the variable [1marrowhead [22mis  non‐
     zero  and  either  TeX  mode is enabled or the [1m-n [22moption is not used.  Ini‐
     tially, [1marrowhead [22mhas a value of 1.  Solid arrow heads  are  always  filled
     with the current outline (stroke) color.

     The  [4mtroff[24m output of [4mpic[24m is device‐independent.  The [1m-T [22moption is therefore
     redundant.  Except where noted, all measurements and dimensions use  inches
     implicitly; they are never interpreted as [4mtroff[24m basic units.

     Objects  can  have  an  [1maligned  [22mattribute, but it is supported only by the
     ]8;;man:grops(1)\[4mgrops[24m(1)]8;;\ and ]8;;man:gropdf(1)\[4mgropdf[24m(1)]8;;\ output drivers.  Any text associated with an [1maligned[0m
     object is rotated about the object’s center such that it is oriented  along
     a  line  connecting the start and end points of the object.  [1maligned [22mhas no
     effect on objects whose start and end points are coincident.

     In places where [4mn[24m[1mth [22mis allowed, [1m`[4m[22mexpr[24m[1m'th [22mis also allowed.  “[1m'th[22m” is a  sin‐
     gle  token:  no space is allowed between the apostrophe and the “[1mth[22m”.  Con‐
     sider the following example.

            for i = 1 to 4 do {
               box
               move right 0.5
            }
            for i = 1 to 3 do {
               arrow from `i'th box.ne to `i+1'th box.sw
            }

     Arbitrary polygons can be drawn using the [1mpolygon [22mkeyword followed by a se‐
     ries of [4mn[24m-1 line segments, where [4mn[24m is the number of edges of  the  polygon.
     This  allows  GNU [4mtroff[24m to interpret the line segments as a complete object
     such that the [1mfilled [22mand [1mshaded [22mattributes may be  used.   The  last  user‐
     specified  line segment determines the polygon’s final drawing position and
     direction.  For example, draw and fill a triangle with the following.

            polygon up 1 then right 1 down 0.5 fill 0.5

     Two reference point suffixes permit the  positioning  of  drawing  elements
     relative to a polygon.  “[1m.vertex [4m[22mexpr[24m” locates the vertices, and “[1m.midpoint[0m
     [4mexpr[24m”  for  locating  the midpoints of edges.  GNU [1mpic [22mnumbers vertices and
     midpoints in drawing order starting from [1m1 .  [22mYou can abbreviate [1m.vertex [22mas
     [1m.v [22mor [1m.ver[22m, and [1m.midpoint [22mas [1m.mid[22m.

     For example,

            arrow down
            polygon up 0.5 right 1 \
            then down 0.5 right 1 \
            then down 0.5 left 1 \
            with .v2 at last line.end
            arrow down from last polygon.v4

     creates and correctly places a flowchart decision diamond.

     [1m.center [22m([1m.c[22m) is also available, but compass points do not work as  expected
     and should not be used with polygons.

   [1mConverting [4mpic[24m to other image formats[0m
     To  create  a  stand‐alone graphics file from a [4mpic[24m file, first compose the
     picture.  Bracket your [4mpic[24m code with [1m.PS [22mand [1m.PE  [22mtokens.   [4mgroff[24m  requests
     that  don’t  produce  formatted output may precede [1m.PS[22m, but format no text,
     not even any injected by a macro package, which may include a  page  number
     even  on  the  first page, as [4mmm[24m does by default.  Consider writing a “raw”
     [4mroff[24m document that uses no macro package.

     Next, convert the [4mroff[24m/[4mpic[24m input into the desired format.   [4mgroff[24m  distrib‐
     utes a simple utility, ]8;;man:pic2graph(1)\[4mpic2graph[24m(1)]8;;\, for this purpose.  Other possibilities
     exist,  particularly  if  you  first transform your picture into PostScript
     format with “[1mgroff -T ps[22m”.  However, such a PostScript file lacks  bounding
     box  information; [4mroff[24m formatters produce page‐sized output.  Several tools
     with names beginning “psto” or “ps2” exist that can infer the bounding  box
     and  perform  a  format  conversion.  One of these is the PostScript inter‐
     preter  Ghostscript  ([4mgs[24m(1)),  which  exposes  format  converters  via  its
     [1m-sDEVICE= [22moption.  “[1mgs --help[22m” lists available devices.

     Alternatively,  produce  a  PDF  with “[1mgroff -T pdf[22m”; ]8;;man:gropdf(1)\[4mgropdf[24m(1)]8;;\’s [1m-p [22moption
     sets the MediaBox of the file.

     The Encapsulated PostScript File (EPS) format is still sometimes seen.  The
     aforementioned Ghostscript offers ]8;;man:ps2epsi(1)\[4mps2epsi[24m(1)]8;;\, and a standalone package  and
     command ]8;;man:ps2eps(1)\[4mps2eps[24m(1)]8;;\ is also available.

     For  raster image formats, use ]8;;man:pstopnm(1)\[4mpstopnm[24m(1)]8;;\; the resulting ]8;;man:pnm(5)\[4mpnm[24m(5)]8;;\ file can be
     then converted to virtually any image format using the [4mnetpbm[24m tools.

     GNU [4mplotutils[24m offers a ]8;;man:pic2plot(1)\[4mpic2plot[24m(1)]8;;\ utility for converting [4mpic[24m  input  to  a
     wide variety of other image formats, including SVG.

[1mExit status[0m
     [4mpic[24m  exits  with  status [1m0 [22mon successful operation, status [1m2 [22mif the program
     cannot interpret its command‐line arguments, and status [1m1 [22mif it  encounters
     an error during operation.

[1mFiles[0m
     [4m/usr/share/groff/1.24.1/tmac/pic.tmac[0m
            offers simple definitions of the [1mPS[22m, [1mPE[22m, [1mPF[22m, and [1mPY [22mmacros.  Load it
            with the [1mmso [22mrequest when eschewing a full‐service macro package, or
            using one that doesn’t supply its own definitions for them.

[1mCaveats[0m
     The  spacing of dots and dashes in broken lines scales with other graphics,
     and is configurable.  For example,

            line from 0,0 to 100,0 dotted 5

     spaces the dots in a dotted line 5 units apart.  The spacing of dashes  can
     be set the same way.  The [1mdashwid [22mvariable sets the length of dashes.

[1mBugs[0m
     Characters  that  are  invalid as input to GNU [4mtroff[24m (see the [4mgroff[24m Texinfo
     manual or ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\ for a list) are rejected even in TeX mode.

     Research Tenth Edition Unix [4mpic[24m’s [1mfillval [22minterprets 0 as black  and  1  as
     white, incompatibly with GNU [4mpic[24m.

[1mSee also[0m
     [4m/usr/share/doc/groff-1.24.1/pic.ps[0m
            “Making  Pictures with GNU pic”, by ]8;;mailto:esr@thyrsus.com\Eric S. Raymond]8;;\.  This file, to‐
            gether with its source, [4mpic.ms[24m, is part of the [4mgroff[24m distribution.

     “PIC——A Graphics Language  for  Typesetting:  User  Manual”,  by  Brian  W.
     Kernighan,  1984  (revised  1991), AT&T Bell Laboratories Computing Science
     Technical Report No. 116

     [4mps2eps[24m  is  available  from   CTAN   mirrors,   e.g.,   ]8;;ftp://ftp.dante.de/tex-archive/support/ps2eps/\ftp://ftp.dante.de/
     tex-archive/support/ps2eps/]8;;\.

     W. Richard Stevens, ]8;;http://www.kohala.com/start/troff/pic2html.html\[4mTurning[24m [4mPIC[24m [4minto[24m [4mHTML[24m]8;;\

     W. Richard Stevens, ]8;;http://www.kohala.com/start/troff/pic.examples.ps\[4mExamples[24m [4mof[24m pic [4mMacros[24m]8;;\

     ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\,  ]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\,  ]8;;man:tex(1)\[4mtex[24m(1)]8;;\, ]8;;man:gs(1)\[4mgs[24m(1)]8;;\, ]8;;man:ps2eps(1)\[4mps2eps[24m(1)]8;;\, ]8;;man:pstopnm(1)\[4mpstopnm[24m(1)]8;;\, ]8;;man:ps2epsi(1)\[4mps2epsi[24m(1)]8;;\,
     ]8;;man:pnm(5)\[4mpnm[24m(5)]8;;\

groff 1.24.1                       2026‐03‐20                             [4mpic[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mpic2graph[24m(1)                 General Commands Manual                [4mpic2graph[24m(1)

[1mName[0m
     pic2graph - convert a [4mpic[24m diagram into a cropped image

[1mSynopsis[0m
     [1mpic2graph [22m[[1m-unsafe[22m] [[1m-format [4m[22moutput‐format[24m] [[1m-eqn [4m[22mdelimiters[24m] [[4mconvert‐[0m
               [4margument[24m ...]

     [1mpic2graph --help[0m

     [1mpic2graph -v[0m
     [1mpic2graph --version[0m

[1mDescription[0m
     [4mpic2graph[24m reads a ]8;;man:pic(1)\[4mpic[24m(1)]8;;\ program from the standard input and writes an  im‐
     age  file,  by  default  in  Portable Network Graphics (PNG) format, to the
     standard output.  It furthermore translates ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\ constructs, so it can be
     used to generate images of mathematical formulae.

     The input PIC code should [4mnot[24m be  wrapped  with  the  [1m.PS  [22mand  [1m.PE[22m/[1m.PF[22m/[1m.PY[0m
     macros that normally guard it within ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ documents.

     Arguments  not  recognized  by  [4mpic2graph[24m  are passed to the ImageMagick or
     GraphicsMagick program ]8;;man:convert(1)\[4mconvert[24m(1)]8;;\.  By specifying these, you can give  your
     image  a  border,  set  the  image’s pixel density, or perform other useful
     transformations.

     The output image is clipped using [4mconvert[24m’s [1m-trim [22moption  to  the  smallest
     possible bounding box that contains all the black pixels.

[1mOptions[0m
     [1m--help [22mdisplays a usage message, while [1m-v [22mand [1m--version [22mshow version infor‐
     mation; all exit afterward.

     [1m-eqn [4m[22mdelimiters[0m
            Use  [4mdelimiters[24m  as  the opening and closing characters that delimit
            [4meqn[24m directives; the default is “$$”.  The option argument [4mdelimiters[0m
            should be a two‐character string, but an empty string  ("")  is  ac‐
            cepted as a directive to disable [4meqn[24m processing.

     [1m-format [4m[22moutput‐format[0m
            Write  the  image  in  [4moutput‐format[24m,  which  must  be understood by
            [4mconvert[24m; the default is PNG.

     [1m-unsafe[0m
            Run [4mgroff[24m in [4munsafe[24m mode, enabling the PIC command [1msh [22mto execute ar‐
            bitrary Unix shell commands.  The [4mgroff[24m default is to forbid this.

[1mEnvironment[0m
     [4mGROFF_TMPDIR[0m
     [4mTMPDIR[0m
     [4mTMP[0m
     [4mTEMP[24m   These environment variables are searched in the order shown  to  de‐
            termine  the  directory  where  temporary files will be created.  If
            none are set, [4m/tmp[24m is used.

[1mAuthors[0m
     [4mpic2graph[24m was written by ]8;;mailto:esr@thyrsus.com\Eric S. Raymond]8;;\, based on a recipe by  W.  Richard
     Stevens.

[1mSee also[0m
     W. Richard Stevens, ]8;;http://www.kohala.com/start/troff/pic2html.html\[4mTurning[24m [4mPIC[24m [4minto[24m [4mHTML[24m]8;;\

     ]8;;man:eqn2graph(1)\[4meqn2graph[24m(1)]8;;\, ]8;;man:grap2graph(1)\[4mgrap2graph[24m(1)]8;;\, ]8;;man:pic(1)\[4mpic[24m(1)]8;;\, ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\, ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, ]8;;man:convert(1)\[4mconvert[24m(1)]8;;\

groff 1.24.1                       2026‐03‐20                       [4mpic2graph[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mpreconv[24m(1)                   General Commands Manual                  [4mpreconv[24m(1)

[1mName[0m
     preconv - prepare files for typesetting with [4mgroff[0m

[1mSynopsis[0m
     [1mpreconv [22m[[1m-dr[22m] [[1m-D [4m[22mfallback‐encoding[24m] [[1m-e [4m[22mencoding[24m] [[4mfile[24m ...]

     [1mpreconv -h[0m
     [1mpreconv --help[0m

     [1mpreconv -v[0m
     [1mpreconv --version[0m

[1mDescription[0m
     [4mpreconv[24m reads each [4mfile[24m, converts its encoded characters to a form ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\
     can  interpret,  and  sends the result to the standard output stream.  Cur‐
     rently, this means that code points in the range 0–127 in ISO 646:1991  IRV
     (US‐ASCII),  ISO  8859,  or Unicode remain as‐is and the remainder are con‐
     verted to the [4mgroff[24m special character form  “[1m\[u[4m[22mXXXX[24m[1m][22m”,  where  [4mXXXX[24m  is  a
     hexadecimal  number  of  four to six digits corresponding to a Unicode code
     point.  By default, [4mpreconv[24m also inserts a [4mroff[24m [1m.lf [22mrequest at  the  begin‐
     ning  of each [4mfile[24m, identifying it for the benefit of later processing (in‐
     cluding diagnostic messages); the [1m-r [22moption suppresses this behavior.

     In typical usage scenarios, [4mpreconv[24m need not be run  directly;  instead  it
     should  be invoked with the [1m-k [22mor [1m-K [22moptions of [4mgroff[24m.  If no [4mfile[24m operands
     are present, or if [4mfile[24m is “[1m-[22m”, [4mpreconv[24m reads the standard input stream.

     [4mpreconv[24m selects an input encoding with the following algorithm, stopping at
     the first success.

     1.  If the input encoding has been explicitly specified with option [1m-e[22m, use
         it.

     2.  If the input starts with a  Unicode  Byte  Order  Mark,  select  UTF‐8,
         UTF‐16, or UTF‐32 accordingly.

     3.  If  the input stream is seekable, check the first two input lines for a
         GNU Emacs file‐local variable identifying the character encoding,  here
         referred to as the “coding tag”.  If found, use it.

     4.  If  the input stream is seekable, and if the [4muchardet[24m library is avail‐
         able on the system, use it to try to infer the encoding of the file.

     5.  If the [1m-D [22moption specifies an encoding, use it.

     6.  Use the encoding specified by the current locale ([4mLC_CTYPE[24m), unless the
         locale is “C”, “POSIX”, or empty, in  which  case  assume  ISO  Latin‐1
         (8859‐1).

     The  coding  tag  and  [4muchardet[24m  methods in the above procedure rely upon a
     seekable input stream; when [4mpreconv[24m reads from a pipe, the  stream  is  not
     seekable,  and  these detection methods are skipped.  If character encoding
     detection of your input is unreliable, arrange for one of the other methods
     to succeed by using [4mpreconv[24m’s [1m-D [22mor [1m-e [22moptions, or by configuring your  lo‐
     cale appropriately.  [4mgroff[24m also supports a [4mGROFF_ENCODING[24m environment vari‐
     able, which can be overridden by its [1m-K [22moption.  Valid values for (or para‐
     meters  to)  all  of these are enumerated in the lists of recognized coding
     tags in the next subsection, and are further influenced  by  [4miconv[24m  library
     support.

   [1mCoding tags[0m
     Text  editors  that support more than a single character encoding need tags
     within the input files to mark the file’s encoding.  While it  is  possible
     to  guess the right input encoding with the help of heuristics that produce
     good results for a preponderance of natural language texts,  they  are  not
     absolutely  reliable.   Heuristics can fail on inputs that are too short or
     don’t represent a natural language.

     Consequently, [4mpreconv[24m supports the coding tag convention used by GNU  Emacs
     (with  some  restrictions).   This notation appears in specially marked re‐
     gions of an input file designated for “file‐local variables”.

     [4mpreconv[24m interprets the following syntax if it occurs in a [4mroff[24m  comment  in
     the  first  or  second line of the input.  Both “\"” and “\#” comment forms
     are recognized, but the control (or no‐break control) character must be the
     default and must begin the line.  Similarly, the escape character  must  be
     the default.
            [1m-*- [22m[...[1m;[22m] [1mcoding: [4m[22mencoding[24m[[1m; [22m...] [1m-*-[0m

     The only variable [4mpreconv[24m interprets is “coding”, which can take the values
     listed below.

     The  following  list  comprises  all MIME “charset” parameter values recog‐
     nized, case‐insensitively, by [4mpreconv[24m.
            big5,  cp1047,  euc-jp,  euc-kr,  gb2312,  iso-8859-1,   iso-8859-2,
            iso-8859-5,   iso-8859-7,   iso-8859-9,   iso-8859-13,  iso-8859-15,
            koi8-r, us-ascii, utf-8, utf-16, utf-16be, utf-16le

     In addition, the following list of other coding tags is recognized, each of
     which is mapped to an appropriate value from the list above.
            ascii, chinese-big5, chinese-euc, chinese-iso-8bit, cn-big5,  cn-gb,
            cn-gb-2312,    cp878,   csascii,   csisolatin1,   cyrillic-iso-8bit,
            cyrillic-koi8,   euc-china,   euc-cn,   euc-japan,   euc-japan-1990,
            euc-korea,    greek-iso-8bit,    iso-10646/utf8,    iso-10646/utf-8,
            iso-latin-1,  iso-latin-2,  iso-latin-5,  iso-latin-7,  iso-latin-9,
            japanese-euc,    japanese-iso-8bit,    jis8,    koi8,    korean-euc,
            korean-iso-8bit,  latin-0,  latin1,   latin-1,   latin-2,   latin-5,
            latin-7,    latin-9,    mule-utf-8,    mule-utf-16,   mule-utf-16be,
            mule-utf-16-be,     mule-utf-16be-with-signature,     mule-utf-16le,
            mule-utf-16-le,   mule-utf-16le-with-signature,   utf8,   utf-16-be,
            utf-16-be-with-signature,    utf-16be-with-signature,     utf-16-le,
            utf-16-le-with-signature, utf-16le-with-signature

     Any  “-dos”, “-unix”, or “-mac” suffix on a coding tag (which indicates the
     end‐of‐line convention used in the file) is ignored during comparison  with
     the above tags.

   [4m[1miconv[24m support[0m
     While [4mpreconv[24m recognizes all of the coding tags listed above, it is capable
     on  its  own of interpreting only two encodings: ISO Latin‐1 and and UTF‐8.
     ISO 646:1991 IRV (US‐ASCII) is a proper subset of both these encodings.  If
     ]8;;man:iconv(3)\[4miconv[24m(3)]8;;\ support is configured at compile time and available at  run  time,
     all  others are passed to [4miconv[24m library functions, which may recognize many
     additional encoding strings.  The command “[1mpreconv  -v[22m”  discloses  whether
     [4miconv[24m support is configured.

     The  use  of  [4miconv[24m  means that characters in the input that encode invalid
     code points for that encoding may be dropped  from  the  output  stream  or
     mapped  to the Unicode replacement character (U+FFFD).  Compare the follow‐
     ing examples using the input “café” (note the “e” with  an  acute  accent),
     which due to its short length challenges inference of the encoding used.
            printf 'caf\351\n' | LC_ALL=en_US.UTF-8 preconv
            printf 'caf\351\n' | preconv -e us-ascii
            printf 'caf\351\n' | preconv -e latin-1
     The  fate of the accented “e” differs in each case.  In the first, [4muchardet[0m
     fails to detect an encoding (though the library on your system  may  behave
     differently) and [4mpreconv[24m falls back to the locale settings, where octal 351
     starts  an incomplete UTF‐8 sequence and results in the Unicode replacement
     character.  In the second, it is not a representable character in  the  de‐
     clared  input encoding of US‐ASCII and is discarded by [4miconv[24m.  In the last,
     it is correctly detected and mapped.

   [1mLimitations[0m
     [4mpreconv[24m cannot perform any transformation on input that it cannot see.  Ex‐
     amples include files that are interpolated by preprocessors that run subse‐
     quently, including ]8;;man:soelim(1)\[4msoelim[24m(1)]8;;\; files included by [4mtroff[24m itself  through  “[1mso[22m”
     and similar requests; and string definitions passed to [4mtroff[24m through its [1m-d[0m
     command‐line option.

     [4mpreconv[24m  assumes  that its input uses the default escape character, a back‐
     slash [1m\[22m, and writes special character escape sequences accordingly.

[1mOptions[0m
     [1m-h [22mand [1m--help [22mdisplay a usage message, while [1m-v [22mand [1m--version [22mshow  version
     and configuration information; all exit afterward.

     [1m-d        [22mEmit debugging messages to the standard error stream.

     [1m-D [4m[22mfbenc[24m  Select the fallback encoding [4mfbenc[24m if all detection methods fail.

     [1m-e [4m[22menc[24m    Skip detection and select encoding [4menc[24m; see [4mgroff[24m’s [1m-K [22moption.

     [1m-r        [22mWrite files “raw”; do not add [1m.lf [22mrequests.

[1mExit status[0m
     [4mpreconv[24m  exits  with status [1m0 [22mon successful operation, status [1m2 [22mif the pro‐
     gram cannot interpret its command‐line arguments, and status [1m1  [22mif  it  en‐
     counters an error during operation.

[1mSee also[0m
     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, ]8;;man:iconv(3)\[4miconv[24m(3)]8;;\, ]8;;man:locale(7)\[4mlocale[24m(7)]8;;\

groff 1.24.1                       2026‐03‐20                         [4mpreconv[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mrefer[24m(1)                     General Commands Manual                    [4mrefer[24m(1)

[1mName[0m
     refer - process bibliographic references for [4mgroff[0m

[1mSynopsis[0m
     [1mrefer [22m[[1m-bCenPRS[22m] [[1m-a [4m[22mn[24m] [[1m-B [4m[22mfield[24m[1m.[4m[22mmacro[24m] [[1m-c [4m[22mfields[24m] [[1m-f [4m[22mn[24m] [[1m-i [4m[22mfields[24m]
           [[1m-k [4m[22mfield[24m] [[1m-l [4m[22mrange‐expression[24m] [[1m-p [4m[22mdatabase‐file[24m] [[1m-s [4m[22mfields[24m]
           [[1m-t [4m[22mn[24m] [[4mfile[24m ...]

     [1mrefer --help[0m

     [1mrefer -v[0m
     [1mrefer --version[0m

[1mDescription[0m
     The GNU implementation of [4mrefer[24m is part of the ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ document formatting
     system.  [4mrefer[24m is a ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ preprocessor that prepares bibliographic cita‐
     tions by looking up keywords specified in a ]8;;man:roff(7)\[4mroff[24m(7)]8;;\ input document, obviat‐
     ing the need to type such annotations, and permitting the citation style in
     formatted output to be altered independently and systematically.  It copies
     the  contents  of  each [4mfile[24m to the standard output stream, looking up each
     [4mcitation[24m between lines starting with [1m.[ [22mand [1m.] [22mand replacing it with a bib‐
     liographic reference.  GNU [4mrefer[24m furthermore interprets lines between those
     starting with [1m.R1 [22mand [1m.R2 [22mas instructions directing how citations are to be
     processed.  [4mrefer[24m interprets and generates [4mroff[24m [1mlf [22mrequests  so  that  file
     names  and line numbers in messages produced by commands that read its out‐
     put correctly describe the source document.  Normally, [4mrefer[24m  is  not  exe‐
     cuted  directly  by  the  user,  but invoked by specifying the [1m-R [22moption to
     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\.  If no [4mfile[24m operands are present, or if [4mfile[24m is “[1m-[22m”, [4mrefer[24m  reads
     the standard input stream.

     A citation identifies a work by reference to a [4mbibliographic[24m [4mrecord[24m detail‐
     ing  it.  Select a work from a database of records by listing keywords that
     uniquely identify its entry.   Alternatively,  a  document  can  specify  a
     record  for  the work at the point its citation occurs.  A document can use
     either or both strategies as desired.

     For each citation, [4mrefer[24m produces a [4mmark[24m in the text, like a  superscripted
     footnote  number  or  “[Lesk1978a]”.   A  mark  consists of a [4mlabel[24m between
     [4mbrackets.[24m  The mark can be separated from surrounding text and  from  other
     labels  in various ways.  [4mrefer[24m produces [4mroff[24m language requests usable by a
     document or a macro package such as [4mme[24m, [4mmm[24m, [4mmom[24m, or [4mms[24m to produce a format‐
     ted reference for each citation.  A citation’s reference can be output  im‐
     mediately  after  it  occurs (as with footnotes), or references may [4maccumu‐[0m
     [4mlate[24m, with corresponding output appearing later in the  document  (as  with
     endnotes).  When references accumulate, multiple citations of the same ref‐
     erence produce a single formatted entry.

     Interpretation of lines between [1m.R1 [22mand [1m.R2 [22mtokens as preprocessor commands
     is  a  GNU  [4mrefer[24m extension.  Documents employing this feature can still be
     processed by AT&T [4mrefer[24m by adding the lines
            .de R1
            .ig R2
            ..
     to the beginning of the document.  The foregoing input causes [4mtroff[24m to  ig‐
     nore  everything  between  [1m.R1 [22mand [1m.R2[22m.  The effects of some [4mrefer[24m commands
     can be achieved by command‐line options; these are supported  for  compati‐
     bility with AT&T [4mrefer[24m.  It is usually more convenient to use commands.

   [1mBibliographic records[0m
     A  bibliographic  record  describes  a referenced work in sufficient detail
     that it may be cited to accepted standards of  scholarly  and  professional
     clarity.   The  record format permits annotation and extension that a docu‐
     ment may use or ignore.  A record is a plain text sequence of  [4mfields,[24m  one
     per  line,  each  consisting of a percent sign [1m%[22m, an alphanumeric character
     classifying it, one space, and its contents.  If  a  field’s  contents  are
     empty, the field is ignored.

     Frequently,  such records are organized into a [4mbibliographic[24m [4mdatabase,[24m with
     each entry separated by blank lines or file boundaries.  This practice  re‐
     lieves  documents  of  the  need to maintain bibliographic data themselves.
     The programs ]8;;man:lookbib(1)\[4mlookbib[24m(1)]8;;\ and ]8;;man:lkbib(1)\[4mlkbib[24m(1)]8;;\ consult a bibliographic database,  and
     ]8;;man:indxbib(1)\[4mindxbib[24m(1)]8;;\  indexes  one to speed retrieval from it, reducing document pro‐
     cessing time.  Use of these tools is optional.

     The conventional uses of the bibliographic field entries  are  as  follows.
     Within  a  record, fields other than [1m%A [22mand [1m%E [22mreplace previous occurrences
     thereof.  The ordering of multiple [1m%A [22mand [1m%E [22mfields is significant.

     [1m%A     [22mnames an author.  If the name contains a suffix  such  as  “Jr.”  or
            “III”,  it should be separated from the surname by a comma.  We rec‐
            ommend always supplying an [1m%A [22mfield or a [1m%Q [22mfield.

     [1m%B     [22mrecords the title of the book within which a cited article  is  col‐
            lected.  See [1m%J [22mand [1m%T[22m.

     [1m%C     [22mnames the city or other place of publication.

     [1m%D     [22mindicates  the  date  of publication.  Specify the year in full.  If
            the month is specified, use its name rather than  its  number;  only
            the first three letters are required.  We recommend always supplying
            a  [1m%D  [22mfield; if the date is unknown, use “[1min press[22m” or “[1munknown[22m” as
            its contents.

     [1m%E     [22mnames an editor of the book within which a  cited  article  is  col‐
            lected.   Where  a work has editors but no authors, name the editors
            in [1m%A [22mfields and append “[1m, (ed.)[22m” or  “[1m,  (eds.)[22m”  to  the  last  of
            these.

     [1m%G     [22mrecords  the  U.S.  government  ordering number, ISBN, DOI, or other
            unique identifier.

     [1m%I     [22mnames the publisher (issuer).

     [1m%J     [22mrecords the name of the journal within which a cited article is col‐
            lected.  See [1m%B [22mand [1m%T[22m.

     [1m%K     [22mlists keywords intended to aid searches.

     [1m%L     [22mis a label; typically unused in database entries,  it  can  override
            the label format otherwise determined.

     [1m%N     [22mrecords the issue number of the journal within which a cited article
            is collected.

     [1m%O     [22mpresents  additional  (“other”) information, typically placed at the
            end of the reference.

     [1m%P     [22mlists the page numbers of a cited work that is part of a larger col‐
            lection.  Specify a range with [4mm[24m[1m-[4m[22mn[24m.

     [1m%Q     [22mnames an institutional author when no [1m%A [22mfields are  present.   Only
            one [1m%Q [22mfield is permitted.

     [1m%R     [22mis  an  identifier for a report, thesis, memorandum, or other unpub‐
            lished work.

     [1m%S     [22mrecords the title of a series to which the cited work belongs.

     [1m%T     [22mis the work’s title.  See [1m%B [22mand [1m%J[22m.

     [1m%V     [22mis the volume number of the journal or  book  containing  the  cited
            work.

     [1m%X     [22mis  an annotation.  By convention, it is not formatted in the citing
            document.

     If the obsolescent “accent strings” feature of the [4mms[24m or [4mme[24m macro  packages
     is  used,  such  strings  should follow the character to be accented; an [4mms[0m
     document must call the [1mAM [22mmacro before using them.   Do  not  quote  accent
     strings:  use  one  [1m\  [22mrather than two.  See ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\ for a modern ap‐
     proach to the problem of diacritics.

   [1mCitations[0m
     Citations have a characteristic format.
            [1m.[[4m[22mopening‐text[0m
            [4mflags[24m [4mkeyword[24m ...
            [4mfield[0m
            ...
            [1m.][4m[22mclosing‐text[0m

     [4mopening‐text[24m, [4mclosing‐text[24m, and [4mflags[24m are optional, and only one [4mkeyword[24m or
     [4mfield[24m need be specified.  If keywords are present, [4mrefer[24m searches the  bib‐
     liographic  database(s)  for  a  unique  reference matching them.  Multiple
     matches are an error; add more keywords to disambiguate the reference.   In
     the  absence of keywords, [4mfields[24m constitute the bibliographic record.  Oth‐
     erwise, [4mfields[24m specify additional data to replace or  supplement  those  in
     the  reference.  When references are accumulating and keywords are present,
     specify additional [4mfields[24m at most on the first  citation  of  a  particular
     reference; they apply to all further citations thereof.

     [4mopening‐text[24m  and  [4mclosing‐text[24m  are  [4mroff[24m input used to bracket the label,
     overriding the [1mbracket-label [22mcommand.  Leading and trailing spaces are sig‐
     nificant.  If either of these is non‐empty, the corresponding  argument  to
     the [1mbracket-label [22mcommand is not used; alter this behavior with the [1m[ [22mand [1m][0m
     [4mflags.[0m

     [4mflags[24m  is  a list of non‐alphanumeric characters each of which modifies the
     treatment of the particular citation.  AT&T [4mrefer[24m ignores them  since  they
     are non‐alphanumeric.  They direct GNU [4mrefer[24m as follows.

     [1m#      [22mUse  the  label specified by the [1mshort-label [22mcommand, if any.  [4mrefer[0m
            otherwise uses the normal label.  Typically, a  short  label  imple‐
            ments  author‐date citation styles consisting of a name, a year, and
            a disambiguating letter if necessary.  “[1m#[22m” is meant to suggest  such
            a (quasi‐)numeric label.

     [1m[      [22mPrecede   [4mopening‐text[24m   with   the  first  argument  given  to  the
            [1mbracket-label [22mcommand.

     [1m]      [22mFollow  [4mclosing‐text[24m  with  the  second  argument   given   to   the
            [1mbracket-label [22mcommand.

     An advantage of the [1m[ [22mand [1m] [22mflags over use of [4mopening‐text[24m and [4mclosing‐text[0m
     is  that  you can update the document’s bracketing style in one place using
     the [1mbracket-label [22mcommand.  Another is that sorting and  merging  of  cita‐
     tions is not necessarily inhibited if the flags are used.

     [4mrefer[24m  appends  any  label resulting from a citation to the [4mroff[24m input line
     preceding the [1m.[ [22mtoken.  If there is no such line, [4mrefer[24m issues  a  warning
     diagnostic.

     There is no special notation for citing multiple references in series.  Use
     a sequence of citations, one for each reference, with nothing between them.
     [4mrefer[24m  attaches all of their labels to the line preceding the first.  These
     labels may be sorted or merged.  See the description of the  [1m<>  [22mlabel  ex‐
     pression,  and of the [1msort-adjacent-labels [22mand [1mabbreviate-label-ranges [22mcom‐
     mands.  A label is not merged if its citation has a non‐empty  [4mopening‐text[0m
     or  [4mclosing‐text[24m.  However, the labels for two adjacent citations, the for‐
     mer using the [1m] [22mflag and without any [4mclosing‐text,[24m and the latter using the
     [1m[ [22mflag and without any [4mopening‐text,[24m may be sorted and merged even  if  the
     former’s  [4mopening‐text[24m or the latter’s [4mclosing‐text[24m is non‐empty.  (To pre‐
     vent these operations, use the dummy character escape sequence  [1m\&  [22mas  the
     former’s [4mclosing‐text[24m.)

   [1mCommands[0m
     Commands are contained between lines starting with [1m.R1 [22mand [1m.R2[22m.  The [1m-R [22mop‐
     tion  prevents  recognition  of  these  lines.  When [4mrefer[24m encounters a [1m.R1[0m
     line, it flushes any accumulated references.  Neither [1m.R1  [22mnor  [1m.R2  [22mlines,
     nor anything between them, is output.

     Commands are separated by newlines or semicolons.  A number sign ([1m#[22m) intro‐
     duces  a  comment that extends to the end of the line, but does not conceal
     the newline.  Each command is broken up into words.  Words are separated by
     spaces or tabs.  A word that begins with a (neutral) double quote  ([1m"[22m)  ex‐
     tends  to  the  next  double  quote  that is not followed by another double
     quote.  If there is no such double quote, the word extends to  the  end  of
     the  line.   Pairs of double quotes in a word beginning with a double quote
     collapse to one double quote.  Neither a number sign  nor  a  semicolon  is
     recognized inside double quotes.  A line can be continued by ending it with
     a backslash “[1m\[22m”; this works everywhere except after a number sign.

     Each  command [4mname[24m that is marked with * has an associated negative command
     [1mno-[4m[22mname[24m that undoes the effect of [4mname[24m.  For example, the  [1mno-sort  [22mcommand
     specifies that references should not be sorted.  The negative commands take
     no arguments.

     In  the following description each argument must be a single word; [4mfield[24m is
     used for a single upper or lower case letter naming a field; [4mfields[24m is used
     for a sequence of such letters; [4mm[24m and [4mn[24m are used for  a  non‐negative  num‐
     bers;  [4mstring[24m is used for an arbitrary string; [4mfile[24m is used for the name of
     a file.

     [1mabbreviate[22m* [4mfields[24m [4mstring1[24m [4mstring2[24m [4mstring3[24m [4mstring4[0m
            Abbreviate the first names of [4mfields[24m.  An  initial  letter  will  be
            separated  from  another initial letter by [4mstring1[24m, from the surname
            by [4mstring2[24m, and from anything  else  (such  as  “von”  or  “de”)  by
            [4mstring3[24m.   These  default to a period followed by a space.  In a hy‐
            phenated first name, the initial of the first part of the name  will
            be  separated from the hyphen by [4mstring4[24m; this defaults to a period.
            No attempt is made to handle any ambiguities that might result  from
            abbreviation.  Names are abbreviated before sorting and before label
            construction.

     [1mabbreviate-label-ranges[22m* [4mstring[0m
            Three  or  more adjacent labels that refer to consecutive references
            will be abbreviated to a label consisting of the first  label,  fol‐
            lowed  by [4mstring[24m, followed by the last label.  This is mainly useful
            with numeric labels.  If [4mstring[24m is omitted, it defaults to “[1m-[22m”.

     [1maccumulate[22m*
            Accumulate references instead of writing out each reference as it is
            encountered.  Accumulated references will be written out whenever  a
            reference of the form
                   [1m.[[0m
                   [1m$LIST$[0m
                   [1m.][0m
            is encountered, after all input files have been processed, and when‐
            ever a [1m.R1 [22mline is recognized.

     [1mannotate[22m* [4mfield[24m [4mstring[0m
            [4mfield[24m  is  an  annotation; print it at the end of the reference as a
            paragraph preceded by the line

                   [1m.[4m[22mstring[0m

            If [4mstring[24m is omitted, it will default to [1mAP[22m; if [4mfield[24m is also  omit‐
            ted it will default to [1mX[22m.  Only one field can be an annotation.

     [1marticles [4m[22mstring[24m ...
            Each  [4mstring[24m  is a definite or indefinite article, and should be ig‐
            nored at the beginning of [1mT [22mfields when  sorting.   Initially,  “a”,
            “an”, and “the” are recognized as articles.

     [1mbibliography [4m[22mfile[24m ...
            Write  out  all the references contained in each bibliographic data‐
            base [4mfile[24m.  This command should come last in an [1m.R1[22m/[1m.R2 [22mblock.

     [1mbracket-label [4m[22mstring1[24m [4mstring2[24m [4mstring3[0m
            In the text, bracket each label with [4mstring1[24m and [4mstring2[24m.  An occur‐
            rence of [4mstring2[24m immediately followed by [4mstring1[24m will be turned into
            [4mstring3[24m.  The default behavior is as follows.
                   bracket-label \*([. \*(.] ", "

     [1mcapitalize [4m[22mfields[0m
            Convert [4mfields[24m to caps and small caps.

     [1mcompatible[22m*
            Recognize [1m.R1 [22mand [1m.R2 [22meven when followed by a character  other  than
            space or newline.

     [1mdatabase [4m[22mfile[24m ...
            Search each bibliographic database [4mfile[24m.  For each [4mfile[24m, if an index
            file[4m.i[24m  created  by  ]8;;man:indxbib(1)\[4mindxbib[24m(1)]8;;\ exists, then it will be searched in‐
            stead; each index can cover multiple databases.

     [1mdate-as-label[22m* [4mstring[0m
            [4mstring[24m is a label expression that specifies a string with  which  to
            replace  the  [1mD  [22mfield after constructing the label.  See subsection
            “Label expressions” below for a description  of  label  expressions.
            This  command  is  useful  if you do not want explicit labels in the
            reference list, but instead want to handle any necessary disambigua‐
            tion by qualifying the date in some way.  The label used in the text
            would typically be some combination of the author and date.  In most
            cases you should also use the  [1mno-label-in-reference  [22mcommand.   For
            example,
                   date-as-label D.+yD.y%a*D.-y
            would attach a disambiguating letter to the year part of the [1mD [22mfield
            in the reference.

     [1mdefault-database[22m*
            The default database should be searched.  This is the default behav‐
            ior,  so the negative version of this command is more useful.  [4mrefer[0m
            determines whether the default database should be  searched  on  the
            first   occasion   that   it   needs   to   do  a  search.   Thus  a
            [1mno-default-database [22mcommand must be given before then, in  order  to
            be effective.

     [1mdiscard[22m* [4mfields[0m
            When  the  reference  is read, [4mfields[24m should be discarded; no string
            definitions for [4mfields[24m will be output.  Initially, [4mfields[24m are [1mXYZ[22m.

     [1met-al[22m* [4mstring[24m [4mm[24m [4mn[0m
            Configure use of “[1met al[22m” in the evaluation of [1m@ [22mexpressions in label
            expressions.  If [4mu[24m is the number of authors needed to make  the  au‐
            thor sequence unambiguous and the total number of authors is [4mt,[24m then
            the last [4mt[24m-[4mu[24m authors will be replaced by [4mstring[24m provided that [4mt[24m-[4mu[24m is
            not  less  than [4mm[24m and [4mt[24m is not less than [4mn[24m.  The default behavior is
            as follows.
                   et-al " et al" 2 3
            Note the absence of a dot from the end of the abbreviation, which is
            arguably not correct.  ([4mEt[24m [4mal[24m[.]  is short for [4met[24m [4malli[24m, as  [4metc.[24m  is
            short for [4met[24m [4mcetera[24m.)

     [1minclude [4m[22mfile[0m
            Include [4mfile[24m and interpret the contents as commands.

     [1mjoin-authors [4m[22mstring1[24m [4mstring2[24m [4mstring3[0m
            Join multiple authors together with [4mstring[24ms.  When there are exactly
            two  authors, they will be joined with [4mstring1[24m.  When there are more
            than two authors, all but the last two will be joined with  [4mstring2[24m,
            and the last two authors will be joined with [4mstring3[24m.  If [4mstring3[24m is
            omitted,  it  will default to [4mstring1[24m; if [4mstring2[24m is also omitted it
            will also default to [4mstring1[24m.  For example,
                   join-authors " and " ", " ", and "
            will restore the default method for joining authors.

     [1mlabel-in-reference[22m*
            When outputting the reference, define the string [1m[F [22mto be the refer‐
            ence’s label.  This is the default behavior, so the negative version
            of this command is more useful.

     [1mlabel-in-text[22m*
            For each reference output a label in the text.  The  label  will  be
            separated   from   the   surrounding   text   as  described  in  the
            [1mbracket-label [22mcommand.  This is the default behavior, so  the  nega‐
            tive version of this command is more useful.

     [1mlabel [4m[22mstring[0m
            [4mstring[24m is a label expression describing how to label each reference.

     [1mseparate-label-second-parts [4m[22mstring[0m
            When merging two‐part labels, separate the second part of the second
            label  from the first label with [4mstring[24m.  See the description of the
            [1m<> [22mlabel expression.

     [1mmove-punctuation[22m*
            In the text, move any punctuation at the end of line past the label.
            We recommend employing this command  unless  you  are  using  super‐
            scripted numbers as labels.

     [1mreverse[22m* [4mstring[0m
            Reverse  the  fields whose names are in [4mstring[24m.  An optional integer
            after a field name limits the number of such  fields  to  the  given
            count; no integer means no limit.

     [1msearch-ignore[22m* [4mfields[0m
            While searching for keys in databases for which no index exists, ig‐
            nore the contents of [4mfields[24m.  Initially, fields [1mXYZ [22mare ignored.

     [1msearch-truncate[22m* [4mn[0m
            Only  require the first [4mn[24m characters of keys to be given.  In effect
            when searching for a given key words in the database  are  truncated
            to the maximum of [4mn[24m and the length of the key.  Initially, [4mn[24m is 6.

     [1mshort-label[22m* [4mstring[0m
            [4mstring[24m  is a label expression that specifies an alternative (usually
            shorter) style of label.  This is used when the [1m# [22mflag is  given  in
            the  citation.  When using author‐date style labels, the identity of
            the author or authors is sometimes clear from the context, and so it
            may be desirable to omit the author or authors from the label.   The
            [1mshort-label  [22mcommand  will typically be used to specify a label con‐
            taining just a date and possibly a disambiguating letter.

     [1msort[22m* [4mstring[0m
            Sort references according to [4mstring[24m.  References will  automatically
            be  accumulated.   [4mstring[24m should be a list of field names, each fol‐
            lowed by a number, indicating how many fields with the  name  should
            be  used  for  sorting.   “[1m+[22m”  can  be used to indicate that all the
            fields with the name should be used.  Also [1m. [22mcan be used to indicate
            the references should be sorted using the (tentative) label.   (Sub‐
            section  “Label expressions” below describes the concept of a tenta‐
            tive label.)

     [1msort-adjacent-labels[22m*
            Sort labels that are adjacent in the text according to  their  posi‐
            tion in the reference list.  This command should usually be given if
            the  [1mabbreviate-label-ranges [22mcommand has been given, or if the label
            expression contains a [1m<> [22mexpression.  This has no effect unless ref‐
            erences are being accumulated.

   [1mLabel expressions[0m
     Label expressions can be evaluated both normally and tentatively.  The  re‐
     sult  of  normal  evaluation  is  used for output.  The result of tentative
     evaluation, called the [4mtentative[24m [4mlabel[24m, is used to gather  the  information
     that  normal evaluation needs to disambiguate the label.  Label expressions
     specified by the [1mdate-as-label [22mand [1mshort-label [22mcommands are  not  evaluated
     tentatively.  Normal and tentative evaluation are the same for all types of
     expression  other  than [1m@[22m, [1m*[22m, and [1m% [22mexpressions.  The description below ap‐
     plies to normal evaluation, except where otherwise specified.

     [4mfield[24m [[4mn[24m]
             is the [4mn[24mth part of [4mfield[24m.  If [4mn[24m is omitted, it defaults to 1.

     [1m'[4m[22mstring[24m[1m'[0m
             The characters in [4mstring[24m literally.

     [1m@       [22mAll authors joined as specified by the [1mjoin-authors  [22mcommand.   The
             whole  of  each  author’s name is used.  However, if the references
             are sorted by author (that is, the sort specification  starts  with
             “[1mA+[22m”),  then  authors’ surnames will be used instead, provided that
             this does not introduce ambiguity, and also an initial  subsequence
             of  the  authors may be used instead of all the authors, again pro‐
             vided that this does not introduce ambiguity.  Given any two refer‐
             enced works with [4mn[24m authors, the use of only the surname for the [4mn[24mth
             author of a reference is regarded as ambiguous if the other  refer‐
             ence  shares  the first [4mn[24m-1 authors, the [4mn[24mth authors of each refer‐
             ence are not identical, but the [4mn[24mth authors’ surnames [4mare[24m the same.
             A proper initial subsequence of the sequence of  authors  for  some
             reference  is  considered  to  be ambiguous if there is a reference
             with some other sequence of authors which also has that subsequence
             as a proper initial subsequence.  When an  initial  subsequence  of
             authors  is  used, the remaining authors are replaced by the string
             specified by the [1met-al [22mcommand; this command may also specify addi‐
             tional requirements that must be met before an initial  subsequence
             can be used.  [1m@ [22mtentatively evaluates to a canonical representation
             of  the authors, such that authors that compare equally for sorting
             purposes have the same representation.

     [1m%[4m[22mn[0m
     [1m%a[0m
     [1m%A[0m
     [1m%i[0m
     [1m%I      [22mThe serial number of the reference formatted according to the char‐
             acter following the [1m%[22m.  The serial number of a reference is 1  plus
             the  number of earlier references with same tentative label as this
             reference.  These expressions  tentatively  evaluate  to  an  empty
             string.

     [4mexpr[24m[1m*   [22mIf there is another reference with the same tentative label as this
             reference,  then  [4mexpr[24m,  otherwise an empty string.  It tentatively
             evaluates to an empty string.

     [4mexpr[24m[1m+[4m[22mn[0m
     [4mexpr[24m[1m-[4m[22mn[24m  The first ([1m+[22m) or last ([1m-[22m) [4mn[24m upper or lower case letters  or  digits
             of  [4mexpr[24m.  [4mroff[24m special characters (such as [1m\('a[22m) count as a single
             letter.  Accent strings are retained but do not  count  toward  the
             total.

     [4mexpr[24m[1m.l  [4m[22mexpr[24m converted to lowercase.

     [4mexpr[24m[1m.u  [4m[22mexpr[24m converted to uppercase.

     [4mexpr[24m[1m.c  [4m[22mexpr[24m converted to caps and small caps.

     [4mexpr[24m[1m.r  [4m[22mexpr[24m reversed so that the surname is first.

     [4mexpr[24m[1m.a  [4m[22mexpr[24m  with  first  names  abbreviated.   Fields  specified  in  the
             [1mabbreviate [22mcommand are abbreviated before any labels are evaluated.
             Thus [1m.a [22mis useful only when you want a field to be abbreviated in a
             label but not in a reference.

     [4mexpr[24m[1m.y  [22mThe year part of [4mexpr[24m.

     [4mexpr[24m[1m.+y[0m
             The part of [4mexpr[24m before the year, or the whole of [4mexpr[24m if  it  does
             not contain a year.

     [4mexpr[24m[1m.-y[0m
             The  part  of  [4mexpr[24m after the year, or an empty string if [4mexpr[24m does
             not contain a year.

     [4mexpr[24m[1m.n  [22mThe surname part of [4mexpr[24m.

     [4mexpr1[24m[1m~[4m[22mexpr2[0m
             [4mexpr1[24m except that if the last character of [4mexpr1[24m is [1m- [22mthen it  will
             be replaced by [4mexpr2[24m.

     [4mexpr1[24m [4mexpr2[0m
             The catenation of [4mexpr1[24m and [4mexpr2[24m.

     [4mexpr1[24m[1m|[4m[22mexpr2[0m
             If [4mexpr1[24m is non‐empty then [4mexpr1[24m otherwise [4mexpr2[24m.

     [4mexpr1[24m[1m&[4m[22mexpr2[0m
             If [4mexpr1[24m is non‐empty then [4mexpr2[24m otherwise an empty string.

     [4mexpr1[24m[1m?[4m[22mexpr2[24m[1m:[4m[22mexpr3[0m
             If [4mexpr1[24m is non‐empty then [4mexpr2[24m otherwise [4mexpr3[24m.

     [1m<[4m[22mexpr[24m[1m>  [22mThe  label is in two parts, which are separated by [4mexpr[24m.  Two adja‐
             cent two‐part labels which have the same first part will be  merged
             by appending the second part of the second label onto the first la‐
             bel     separated     by    the    string    specified    in    the
             [1mseparate-label-second-parts [22mcommand (initially, a comma followed by
             a space); the resulting label will also be a  two‐part  label  with
             the same first part as before merging, and so additional labels can
             be  merged  into  it.   It  is permissible for the first part to be
             empty;  this  may  be  desirable  for  expressions  used   in   the
             [1mshort-label [22mcommand.

     [1m([4m[22mexpr[24m[1m)  [22mThe same as [4mexpr[24m.  Used for grouping.

     The  above expressions are listed in order of precedence (highest first); [1m&[0m
     and [1m| [22mhave the same precedence.

   [1mMacro interface[0m
     Each reference starts with a call to the macro [1m]-[22m.  The string [1m[F  [22mwill  be
     defined    to    be    the   label   for   this   reference,   unless   the
     [1mno-label-in-reference [22mcommand has been given.  There then follows a  series
     of  string  definitions, one for each field: string [1m[[4m[22mX[24m corresponds to field
     [4mX[24m.  The register [1m[P [22mis set to 1 if the [1mP [22mfield contains a range  of  pages.
     The [1m[T[22m, [1m[A [22mand [1m[O [22mregisters are set to 1 according as the [1mT[22m, [1mA [22mand [1mO [22mfields
     end  with  any of [1m.?! [22m(an end‐of‐sentence character).  The [1m[E [22mregister will
     be set to 1 if the [1m[E [22mstring contains more than one name.  The reference is
     followed by a call to the [1m][ [22mmacro.  The first argument to this macro gives
     a number representing the type of the reference.  If a reference contains a
     [1mJ [22mfield, it will be classified as type 1, otherwise  if  it  contains  a  [1mB[0m
     field,  it  will be type 3, otherwise if it contains a [1mG [22mor [1mR [22mfield it will
     be type 4, otherwise if it contains an [1mI [22mfield it will be type 2, otherwise
     it will be type 0.  The second argument is a symbolic name  for  the  type:
     [1mother[22m,  [1mjournal-article[22m,  [1mbook[22m, [1marticle-in-book[22m, or [1mtech-report[22m.  Groups of
     references that have been accumulated or are produced by  the  [1mbibliography[0m
     command  are  preceded  by a call to the [1m]< [22mmacro and followed by a call to
     the [1m]> [22mmacro.

[1mOptions[0m
     [1m--help [22mdisplays a usage message, while [1m-v [22mand [1m--version [22mshow version infor‐
     mation; all exit afterward.

     [1m-R     [22mDon’t recognize lines beginning with [1m.R1[22m/[1m.R2[22m.

     Other options are equivalent to [4mrefer[24m commands.

     [1m-a [4m[22mn[24m            [1mreverse A[4m[22mn[0m

     [1m-b              no-label-in-text; no-label-in-reference[0m

     [1m-B              [22mSee below.

     [1m-c [4m[22mfields[24m       [1mcapitalize [4m[22mfields[0m

     [1m-C              compatible[0m

     [1m-e              accumulate[0m

     [1m-f [4m[22mn[24m            [1mlabel %[4m[22mn[0m

     [1m-i [4m[22mfields[24m       [1msearch-ignore [4m[22mfields[0m

     [1m-k              label L~%a[0m

     [1m-k [4m[22mfield[24m        [1mlabel [4m[22mfield[24m[1m~%a[0m

     [1m-l              label A.nD.y%a[0m

     [1m-l [4m[22mm[24m            [1mlabel A.n+[4m[22mm[24m[1mD.y%a[0m

     [1m-l ,[4m[22mn[24m           [1mlabel A.nD.y-[4m[22mn[24m[1m%a[0m

     [1m-l [4m[22mm[24m[1m,[4m[22mn[24m          [1mlabel A.n+[4m[22mm[24m[1mD.y-[4m[22mn[24m[1m%a[0m

     [1m-n              no-default-database[0m

     [1m-p [4m[22mdb‐file[24m      [1mdatabase [4m[22mdb‐file[0m

     [1m-P              move-punctuation[0m

     [1m-s [4m[22mspec[24m         [1msort [4m[22mspec[0m

     [1m-S              label "(A.n|Q) ', ' (D.y|D)"; bracket‐label " (" ) "; "[0m

     [1m-t [4m[22mn[24m            [1msearch-truncate [4m[22mn[0m

     The [1mB [22moption has command equivalents with the addition that the file  names
     specified  on  the  command line are processed as if they were arguments to
     the [1mbibliography [22mcommand instead of in the normal way.

     [1m-B              annotate X AP; no-label-in-reference[0m

     [1m-B [4m[22mfield[24m[1m.[4m[22mmacro[24m  [1mannotate [4m[22mfield[24m [4mmacro[24m[1m; no-label-in-reference[0m

[1mExit status[0m
     [4mrefer[24m exits with status [1m0 [22mon successful operation, status [1m2 [22mif the  program
     cannot  interpret its command‐line arguments, and status [1m1 [22mif it encounters
     an error during operation.

[1mEnvironment[0m
     [4mREFER[24m    Assign this variable a file name to override the default database.

[1mFiles[0m
     [4m/usr/dict/papers/Ind[0m
            Default database.

     file[4m.i[0m
            Index files.

     [4m/usr/share/groff/1.24.1/tmac/refer.tmac[0m
            defines macros and strings facilitating integration with macro pack‐
            ages that wish to support [4mrefer[24m.

     [4mrefer[24m uses temporary files.  See the ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ man page for details of where
     such files are created.

[1mBugs[0m
     In label expressions, [1m<> [22mexpressions are ignored inside [1m.[4m[22mchar[24m expressions.

[1mExamples[0m
     We can illustrate the operation of [4mrefer[24m with a sample bibliographic  data‐
     base containing one entry and a simple [4mroff[24m document to cite that entry.

            $ [1mcat > my-db-file[0m
            [1m%A Daniel P.\& Friedman[0m
            [1m%A Matthias Felleisen[0m
            [1m%C Cambridge, Massachusetts[0m
            [1m%D 1996[0m
            [1m%I The MIT Press[0m
            [1m%T The Little Schemer, Fourth Edition[0m
            $ [1mrefer ‐p my-db-file[0m
            [1mRead the book[0m
            [1m.[[0m
            [1mfriedman[0m
            [1m.][0m
            [1mon your summer vacation.[0m
            [4m<Control+D>[0m
            .lf 1 -
            Read the book\*([.1\*(.]
            .ds [F 1
            .]-
            .ds [A Daniel P. Friedman and Matthias Felleisen
            .ds [C Cambridge, Massachusetts
            .ds [D 1996
            .ds [I The MIT Press
            .ds [T The Little Schemer, Fourth Edition
            .nr [T 0
            .nr [A 0
            .][ 2 book
            .lf 5 -
            on your summer vacation.

     The  foregoing  shows  us that [4mrefer[24m (a) produces a label “1”; (b) brackets
     that label with interpolations of the “[1m[.[22m”  and “[1m.][22m”  strings; (c) calls  a
     macro “[1m]-[22m”; (d) defines strings and registers containing the label and bib‐
     liographic data for the reference; (e) calls a macro “[1m][[22m”; and (f) uses the
     [1mlf  [22mrequest  to restore the line numbers of the input.  As noted in subsec‐
     tion “Macro interface” above, it is the document’s responsibility to employ
     and format the  information  usefully.   Let  us  see  how  we  might  turn
     ]8;;man:groff_ms(7)\[4mgroff_ms[24m(7)]8;;\ to this task.

            $ [1mREFER=my-db-file groff -R -ms[0m
            [1m.LP[0m
            [1mRead the book[0m
            [1m.[[0m
            [1mfriedman[0m
            [1m.][0m
            [1mon your summer vacation.[0m
            [1mCommentary is available.\*{*\*}[0m
            [1m.FS \*{*\*}[0m
            [1mSpace reserved for penetrating insight.[0m
            [1m.FE[0m

     [4mms[24m’s  automatic  footnote numbering mechanism is not aware of [4mrefer[24m’s label
     numbering, so we have manually specified a (superscripted)  symbolic  foot‐
     note for our non‐bibliographic aside.

[1mSee also[0m
     “Refer  ——  A  Bibliography  System”, by Bill Tuthill, 1983, Computing Ser‐
     vices, University of California, Berkeley.

     “Some Applications of Inverted Indexes on the Unix System”, by M. E.  Lesk,
     1978, AT&T Bell Laboratories Computing Science Technical Report No. 69.

     ]8;;man:indxbib(1)\[4mindxbib[24m(1)]8;;\, ]8;;man:lookbib(1)\[4mlookbib[24m(1)]8;;\, ]8;;man:lkbib(1)\[4mlkbib[24m(1)]8;;\

groff 1.24.1                       2026‐03‐20                           [4mrefer[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4msoelim[24m(1)                    General Commands Manual                   [4msoelim[24m(1)

[1mName[0m
     soelim  -  recursively  interpolate  source  requests in [4mroff[24m or other text
     files

[1mSynopsis[0m
     [1msoelim [22m[[1m-Crt[22m] [[1m-I [4m[22mdir[24m] [[4minput‐file[24m ...]

     [1msoelim --help[0m

     [1msoelim -v[0m
     [1msoelim --version[0m

[1mDescription[0m
     GNU [4msoelim[24m is a preprocessor for the ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\ document  formatting  system.
     [4msoelim[24m eliminates source requests in ]8;;man:roff(7)\[4mroff[24m(7)]8;;\ and other text files; that is,
     it  replaces  lines of the form “[1m.so [4m[22mincluded‐file[24m” within each text [4minput‐[0m
     [4mfile[24m with the contents of [4mincluded‐file[24m recursively, flattening a  tree  of
     documents.   By  default,  it writes [4mroff[24m [1mlf [22mrequests as well to record the
     name and line number of each [4minput‐file[24m and [4mincluded‐file[24m, so that any  di‐
     agnostics  produced  by  later  processing  can be accurately traced to the
     original input.  Options allow this information to be  suppressed  ([1m-r[22m)  or
     supplied  in TeX comments instead ([1m-t[22m).  In the absence of [4minput‐file[24m argu‐
     ments, [4msoelim[24m reads the standard input stream.  The program writes  to  the
     standard output stream.

     [4msoelim[24m  reads  the  [4mincluded‐file[24m  argument  as GNU [4mtroff[24m does.  It ignores
     spaces immediately after “so”; to embed a sequence of one or  more  leading
     spaces  in  the  argument,  prefix the sequence with a neutral double quote
     ([1m"[22m).  Non‐leading spaces are interpreted literally.  A  backslash  followed
     by a space (“[1m\ [22m”) also encodes a space, for compatibility with earlier ver‐
     sions  of  GNU [4msoelim[24m.  If the included file name requires a backslash, use
     [1m\\ [22mor [1m\e [22mto embed it.  Any other escape sequence in [4mincluded‐file[24m,  includ‐
     ing  “[1m\[rs][22m”,  prevents [4msoelim[24m from replacing the source request.  AT&T and
     descendant versions of [4msoelim[24m have no means of  embedding  spaces  in  file
     names; they replace the first space encountered with a newline and stop in‐
     terpreting the request.

     The  dot  must  be  at the beginning of a line and must be followed by “[1mso[22m”
     without intervening spaces or tabs for [4msoelim[24m to handle it.   This  conven‐
     tion  allows  source  requests to be “protected” from processing by [4msoelim[24m,
     for instance as part of macro definitions or “[1mif[22m” requests.

     There must also be at least one space between “[1mso[22m”  and  its  [4mincluded‐file[0m
     argument.  The [1m-C [22moption overrides this requirement.

     The  foregoing is the limit of [4msoelim[24m’s understanding of the [4mroff[24m language;
     it does not, for example, replace the input line
            .if 1 .so otherfile
     with the contents of [4motherfile[24m.  With its [1m-r [22moption, therefore, [4msoelim[24m  can
     be used to process text files in general.

     [4msoelim[24m  was designed to handle situations where the target of a [4mroff[24m source
     request requires a  preprocessor  such  as  ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\,  ]8;;man:pic(1)\[4mpic[24m(1)]8;;\,  ]8;;man:refer(1)\[4mrefer[24m(1)]8;;\,  or
     ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\.  The usual processing sequence of ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ is as follows.

               input        sourced
               file          file
                 ⎪             ⎪
                 ↓             ↓
             preprocessor ⎯→ troff ⎯→ postprocessor
                                           ⎪
                                           ↓
                                        output
                                         file

     That  is,  files sourced with “[1mso[22m” are normally read [4monly[24m by the formatter,
     ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\.  [4msoelim[24m is [4mnot[24m required for [4mtroff[24m to source files.

     If a file to be sourced should also be preprocessed,  it  must  already  be
     read  [4mbefore[24m  the  input passes through the preprocessor.  [4msoelim[24m, normally
     invoked via [4mgroff[24m’s [1m-s [22moption, handles this.

               input
               file
                 ⎪
                 ↓
               soelim ⎯→ preprocessor ⎯→ troff ⎯→ postprocessor
                 ↑                                     ⎪
                 ⎪                                     ↓
              sourced                               output
               file                                  file

[1mOptions[0m
     [1m--help [22mdisplays a usage message, while [1m-v [22mand [1m--version [22mshow version infor‐
     mation; all exit afterward.

     [1m-C      [22mRecognize an input line starting with [1m.so [22meven if a character other
             than a space or newline follows.

     [1m-I [4m[22mdir[24m  Search the directory [4mdir[24m for [4minput‐[24m and [4mincluded‐files.[24m  If  speci‐
             fied  more  than once, each [4mdir[24m is searched in the given order.  To
             search the current working directory before others, add “[1m-I  .[22m”  at
             the desired place; it is otherwise searched last.

     [1m-r      [22mWrite files “raw”; do not add [1mlf [22mrequests.

     [1m-t      [22mEmit  TeX  comment  lines  starting with “[1m%[22m” indicating the current
             file and line number, rather than [1mlf [22mrequests for the same purpose.

     If both [1m-r [22mand [1m-t [22mare given, the last one specified controls.

[1mExit status[0m
     [4msoelim[24m exits with status [1m0 [22mon successful operation, status [1m2 [22mif the program
     cannot interpret its command‐line arguments, and status [1m1 [22mif it  encounters
     an error during operation.

[1mSee also[0m
     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\

groff 1.24.1                       2026‐03‐20                          [4msoelim[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mtbl[24m(1)                       General Commands Manual                      [4mtbl[24m(1)

[1mName[0m
     tbl - prepare tables for [4mgroff[24m documents

[1mSynopsis[0m
     [1mtbl [22m[[1m-C[22m] [[4mfile[24m ...]

     [1mtbl --help[0m

     [1mtbl -v[0m
     [1mtbl --version[0m

[1mDescription[0m
     The  GNU  implementation of [4mtbl[24m is part of the ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ document formatting
     system.  [4mtbl[24m is a ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ preprocessor that translates descriptions of ta‐
     bles embedded in ]8;;man:roff(7)\[4mroff[24m(7)]8;;\ input into the language understood by  [4mtroff[24m.   It
     copies  each  [4mfile[24m’s  contents  to the standard output stream, transforming
     each [4mtable[24m [4mregion[24m between lines starting with [1m.TS [22mand [1m.TE [22minto instructions
     to the GNU [4mtroff[24m formatter.  While GNU [4mtbl[24m’s input syntax is highly compat‐
     ible with AT&T [4mtbl[24m, the output GNU [4mtbl[24m produces cannot be processed by AT&T
     [4mtroff[24m; GNU [4mtroff[24m (or a [4mtroff[24m implementing any GNU extensions employed) must
     be used.  Normally, [4mtbl[24m is not executed directly by the user,  but  invoked
     by  specifying the [1m-t [22moption to ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\.  If no [4mfile[24m operands are present,
     or if [4mfile[24m is “[1m-[22m”, [4mtbl[24m reads the standard input stream.

   [1mOverview[0m
     [4mtbl[24m expects to find table descriptions between input lines that begin  with
     [1m.TS [22m(table start) and [1m.TE [22m(table end).  Each such table region encloses one
     or  more table descriptions.  Within a table region, table descriptions be‐
     yond the first must each be preceded by an input line beginning  with  [1m.T&[22m.
     This  mechanism  does  not start a new table region; all table descriptions
     are treated as part of their [1m.TS[22m/[1m.TE [22menclosure, even if they are  boxed  or
     have column headings that repeat on subsequent pages (see below).

     (Experienced  [4mroff[24m users should observe that [4mtbl[24m is not a [4mroff[24m language in‐
     terpreter: the default control character must be used,  and  no  spaces  or
     tabs are permitted between the control character and the macro name.  These
     [4mtbl[24m  input  tokens  remain  as‐is in the output, where they become ordinary
     macro calls.  Macro packages often define [1mTS[22m, [1mT&[22m, and [1mTE [22mmacros  to  handle
     issues  of table placement on the page.  [4mtbl[24m produces [4mtroff[24m requests to de‐
     fine these macros as empty if their definitions do not exist when the  for‐
     matter encounters a table region.)

     Each  table  region  may begin with [4mregion[24m [4moptions,[24m and must contain one or
     more [4mtable[24m [4mdefinitions;[24m each table definition contains a [4mformat[24m  [4mspecifica‐[0m
     [4mtion[24m  followed by one or more input lines (rows) of [4mentries.[24m  These entries
     comprise the [4mtable[24m [4mdata.[0m

   [1mRegion options[0m
     The line immediately following the [1m.TS [22mtoken may  specify  region  options,
     keywords  that influence the interpretation or rendering of the region as a
     whole or all table entries within it indiscriminately.   Separate  multiple
     region  options  with commas, spaces, or tabs.  Those that require a paren‐
     thesized argument permit spaces and tabs between the option’s name and  the
     opening  parenthesis.   Options accumulate and cannot be unset within a re‐
     gion once declared; if an option that takes a parameter  is  repeated,  the
     last  occurrence  controls.   If present, the set of region options must be
     terminated with a semicolon ([1m;[22m).

     Any of the [1mallbox[22m, [1mbox[22m, [1mdoublebox[22m, [1mframe[22m, and  [1mdoubleframe  [22mregion  options
     makes a table “boxed” for the purpose of later discussion.

     [1mallbox           [22mEnclose each table entry in a box; implies [1mbox[22m.

     [1mbox              [22mEnclose  the entire table region in a box.  GNU [4mtbl[24m recog‐
                      nizes [1mframe [22mas a synonym.

     [1mcenter           [22mCenter the table region with respect to the  line  length,
                      reducing  the  indentation if necessary (with a warning at
                      formatting time) to make the table region fit; the default
                      is to left‐align it.  GNU [4mtbl[24m recognizes [1mcentre [22mas a  syn‐
                      onym.

     [1mdecimalpoint([4m[22mc[24m[1m)  [22mRecognize  character [4mc[24m as the decimal separator in columns
                      using the [1mN [22m(numeric) classifier (see  subsection  “Column
                      classifiers” below).  This is a GNU extension.

     [1mdelim([4m[22mxy[24m[1m)        [22mRecognize  characters [4mx[24m and [4my[24m as start and end delimiters,
                      respectively, for ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\ input, and ignore  input  between
                      them.  [4mx[24m and [4my[24m need not be distinct.

     [1mdoublebox        [22mEnclose  the  entire table region in a double box; implies
                      [1mbox[22m.  GNU [4mtbl[24m recognizes [1mdoubleframe [22mas a synonym.

     [1mexpand           [22mSpread the table horizontally to fill the available  space
                      (line length minus indentation) by increasing column sepa‐
                      ration.   Ordinarily, a table is made only as wide as nec‐
                      essary to accommodate the widths of its  entries  and  its
                      column  separations  (whether specified or default).  When
                      [1mexpand [22mapplies to a table that exceeds the available hori‐
                      zontal space, [4mtbl[24m reduces column separation as far as nec‐
                      essary (even to zero).  [4mtbl[24m produces [4mtroff[24m input that  is‐
                      sues  a diagnostic if such compression occurs.  The column
                      modifier [1mx [22m(see below) overrides this option.

     [1mlinesize([4m[22mn[24m[1m)      [22mDraw lines or rules (e.g., from [1mbox[22m) with a  thickness  of
                      [4mn[24m  points.   The default is the current type size when the
                      region begins.  This option has no effect on terminal  de‐
                      vices.

     [1mnokeep           [22mDon’t  use  [4mroff[24m  diversions  to manage page breaks.  Nor‐
                      mally, [4mtbl[24m employs them to avoid breaking a page within  a
                      table  row.   This usage can sometimes interact badly with
                      macro packages’ own use of diversions——when footnotes, for
                      example, are employed.  This is a GNU extension.

     [1mnospaces         [22mIgnore leading and trailing spaces in table entries.  This
                      is a GNU extension.

     [1mnowarn           [22mSuppress diagnostic messages produced at document  format‐
                      ting  time  when  the  line length and indentation or page
                      length is inadequate to contain a table row.   This  is  a
                      GNU extension.

     [1mtab([4m[22mc[24m[1m)           [22mUse  the  character [4mc[24m instead of a tab to separate entries
                      in a row of table data.

   [1mTable format specification[0m
     The table format specification is mandatory: it determines  the  number  of
     columns  in the table and directs how the entries within it are to be type‐
     set.  The format specification is a series of column [4mdescriptors.[24m  Each de‐
     scriptor encodes a [4mclassifier[24m followed by zero or more [4mmodifiers.[24m   Classi‐
     fiers  are  letters (recognized case‐insensitively) or punctuation symbols;
     modifiers consist of or begin with letters or numerals.  Spaces, tabs, new‐
     lines, and commas separate descriptors.  Newlines and commas apply the  de‐
     scriptors  following them to a subsequent row of the table (enabling column
     headings to be centered or emboldened while the table entries for the  data
     are  not, for instance).  We term the resulting group of column descriptors
     a [4mrow[24m [4mdefinition.[24m  Within a row definition, separation between  column  de‐
     scriptors  by  spaces  or  tabs is often optional; only some modifiers, de‐
     scribed below, make separation necessary.

     The classifier selects from one of several  arrangements.   Some  determine
     the positioning of table entries within a rectangular cell: centered, left‐
     aligned,  numeric (aligned to a configurable decimal separator), and so on.
     Others perform special operations like drawing lines  or  spanning  entries
     from  adjacent  cells  in the table.  Except for “[1m|[22m”, any classifier can be
     followed by one or more [4mmodifiers;[24m some of these accept an argument,  which
     in  GNU  [4mtbl[24m  can  be  parenthesized.  Modifiers select fonts, set the type
     size, and perform other tasks described below.

     The format specification can occupy multiple input lines, but must conclude
     with a dot “[1m.[22m” followed by a newline.  Each row definition applies in  turn
     to  one  row  of the table.  [4mtbl[24m applies the last row definition to rows of
     table data in excess of the row definitions.

     For clarity in this document’s examples, we write classifiers in  uppercase
     and  modifiers  in  lowercase.   Thus,  “[1mCbCb,LR.[22m”  defines two rows of two
     columns.  The first row’s entries are centered and  boldfaced;  the  second
     and any further rows’ first and second columns are left‐ and right‐aligned,
     respectively.  Any rows of entries appended to the table data reuse the row
     definition “[1mLR[22m”.

     The  row  definition with the most column descriptors determines the number
     of columns in the table; any row definition with fewer, GNU [4mtbl[24m  implicitly
     extends  on  the right‐hand side with [1mL [22mdescriptors as many times as neces‐
     sary to make the table rectangular.

   [1mColumn classifiers[0m
     The [1mL[22m, [1mR[22m, and [1mC [22mclassifiers are the easiest to understand and use.

     [1mA[22m, [1ma   [22mCenter longest entry in this column, left‐align remaining entries in
            the column with respect to the centered entry, then indent  all  en‐
            tries  by  one en.  Such “alphabetic” entries (hence the name of the
            classifier) can be used in the same column as [1mL[22m‐classified  entries,
            as in “[1mLL,AR.[22m”.  The [1mA [22mentries are often termed “sub‐columns” due to
            their indentation.

     [1mC[22m, [1mc   [22mCenter entry within the column.

     [1mL[22m, [1ml   [22mLeft‐align entry within the column.

     [1mN[22m, [1mn   [22mNumerically  align entry in the column.  [4mtbl[24m aligns columns of deci‐
            mal numbers vertically at the units place.  If multiple decimal sep‐
            arators are adjacent to a digit, it uses the rightmost one for  ver‐
            tical  alignment.   If  there  is no decimal separator, [4mtbl[24m uses the
            rightmost digit for vertical alignment; if no  digits  are  present,
            [4mtbl[24m  centers  the entry within the column.  The [4mroff[24m dummy character
            [1m\& [22min an entry marks the glyph preceding it (if any)  as  the  units
            place;  if  multiple instances occur in the data, [4mtbl[24m uses the left‐
            most for alignment.

            If [1mN[22m‐classified entries share a column with [1mL [22mor [1mR [22mentries, [4mtbl[24m cen‐
            ters the widest [1mN [22mentry with respect to the widest  [1mL  [22mor  [1mR  [22mentry,
            preserving the alignment of [1mN [22mentries with respect to each other.

            Decimal  separators in [4meqn[24m equations within [1mN[22m‐classified columns can
            conflict with [4mtbl[24m’s use of them for alignment.   Specify  the  [1mdelim[0m
            region option to make [4mtbl[24m ignore the data within [4meqn[24m delimiters.

     [1mR[22m, [1mr   [22mRight‐align entry within the column.

     [1mS[22m, [1ms   [22mSpan previous entry on the left into this column.

     [1m^      [22mSpan entry in the same column from the previous row into this row.

     [1m_[22m, [1m-   [22mReplace  table  entry  with a horizontal rule.  [4mtbl[24m expects an empty
            table entry to correspond to this  classifier;  if  data  are  found
            there, it issues a diagnostic message.  If the entire row definition
            consists of these classifiers (only one is necessary), it is treated
            as a “[1m_[22m” occupying a row of table entries, and no corresponding data
            are expected.

     [1m=      [22mReplace  table  entry with a double horizontal rule.  [4mtbl[24m expects an
            empty table entry to correspond to  this  classifier;  if  data  are
            found there, it issues a diagnostic message.  If the entire row def‐
            inition consists of these classifiers (only one is necessary), it is
            treated  as  a  “[1m=[22m”  occupying a row of table entries, and no corre‐
            sponding data are expected.

     [1m|      [22mPlace a vertical rule (line) on the corresponding row of  the  table
            (if  two of these are adjacent, a double vertical rule).  This clas‐
            sifier does not contribute to the column count and no table  entries
            correspond to it.  A [1m| [22mto the left of the first column descriptor or
            to the right of the last one produces a vertical rule at the edge of
            the table; these are redundant (and ignored) in boxed tables.

     To  change  the  table format within a [4mtbl[24m region, use the [1m.T& [22mtoken at the
     start of a line.  Follow it with a format specification and table data, but
     [4mnot[24m region options.  The quantity of columns in a  format  thus  introduced
     cannot increase relative to the previous format; in that case, you must end
     the table region and start another.  If that will not serve because the re‐
     gion  uses  box  options or the columns align in an undesirable manner, you
     must design the initial table format specification to include  the  maximum
     quantity  of columns required, and use the [1mS [22mhorizontal spanning classifier
     where necessary to achieve the desired columnar alignment.

     Spanning horizontally in the first column or vertically on the first row is
     an error.  [4mtbl[24m does not support non‐rectangular span areas.

   [1mColumn modifiers[0m
     Any number of modifiers can follow a  column  classifier.   Modifier  argu‐
     ments,  where  accepted, are case‐sensitive.  If you apply a given modifier
     to a classifier more than once, or apply conflicting  modifiers,  only  the
     last  occurrence  has  effect.  The modifier [1mx [22mis mutually exclusive with [1me[0m
     and [1mw[22m, but [1me [22mis not mutually exclusive with [1mw[22m; if these are used in  combi‐
     nation, [1mx [22munsets both [1me [22mand [1mw[22m, while either [1me [22mor [1mw [22moverrides [1mx[22m.

     [1mb[22m, [1mB   [22mTypeset entry in boldface, abbreviating [1mf(B)[22m.

     [1md[22m, [1mD   [22mAlign  a  vertically spanned table entry to the bottom (“down”), in‐
            stead of the center, of its range.  This is a GNU extension.

     [1me[22m, [1mE   [22mEqualize the widths of columns with this modifier  to  that  of  the
            widest.   This  modifier sets the default line length used in a text
            block.

     [1mf[22m, [1mF   [22mSelect the typeface for the table entry.  A font or style name  (one
            or two characters not starting with a digit), font mounting position
            (a  single  digit),  or a name or mounting position of any length in
            parentheses, must follow.  The last form is a GNU  extension.   (The
            parameter  corresponds to that accepted by the [4mtroff[24m [1mft [22mrequest.)  A
            one‐character argument not in parentheses must end the row  descrip‐
            tion  or  be  separated by one or more spaces or tabs from what fol‐
            lows.

     [1mi[22m, [1mI   [22mTypeset entry in an oblique or italic face, abbreviating [1mf(I)[22m.

     [1mm[22m, [1mM   [22mCall a [4mgroff[24m macro before typesetting a text block  (see  subsection
            “Text blocks” below).  This is a GNU extension.  A macro name of one
            or two characters, or a name of any length in parentheses, must fol‐
            low.   A  one‐character  macro name not in parentheses must be sepa‐
            rated by one or more spaces or tabs from what  follows.   The  named
            macro must be defined before the table region containing this column
            modifier is encountered.  The macro should contain only simple [4mgroff[0m
            requests  to change text formatting, like adjustment or hyphenation.
            The macro is called [4mafter[24m the column modifiers [1mb[22m, [1mf[22m,  [1mi[22m,  [1mp[22m,  and  [1mv[0m
            take effect; it can thus override other column modifiers.

     [1mp[22m, [1mP   [22mSet  the type size.  An integer [4mn[24m with an optional leading sign must
            follow.  If unsigned, the type size is set to [4mn[24m points.   Otherwise,
            the  type  size  is  incremented  or  decremented  per  the  sign by
            [4mn[24m points.  The use of a signed multi‐digit number is  a  GNU  exten‐
            sion.   (The  parameter corresponds to that accepted by the [4mtroff[24m [1mps[0m
            request.)  If a type size modifier is followed by a  column  separa‐
            tion  modifier  (see  below), they must be separated by at least one
            space or tab.

     [1mt[22m, [1mT   [22mAlign a vertically spanned table entry to the top,  instead  of  the
            center, of its range.

     [1mu[22m, [1mU   [22mMove  the column up one half‐line, “staggering” the rows.  This is a
            Documenter’s Workbench (DWB) 1.0 and Research Tenth Edition Unix ex‐
            tension.

     [1mv[22m, [1mV   [22mSet the vertical spacing of a text block.  An integer [4mn[24m with an  op‐
            tional  leading sign must follow.  If unsigned, the vertical spacing
            is set to [4mn[24m points.  Otherwise, the vertical spacing is  incremented
            or decremented per the sign by [4mn[24m points.  The use of a signed multi‐
            digit  number  is  a  GNU extension.  (This parameter corresponds to
            that accepted by the [4mtroff[24m [1mvs [22mrequest.)  If a vertical spacing modi‐
            fier is followed by a column separation modifier (see  below),  they
            must be separated by at least one space or tab.

     [1mw[22m, [1mW   [22mSet  the  column’s minimum width.  A number, either a unitless inte‐
            ger, or a [4mroff[24m horizontal measurement in parentheses,  must  follow.
            Parentheses  are required if the width is to be followed immediately
            by an explicit column separation (alternatively,  follow  the  width
            with  one or more spaces or tabs).  If no unit is specified, ens are
            assumed.  This modifier sets the default line length used in a  text
            block.

     [1mx[22m, [1mX   [22mExpand  the  column.   After computing the column widths, distribute
            any remaining line length evenly over all columns bearing this modi‐
            fier.  This is a Documenter’s Workbench (DWB) 3.3 extension.  Apply‐
            ing the [1mx [22mmodifier to more than one column is a GNU extension.  This
            modifier sets the default line length used in a text block.

     [1mz[22m, [1mZ   [22mIgnore the table entries corresponding to this column for width cal‐
            culation purposes; that is, compute the column’s  width  using  only
            the information in its descriptor.  This is a Documenter’s Workbench
            (DWB) 1.0 and Research Tenth Edition Unix extension.

     [4mn[24m      A numeric suffix on a column descriptor sets the separation distance
            (in  ens)  from the succeeding column; the default separation is [1m3n[22m.
            This separation is proportionally multiplied if  the  [1mexpand  [22mregion
            option  is  in  effect;  in the case of tables wider than the output
            line length, this separation might be zero.  A  negative  separation
            cannot be specified.  A separation amount after the last column in a
            row is nonsensical and provokes a diagnostic from [4mtbl[24m.

   [1mTable data[0m
     Place  table  data on lines after the format specification.  Each text line
     corresponds to a table row, except that a backslash at the end of a line of
     table data continues an entry on the next input line.  (Text  blocks,  dis‐
     cussed  below, also spread table entries across multiple input lines.)  Ta‐
     ble entries within a row are separated in the input by a tab  character  by
     default; see the [1mtab [22mregion option above.  Excess entries in a row of table
     data  (those  that have no corresponding column descriptor, not even an im‐
     plicit one arising from rectangularization of the table), [4mtbl[24m discards with
     a diagnostic message.  [4mtbl[24m passes [4mroff[24m control lines through  unaltered  to
     its  output.  If you wish to visibly mark an empty table entry in the docu‐
     ment source, populate it with the [1m\& [4m[22mroff[24m dummy character.  The table  data
     are  interrupted  by a line consisting of the [1m.T& [22minput token, and conclude
     with the line [1m.TE[22m.

     Ordinarily, a table entry is typeset rigidly.  It is  not  filled,  broken,
     hyphenated,  adjusted, or populated with supplemental inter‐sentence space.
     [4mtbl[24m instructs the formatter to measure each table entry as it occurs in the
     input, updating the width required by its corresponding column.  If  the  [1mz[0m
     modifier  applies  to  the entry, this measurement is ignored; if [1mw [22mapplies
     and its argument is larger than this width, that argument is used  instead.
     In  contrast  to conventional [4mroff[24m input (within a paragraph, say), changes
     to text formatting, such as font selection or vertical spacing, do not per‐
     sist between entries.

     [4mtbl[24m interprets several forms of table entry specially.

     •  If a table row contains only an underscore or equals sign ([1m_ [22mor [1m=[22m),  [4mtbl[0m
        draws  a a single or double horizontal rule (line), respectively, across
        the table at that point.

     •  If a table entry contains only [1m_ [22mor [1m= [22mon an otherwise populated row, [4mtbl[0m
        populates its cell with a single  or  double  horizontal  rule,  respec‐
        tively, that joins its neighbors.

     •  If  a  table entry contains only [1m\_ [22mor [1m\= [22mon an otherwise populated row,
        [4mtbl[24m populates its cell with a single or double horizontal rule,  respec‐
        tively, that does [4mnot[24m (quite) join its neighbors.

     •  If  a  table entry contains only [1m\R[4m[22mx[24m, where [4mx[24m is any [4mroff[24m ordinary, spe‐
        cial, or indexed character, [4mtbl[24m populates its cell with  enough  repeti‐
        tions of the glyph corresponding to [4mx[24m to fill the column without joining
        its neighbors.

     •  On  any row but the first, a table entry of [1m\^ [22mcauses the entry above it
        to span down into the current one.

     On occasion, these special tokens may be required as  literal  table  data.
     To  use  either [1m_ [22mor [1m= [22mliterally and alone in an entry, prefix or suffix it
     with the [4mroff[24m dummy character [1m\&[22m.  To express [1m\_[22m, [1m\=[22m, or [1m\R[22m, use a [4mroff[24m es‐
     cape sequence to interpolate the backslash ([1m\e [22mor [1m\[rs][22m).  A  reliable  way
     to  emplace  the [1m\^ [22mglyph sequence within a table entry is to use a pair of
     [4mgroff[24m special character escape sequences ([1m\[rs]\[ha][22m).

     Rows of table entries can be interleaved with [4mgroff[24m control lines; these do
     not count as table data.  On such lines the default control  character  ([1m.[22m)
     must  be used (and not changed); the no‐break control character is not rec‐
     ognized.  To start the first table entry in a row with a  dot,  precede  it
     with the [4mroff[24m dummy character [1m\&[22m.

   [1mText blocks[0m
     An ordinary table entry’s contents can make a column, and therefore the ta‐
     ble,  too wide; the table then exceeds the line length of the page, and be‐
     comes ugly or is exposed to truncation by the output device.  When a  table
     entry requires more conventional typesetting, breaking across more than one
     output  line  (and  thereby  increasing  the  height of its row), it can be
     placed within a [4mtext[24m [4mblock.[0m

     [4mtbl[24m interprets a table entry of “[1mT{[22m” at the end of an input line specially,
     as a token starting a text block.  Similarly, an entry “[1mT}[22m” at the start of
     an input line ends a text block.  Text block tokens can share an input line
     with other table data (preceding [1mT{ [22mand following [1mT}[22m).  Input lines between
     these tokens are formatted in a diversion by [4mtroff[24m.  Text blocks cannot  be
     nested.  Multiple text blocks can occur in a table row.

     Text  blocks  are formatted as was the text prior to the table, modified by
     applicable column descriptors.  Specifically, the classifiers [1mA[22m, [1mC[22m,  [1mL[22m,  [1mN[22m,
     [1mR[22m,  and  [1mS  [22mdetermine a text block’s [4malignment[24m within its cell, but not its
     [4madjustment.[24m  Add [1mna [22mor [1mad [22mrequests to the beginning of a text block to  al‐
     ter  its  adjustment  distinctly  from other text in the document.  As with
     other table entries, when a text block ends, any alterations to  formatting
     parameters are discarded.  They do not affect subsequent table entries, not
     even other text blocks.

     If  [1mw  [22mor  [1mx  [22mmodifiers are not specified for [4mall[24m columns of a text block’s
     span, the default length of the text block (more precisely, the line length
     used to process the text block’s diversion) is computed as [4mL[24m×[4mC[24m/([4mN[24m+1), where
     [4mL[24m is the current line length, [4mC[24m the number of columns spanned by  the  text
     block,  and  [4mN[24m  the  number of columns in the table.  If necessary, you can
     also control a text block’s width by including an [1mll [22m(line length)  request
     in  it  prior to any text to be formatted.  Because [4mtbl[24m uses a diversion to
     format the text block, its height and width are subsequently  available  in
     the [4mtroff[24m registers [1mdn [22mand [1mdl[22m, respectively.

   [4m[1mroff[24m interface[0m
     The  register  [1mTW  [22mstores  the width of the table region in basic units; it
     can’t be used within the region itself, but is defined before the [1m.TE [22mtoken
     is output so that a [4mtroff[24m macro named [1mTE [22mcan make use of  it.   “[1mT.[22m”  is  a
     Boolean‐valued register indicating whether the bottom of the table is being
     processed.   A [1m#T [22mregister is used internally.  Avoid using these names for
     any other purpose.

     [4mtbl[24m also defines a macro [1mT# [22mto produce the bottom and side lines of a boxed
     table.  While [4mtbl[24m itself arranges for the output to include a call of  this
     macro  at the end of such a table, it can also be used by macro packages to
     create boxes for multi‐page tables by calling it from a page  footer  macro
     that  is  itself called by a trap planted near the bottom of the page.  See
     section “Limitations” below for more on multi‐page tables.

     GNU [4mtbl[24m internally employs register, string, macro, and diversion names be‐
     ginning with the numeral [1m3[22m.  A document to be  preprocessed  with  GNU  [4mtbl[0m
     should not use any such identifiers.

   [1mInteraction with [4meqn[0m
     Process  a  document  with  [4mtbl[24m  before  ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\.   (]8;;man:groff(1)\[4mgroff[24m(1)]8;;\  automatically
     arranges preprocessors in the correct order.)  Don’t call  the  [1mEQ  [22mand  [1mEN[0m
     macros  within tables; instead, set up delimiters in your [4meqn[24m input and use
     the [1mdelim [22mregion option so that [4mtbl[24m will recognize them.

   [1mGNU [4mtbl[24m enhancements[0m
     In addition to extensions noted above, GNU [4mtbl[24m removes constraints  endured
     by users of AT&T [4mtbl[24m.

     •  Region options can be specified in any lettercase.

     •  There  is  no  limit  on the number of columns in a table, regardless of
        their classification, nor any limit on the number of text blocks.

     •  GNU [4mtbl[24m considers all table rows when computing column widths, not  just
        those occurring in the first 200 input lines of a region.  Similarly, it
        recognizes  table continuation tokens ([1m.T&[22m) outside a region’s first 200
        input lines.

     •  Numeric and alphabetic entries may appear in the same column.

     •  Numeric and alphabetic entries may span horizontally.

   [1mUsing GNU [4mtbl[24m within macros[0m
     You can embed a table region inside a macro definition.  However, since [4mtbl[0m
     writes its own macro definitions at the beginning of each table region,  it
     is  necessary  to  call end macros instead of ending macro definitions with
     “[1m..[22m”.  Additionally, the escape character must be disabled.

     Not all [4mtbl[24m features can be exercised from such macros  because  [4mtbl[24m  is  a
     [4mroff[24m preprocessor: it sees the input earlier than [4mtroff[24m does.  For example,
     vertically aligning decimal separators fails if the numbers containing them
     occur  as macro or string parameters; the alignment is performed by [4mtbl[24m it‐
     self, which sees only [1m\$1[22m, [1m\$2[22m, and so on, and therefore can’t recognize  a
     decimal  separator  that appears only later when [4mtroff[24m interpolates a macro
     or string definition.

     Using [4mtbl[24m macros within conditional input (that is, contingent upon an  [1mif[22m,
     [1mie[22m,  [1mel[22m,  or [1mwhile [22mrequest) can result in misleading line numbers in subse‐
     quent diagnostics.  [4mtbl[24m unconditionally injects its output into the  source
     document, but the conditional branch containing it may not be taken, and if
     it is not, the [1mlf [22mrequests that [4mtbl[24m injects to restore the source line num‐
     ber  cannot  take effect.  Consider copying the input line counter register
     “[1mc.[22m” and restoring its value at  a  convenient  location  after  applicable
     arithmetic.

[1mOptions[0m
     [1m--help [22mdisplays a usage message, while [1m-v [22mand [1m--version [22mshow version infor‐
     mation; all exit afterward.

     [1m-C     [22mEnable AT&T compatibility mode: recognize [1m.TS [22mand [1m.TE [22meven when fol‐
            lowed  by a character other than space or newline, and interpret the
            copy‐mode leader escape sequence [1m\a [22mas a leader character.

[1mExit status[0m
     [4mtbl[24m exits with status [1m0 [22mon successful operation, status [1m2  [22mif  the  program
     cannot  interpret its command‐line arguments, and status [1m1 [22mif it encounters
     an error during operation.

[1mLimitations[0m
     Within a [4mtbl[24m region (except in text blocks or on [4mroff[24m control lines), avoid
     escape sequences that read the rest of the input line, as [1m\" [22mand [1m\! [22mdo.

     Multi‐page tables, if boxed and/or if you want their  column  headings  re‐
     peated  after page breaks, require support at the time the document is for‐
     matted.  A convention for such support has arisen in macro packages such as
     [4mms[24m, [4mmm[24m, and [4mme[24m.  To use it, follow the [1m.TS [22mtoken with a space and then “[1mH[22m”;
     this will be interpreted by the formatter as a [1mTS [22mmacro call with an [1mH  [22mar‐
     gument.   Then,  within the table data, call the [1mTH [22mmacro; this informs the
     macro package where the headings end.  If your table has  no  such  heading
     rows,  or you do not desire their repetition, call [1mTH [22mimmediately after the
     table format specification.  If a multi‐page table is boxed or has  repeat‐
     ing  column headings, do not enclose it with keep/release macros, or divert
     it in any other way.  Further, the [1mbp [22mrequest will not cause a  page  break
     in  a “[1mTS H[22m” table.  Define a macro to wrap [1mbp[22m: invoke it normally if there
     is no current diversion.  Otherwise, pass the macro call to  the  enclosing
     diversion  using the transparent line escape sequence [1m\![22m; this will “bubble
     up” the page break to the output device.  See section “Examples” below  for
     a demonstration.

     ]8;;man:grotty(1)\[4mgrotty[24m(1)]8;;\  does  not  support double horizontal rules; it uses single rules
     instead.  It also ignores half‐line motions, so the [1mu [22mcolumn  modifier  has
     no  effect.   On  terminal devices (“[4mnroff[24m mode”), horizontal rules and box
     borders occupy a full vee of space; [1mdoublebox  [22mdoubles  that  for  borders.
     Tables  using these features thus require more vertical space in [4mnroff[24m mode
     than in [4mtroff[24m mode: write [1mne [22mrequests accordingly.  Vertical rules  between
     columns  are drawn in the space between columns in [4mnroff[24m mode; using double
     vertical rules and/or reducing the column separation below the default  can
     make them ugly or overstrike them with table data.

     A text block within a table must be able to fit on one page.

     Using  [1m\a  [22mto put leaders in table entries does not work in GNU [4mtbl[24m, except
     in compatibility mode.  This is correct behavior: [1m\a  [22mis  an  [4muninterpreted[0m
     leader.   You can still use the [4mroff[24m leader character (Control+A) or define
     a string to use [1m\a [22mas it was designed: to be interpreted only in copy mode.

            .ds a \a
            .TS
            box center tab(;);
            Lw(2i)0 L.
            Population\*a;6,327,119
            .TE

                         ┌───────────────────────────────┐
                         │ Population..........6,327,119 │
                         └───────────────────────────────┘

     A leading or trailing “[1m|[22m” in a format specification, as in  “[1m|LCR|.[22m”,  pro‐
     duces  an  en  space between the rules and the content of adjacent columns.
     If such space is undesired (the rule should abut the content), you can  in‐
     troduce  “dummy” columns with zero separation and empty corresponding table
     entries before and/or after.

            .TS
            center tab(#);
            R0|L C R0|L.
            _
            #levulose#glucose#dextrose#
            _
            .TE

     These dummy columns have zero width and are therefore  invisible;  unfortu‐
     nately they usually don’t work as intended on terminal devices.

[1mExamples[0m
     It  can be easier to acquire the language of [4mtbl[24m through examples than for‐
     mal description, especially at first.

            .TS
            box center tab(#);
            Cb Cb
            L  L.
            Ability#Application
            Strength#crushes a tomato
            Dexterity#dodges a thrown tomato
            Constitution#eats a month‐old tomato without becoming ill
            Intelligence#knows that a tomato is a fruit
            Wisdom#chooses \f[I]not\f[] to put tomato in a fruit salad
            Charisma#sells tomato‐based fruit salads to hypercarnivores
            .TE

       ┌───────────────────────────────────────────────────────────────────┐
       │   [1mAbility                         Application                     [22m│
       │ Strength       crushes a tomato                                   │
       │ Dexterity      dodges a thrown tomato                             │
       │ Constitution   eats a month‐old tomato without becoming ill       │
       │ Intelligence   knows that a tomato is a fruit                     │
       │ Wisdom         chooses [4mnot[24m to put tomato in a fruit salad         │
       │ Charisma       sells tomato‐based fruit salads to hypercarnivores │
       └───────────────────────────────────────────────────────────────────┘

     The [1mA [22mand [1mN [22mcolumn classifiers can be easier to grasp in  visual  rendering
     than in description.

            .TS
            center tab(;);
            CbS,LN,AN.
            Daily energy intake (in MJ)
            Macronutrients
            .\" assume 3 significant figures of precision
            Carbohydrates;4.5
            Fats;2.25
            Protein;3
            .T&
            LN,AN.
            Mineral
            Pu-239;14.6
            _
            .T&
            LN.
            Total;\[ti]24.4
            .TE

                                [1mDaily energy intake (in MJ)[0m
                                Macronutrients
                                  Carbohydrates       4.5
                                  Fats                2.25
                                  Protein             3
                                Mineral
                                  Pu‐239             14.6
                                ────────────────────────────
                                Total               ~24.4

     Next,  we’ll  lightly  adapt  a  compact presentation of spanning, vertical
     alignment, and zero‐width column modifiers from the  [4mmandoc[24m  reference  for
     its [4mtbl[24m interpreter.  It rewards close study.

            .TS
            box center tab(:);
            Lz  S | Rt
            Ld| Cb| ^
            ^ | Rz  S.
            left:r
            l:center:
            :right
            .TE

                                    ┌────────────┬───┐
                                    │ le│ft       │ r │
                                    │   │ [1mcenter [22m│   │
                                    │ l │      right │
                                    └───┴────────────┘

     Row  staggering is not visually achievable on terminal devices, but a table
     using it can remain comprehensible nonetheless.

            .TS
            center tab(|);
            Cf(BI) Cf(BI) Cf(B), C C Cu.
            n|n\f[B]\[tmu]\f[]n|difference
            1|1
            2|4|3
            3|9|5
            4|16|7
            5|25|9
            6|36|11
            .TE

                                    [4m[1mn[24m   [4mn[24m×[4mn[24m   difference[0m
                                    1    1
                                    2    4        3
                                    3    9        5
                                    4   16        7
                                    5   25        9
                                    6   36        11

     Some [4mtbl[24m features cannot be illustrated in the  limited  environment  of  a
     portable man page.

     We  can define a macro outside of a [4mtbl[24m region that we can call from within
     it to cause a page break inside a multi‐page boxed table.  You can choose a
     different name; be sure to change both occurrences of “BP”.

            .de BP
            .  ie '\\n(.z'' .bp \\$1
            .  el \!.BP \\$1
            ..

[1mSee also[0m
     “Tbl——A Program to Format Tables”, by M. E. Lesk, 1976 (revised 16  January
     1979), AT&T Bell Laboratories Computing Science Technical Report No. 49.

     The spanning example above was taken from ]8;;https://man.openbsd.org/tbl.7\[4mmandoc[24m’s man page for its [4mtbl[24m im‐
     plementation]8;;\.

     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\

groff 1.24.1                       2026‐03‐20                             [4mtbl[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mtfmtodit[24m(1)                  General Commands Manual                 [4mtfmtodit[24m(1)

[1mName[0m
     tfmtodit - adapt TeX Font Metrics files for use with [4mgroff[24m and [4mgrodvi[0m

[1mSynopsis[0m
     [1mtfmtodit [22m[[1m-s[22m] [[1m-g [4m[22mgf‐file[24m] [[1m-k [4m[22mskew‐char[24m] [4mtfm‐file[24m [4mmap‐file[24m [4mfont‐[0m
              [4mdescription[0m

     [1mtfmtodit --help[0m

     [1mtfmtodit -v[0m
     [1mtfmtodit --version[0m

[1mDescription[0m
     [4mtfmtodit[24m creates a font description file for use with ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\’s [1mdvi [22moutput
     device.   [4mtfm‐file[24m  is  the  name of the TeX font metric file for the font.
     [4mmap‐file[24m assigns [4mgroff[24m ordinary or special character identifiers  to  glyph
     indices in the font; it should consist of a sequence of lines of the form
            [4mi[24m [4mc1[24m ... [4mcn[0m
     where  [4mi[24m  is a position of the glyph in the font in decimal, and [4mc1[24m through
     [4mcn[24m are glyph identifiers in the form used by [4mgroff[24m font descriptions.  If a
     glyph has no [4mgroff[24m names but exists in [4mtfm‐file,[24m it is  put  in  the  [4mgroff[0m
     font   description  file  as  an  unnamed  glyph.   Output  is  written  in
     ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\ format to [4mfont‐description,[24m a file  named  for  the  intended
     [4mgroff[24m font name.

     If  the  font  is “special”, meaning that [4mgroff[24m should search it whenever a
     glyph is not found in the current font, use the [1m-s [22moption and name [4mfont‐de‐[0m
     [4mscription[24m in the [1mfonts [22mdirective in the output device’s [4mDESC[24m file.

     To do a good job of math typesetting, [4mgroff[24m requires font  metric  informa‐
     tion not present in [4mtfm‐file.[24m  This is because TeX has separate math italic
     fonts, whereas [4mgroff[24m uses normal italic fonts for math.  The additional in‐
     formation  required  by [4mgroff[24m is given by the two arguments to the [1mmath_fit[0m
     macro in the Metafont programs for the Computer Modern fonts.   In  a  text
     font  (a font for which [1mmath_fit [22mis false), Metafont normally ignores these
     two arguments.  Metafont can be made to put this information  into  the  GF
     (“generic  font”) files it produces by loading the following definition af‐
     ter [1mcmbase [22mwhen creating [4mcm.base[24m.
            def ignore_math_fit(expr left_adjustment,right_adjustment) =
                special "adjustment";
                numspecial left_adjustment*16/designsize;
                numspecial right_adjustment*16/designsize;
                enddef;
     For the EC font family, load the following definition  after  [1mexbase[22m;  con‐
     sider patching [4mexbase.mf[24m locally.
            def ignore_math_fit(expr left_adjustment,right_adjustment) =
                ori_special "adjustment";
                ori_numspecial left_adjustment*16/designsize;
                ori_numspecial right_adjustment*16/designsize;
                enddef;
     The only difference from the previous example is the “ori_” prefix to “spe‐
     cial” and “numspecial”.  The GF file created using this modified [4mcm.base[24m or
     [4mexbase.mf[24m should be specified with the [1m-g [22moption, which should [4mnot[24m be given
     for a font for which [1mmath_fit [22mis true.

[1mOptions[0m
     [1m--help [22mdisplays a usage message, while [1m-v [22mand [1m--version [22mshow version infor‐
     mation; all exit afterward.

     [1m-g [4m[22mgf‐file[0m
            Use  the [4mgf‐file[24m produced by Metafont containing “[1mspecial[22m” and “[1mnum‐[0m
            [1mspecial[22m” commands to obtain additional font metric information.

     [1m-k [4m[22mskew‐char[0m
            The skew character of this font is at position [4mskew‐char.[24m  [4mskew‐char[0m
            should be an integer; it may be given in decimal, with a  leading  0
            in octal, or with a leading 0x in hexadecimal.  Any kerns whose sec‐
            ond component is [4mskew‐char[24m are ignored.

     [1m-s     [22mAdd the [1mspecial [22mdirective to the font description file.

[1mExit status[0m
     [4mtfmtodit[24m  exits with status [1m0 [22mon successful operation, status [1m2 [22mif the pro‐
     gram cannot interpret its command‐line arguments, and status [1m1  [22mif  it  en‐
     counters an error during operation.

[1mFiles[0m
     [4m/usr/share/groff/1.24.1/font/devdvi/DESC[0m
            describes the [1mdvi [22moutput device.

     [4m/usr/share/groff/1.24.1/font/devdvi/[24mF
            describes the font known as [4mF[24m on device [1mdvi[22m.

     [4m/usr/share/groff/1.24.1/font/devdvi/generate/ec.map[0m
     [4m/usr/share/groff/1.24.1/font/devdvi/generate/msam.map[0m
     [4m/usr/share/groff/1.24.1/font/devdvi/generate/msbm.map[0m
     [4m/usr/share/groff/1.24.1/font/devdvi/generate/tc.map[0m
     [4m/usr/share/groff/1.24.1/font/devdvi/generate/texb.map[0m
     [4m/usr/share/groff/1.24.1/font/devdvi/generate/texex.map[0m
     [4m/usr/share/groff/1.24.1/font/devdvi/generate/texi.map[0m
     [4m/usr/share/groff/1.24.1/font/devdvi/generate/texitt.map[0m
     [4m/usr/share/groff/1.24.1/font/devdvi/generate/texmi.map[0m
     [4m/usr/share/groff/1.24.1/font/devdvi/generate/texr.map[0m
     [4m/usr/share/groff/1.24.1/font/devdvi/generate/texsy.map[0m
     [4m/usr/share/groff/1.24.1/font/devdvi/generate/textex.map[0m
     [4m/usr/share/groff/1.24.1/font/devdvi/generate/textt.map[0m
            map glyph indices in TeX fonts to [4mgroff[24m ordinary and special charac‐
            ter  identifiers.  [4mec.map[24m is used for [1mTREC[22m, [1mTIEC[22m, [1mTBEC[22m, [1mTBIEC[22m, [1mHREC[22m,
            [1mHIEC[22m, [1mHBEC[22m, [1mHBIEC[22m, [1mCWEC[22m, and [1mCWIEC[22m; [4mmsam.map[24m for  [1mSA[22m;  [4mmsbm.map[24m  for
            [1mSB[22m;  [4mtc.map[24m  for  [1mTRTC[22m,  [1mTITC[22m, [1mTBTC[22m, [1mTBITC[22m, [1mHRTC[22m, [1mHITC[22m, [1mHBTC[22m, [1mHBITC[22m,
            [1mCWTC[22m, and [1mCWITC[22m; [4mtexb.map[24m for [1mTB[22m, [1mHR[22m, [1mHI[22m, [1mHB[22m, and [1mHBI[22m; [4mtexex.map[24m for
            [1mEX[22m; [4mtexi.map[24m for [1mTI [22mand [1mTBI[22m; [4mtexitt.map[24m for [1mCWI[22m; [4mtexmi.map[24m  for  [1mMI[22m;
            [4mtexr.map[24m  for  [1mTR[22m; [4mtexsy.map[24m for [1mS[22m; [4mtextex.map[24m for [1mSC[22m; and [4mtextt.map[0m
            for [1mCW[22m.

[1mSee also[0m
     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, ]8;;man:grodvi(1)\[4mgrodvi[24m(1)]8;;\, ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\

groff 1.24.1                       2026‐03‐20                        [4mtfmtodit[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mtroff[24m(1)                     General Commands Manual                    [4mtroff[24m(1)

[1mName[0m
     troff - GNU [4mroff[24m typesetter and document formatter

[1mSynopsis[0m
     [1mtroff [22m[[1m-abcCEiRSUz[22m] [[1m-d [4m[22mctext[24m] [[1m-d [4m[22mstring[24m[1m=[4m[22mtext[24m] [[1m-f [4m[22mfont‐family[24m] [[1m-F [4m[22mfont‐[0m
           [4mdirectory[24m] [[1m-I [4m[22minclusion‐directory[24m] [[1m-m [4m[22mmacro‐package[24m] [[1m-M [4m[22mmacro‐[0m
           [4mdirectory[24m] [[1m-n [4m[22mpage‐number[24m] [[1m-o [4m[22mpage‐list[24m] [[1m-r [4m[22mcnumeric‐expression[24m]
           [[1m-r [4m[22mregister[24m[1m=[4m[22mnumeric‐expression[24m] [[1m-T [4m[22moutput‐device[24m] [[1m-w [4m[22mwarning‐[0m
           [4mcategory[24m] [[1m-W [4m[22mwarning‐category[24m] [[4mfile[24m ...]

     [1mtroff --help[0m

     [1mtroff -v[0m
     [1mtroff --version[0m

[1mDescription[0m
     GNU [4mtroff[24m transforms ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\ language input  into  the  device‐independent
     page description language detailed in ]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\; [4mtroff[24m is thus the heart
     of  the  GNU  [4mroff[24m  document  formatting  system.   If no [4mfile[24m operands are
     present, or if [4mfile[24m is “[1m-[22m”, [4mtroff[24m reads the standard input stream.

     GNU [4mtroff[24m is functionally compatible with the  AT&T  [4mtroff[24m  typesetter  and
     features  numerous extensions.  Many people prefer to use the ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ com‐
     mand, a front end which also runs preprocessors and output drivers  in  the
     appropriate order and with appropriate options.

[1mOptions[0m
     [1m-h  [22mand [1m--help [22mdisplay a usage message, while [1m-v [22mand [1m--version [22mshow version
     information; all exit afterward.

     [1m-a       [22mGenerate a plain text approximation of the  typeset  output.   The
              read‐only register [1m.A [22mis set to 1.  This option produces a sort of
              abstract preview of the formatted output.

              •  Page breaks are marked by a phrase in angle brackets; for exam‐
                 ple, “<beginning of page>”.

              •  Lines are broken where they would be in formatted output.

              •  Vertical  motion,  apart  from  that implied by a break, is not
                 represented.

              •  A horizontal motion of any size is represented  as  one  space.
                 Adjacent horizontal motions are not combined.  Supplemental in‐
                 ter‐sentence  space  (configured  by the second argument to the
                 [1m.ss [22mrequest) is not represented.

              •  A special character is rendered as its identifier between angle
                 brackets; for example, a hyphen appears as “<hy>”.

              The above description should not be  considered  a  specification;
              the details of [1m-a [22moutput are subject to change.

     [1m-b       [22mWrite  a  backtrace reporting the state of [4mtroff[24m’s input parser to
              the standard error stream with each diagnostic message.  The  line
              numbers  given  in  the backtrace might not always be correct, be‐
              cause [4mtroff[24m’s idea of line numbers can  be  confused  by  requests
              that append to macros.

     [1m-c       [22mDisable multi‐color output and “[1mcolor[22m” request’s ability to enable
              it.

     [1m-C       [22mEnable   AT&T   [4mtroff[24m   compatibility   mode;   implies  [1m-c[22m.   See
              ]8;;man:groff_diff(7)\[4mgroff_diff[24m(7)]8;;\.

     [1m-d [4m[22mctext[0m
     [1m-d [4m[22mstring[24m[1m=[4m[22mtext[0m
              Define [4mroff[24m string [4mc[24m or [4mstring[24m as [4mtext.[24m  [4mc[24m must be a one‐character
              identifier; [4mstring[24m can be of arbitrary length.   Such  assignments
              happen  before  any  macro  file  is loaded, including the startup
              file.  Due to ]8;;man:getopt_long(3)\[4mgetopt_long[24m(3)]8;;\ limitations, [4mc[24m cannot be, and  [4mstring[0m
              cannot  contain, an equals sign, even though that is a valid char‐
              acter in a [4mroff[24m identifier.

     [1m-E       [22mInhibit [4mtroff[24m error messages; implies [1m-Ww[22m.  This option  does  [4mnot[0m
              suppress  messages  sent to the standard error stream by documents
              or macro packages using [1mtm [22mor related requests.

     [1m-f [4m[22mfam[24m   Use [4mfam[24m as the default font family.

     [1m-F [4m[22mdir[24m   Search in directory [4mdir[24m for the selected output device’s directory
              of device and font description  files.   See  the  description  of
              [4mGROFF_FONT_PATH[24m  in  section  “Environment”  below for the default
              search locations and ordering.

     [1m-i       [22mRead the standard input stream after all named  input  files  have
              been processed.

     [1m-I [4m[22mdir[24m   Search  the  directory  [4mdir[24m  for files (those named on the command
              line; in [1mpsbb[22m, [1mso[22m, and [1msoquiet [22mrequests; and in “[1m\X'ps:  import'[22m”,
              “[1m\X'ps:  file'[22m”, and “[1m\X'pdf: pdfpic'[22m” device extension escape se‐
              quences).  [1m-I [22mmay  be  specified  more  than  once;  each  [4mdir[24m  is
              searched in the given order.  To search the current working direc‐
              tory  before others, add “[1m-I .[22m” at the desired place; it is other‐
              wise searched last.  [1m-I [22mworks similarly to, and is named for,  the
              “include” option of Unix C compilers.

     [1m-m [4m[22mmac[24m   Search for the macro package mac[4m.tmac[24m and read it prior to any in‐
              put.  If not found, [4mtmac.[24mmac is attempted.  See the description of
              [4mGROFF_TMAC_PATH[24m  in  section  “Environment”  below for the default
              search locations and ordering.

     [1m-M [4m[22mdir[24m   Search directory [4mdir[24m for macro  files.   See  the  description  of
              [4mGROFF_TMAC_PATH[24m  in  section  “Environment”  below for the default
              search locations and ordering.

     [1m-n [4m[22mnum[24m   Begin numbering pages at [4mnum.[24m  The default is [1m1[22m.

     [1m-o [4m[22mlist[24m  Output only pages in [4mlist,[24m which is a comma‐separated list of  in‐
              clusive  page  ranges;  [4mn[24m  means  page [4mn,[24m [4mm[24m[1m-[4m[22mn[24m means every page be‐
              tween [4mm[24m and [4mn[24m, [1m-[4m[22mn[24m means every page up to [4mn[24m,  and  [4mn[24m[1m-  [22mmeans  every
              page from [4mn[24m on.  [4mtroff[24m stops processing and exits after formatting
              the last page enumerated in [4mlist.[0m

     [1m-r [4m[22mcnumeric‐expression[0m
     [1m-r [4m[22mregister[24m[1m=[4m[22mnumeric‐expression[0m
              Define  [4mroff[24m register [4mc[24m or [4mregister[24m as [4mnumeric‐expression.[24m  [4mc[24m must
              be a  one‐character  identifier;  [4mregister[24m  can  be  of  arbitrary
              length.   Such assignments happen before any macro file is loaded,
              including the startup file.  Due  to  ]8;;man:getopt_long(3)\[4mgetopt_long[24m(3)]8;;\  limitations,
              [4mc[24m  cannot  be,  and  [4mregister[24m cannot contain, an equals sign, even
              though that is a valid character in a [4mroff[24m identifier.

     [1m-R       [22mPrevent loading of [4mtroffrc[24m and [4mtroffrc-end[24m;  this  option  can  be
              useful for troubleshooting.

     [1m-S       [22mEnable safer mode and ignore any subsequent [1m-U [22moption.

     [1m-T [4m[22mdev[24m   Prepare output for device [4mdev.[24m  The default is [1mps[22m; see ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\.

     [1m-U       [22mOperate in [4munsafe[24m [4mmode,[24m enabling the [1mcf[22m, [1mopen[22m, [1mopena[22m, [1mpi[22m, [1mpso[22m, and
              [1msy  [22mrequests,  which are disabled by default because they allow an
              untrusted input document to run arbitrary commands, put  arbitrary
              content into [4mtroff[24m output, or write to arbitrary file names.  (GNU
              [4mtroff[24m  does  not,  however,  accept  newlines (line feeds) in file
              names supplied as arguments to requests.)  This option  also  adds
              the current directory to the macro package search path; see the [1m-m[0m
              and [1m-M [22moptions above.

     [1m-w [4m[22mcat[0m
     [1m-W [4m[22mcat[24m   Enable  and  inhibit, respectively, warnings in category [4mcat.[24m  See
              section “Warnings” below.

     [1m-z       [22mSuppress formatted output.

[1mWarnings[0m
     GNU [4mtroff[24m divides its warning diagnostics into named, numbered  categories.
     The  [1m-w [22mand [1m-W [22moptions use the associated names.  A power of two character‐
     izes each category; the [1mwarn [22mrequest and the  [1m.warn  [22mregister  respectively
     set  and  report the sum of enabled category codes.  Warnings of each cate‐
     gory are produced under the following circumstances.

                ┌───────────────────────┬──────────────────────────┐
                │ Bit   Code   Category │ Bit    Code     Category │
                ├───────────────────────┼──────────────────────────┤
                │   0      [4m1[24m   [1mchar     [22m│  10      [4m1024[24m   [1mreg      [22m│
                │   1      [4m2[24m   [4munused[24m   │  11      [4m2048[24m   [1mtab      [22m│
                │   2      [4m4[24m   [1mbreak    [22m│  12      [4m4096[24m   [4munused[24m   │
                │   3      [4m8[24m   [1mdelim    [22m│  13      [4m8192[24m   [1mmissing  [22m│
                │   4     [4m16[24m   [4munused[24m   │  14     [4m16384[24m   [1minput    [22m│
                │   5     [4m32[24m   [1mscale    [22m│  15     [4m32768[24m   [1mescape   [22m│
                │   6     [4m64[24m   [1mrange    [22m│  16     [4m65536[24m   [1mspace    [22m│
                │   7    [4m128[24m   [1msyntax   [22m│  17    [4m131072[24m   [1mfont     [22m│
                │   8    [4m256[24m   [1mdi       [22m│  18    [4m262144[24m   [1mig       [22m│
                │   9    [4m512[24m   [1mmac      [22m│  19    [4m524288[24m   [1mcolor    [22m│
                │                       │  20   [4m1048576[24m   [1mfile     [22m│
                └───────────────────────┴──────────────────────────┘

     [1mbreak           [22m4   A filled output line could not be broken such that  its
                         length was less than or equal to, or adjusted such that
                         its length was exactly equal to, the output line length
                         “[1m\n[.l][22m”.   GNU  [4mtroff[24m reports the amount of overset or
                         underset  in  the  scaling  unit  configured   by   the
                         [1mwarnscale [22mrequest in [1mtroff [22mmode, and in ens (‘[1mn[22m’; char‐
                         acter  cells)  in [1mnroff [22mmode.  This category is enabled
                         by default.

     [1mchar            [22m1   No user‐defined character of the requested name or  in‐
                         dex  exists and no mounted font defines a glyph for it,
                         or input could not be  encoded  for  device‐independent
                         output.  This category is enabled by default.

     [1mcolor      [22m524288   An  undefined  color  name was selected, an attempt was
                         made to define a  color  using  an  unrecognized  color
                         space,  an  invalid channel value in a color definition
                         was encountered, or an attempt was made to  redefine  a
                         default color.

     [1mdelim           [22m8   The  selected delimiter character was ambiguous because
                         it is also meaningful when beginning a numeric  expres‐
                         sion,  or  the  closing delimiter in an escape sequence
                         was missing or mismatched.

                         A future [4mgroff[24m release may reject ambiguous delimiters.
                         In compatibility mode,  ambiguous  delimiters  are  ac‐
                         cepted without warning.

     [1mdi            [22m256   A  [1mdi[22m,  [1mda[22m, [1mbox[22m, or [1mboxa [22mrequest was invoked without an
                         argument when there was no current diversion.

     [1mescape      [22m32768   An unsupported escape sequence was encountered.

     [1mfile      [22m1048576   An attempt was made to read a file that does not exist.
                         or a stream remained open at formatter exit.  This cat‐
                         egory is enabled by default.

     [1mfont       [22m131072   A non‐existent font was selected.  This category is en‐
                         abled by default.

     [1mig         [22m262144   An invalid escape sequence occurred  in  input  ignored
                         using  the [1mig [22mrequest.  This warning category diagnoses
                         a condition that is an error when it occurs in  non‐ig‐
                         nored input.

     [1minput       [22m16384   An invalid character occurred on the input stream.

     [1mmac           [22m512   An  undefined  string,  macro,  or  diversion was used.
                         When such an object is dereferenced, an  empty  one  of
                         that  name  is automatically created.  So, unless it is
                         later deleted, [4mtroff[24m issues at  most  one  warning  for
                         each.

                         [4mtroff[24m  also uses this category to warn of an attempt to
                         move an unplanted trap macro.  In such cases,  the  un‐
                         planted macro is [4mnot[24m dereferenced, so it is not created
                         if it does not exist.

     [1mmissing      [22m8192   A request was invoked with a mandatory argument absent.

     [1mrange          [22m64   A numeric expression was out of range for its context.

     [1mreg          [22m1024   An undefined register was used.  When an undefined reg‐
                         ister  is dereferenced, the formatter automatically de‐
                         fines it with a value of 0.  So,  unless  it  is  later
                         deleted, GNU [4mtroff[24m issues at most one warning for each.

     [1mscale          [22m32   A scaling unit inappropriate to its context was used in
                         a numeric expression.

     [1mspace       [22m65536   A  space was missing between a request or macro and its
                         argument.  This warning is produced when  an  undefined
                         name  longer than two characters is encountered and the
                         first two characters of the name constitute  a  defined
                         name.   No  request is invoked, no macro called, and an
                         empty macro is not defined.  This category  is  enabled
                         by default.  It never occurs in compatibility mode.

     [1msyntax        [22m128   A  self‐contradictory  hyphenation  mode  or  character
                         flags were requested; an empty  or  incomplete  numeric
                         expression was encountered; an operand to a numeric op‐
                         erator was missing; an attempt was made to format char‐
                         acters  or spaces on an input line after an output line
                         continuation escape sequence; a recognized but  inappo‐
                         site  escape sequence or unprintable character code was
                         used in a device extension command; an attempt was made
                         to define a recursive, empty, or nonsensical  character
                         class;  or  a [4mgroff[24m extension escape sequence or condi‐
                         tional expression operator was used while  in  compati‐
                         bility mode.

     [1mtab          [22m2048   A  tab character appeared in a parameterized escape se‐
                         quence, in an unquoted macro argument, or where  a  re‐
                         quest expected a numeric expression argument.

     Two warning names group other warning categories for convenience.

     [1mall    [22mAll  warning  categories except [1mdi[22m, [1mmac[22m, and [1mreg[22m.  This shorthand is
            intended to produce all warnings that are useful with macro packages
            and documents written for AT&T [4mtroff[24m and its descendants, which have
            less fastidious diagnostics than GNU [4mtroff[24m.

     [1mw      [22mAll warning categories.  Authors of  documents  and  macro  packages
            targeting [4mgroff[24m are encouraged to use this setting.

[1mExit status[0m
     [4mtroff[24m  exits with status [1m0 [22mon successful operation, status [1m2 [22mif the program
     cannot interpret its command‐line arguments, and status [1m1 [22mif it  encounters
     a fatal error during operation, or is directed to abort by the input.

[1mEnvironment[0m
     [4mGROFF_FONT_PATH[24m  and  [4mGROFF_TMAC_PATH[24m each accept a search path of directo‐
     ries; that is, a list of directory names separated  by  the  system’s  path
     component  separator character.  On Unix systems, this character is a colon
     (:); on Windows systems, it is a semicolon (;).

     [4mGROFF_FONT_PATH[0m
            A list of directories in which to seek the selected output  device’s
            directory of device and font description files.  [4mtroff[24m will scan di‐
            rectories  given  as  arguments  to  any specified [1m-F [22moptions before
            these,  then  in  a   site‐specific   directory   ([4m/usr/share/groff/[0m
            [4msite-font[24m),  a standard location ([4m/usr/share/groff/1.24.1/font[24m), and
            a compatibility directory ([4m/usr/lib/font[24m) after them.

     [4mGROFF_TMAC_PATH[0m
            A list of directories in which to search  for  macro  files.   [4mtroff[0m
            will scan directories given as arguments to any specified [1m-M [22moptions
            before  these,  then the current directory (only if in unsafe mode),
            the user’s home directory, a  site‐specific  directory  ([4m/usr/share/[0m
            [4mgroff/site-tmac[24m),  and a standard location ([4m/usr/share/groff/1.24.1/[0m
            [4mtmac[24m) after them.

     [4mGROFF_TYPESETTER[0m
            Set the default output device.  If empty or not  set,  [1mps  [22mis  used.
            The [1m-T [22moption overrides [4mGROFF_TYPESETTER[24m.

     [4mSOURCE_DATE_EPOCH[0m
            A  timestamp  (expressed  as seconds since the Unix epoch) to use as
            the output creation timestamp in place of  the  current  time.   The
            time  is  converted  to  human‐readable  form  using  ]8;;man:gmtime(3)\[4mgmtime[24m(3)]8;;\  and
            ]8;;man:asctime(3)\[4masctime[24m(3)]8;;\ when the formatter starts up and stored in registers  us‐
            able by documents and macro packages.

     [4mTZ[24m     The time zone to use when converting the current time to human‐read‐
            able form; see ]8;;man:tzset(3)\[4mtzset[24m(3)]8;;\.  If [4mSOURCE_DATE_EPOCH[24m is used, it is always
            converted to human‐readable form using UTC.

[1mFiles[0m
     [4m/usr/share/groff/1.24.1/tmac/troffrc[0m
            is  an  initialization  macro  file loaded before any macro packages
            specified with [1m-m [22moptions.

     [4m/usr/share/groff/1.24.1/tmac/troffrc-end[0m
            is an initialization macro file  loaded  after  all  macro  packages
            specified with [1m-m [22moptions.

     [4m/usr/share/groff/1.24.1/tmac/[24mname[4m.tmac[0m
            are macro files distributed with [4mgroff[24m.

     [4m/usr/share/groff/1.24.1/font/dev[24mname[4m/DESC[0m
            describes the output device [4mname[24m.

     [4m/usr/share/groff/1.24.1/font/dev[24mname[4m/[24mF
            describes the font [4mF[24m of device [4mname.[0m

     [4mtroffrc[24m  and [4mtroffrc-end[24m are sought neither in the current nor the home di‐
     rectory by default for security reasons, even if the [1m-U  [22moption  is  speci‐
     fied.   Use  the  [1m-M [22mcommand‐line option or the [4mGROFF_TMAC_PATH[24m environment
     variable to add these directories to the search path if necessary.

[1mAuthors[0m
     The GNU version of [4mtroff[24m was originally written by  James  Clark;  he  also
     wrote  the  original  version of this document, which was updated by ]8;;mailto:wl@gnu.org\Werner
     Lemberg]8;;\, ]8;;mailto:groff-bernd.warken-72@web.de\Bernd Warken]8;;\, and ]8;;mailto:g.branden.robinson@gmail.com\G. Branden Robinson]8;;\.

[1mSee also[0m
     [4mGroff:[24m [4mThe[24m [4mGNU[24m [4mImplementation[24m [4mof[24m [4mtroff[24m, by Trent A. Fisher and Werner  Lem‐
     berg,  is  the  primary [4mgroff[24m manual.  You can browse it interactively with
     “info groff”.

     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\
            offers an overview of the GNU [4mroff[24m system and  describes  its  front
            end executable.

     ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\
            details the [4mgroff[24m language, including a short but complete reference
            of all predefined requests, registers, and escape sequences.

     ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\
            explains the syntax of [4mgroff[24m special character escape sequences, and
            lists all special characters predefined by the language.

     ]8;;man:groff_diff(7)\[4mgroff_diff[24m(7)]8;;\
            enumerates the differences between AT&T device‐independent [4mtroff[24m and
            [4mgroff[24m.

     ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\
            covers the format of [4mgroff[24m device and font description files.

     ]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\
            describes the format of [4mtroff[24m’s output.

     ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\
            includes information about macro files that ship with [4mgroff[24m.

     ]8;;man:roff(7)\[4mroff[24m(7)]8;;\
            supplies  background  on [4mroff[24m systems in general, including pointers
            to further related documentation.

groff 1.24.1                       2026‐03‐20                           [4mtroff[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mgroff_font[24m(5)                  File Formats Manual                 [4mgroff_font[24m(5)

[1mName[0m
     groff_font - GNU [4mroff[24m device and font description files

[1mDescription[0m
     The [4mgroff[24m font and output device description formats are slight  extensions
     of those used by AT&T device‐independent [4mtroff[24m.  In distinction to the AT&T
     implementation,  [4mgroff[24m  lacks  a  binary  format; all files are text files.
     (Plan 9 [4mtroff[24m has also abandoned the binary format.)  The device  and  font
     description files for a device [4mname[24m are stored in a [4mdev[24mname directory.  The
     device description file is called [4mDESC[24m, and, for each font supported by the
     device, a font description file is called [4mf,[24m where [4mf[24m is usually an abbrevi‐
     ation  of a font’s name and/or style.  For example, the [1mps [22m(PostScript) de‐
     vice has [4mgroff[24m font  description  files  for  Times  roman  ([1mTR[22m)  and  Zapf
     Chancery  Medium  italic  ([1mZCMI[22m),  among many others, while the [1mutf8 [22mdevice
     (for terminals) has font descriptions for  the  roman,  italic,  bold,  and
     bold‐italic styles ([1mR[22m, [1mI[22m, [1mB[22m, and [1mBI[22m, respectively).

     Device  and font description files are read by the formatter, [4mtroff[24m, and by
     output drivers.  The programs typically delegate these files’ processing to
     an internal library, [4mlibgroff[24m, ensuring their consistent interpretation.

[4m[1mDESC[24m file format[0m
     The [4mDESC[24m file contains a series of directives; each begins a  line.   Their
     order  is  not  important,  with two exceptions: (1) the [1mres [22mdirective must
     precede any [1mpapersize [22mdirective; and (2) the [1mcharset  [22mdirective  must  come
     last  (if  at  all).  If a directive name is repeated, later entries in the
     file override previous ones (except that the paper dimensions are  computed
     based  on  the  [1mres  [22mdirective  last  seen  when [1mpapersize [22mis encountered).
     Spaces and/or tabs separate words and are ignored at line boundaries.  Com‐
     ments start with the “[1m#[22m” character and extend to the end of a line.   Empty
     lines are ignored.

     [1mfamily [4m[22mfam[0m
             The default font family is [4mfam[24m.

     [1mfonts [4m[22mn[24m [4mF1[24m ... [4mFn[0m
             Fonts [4mF1[24m, ..., [4mFn[24m are mounted at font positions [4mm[24m+1, ..., [4mm[24m+[4mn[24m where
             [4mm[24m  is  the number of [1mstyles [22m(see below).  This directive may extend
             over more than one line.  A font name of [1m0 [22mcauses  no  font  to  be
             mounted at the corresponding position.

     [1mhor [4m[22mn[24m   The  horizontal  motion  quantum is [4mn[24m basic units.  Horizontal mea‐
             surements round to multiples of [4mn.[0m

     [1mimage_generator [4m[22mprogram[0m
             Use [4mprogram[24m to generate PNG images from  PostScript  input.   Under
             GNU/Linux,  this is usually ]8;;man:gs(1)\[4mgs[24m(1)]8;;\, but under other systems (notably
             Cygwin) it might be set to another  name.   The  ]8;;man:grohtml(1)\[4mgrohtml[24m(1)]8;;\  driver
             uses this directive.

     [1mpaperlength [4m[22mn[0m
             The  vertical dimension of the output medium is [4mn[24m basic units (dep‐
             recated: use [1mpapersize [22minstead).

     [1mpapersize [4m[22mformat‐or‐dimension‐pair‐or‐file‐name[24m ...
             The dimensions of the output medium are as according to  the  argu‐
             ment,  which  is  either  a standard paper format, a pair of dimen‐
             sions, or the name of a plain text file containing  either  of  the
             foregoing.   Recognized  paper  formats are the ISO and DIN formats
             [1mA0[22m–[1mA7[22m, [1mB0[22m–[1mB7[22m, [1mC0[22m–[1mC7[22m, and [1mD0[22m–[1mD7[22m; the  U.S.  formats  [1mletter[22m,  [1mlegal[22m,
             [1mtabloid[22m, [1mledger[22m, [1mstatement[22m, and [1mexecutive[22m; and the envelope formats
             [1mcom10[22m,  [1mmonarch[22m,  and [1mDL[22m.  Matching is performed without regard for
             lettercase.

             Alternatively,  the  argument  can  be  a   custom   paper   format
             [4mlength[24m[1m,[4m[22mwidth[24m  (with  no  spaces  before  or after the comma).  Both
             [4mlength[24m and [4mwidth[24m must have a unit appended; valid units are “[1mi[22m” for
             inches, “[1mc[22m” for centimeters, “[1mp[22m” for points,  and  “[1mP[22m”  for  picas.
             Example:  “[1m12c,235p[22m”.   An argument that starts with a digit is al‐
             ways treated as a custom paper format.

             Finally, the argument can be a file name (e.g., [4m/etc/papersize[24m); if
             the file can be opened, the first line is  read  and  a  match  at‐
             tempted against each other form.  No comment syntax is supported.

             More  than  one  argument can be specified; each is scanned in turn
             and the first valid paper specification used.

     [1mpaperwidth [4m[22mn[0m
             The horizontal dimension of the output  medium  is  [4mn[24m  basic  units
             (deprecated: use [1mpapersize [22minstead).

     [1mpass_filenames[0m
             Direct  [4mtroff[24m  to emit the name of the source file being processed.
             This is achieved with the intermediate output command “[1mx F[22m”,  which
             [4mgrohtml[24m interprets.

     [1mpostpro [4m[22mprogram[0m
             Use [4mprogram[24m as the postprocessor.

     [1mprepro [4m[22mprogram[0m
             Use  [4mprogram[24m  as a preprocessor.  The [1mhtml [22mand [1mxhtml [22moutput devices
             use this directive.

     [1mprint [4m[22mprogram[0m
             Use [4mprogram[24m as the print spooler.  If omitted, [4mgroff[24m’s  [1m-l  [22mand  [1m-L[0m
             options are ignored.

     [1mres [4m[22mn[24m   The device resolution is [4mn[24m basic units per inch.

     [1msizes [4m[22ms1[24m ... [4msn[24m [1m0[0m
             The device has fonts at [4ms1[24m, ..., [4msn[24m scaled points (see below).  The
             list  of  sizes  must  be terminated by a [1m0[22m.  Each [4msi[24m can also be a
             range of sizes [4mm[24m–[4mn[24m.  The list can extend over more than one line.

     [1msizescale [4m[22mn[0m
             A typographical point is subdivided into [4mn[24m scaled points.  The  de‐
             fault is [1m1[22m.

     [1mstyles [4m[22mS1[24m ... [4mSm[0m
             The  first [4mm[24m font mounting positions are associated with styles [4mS1[24m,
             ..., [4mSm[24m.

     [1mtcommand[0m
             The postprocessor can handle the [1mt [22mand [1mu [22mintermediate  output  com‐
             mands.

     [1municode[0m
             The  output  device supports the complete Unicode repertoire.  This
             directive is useful only for devices which produce character  enti‐
             ties instead of glyphs.

             If  [1municode  [22mis present, no [1mcharset [22msection is required in the font
             description files since the Unicode handling built  into  [4mgroff[24m  is
             used.   However,  if there are entries in a font description file’s
             [1mcharset [22msection, they either  override  the  default  mappings  for
             those  particular characters or add new mappings (normally for com‐
             posite characters).

             The [1mutf8[22m, [1mhtml[22m, and [1mxhtml [22moutput devices use this directive.

     [1munitwidth [4m[22mn[0m
             Arbitrary basis with respect to which font metrics are  proportion‐
             ally scaled when rendering glyphs at a type size of one point.

     [1munscaled_charwidths[0m
             Make  the font handling module always return unscaled glyph widths.
             The [4mgrohtml[24m driver uses this directive.

     [1muse_charnames_in_special[0m
             [4mtroff[24m should encode special characters in arguments to  device  ex‐
             tension commands.  The [4mgrohtml[24m driver uses this directive.

     [1mvert [4m[22mn[24m  The  vertical  motion  quantum is [4mn[24m basic units.  Vertical measure‐
             ments round to multiples of [4mn.[0m

     [1mcharset[0m
             This directive and the rest of the file are ignored.  It is  recog‐
             nized  for  compatibility with other [4mtroff[24m implementations.  In GNU
             [4mtroff[24m, character set repertoire is described on a per‐font basis.

     [4mtroff[24m recognizes but ignores the directives [1mspare1[22m,  [1mspare2[22m,  and  [1mbiggest‐[0m
     [1mfont[22m.

     The  [1mres[22m,  [1munitwidth[22m, [1mfonts[22m, and [1msizes [22mlines are mandatory.  Directives not
     listed above are ignored by [4mtroff[24m but may be used by postprocessors to  ob‐
     tain further information about the device.

[1mFont description file format[0m
     On typesetting output devices, each font is typically available at multiple
     sizes.   While paper measurements in the device description file are in ab‐
     solute units, measurements applicable to fonts must be proportional to  the
     type  size.   The font’s [4munit[24m [4mwidth[24m establishes a numerical basis that per‐
     mits all of its metrics to be expressed as  integers  if  rendered  at  one
     point.   When  the  formatter configures a type size, it scales the metrics
     linearly relative to that basis.  The unit width has no inherent  relation‐
     ship  to  the device resolution, and the same division procedure applies to
     all font metrics.  Observe that whatever unit might one select for the unit
     width, the division operation implied by scaling cancels it out, leaving  a
     dimensionless quantity.

     For  instance,  [4mgroff[24m’s [1mlbp [22mdevice uses a [1munitwidth [22mdirective with an argu‐
     ment of 800.  Its Times roman font [1mTR [22mhas a [1mspacewidth [22mof 833; this is also
     the width of its comma, period, centered period, and mathematical asterisk,
     while its “[1mM[22m” has a width of 2,963.  Thus, an “[1mM[22m”  on  the  [1mlbp  [22mdevice  is
     2,963  ÷ 800 times the unit width, or approximately 3.7.  At a type size of
     10 points, a Times roman “[1mM[22m” is therefore 37 units wide.

     A font description file has two sections.  The first is a sequence  of  di‐
     rectives, and is parsed similarly to the [4mDESC[24m file described above.  Except
     for  the  directive  names that begin the second section, their ordering is
     immaterial.  Later directives of  the  same  name  override  earlier  ones,
     spaces and tabs are handled in the same way, and the same comment syntax is
     supported.  Empty lines are ignored throughout.

     [1mname [4m[22mF[24m  The name of the font is [4mF[24m.  “[1mDESC[22m” is an invalid font name.  Simple
             integers  are valid, but their use is discouraged.  ([4mgroff[24m requests
             and escape sequences interpret non‐negative  integers  as  mounting
             positions  instead.   Further, a font named “[1m0[22m” cannot be automati‐
             cally mounted by the [1mfonts [22mdirective of a [4mDESC[24m file.)

     [1mspacewidth [4m[22mn[0m
             The width of an unadjusted inter‐word space is [4mn[24m, relative  to  the
             device’s unit width.

     The  directives above must appear in the first section; those below are op‐
     tional.

     [1mslant [4m[22mn[0m
            The font’s glyphs have a slant of [4mn[24m degrees; a positive [4mn[24m slants  in
            the direction of text flow.

     [1mligatures [4m[22mlig1[24m ... [4mlign[24m [[1m0[22m]
            Glyphs [4mlig1[24m, ..., [4mlign[24m are ligatures; possible ligatures are [1mff[22m, [1mfi[22m,
            [1mfl[22m,  [1mffi[22m,  and  [1mffl[22m.  For compatibility with other [4mtroff[24m implementa‐
            tions, the list of ligatures may be terminated with a [1m0[22m.   The  list
            of ligatures must not extend over more than one line.

     [1mspecial[0m
            The  font  is  [4mspecial[24m: when the document attempts to format a glyph
            that is not present in the formatter’s currently selected font,  the
            glyph  is  sought in any mounted fonts that bear this property.  Of‐
            ten, such fonts are [4munstyled[24m, having  no  heavy  (bold)  or  slanted
            (italic or oblique) variants.

     Other  directives in this section are ignored by GNU [4mtroff[24m, but may be used
     by postprocessors to obtain further information about the font.

     The second section contains one to three subsections, which can  appear  in
     any  order, and any of which starts the second section.  Each starts with a
     directive on a line by itself.  A [1mcharset [22msubsection  is  mandatory  unless
     the  associated  [4mDESC[24m file contains the [1municode [22mdirective.  Another subsec‐
     tion, [1mkernpairs[22m, is optional.

     The directive [1mcharset [22mstarts the character set  subsection.   (On  typeset‐
     ters,  this  directive  is  misnamed  since it starts a list of glyphs, not
     characters.)  It precedes a series of glyph  descriptions,  one  per  line.
     Each  such  glyph description comprises a set of fields separated by spaces
     or tabs and organized as follows.

            [4mname[24m [4mmetrics[24m [4mtype[24m [4mindex[24m [[4mentity‐name[24m] [[1m-- [4m[22mcomment[24m]

     [4mname[24m identifies the glyph: a printable character [4mc[24m corresponds to the [4mtroff[0m
     ordinary character [4mc[24m, and a multi‐character sequence not beginning with  [1m\[22m,
     corresponds  to  the GNU [4mtroff[24m special character escape sequence “[1m\[[4m[22mname[24m[1m][22m”.
     A name consisting of three minus signs, “[1m---[22m”, indicates that the glyph  is
     unnamed:  such  glyphs  can  be  accessed only by the [1m\N [22mescape sequence in
     [4mtroff[24m.  A special character named “[1m---[22m” can still be  defined  using  [1m.char[0m
     and  similar  requests.   The  [4mname[24m “[1m\-[22m” defines the minus sign glyph.  Fi‐
     nally, [4mname[24m can be the  horizontal  motion  escape  sequences,  [1m\|  [22mand  [1m\^[0m
     (“thin” and “hair” spaces, respectively), in which case only the width met‐
     ric  described  below  is  applied; a font can thus customize the widths of
     these spaces.

     The form of the [4mmetrics[24m field is as follows (on one line; it may be  broken
     here for readability).

            [4mwidth[24m[[1m,[22m[[4mheight[24m[[1m,[22m[[4mdepth[24m[[1m,[22m[[4mitalic‐correction[24m[[1m,[22m[
            [4mleft‐italic‐correction[24m[[1m,[22m[[4msubscript‐correction[24m]]]]]]]]]]

     Spaces,  tabs,  and  newlines are prohibited between these [4msubfields,[24m which
     are expressed as decimal integers.  The unit of measure is that established
     by the [1munitwidth [22mdirective and scaled to the type size.   Unspecified  sub‐
     fields  default  to  0.   Since there is no associated binary format, these
     values are not required to fit into the C language data type [4mchar[24m  as  they
     are in AT&T device‐independent [4mtroff[24m.

     The [4mwidth[24m subfield gives the width of the glyph.  The [4mheight[24m subfield gives
     the  height  of  the glyph (upward is positive); if a glyph does not extend
     above the baseline, give it a zero height,  not  a  negative  height.   The
     [4mdepth[24m  subfield  gives  the depth of the glyph——that is, the distance below
     the baseline to which the glyph extends (downward is positive); if a  glyph
     does  not  extend  below the baseline, give it a zero depth, not a negative
     depth.  Italic corrections  apply  when  upright  and  slanted  (italic  or
     oblique)  styles  are  typeset  adjacently.   The  [4mitalic‐correction[24m is the
     amount of space to add after a slanted glyph to be followed immediately  by
     an upright glyph.  The [4mleft‐italic‐correction[24m is the amount of space to add
     before a slanted glyph to be preceded immediately by an upright glyph.  The
     [4msubscript‐correction[24m is the amount of space to add after a slanted glyph to
     be followed by a subscript; it should be less than the italic correction.

     For  fonts  used with typesetters, the [4mtype[24m field gives a featural descrip‐
     tion of the glyph: it is a bit mask recording whether the glyph is  an  as‐
     cender, descender, both, or neither.  When a [1m\w [22mescape sequence is interpo‐
     lated, these values are bitwise or‐ed together for each glyph and stored in
     the [1mct [22mregister.  In font descriptions for terminals, all glyphs might have
     a type of zero, regardless of their appearance.

     0      means  the glyph lies entirely between the baseline and a horizontal
            line at the “x‐height” of the font, as with “a”, “c”, and “x”;

     1      means the glyph descends below the baseline, like “p”;

     2      means the glyph ascends above the font’s x‐height, like “A” or “b”);
            and

     3      means the glyph is both an ascender and a descender——this is true of
            parentheses in some fonts.

     The [4mindex[24m field is an integer that uniquely identifies a glyph  within  the
     font;  any  integer is accepted as input, (that is, any integer parsable by
     the C standard library’s ]8;;man:strtol(3)\[4mstrtol[24m(3)]8;;\ function) but no practical font  employs
     all  possible  values.   An [4mindex[24m is limited to the range of the system’s C
     language data type [4mint[24m.  In a [4mtroff[24m document, use the indexed character es‐
     cape sequence [1m\N [22mto specify a glyph by index.

     The [4mentity‐name[24m field defines an identifier for the glyph  that  the  post‐
     processor  uses  to print the [4mtroff[24m glyph [4mname[24m.  This field is optional; it
     was introduced so that the [4mgrohtml[24m output driver could encode its character
     set.  For example, the glyph [1m\[Po] [22mis represented by “[1m&pound;[22m” in HTML 4.0.
     For efficiency, these data are now compiled directly into  [4mgrohtml[24m.   [4mgrops[0m
     uses the field to build sub‐encoding arrays for PostScript fonts containing
     more than 256 glyphs.

     Anything  on the line after the [4mentity‐name[24m field or “[1m--[22m” is ignored.  When
     [4mafmtodit[24m generates font description files for ]8;;man:gropdf(1)\[4mgropdf[24m(1)]8;;\  and  ]8;;man:grops(1)\[4mgrops[24m(1)]8;;\,  it
     writes the UTF‐16 code for the character to the comment field.

     A line in the [1mcharset [22msection can also have the form
            [4mname[24m [1m"[0m
     identifying  [4mname[24m  as another name for the glyph mentioned in the preceding
     line.  Such aliases can be chained.

     A [1mcharset-range [22msubsection works like the [1mcharset [22mdirective except that the
     glyph descriptions use a [4mname[24m of the form [1mu[4m[22mAAAA[24m[1m..u[4m[22mFFFF[24m, where [4mAAAA[24m and [4mFFFF[0m
     are hexadecimal digit sequences; the specified metrics then  apply  identi‐
     cally to all glyphs in the designated range.

     The  directive [1mkernpairs [22mstarts a list of kerning adjustments to be made to
     adjacent glyph pairs from this font.  It contains a sequence of lines  for‐
     matted as follows.
            [4mg1[24m [4mg2[24m [4mn[0m
     The  foregoing  means  that when glyph [4mg1[24m is typeset immediately before [4mg2[24m,
     the space between them should be increased by [4mn[24m.  The unit  of  measure  is
     that  established  by  the [1munitwidth [22mdirective and scaled to the type size.
     Most kerning pairs should have a negative value for [4mn[24m.

[1mFiles[0m
     [4m/usr/share/groff/1.24.1/font/dev[24mname[4m/DESC[0m
            describes the output device [4mname[24m.

     [4m/usr/share/groff/1.24.1/font/dev[24mname[4m/[24mF
            describes the font known as [4mF[24m on device [4mname[24m.

[1mSee also[0m
     [4mGroff:[24m [4mThe[24m [4mGNU[24m [4mImplementation[24m [4mof[24m [4mtroff[24m, by Trent A. Fisher and Werner  Lem‐
     berg,  is  the  primary [4mgroff[24m 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 device‐independent page description lan‐
     guage referred to collectively in [4mgroff[24m documentation as “AT&T [4mtroff[24m”.

     “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 device‐inde‐
     pendent page description language.

     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, subsection “Utilities”, lists programs available  for  describing
     fonts in a variety of formats such that [4mgroff[24m output drivers can use them.

     ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\  documents  the  default  device  and font description file search
     path.

     ]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\, ]8;;man:addftinfo(1)\[4maddftinfo[24m(1)]8;;\

groff 1.24.1                       2026‐03‐20                      [4mgroff_font[24m(5)
────────────────────────────────────────────────────────────────────────────────
[4mgroff_out[24m(5)                   File Formats Manual                  [4mgroff_out[24m(5)

[1mName[0m
     groff_out - GNU [4mroff[24m device‐independent page description language

[1mDescription[0m
     The fundamental operation of the GNU  [4mtroff[24m  formatter,  ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\,  is  the
     translation  of  the  ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\ input language into a series of instructions
     concerned primarily with placing glyphs or geometric  objects  at  specific
     positions  on  a  rectangular  page.  In the following discussion, the term
     [4mcommand[24m refers to this device‐independent output  language,  never  to  the
     language  intended  for use by document authors.  Device‐independent output
     commands comprise several categories: glyph output; font, color,  and  text
     size  selection;  motion of the drawing position; page advancement; drawing
     of geometric primitives; and device extension  commands,  a  catch‐all  for
     other  operations.   The last includes directives to start and stop output,
     identify the intended output device, and embed URL hyperlinks in  supported
     output formats.

   [1mBackground[0m
     As  ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\  is a wrapper program around GNU [4mtroff[24m and automatically calls
     an output driver, users seldom encounter this format under  normal  circum‐
     stances.   [4mgroff[24m  offers  the option [1m-Z [22mto inhibit postprocessing such that
     GNU [4mtroff[24m’s output is sent to the standard output stream just as it is when
     running GNU [4mtroff[24m directly.

     The purpose of device‐independent output is to facilitate  the  development
     of  postprocessors  by providing a common programming interface for all de‐
     vices.  It is a distinct, and much simpler, language from that of the  for‐
     matter,  [4mtroff[24m.  The device‐independent output can be thought of as a “page
     description language”.

     In the following discussion, the term [4mtroff[24m [4moutput[24m describes what is output
     by GNU [4mtroff[24m, while [4mpage[24m [4mdescription[24m denotes the language accepted  by  the
     parser  that  interprets  this  output for the output drivers.  This parser
     handles whitespace more flexibly than AT&T [4mtroff[24m’s  implementation,  recog‐
     nizes a GNU extension to the language, and supports a legacy compressed en‐
     coding  of  a  subset of commands for compatibility; otherwise, the formats
     are the same.  (The parser for device‐independent output can  be  found  in
     the [4mgroff[24m sources at [4msrc/libs/libdriver/input.cpp[24m.)

     When Brian Kernighan designed AT&T [4mtroff[24m’s device‐independent page descrip‐
     tion language circa 1980, he had to balance readability and maintainability
     against  severe constraints on file size and transmission speed to the out‐
     put device.  A decade later, when  James  Clark  wrote  [4mgroff[24m,  these  con‐
     straints were no longer as tight.

   [1mSyntax[0m
     [4mroff[24m’s  page  description  language  is a sequence of [4mtokens:[24m single‐letter
     commands or their arguments.  Some commands accept a subcommand as a  first
     argument, followed by one or more further arguments.

     AT&T device‐independent [4mtroff[24m used whitespace minimally when producing out‐
     put.   GNU [4mtroff[24m, in contrast, attempts to make its output more human‐read‐
     able.  The whitespace characters——tab, space, and newline——are always mean‐
     ingful.  They are never used to represent spacing in the document; that  is
     done  with horizontal ([1mh[22m, [1mH[22m) and vertical ([1mv[22m, [1mV[22m) positioning commands.  Any
     sequence of space and/or tab characters is equivalent to  a  single  space,
     separating commands from arguments and arguments from each other.  Space is
     required  only where omitting it would cause ambiguity.  A line break sepa‐
     rates commands.  The comment character is a pound/hash sign ([1m#[22m), and  marks
     the  remainder of the line as a comment.  A line comprising only whitespace
     after comment removal does nothing but separate input tokens.

     For example, the relative horizontal motion command ([1mh[22m) and the command  to
     write one glyph ([1mc[22m), each take a single argument; the former a signed inte‐
     ger,  and  the  latter  a printable ISO 646/“ASCII” character.  A series of
     such commands could validly occur without spaces on an input line, but  GNU
     [4mtroff[24m follows each with a newline.

     Some  commands  have a more complex syntax; the GNU [4mtroff[24m extension command
     for writing glyph sequences ([1mt[22m) accepts a  variable  number  of  arguments.
     Those that draw geometric objects ([1mD[22m) or control the device ([1mx[22m) furthermore
     recognize  subcommand  arguments.   Such commands thus must end with a new‐
     line.  In GNU [4mtroff,[24m the device extension (sub)command “[1mx X[22m” uniquely  sup‐
     ports a line continuation syntax; a single input line contains any other.

   [1mArgument units[0m
     Some commands accept integer arguments that represent measurements, but the
     scaling  units  of  the formatter’s language are never used.  Most commands
     assume a scaling unit of “[1mu[22m” (basic units),  and  others  use  “[1ms[22m”  (scaled
     points).   These  are  defined  by the parameters specified in the device’s
     [4mDESC[24m file; see ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\ and, for more on scaling units,  ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\  and
     [4mGroff:[24m  [4mThe[24m  [4mGNU[24m [4mImplementation[24m [4mof[24m [4mtroff[24m, the [4mgroff[24m Texinfo manual.  Color‐
     related commands use dimensionless integers.

     Note that single characters can have the eighth bit set, as can  the  names
     of fonts and special characters (this is, glyphs).  The names of glyphs and
     fonts  can  be of arbitrary length.  A glyph that is to be printed will al‐
     ways be in the current font.

     A string argument is always terminated by  the  next  whitespace  character
     (space,  tab,  or  newline); an embedded [1m# [22mcharacter is regarded as part of
     the argument, not as the beginning of a comment command.  An integer  argu‐
     ment  is  already terminated by the next non‐digit character, which then is
     regarded as the first character of the next argument or command.

   [1mOutput structure[0m
     Device‐independent [4mtroff[24m output is organized into three parts: a header,  a
     body, and a trailer.

     The  task  of  the  header  is to set general device parameters.  GNU [4mtroff[0m
     guarantees that its header consists of the following three lines:

            [1mx T [4m[22mdevice[0m
            [1mx res [4m[22mn[24m [4mh[24m [4mv[0m
            [1mx init[0m

     with the parameters [4mn[24m, [4mh[24m, and [4mv[24m set as outlined in subsection “Device  Con‐
     trol  Commands” below.  The parser for the device‐independent page descrip‐
     tion language format is able to interpret additional  whitespace  and  com‐
     ments as well even in the header.

     The  body  contains  the document’s visible content.  Once an output driver
     interprets “[1mx init[22m”, it prepares to handle commands in general.  Processing
     terminates when a “[1mx stop[22m” command is encountered; the last line of any GNU
     [4mtroff[24m page description output always contains such a command.

     Semantically, the body is page‐oriented.  The [1mp [22mcommand starts a new  page.
     Positioning,  writing, and drawing commands are performed within a page, so
     they cannot occur before the first [1mp [22mcommand.  The  output  driver  reckons
     absolute  positioning (by the [1mH [22mand [1mV [22mcommands) with respect to the current
     page’s origin at the top left corner, and all other positioning relative to
     the drawing position on the page.

     The trailer advances the drawing position to the bottom of the page and in‐
     forms the device that the document (or “job”) has ended.

[1mCommand reference[0m
     This section describes all page description output commands, both from AT&T
     [4mtroff[24m as well as extension commands issued by GNU [4mtroff.[0m

   [1mComment command[0m
     [1m#[4m[22manything[24m⟨line‐break⟩
            Apply comment annotation.  Ignore any characters from the [1m#  [22mcharac‐
            ter  up  to the next newline.  Each comment can be preceded by arbi‐
            trary syntactical space, and every command can be  terminated  by  a
            comment.

   [1mSimple commands[0m
     The  commands in this subsection have a command code consisting of a single
     character, taking a fixed number of arguments.  Most of them  are  commands
     for  positioning  and  text writing.  These commands are smart about white‐
     space.  Optionally, [4msyntactical[24m [4mspace[24m can be inserted  before,  after,  and
     between  the  command  letter and its arguments.  All of these commands are
     stackable, i.e., they can be preceded by other simple commands or  followed
     by  arbitrary  other  commands  on the same line.  A separating [4msyntactical[0m
     [4mspace[24m is necessary only when two integer arguments would clash  or  if  the
     preceding argument ends with a string argument.

     [1mC [4m[22mid[24m⟨white‐space⟩
            Typeset the glyph of the special character [4mid[24m.  Trailing syntactical
            space  is  necessary  to  allow special character names of arbitrary
            length.  The drawing position is not advanced.

     [1mc [4m[22mc[24m    Typeset the glyph of the ordinary character [4mc[24m.  The drawing position
            is not advanced.

     [1mf [4m[22mn[24m    Select the font mounted at position [4mn[24m.  [4mn[24m cannot be negative.

     [1mH [4m[22mn[24m    Horizontally move the drawing position to [4mn[24m  basic  units  from  the
            left edge of the page.  [4mn[24m cannot be negative.

     [1mh [4m[22mn[24m    Move  the  drawing position right [4mn[24m basic units.  AT&T [4mtroff[24m allowed
            negative [4mn;[24m GNU [4mtroff[24m does not produce such values, but [4mgroff[24m’s out‐
            put driver library handles them.

     [1mm [4m[22mscheme[24m [[4mcomponent[24m ...]
            Select the stroke color using the  [4mcomponent[24ms  in  the  color  space
            [4mscheme[24m.   Each  [4mcomponent[24m  is  an  integer between 0 and 65536.  The
            quantity of components and their meanings  vary  with  each  [4mscheme[24m.
            This command is a [4mgroff[24m extension.

            [1mmc [4m[22mcyan[24m [4mmagenta[24m [4myellow[0m
                   Use  the  CMY color scheme with components cyan, magenta, and
                   yellow.

            [1mmd     [22mUse the default color (no components; black in most cases).

            [1mmg [4m[22mgray[0m
                   Use a grayscale color scheme with a component ranging between
                   0 (black) and 65536 (white).

            [1mmk [4m[22mcyan[24m [4mmagenta[24m [4myellow[24m [4mblack[0m
                   Use the CMYK color scheme with components cyan, magenta, yel‐
                   low, and black.

            [1mmr [4m[22mred[24m [4mgreen[24m [4mblue[0m
                   Use the RGB color scheme  with  components  red,  green,  and
                   blue.

     [1mN [4m[22mn[24m    Typeset the glyph with index [4mn[24m in the current font.  [4mn[24m is normally a
            non‐negative  integer.   The  drawing position is not advanced.  The
            [1mhtml [22mand [1mxhtml [22mdevices use this command with negative [4mn[24m  to  produce
            unbreakable  space; the absolute value of [4mn[24m is taken and interpreted
            in basic units.

     [1mn [4m[22mb[24m [4ma[24m  Indicate a break.  No action is performed; the command is present to
            make the output more easily parsed.  The integers [4mb[24m and  [4ma[24m  describe
            the vertical space amounts before and after the break, respectively.
            GNU  [4mtroff[24m issues this command but [4mgroff[24m’s output driver library ig‐
            nores it.  See [1mv [22mand [1mV[22m.

     [1mp [4m[22mn[24m    Begin a new page, setting its number to [4mn[24m.  Each  page  is  indepen‐
            dent,  even  from those using the same number.  The vertical drawing
            position is set to 0.  All positioning, writing,  and  drawing  com‐
            mands  are interpreted in the context of a page, so a [1mp [22mcommand must
            precede them.

     [1ms [4m[22mn[24m    Set type size to [4mn[24m scaled points (unit [1mz [22min GNU [4mtroff[24m).  AT&T  [4mtroff[0m
            used unscaled points ([1mp[22m) instead; see section “Compatibility” below.

     [1mt [4m[22mxyz[24m...⟨white‐space⟩
     [1mt [4m[22mxyz[24m... [4mdummy‐arg[24m⟨white‐space⟩
            Typeset  word  [4mxyz[24m; that is, set a sequence of ordinary glyphs named
            [4mx[24m, [4my[24m, [4mz[24m, ..., 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  [1mC  [22mcommand
            to  emplace  glyphs of special characters.  The [1mt [22mcommand is a [4mgroff[0m
            extension and is output only for devices whose  [4mDESC[24m  file  contains
            the [1mtcommand [22mdirective; see ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

     [1mu [4m[22mn[24m [4mxyz[24m...
     [1mu [4m[22mxyz[24m... [4mdummy‐arg[24m⟨white‐space⟩
            Typeset  word  [4mxyz[24m with track kerning.  As [1mt[22m, but after placing each
            glyph, the drawing position is further advanced  horizontally  by  [4mn[0m
            basic  units.  The [1mu [22mcommand is a [4mgroff[24m extension and is output only
            for devices whose [4mDESC[24m file contains  the  [1mtcommand  [22mdirective;  see
            ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

     [1mV [4m[22mn[24m    Vertically  move  the drawing position to [4mn[24m basic units from the top
            edge of the page.  [4mn[24m cannot be negative.

     [1mv [4m[22mn[24m    Move the drawing position down [4mn[24m basic units.   AT&T  [4mtroff[24m  allowed
            negative [4mn;[24m GNU [4mtroff[24m does not produce such values, but [4mgroff[24m’s out‐
            put driver library handles them.

     [1mw      [22mIndicate  an  inter‐word space.  No action is performed; the command
            is present to make the output more easily parsed.   Only  inter‐word
            spaces  on  an  output  line (be they breakable or not) are thus de‐
            scribed; those resulting from horizontal motion escape sequences are
            not.  GNU [4mtroff[24m issues this command but [4mgroff[24m’s  output  driver  li‐
            brary ignores it.  See [1mh [22mand [1mH[22m.

   [1mGraphics commands[0m
     Each  graphics  or  drawing command in the page description language starts
     with the letter “[1mD[22m”, followed by one or two characters that specify a  sub‐
     command;  this  is  followed by a fixed or variable number of integer argu‐
     ments that are separated by a single space character.  A “[1mD[22m”,  command  may
     not be followed by another command on the same line (apart from a comment),
     so each “[1mD[22m” command is terminated by a syntactical line break.

     GNU  [4mtroff[24m output follows AT&T [4mtroff[24m’s output conventions (no space between
     command and subcommand, all arguments are preceded by a single space  char‐
     acter),  but  [4mgroff[24m’s parser allows optional space between the command let‐
     ters and makes the space before the first  argument  optional.   As  usual,
     each space can be any sequence of tab and space characters.

     Some  graphics  commands  can take a variable number of arguments.  In this
     case, they are integers representing a size measured in basic units [1mu[22m.  The
     [4mh[24m arguments stand for horizontal distances where positive means right, neg‐
     ative left.  The [4mv[24m arguments stand for vertical  distances  where  positive
     means  down,  negative up.  All these distances are offsets relative to the
     current location.

     Each graphics command directly corresponds to a [4mtroff[24m [1m\D  [22mescape  sequence.
     See subsection “Drawing commands” of ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\.

     Unless indicated otherwise, each graphics command directly corresponds to a
     similar [4mgroff[24m [1m\D [22mescape sequence; see ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\.

     Unknown  [1mD  [22mcommands  are assumed to be device‐specific.  Its arguments are
     parsed as strings; the whole information is then sent to the postprocessor.

     In the following command reference, the syntax element [4m⟨line‐break⟩[24m means a
     [4msyntactical[24m [4mline[24m [4mbreak[24m as defined in subsection “Separation” above.

     [1mD~ [4m[22mh1[24m [4mv1[24m [4mh2[24m [4mv2[24m ... [4mhn[24m [4mvn[24m⟨line‐break⟩
            Draw B‐spline from current position to offset ([4mh1[24m, [4mv1[24m), then to off‐
            set ([4mh2[24m, [4mv2[24m) if given, etc., up to ([4mhn[24m, [4mvn[24m). This  command  takes  a
            variable  number of argument pairs; the current position is moved to
            the terminal point of the drawn curve.

     [1mDa [4m[22mh1[24m [4mv1[24m [4mh2[24m [4mv2[24m⟨line‐break⟩
            Draw arc from current position to ([4mh1[24m, [4mv1[24m)+([4mh2[24m, [4mv2[24m) with  center  at
            ([4mh1[24m, [4mv1[24m);  then  move the current position to the final point of the
            arc.

     [1mDC [4m[22md[24m⟨line‐break⟩
     [1mDC [4m[22md[24m [4mdummy‐arg[24m⟨line‐break⟩
            Draw a solid circle using the current fill  color  with  diameter  [4md[0m
            (integer  in basic units [1mu[22m) with leftmost point at the current posi‐
            tion; then move the current position to the rightmost point  of  the
            circle.  An optional second integer argument is ignored (this allows
            the  formatter  to generate an even number of arguments).  This com‐
            mand is a GNU extension.

     [1mDc [4m[22md[24m⟨line‐break⟩
            Draw circle line with diameter [4md[24m (integer in  basic  units  [1mu[22m)  with
            leftmost  point at the current position; then move the current posi‐
            tion to the rightmost point of the circle.

     [1mDE [4m[22mh[24m [4mv[24m⟨line‐break⟩
            Draw a solid ellipse in the current fill color with a horizontal di‐
            ameter of [4mh[24m and a vertical diameter of [4mv[24m  (both  integers  in  basic
            units  [1mu[22m) with the leftmost point at the current position; then move
            to the rightmost point of the ellipse.  This command is a GNU exten‐
            sion.

     [1mDe [4m[22mh[24m [4mv[24m⟨line‐break⟩
            Draw an outlined ellipse with a horizontal diameter of [4mh[24m and a  ver‐
            tical  diameter of [4mv[24m (both integers in basic units [1mu[22m) with the left‐
            most point at current position; then move to the rightmost point  of
            the ellipse.

     [1mDF [4m[22mcolor‐scheme[24m [[4mcomponent[24m ...]⟨line‐break⟩
            Set  fill  color  for  solid  drawing  objects using different color
            schemes; the analogous command for setting the color of  text,  line
            graphics, and the outline of graphic objects is [1mm[22m.  The color compo‐
            nents  are  specified as integer arguments between 0 and 65536.  The
            number of color components and their meaning vary for the  different
            color  schemes.   These commands are generated by GNU [4mtroff[24m’s escape
            sequences “[1m\D'F [22m...[1m'[22m” [1m\M [22m(with no other corresponding graphics  com‐
            mands).  No position changing.  This command is a GNU extension.

            [1mDFc [4m[22mcyan[24m [4mmagenta[24m [4myellow[24m⟨line‐break⟩
                   Set  fill color for solid drawing objects using the CMY color
                   scheme, having the 3 color components cyan, magenta, and yel‐
                   low.

            [1mDFd [22m⟨line‐break⟩
                   Set fill color for solid drawing objects to the default  fill
                   color value (black in most cases).  No component arguments.

            [1mDFg [4m[22mgray[24m⟨line‐break⟩
                   Set fill color for solid drawing objects to the shade of gray
                   given by the argument, an integer between 0 (black) and 65536
                   (white).

            [1mDFk [4m[22mcyan[24m [4mmagenta[24m [4myellow[24m [4mblack[24m⟨line‐break⟩
                   Set fill color for solid drawing objects using the CMYK color
                   scheme,  having the 4 color components cyan, magenta, yellow,
                   and black.

            [1mDFr [4m[22mred[24m [4mgreen[24m [4mblue[24m⟨line‐break⟩
                   Set fill color for solid drawing objects using the RGB  color
                   scheme, having the 3 color components red, green, and blue.

     [1mDf [4m[22mn[24m⟨line‐break⟩
            The argument [4mn[24m must be an integer in the range -32767 to 32767.

            0≤[4mn[24m≤1000
                   Set the color for filling solid drawing objects to a shade of
                   gray,  where 0 corresponds to solid white, 1000 (the default)
                   to solid black, and values in between to intermediate  shades
                   of gray; this command is superseded by “[1mDFg[22m”.

            [4mn[24m<0 or [4mn[24m>1000
                   Set  the  filling  color to the color that is currently being
                   used for the text and the outline, see command [1mm[22m.  For  exam‐
                   ple, the command sequence

                          mg 0 0 65536
                          Df -1

                   sets all colors to blue.

            This command is a GNU extension.

     [1mDl [4m[22mh[24m [4mv[24m⟨line‐break⟩
            Draw  line from current position to offset ([4mh[24m, [4mv[24m) (integers in basic
            units [1mu[22m); then set current position to the end of the drawn line.

     [1mDp [4m[22mh1[24m [4mv1[24m [4mh2[24m [4mv2[24m ... [4mhn[24m [4mvn[24m⟨line‐break⟩
            Draw a polygon line from current position to offset  ([4mh1[24m, [4mv1[24m),  from
            there  to  offset  ([4mh2[24m, [4mv2[24m),  etc.,  up to offset ([4mhn[24m, [4mvn[24m), and from
            there back to the starting position.  For  historical  reasons,  the
            position  is changed by adding the sum of all arguments with odd in‐
            dex to the current horizontal position and the even ones to the ver‐
            tical position.  Although this doesn’t make sense  it  is  kept  for
            compatibility.  This command is a [4mgroff[24m extension.

     [1mDP [4m[22mh1[24m [4mv1[24m [4mh2[24m [4mv2[24m ... [4mhn[24m [4mvn[24m⟨line‐break⟩
            The  same  macro as the corresponding [1mDp [22mcommand with the same argu‐
            ments, but draws a solid polygon in the current  fill  color  rather
            than  an  outlined polygon.  The position is changed in the same way
            as with [1mDp[22m.  This command is a GNU extension.

     [1mDt [4m[22mn[24m⟨line‐break⟩
            Set the current line thickness to [4mn[24m (an integer in basic units [1mu[22m) if
            [4mn[24m>0; if [4mn[24m=0 select the smallest available line thickness; otherwise,
            the line thickness is made proportional to the type size,  which  is
            the  default.   For  historical  reasons, the horizontal position is
            changed by adding the argument to the current  horizontal  position,
            while  the  vertical position is not changed.  Although this doesn’t
            make sense, it is kept for compatibility.  This command is a GNU ex‐
            tension.

   [1mDevice control commands[0m
     Each device control command starts with the letter “[1mx[22m”, followed by a space
     character (optional or arbitrary space or tab in GNU [4mtroff[24m) and  a  subcom‐
     mand letter or word; each argument (if any) must be preceded by a syntacti‐
     cal  space.   All “[1mx[22m”, commands are terminated by a syntactical line break;
     no device control command can be followed by another command  on  the  same
     line (except a comment).

     The  subcommand  is basically a single letter, but to increase readability,
     it can be written as a word, i.e., an arbitrary sequence of characters ter‐
     minated by the next tab, space, or newline character.   All  characters  of
     the  subcommand  word  but  the first are simply ignored.  For example, GNU
     [4mtroff[24m outputs the initialization command “[1mx i[22m” as “[1mx init[22m” and the  resolu‐
     tion command “[1mx r[22m” as “[1mx res[22m”.

     In  the following, the syntax element [4m⟨line‐break⟩[24m means a [4msyntactical[24m [4mline[0m
     [4mbreak[24m as defined in subsection “Separation” above.

     [1mxF [4m[22mname[24m⟨line‐break⟩
            ([4mFilename[24m control command)
            Use [4mname[24m as the intended name for the current file in error reports.
            This is useful for remembering the original  file  name  when  [4mgroff[0m
            uses  its  internal piping mechanism.  The input file is not changed
            by this command.  This command is a GNU extension.

     [1mxf [4m[22mn[24m [4ms[24m⟨line‐break⟩
            ([4mfont[24m control command)
            Mount font position [4mn[24m (a non‐negative integer) with font named [4ms[24m  (a
            text word); see ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

     [1mxH [4m[22mn[24m⟨line‐break⟩
            ([4mHeight[24m control command)
            Set  character  height to [4mn[24m (a positive integer in scaled points [1mz[22m).
            [4mClassical[24m [4mtroff[24m used the unit points ([1mp[22m) instead; see section  “Com‐
            patibility” below.

     [1mxi [22m⟨line‐break⟩
            ([4minit[24m control command)
            Initialize device.  This is the third command of the header.

     [1mxp [22m⟨line‐break⟩
            ([4mpause[24m control command)
            Parsed but ignored.  The classical documentation reads [4mpause[24m [4mdevice,[0m
            [4mcan[24m [4mbe[24m [4mrestarted[24m.

     [1mxr [4m[22mn[24m [4mh[24m [4mv[24m⟨line‐break⟩
            ([4mresolution[24m control command)
            Resolution is [4mn[24m, while [4mh[24m is the minimal horizontal motion, and [4mv[24m the
            minimal vertical motion possible with this device; all arguments are
            positive  integers  in  basic  units [1mu [22mper inch.  This is the second
            command of the header.

     [1mxS [4m[22mn[24m⟨line‐break⟩
            ([4mSlant[24m control command)
            Set slant to [4mn[24m degrees (an integer in basic units [1mu[22m).

     [1mxs [22m⟨line‐break⟩
            ([4mstop[24m control command)
            Terminates the processing of the current file; issued  as  the  last
            command of device‐independent [4mtroff[24m output.

     [1mxt [22m⟨line‐break⟩
            ([4mtrailer[24m control command)
            Generate  trailer  information, if any.  In [1mgroff[22m, this is currently
            ignored.

     [1mxT [4m[22mxxx[24m⟨line‐break⟩
            ([4mTypesetter[24m control command)
            Set the name of the output driver to [4mxxx[24m, a sequence  of  non‐white‐
            space  characters terminated by whitespace.  The possible names cor‐
            respond to those of [4mgroff[24m’s [1m-T [22moption.  This is the first command of
            the header.

     [1mxu [4m[22mn[24m⟨line‐break⟩
            ([4munderline[24m control command)
            Configure underlining of spaces.  If [4mn[24m is 1,  start  underlining  of
            spaces;  if  [4mn[24m is 0, stop underlining of spaces.  This is needed for
            the [1mcu [22mrequest in [1mnroff [22mmode and is ignored otherwise.  This command
            is a GNU extension.

     [1mxX [4m[22manything[24m⟨line‐break⟩
            ([4mX‐escape[24m control command)
            Send string [4manything[24m uninterpreted to the device.  If the line  fol‐
            lowing  this  command  starts with a [1m+ [22mcharacter this line is inter‐
            preted as a continuation line in the following sense.  The [1m+ [22mis  ig‐
            nored,  but  a  newline character is sent instead to the device, the
            rest of the line is sent uninterpreted.  The  same  applies  to  all
            following lines until the first character of a line is not a [1m+ [22mchar‐
            acter.   This  command is generated by the [4mgroff[24m escape sequence [1m\X[22m.
            Line continuation is a GNU extension.

   [1mLegacy compressed encoding[0m
     AT&T [4mtroff[24m primarily emitted glyphs by writing two digits (a  motion)  fol‐
     lowed  by a single character corresponding to a glyph.  This syntax is less
     a command itself than a compressed encoding of the [1mc [22mand [1mh [22mcommands.

     [4mddc[24m    Move right [4mdd[24m (exactly two decimal digits) basic units [1mu[22m, then print
            glyph with single‐letter name [4mc[24m.

            In [4mgroff[24m, arbitrary [4msyntactical[24m [4mspace[24m around and within this command
            is allowed to be added.  Only when a preceding command on  the  same
            line  ends with an argument of variable length a separating space is
            obligatory.  In [4mclassical[24m [4mtroff[24m, large clusters of these  and  other
            commands were used, mostly without spaces; this made such output al‐
            most unreadable.

     For modern high‐resolution devices, this command is impractical because the
     widths of the glyphs have a greater magnitude in basic units than two deci‐
     mal digits can represent.  In [4mgroff[24m, it is used only for output to the [1mX75[22m,
     [1mX75-12[22m,  [1mX100[22m,  and [1mX100-12 [22mdevices.  For others, the commands [1mt [22mand [1mu [22mpro‐
     vide greater functionality and superior troubleshooting capacity.

[1mCompatibility[0m
     The page description language of AT&T [4mtroff[24m  was  first  documented  in  “A
     Typesetter‐independent  TROFF”,  by  Brian  Kernighan, and by 1992 the AT&T
     [4mtroff[24m manual was updated to incorporate a description of it.

     [4mgroff[24m’s page description language is compatible with this specification ex‐
     cept in the following aspects.

     •  AT&T device‐independent [4mtroff[24m’s quasi‐device independence is not yet im‐
        plemented.

     •  The printing hardware of the early 1980s differed from today’s.  [4mgroff[24m’s
        output device names also differ from those of AT&T  [4mtroff[24m  For  example,
        the  PostScript  device  in  AT&T [4mtroff,[24m [1mpost [22m(implemented by the driver
        command [4mdpost[24m), has a resolution of only 720 units  per  inch,  suitable
        for  printers  of  decades  past.  [4mgroff[24m’s [1mps [22mdevice has a resolution of
        72000 units per inch.  In principle, by implementing a rescaling  mecha‐
        nism, [4mgroff[24m could come to emulate AT&T’s [1mpost [22mdevice.

     •  While  the  B‐spline  command [1mD~ [22mis reliably interpreted by [4mgroff[24m’s page
        description language parser, some output drivers don’t implement drawing
        routines for it.

     •  In GNU [4mtroff,[24m the argument to the commands [1ms [22mand [1mx H  [22muses  an  implicit
        unit  of scaled points [1mz [22mwhereas AT&T [4mtroff[24m uses spacing points [1mp[22m.  This
        isn’t an incompatibility, but a compatible extension, for both units co‐
        incide for any device without a [1msizescale [22mdirective in  its  [4mDESC[24m  file,
        including all postprocessors from AT&T and [4mgroff[24m’s text ([4mnroff[24m‐mode) de‐
        vices.   [4mgroff[24m  devices  that use [1msizescale [22meither do not exist for AT&T
        [4mtroff[24m have a different name, or seem to have a different resolution.  So
        conflicts are very unlikely.

     •  The drawing position after  the  commands  “[1mDp[22m”,  “[1mDP[22m”,  and  “[1mDt[22m”,  are
        processed  is illogical.  Since old versions of GNU [4mtroff[24m had this wart,
        we’ve retained it for compatibility, but may change it  in  the  future.
        Wrap these drawing commands with the [1m\Z [22mescape sequence to both overcome
        the  illogical  positioning and keep your input working consistently re‐
        gardless of the wart’s presence in the implementation.

     The differences  between  [4mgroff[24m  and  [4mclassical[24m  [4mtroff[24m  are  documented  in
     ]8;;man:groff_diff(7)\[4mgroff_diff[24m(7)]8;;\.

[1mFiles[0m
     [4m/usr/share/groff/1.24.1/font/dev[24mname[4m/DESC[0m
            describes the output device [4mname[24m.

[1mAuthors[0m
     James  Clark  wrote an early version of this document, which described only
     the differences between AT&T device‐independent  [4mtroff[24m’s  page  description
     language  and that of GNU [4mtroff[24m.  It has since been expanded and revised by
     ]8;;mailto:groff-bernd.warken-72@web.de\Bernd Warken]8;;\ and ]8;;mailto:g.branden.robinson@gmail.com\G. Branden Robinson]8;;\.

[1mSee also[0m
     [4mGroff:[24m [4mThe[24m [4mGNU[24m [4mImplementation[24m [4mof[24m [4mtroff[24m, by Trent A. Fisher and Werner  Lem‐
     berg,  is  the  primary [4mgroff[24m 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 device‐independent page description lan‐
     guage referred to collectively in [4mgroff[24m documentation as “AT&T [4mtroff[24m”.

     “A  Typesetter‐independent  TROFF”  by  Brian W. Kernighan, 1982, AT&T Bell
     Laboratories Computing Science Technical Report No. 97,  (CSTR  #97),  pro‐
     vides additional insights into the device and font description file formats
     and device‐independent page description language.

     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\
            documents the [1m-Z [22moption and contains pointers to further [4mgroff[24m docu‐
            mentation.

     ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\
            describes  the  [4mgroff[24m  language,  including its escape sequences and
            system of units.

     ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\
            details the scaling parameters of [4mDESC[24m (device description) files.

     ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\
            generates the language documented here.

     ]8;;man:roff(7)\[4mroff[24m(7)]8;;\
            presents historical aspects and the general structure of  [4mroff[24m  sys‐
            tems.

     ]8;;man:groff_diff(7)\[4mgroff_diff[24m(7)]8;;\
            enumerates  differences between the output of AT&T [4mtroff[24m and that of
            GNU [4mtroff[24m.

     ]8;;man:gxditview(1)\[4mgxditview[24m(1)]8;;\
            is a viewer for device‐independent [4mtroff[24m output.

     ]8;;https://github.com/Alhadis/Roff.js/\[4mRoff.js[24m]8;;\
            is  a  viewer  for  device‐independent  [4mtroff[24m  output   written   in
            JavaScript.

     ]8;;man:grodvi(1)\[4mgrodvi[24m(1)]8;;\,  ]8;;man:grohtml(1)\[4mgrohtml[24m(1)]8;;\,  ]8;;man:grolbp(1)\[4mgrolbp[24m(1)]8;;\,  ]8;;man:grolj4(1)\[4mgrolj4[24m(1)]8;;\,  ]8;;man:gropdf(1)\[4mgropdf[24m(1)]8;;\,  ]8;;man:grops(1)\[4mgrops[24m(1)]8;;\,  and
     ]8;;man:grotty(1)\[4mgrotty[24m(1)]8;;\ are [4mgroff[24m postprocessors.

groff 1.24.1                       2026‐03‐20                       [4mgroff_out[24m(5)
────────────────────────────────────────────────────────────────────────────────
[4mgroff_tmac[24m(5)                  File Formats Manual                 [4mgroff_tmac[24m(5)

[1mName[0m
     groff_tmac - macro files in the GNU [4mroff[24m typesetting system

[1mDescription[0m
     Definitions of macros, strings, and registers for use in a ]8;;man:roff(7)\[4mroff[24m(7)]8;;\ document
     can be collected into [4mmacro[24m [4mfiles[24m, [4mroff[24m input files designed to produce  no
     output themselves but instead ease the preparation of other [4mroff[24m documents.
     There  is no syntactical difference between a macro file and any other [4mroff[0m
     document; only its purpose distinguishes it.  When  a  macro  file  is  in‐
     stalled  at  a  standard location, named according to a certain convention,
     and suitable for use by a general audience, it is termed a  [4mmacro[24m  [4mpackage[24m.
     The  “tmac”  name  originated  in  early Unix culture as an abbreviation of
     “[4mtroff[24m macros”.

     Macro packages can be loaded by supplying the [1m-m [22moption to  ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\  or  a
     [4mgroff[24m  front  end.   A  macro  file’s name must have the form name[4m.tmac[24m (or
     [4mtmac.[24mname) and be placed in a “[4mtmac[24m directory” to be loadable with the  “[1m-m[0m
     [4mname[24m”  option.   Section “Environment” of ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ lists these directories.
     Alternatively, a [4mgroff[24m document requiring a macro file can load it with the
     [1mmso [22m(“macro source”) request.

     Macro files are named for their most noteworthy application,  but  a  macro
     file need not define any macros.  It can restrict itself to defining regis‐
     ters and strings or invoking other [4mgroff[24m requests.  It can even be empty.

     Encode  macro files in ISO 646:1991 IRV (US‐ASCII) or ISO Latin‐1 (8859‐1).
     To prepare for a future [4mgroff[24m  release  supporting  UTF‐8  input,  restrict
     files  to  ISO  646  codes.  ]8;;man:soelim(1)\[4msoelim[24m(1)]8;;\ by design does not interpret [1mmso [22mre‐
     quests, and the encodings used by documents  employing  a  macro  file  can
     vary.

[1mMacro packages[0m
     Some  macro  packages (“major” or “full‐service”) assume responsibility for
     page layout and other critical functions; others (“supplemental” or “auxil‐
     iary”) do not.  GNU [4mroff[24m provides most major macro packages found  in  AT&T
     and  BSD Unix systems, an additional full‐service package, and many supple‐
     mental packages.  Multiple full‐service macro packages cannot  be  used  by
     the same document.  Auxiliary packages can, in general, be freely combined,
     though attention to their use of the [4mgroff[24m language name spaces for identi‐
     fiers  (particularly  registers, macros, strings, and diversions) should be
     paid.  Name space management challenged AT&T [4mtroff[24m users; GNU [4mtroff[24m’s  sup‐
     port  for  arbitrarily long identifiers affords few excuses for name colli‐
     sions, apart from attempts at compatibility with the demands of  historical
     documents.

   [1mMan pages[0m
     Two  full‐service macro packages are specialized for formatting Unix refer‐
     ence manuals; they do not  support  features  like  footnotes  or  multiple
     columnation.

     [4man[24m       constructs  man  pages  in  a format introduced by Seventh Edition
              Unix (1979).  Its macro interface is small, and the package widely
              used; see ]8;;man:groff_man(7)\[4mgroff_man[24m(7)]8;;\.

     [4mdoc[24m      constructs man pages in a format introduced by 4.3BSD‐Reno (1990).
              It provides many more features than [4man[24m, but is also  larger,  more
              complex, and not as widely adopted; see ]8;;man:groff_mdoc(7)\[4mgroff_mdoc[24m(7)]8;;\.

     Because  readers of man pages often do not know in advance which macros are
     used to format a given document, a wrapper is available.

     [4mandoc[24m    recognizes a document’s use of [4man[24m or [4mdoc[24m and loads the correspond‐
              ing macro package.  Multiple man pages, in either format,  can  be
              handled; [4mandoc[24m reloads each macro package as necessary.

   [1mGeneral full‐service packages[0m
     The  following  packages each support composition of documents of any kind,
     from single‐page memos to lengthy monographs.  They are  similar  in  func‐
     tionality; select one that suits your taste.

     [4mme[24m     originates in 2BSD (1978); see ]8;;man:groff_me(7)\[4mgroff_me[24m(7)]8;;\.

     [4mmm[24m     originates  in  Programmer’s  Workbench  (PWB)  Unix 1.0 (1977); see
            ]8;;man:groff_mm(7)\[4mgroff_mm[24m(7)]8;;\.

     [4mmom[24m    was contributed to [4mgroff[24m in 2002, and freely exercises its many  ex‐
            tended features.  See ]8;;man:groff_mom(7)\[4mgroff_mom[24m(7)]8;;\.

     [4mms[24m     originates in Sixth Edition Unix (1975); see ]8;;man:groff_ms(7)\[4mgroff_ms[24m(7)]8;;\.

   [1mLocalization packages[0m
     For  Western  languages, an auxiliary package for localization sets the hy‐
     phenation mode and loads hyphenation patterns and exceptions.  Localization
     files can also adjust the date format and provide translations  of  strings
     used  by  some of the full‐service macro packages; alter the input encoding
     (see the next section); and change the amount  of  supplemental  inter‐sen‐
     tence  space.  For Eastern languages, the localization file defines charac‐
     ter classes and sets flags on them.  By default, [4mtroffrc[24m loads  the  local‐
     ization file for English.

     [4mtrans[24m  loads  localized  strings used by various macro packages after their
            localized forms have been prepared by a localization macro file.

     [4mgroff[24m provides the following localization files.

     [4mcs[24m     Czech; localizes [4mman[24m, [4mme[24m, [4mmm[24m, [4mmom[24m, and [4mms[24m.  Sets the input  encoding
            to Latin‐2 by loading [4mlatin2.tmac[24m.

     [4mde[0m
     [4mden[24m    German; localizes [4mman[24m, [4mme[24m, [4mmm[24m, [4mmom[24m, and [4mms[24m.  Sets the input encoding
            to Latin‐1 by loading [4mlatin1.tmac[24m.

            [4mde.tmac[24m  selects  hyphenation  patterns for traditional orthography,
            and [4mden.tmac[24m does the same for the new  orthography  (“Rechtschreib‐
            reform”).

     [4men[24m     English.  Sets the input encoding to Latin‐1 by loading [4mlatin1.tmac[24m.

     [4mes[24m     Spanish;  localizes [4mman[24m, [4mme[24m, [4mmm[24m, [4mmom[24m, and [4mms[24m.  Sets the input encod‐
            ing to Latin‐9 by loading [4mlatin9.tmac[24m.

     [4mfr[24m     French; localizes [4mman[24m, [4mme[24m, [4mmm[24m, [4mmom[24m, and [4mms[24m.  Sets the input encoding
            to Latin‐9 by loading [4mlatin9.tmac[24m.

     [4mit[24m     Italian; localizes [4mman[24m, [4mme[24m, [4mmm[24m, [4mmom[24m, and [4mms[24m.  Sets the input  encod‐
            ing to Latin‐1 by loading [4mlatin1.tmac[24m.

     [4mja[24m     Japanese.

     [4mpl[24m     Polish; localizes [4mman[24m, [4mme[24m, [4mmm[24m, [4mmom[24m, and [4mms[24m.  Sets the input encoding
            to Latin‐2 by loading [4mlatin2.tmac[24m.

     [4mru[24m     Russian;  localizes [4mman[24m, [4mme[24m, [4mmm[24m, [4mmom[24m, and [4mms[24m.  Sets the input encod‐
            ing to KOI8‐R by loading [4mkoi8‐r.tmac[24m.

     [4msv[24m     Swedish; localizes [4mman[24m, [4mme[24m, [4mmm[24m, [4mmom[24m, and [4mms[24m.  Sets the input  encod‐
            ing  to Latin‐1 by loading [4mlatin1.tmac[24m.  Some of the localization of
            the [4mmm[24m package is handled separately; see ]8;;man:groff_mmse(7)\[4mgroff_mmse[24m(7)]8;;\.

     [4mzh[24m     Chinese.

   [1mInput encodings[0m
     Localization influences automatic hyphenation in two distinct  but  related
     respects.   A  macro  file  specific to a character coding identifies which
     character codes correspond to letters expected in  the  language’s  hyphen‐
     ation  pattern  files  and  sets up case equivalences for those letters.  A
     language’s macro file determines which of these letters are  equivalent  to
     other letters for hyphenation purposes.

     For  example,  in  English,  the  letter  “ñ”  occurs  in  loan words.  The
     [4mlatin1.tmac[24m and [4mlatin9.tmac[24m macro files define a hyphenation code  for  “ñ”
     and  make “Ñ” equivalent to it.  The English localization file [4men.tmac[24m fur‐
     thermore makes “ñ” equivalent to “n”.  In Spanish ([4mes.tmac[24m),  however,  “ñ”
     and “n” are [4mnot[24m equivalent.  The language localization file loads an appro‐
     priate encoding localization file; a document need not do so directly.

     [4mlatin1[0m
     [4mlatin2[0m
     [4mlatin5[0m
     [4mlatin9[24m  support  the  ISO  Latin‐1, Latin‐2, Latin‐5, and Latin‐9 encodings
             (8859‐1, 8859‐2, 8859‐9, and 8859‐15, respectively).

     [4mkoi8-r[24m  supports the KOI8‐R encoding.  KOI8‐R  code  points  in  the  range
             0x80–0x9F  are  not  valid input to GNU [4mtroff[24m; see section “Identi‐
             fiers” in ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\.  This should be no impediment to practical doc‐
             uments, as these KOI8‐R code points do not encode letters, but box‐
             drawing symbols and characters that are better obtained via special
             character escape sequences; see ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\.

   [1mGeneral auxiliary packages[0m
     The macro packages in this section are not intended  for  stand‐alone  use,
     but  can  add  functionality to any other macro package or to plain (“raw”)
     [4mgroff[24m documents.

     [4m62bit[24m      provides macros for addition, multiplication,  and  division  of
                62‐bit  integers  (allowing safe multiplication of signed 31‐bit
                integers, for example).

     [4mhdtbl[24m      allows the generation of tables using a syntax  similar  to  the
                HTML  table model.  This Heidelberger table macro package is not
                a preprocessor, which can be useful if the contents of table en‐
                tries are determined by macro calls  or  string  interpolations.
                Compare to ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\.  It works only with the [1mps [22mand [1mpdf [22moutput de‐
                vices.  See ]8;;man:groff_hdtbl(7)\[4mgroff_hdtbl[24m(7)]8;;\.

     [4mpapersize[24m  enables  the paper format to be set on the command line with the
                “[1m-d paper=[4m[22mfmt[24m” option to [4mtroff[24m.  Valid [4mfmt[24ms are the ISO and  DIN
                formats “[1mA0[22m–[1mA6[22m”, “[1mB0[22m–[1mB6[22m”, “[1mC0[22m–[1mC6[22m”, and “[1mD0[22m–[1mD6[22m”; the U.S. formats
                “[1mletter[22m”,   “[1mlegal[22m”,   “[1mtabloid[22m”,   “[1mledger[22m”,  “[1mstatement[22m”,  and
                “[1mexecutive[22m”; and the envelope formats  “[1mcom10[22m”,  “[1mmonarch[22m”,  and
                “[1mDL[22m”.   All  formats,  even those for envelopes, are in portrait
                orientation: the longer measurement is vertical.  Appending  “l”
                (ell)  to  any  of  these denotes landscape orientation instead.
                This macro file assumes one‐inch horizontal  margins,  and  sets
                registers  recognized  by  the  [4mgroff[24m [4mman[24m, [4mmdoc[24m, [4mmm[24m, [4mmom[24m, and [4mms[0m
                packages to configure them accordingly.  If you  want  different
                margins,  you  will  need  to use those packages’ facilities, or
                [4mtroff[24m [1mll [22mand/or [1mpo [22mrequests, to adjust them.  An  output  device
                typically  requires  command‐line  options [1m-p [22mand [1m-l [22mto override
                the paper dimensions and orientation, respectively,  defined  in
                its  [4mDESC[24m file; see subsection “Paper format” of ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\.  This
                macro file is normally loaded at startup  by  the  [4mtroffrc[24m  file
                when formatting for a typesetter (but not a terminal).

     [4mpdfpic[24m     provides a single macro, [1mPDFPIC[22m, that operates in two modes.  If
                it is not used with [4mgropdf[24m, the given [4mfile[24m must be a PDF; [1mPDFPIC[0m
                then  relies  on  the external program ]8;;man:pdftops(1)\[4mpdftops[24m(1)]8;;\ to convert the
                PDF to an encapsulated PostScript (EPS) file and calls the [1mPSPIC[0m
                macro with which it shares an interface.  If output is to a  PDF
                document, [1mPDFPIC [22muses the “[1mpdf: pdfpic[22m” device extension command
                (see ]8;;man:gropdf(1)\[4mgropdf[24m(1)]8;;\); the given [4mfile[24m can then be a PDF or any graphic
                file format supported by [4mgropdf[24m.

                Since [1mPDFPIC [22mneeds to discover the width and height of the image
                (to check if sufficient room exists to place it on the page), it
                has dependencies on external programs as shown below.

                        ┌───────┬────────────┬─────────┬─────────────┐
                        │       │ [4mpdfinfo[24m(1) │ [4mfile[24m(1) │ [4midentify[24m(1) │
                        ├───────┼────────────┼─────────┼─────────────┤
                        │ [4m.pdf[24m  │     ✓      │    ✓    │      ✓      │
                        ├───────┼────────────┼─────────┼─────────────┤
                        │ [4m.jpg[24m  │     ✗      │    ✓    │      ✓      │
                        ├───────┼────────────┼─────────┼─────────────┤
                        │ [4m.jp2[24m  │     ✗      │    ✗    │      ✓      │
                        ├───────┼────────────┼─────────┼─────────────┤
                        │ other │     ✗      │    ✗    │      ✓      │
                        └───────┴────────────┴─────────┴─────────────┘

                To  include  image formats such as PNG, PAM, and GIF, [4mgropdf[24m re‐
                lies upon PerlMagick modules to embed the graphic.  They are not
                needed for the types listed in the table above.

                If the required programs are not available, [4mfile[24m is treated as a
                PDF; failure is likely if it is not one.

     [4mpic[24m        supplies definitions of the macros [1mPS[22m, [1mPE[22m, [1mPF[22m, and [1mPY[22m, used with
                the ]8;;man:pic(1)\[4mpic[24m(1)]8;;\ preprocessor.  They center each picture.  Use  it  if
                your document does not use a full‐service macro package, or that
                package  does  not supply working [4mpic[24m macro definitions.  Except
                for [4mman[24m and [4mmdoc[24m, those provided with [4mgroff[24m already do  so  (ex‐
                ception: [4mmm[24m employs the name [1mPF [22mfor a different purpose).

     [4mpspic[24m      provides a macro, [1mPSPIC[22m, that includes a PostScript graphic in a
                document.   The  [1mps[22m, [1mdvi[22m, [1mhtml[22m, and [1mxhtml [22moutput devices support
                such inclusions; for all other drivers, the  image  is  replaced
                with  a  rectangular  border  of  the  same size.  [4mpspic.tmac[24m is
                loaded at startup by the [4mtroffrc[24m file.

                Its syntax is as follows.

                       [1m.PSPIC [22m[[1m-L[22m|[1m-R[22m|[1m-C[22m|[1m-I [4m[22mn[24m] [4mfile[24m [[4mwidth[24m [[4mheight[24m]]

                [4mfile[24m is the name of the PostScript file; [4mwidth[24m and  [4mheight[24m  give
                the  desired  width and height of the image.  If neither a [4mwidth[0m
                nor a [4mheight[24m argument is specified, the  image’s  natural  width
                (as given in the file’s bounding box) or the current line length
                is used as the width, whatever is smaller.  The [4mwidth[24m and [4mheight[0m
                arguments  may  have scaling units attached; the default scaling
                unit is [1mi[22m.  [1mPSPIC [22mscales the graphic uniformly in the horizontal
                and vertical directions so that it is no more  than  [4mwidth[24m  wide
                and  [4mheight[24m  high.   Option [1m-C [22mcenters the graphic horizontally;
                this is the default.   [1m-L  [22mand  [1m-R  [22mleft‐  and  right‐align  the
                graphic,  respectively.  [1m-I [22mindents the graphic by [4mn[24m (with a de‐
                fault scaling unit of [1mm[22m).

                To use [1mPSPIC [22mwithin a diversion, we recommend extending it  with
                the  following  code,  assuring  that the diversion’s width com‐
                pletely covers the image’s width.

                       .am PSPIC
                       .  vpt 0
                       \h'(\\n[ps-offset]u + \\n[ps-deswid]u)'
                       .  sp -1
                       .  vpt 1
                       ..

                Failure to load [1mPSPIC[22m’s image argument is not  an  error.   (The
                [1mpsbb  [22mrequest  does  issue an error diagnostic.)  To make such a
                failure fatal, append to the [1mpspic*error-hook [22mmacro.

                       .am pspic*error-hook
                       .  ab
                       ..

     [4mptx[24m        provides a macro, [1mxx[22m, to format permuted index entries  as  pro‐
                duced  by the GNU ]8;;man:ptx(1)\[4mptx[24m(1)]8;;\ program.  If your formatting needs dif‐
                fer, copy the macro into your document and adapt it.

     [4mrfc1345[24m    defines special character escape sequences named for  the  glyph
                mnemonics specified in RFC 1345 and the digraph table of the Vim
                text editor.  See ]8;;man:groff_rfc1345(7)\[4mgroff_rfc1345[24m(7)]8;;\.

     [4msboxes[24m     offers  an  interface  to the “[1mpdf: background[22m” device extension
                command supported by ]8;;man:gropdf(1)\[4mgropdf[24m(1)]8;;\.  Using this  package,  [4mgroff[24m  [4mms[0m
                documents can draw colored rectangles beneath any output.

                [1m.BOXSTART SHADED [4m[22mcolor[24m [1mOUTLINED [4m[22mcolor[24m [1mINDENT [4m[22msize[24m [1mWEIGHT [4m[22msize[0m
                       begins  a  box, where the argument after [1mSHADED [22mgives the
                       fill color and that  after  [1mOUTLINED  [22mthe  border  color.
                       Omit  the  former  to get a borderless filled box and the
                       latter for a border with no fill.  The  specified  [1mWEIGHT[0m
                       is used if the box is [1mOUTLINED[22m.

                       [1mINDENT  [22mprecedes  a  value  that leaves a gap between the
                       border and the contents inside the box.

                       Each [4mcolor[24m must be a defined [4mgroff[24m color name,  and  each
                       [4msize[24m a valid [4mgroff[24m numeric expression.  The keyword/value
                       pairs can be specified in any order.

                Boxes can be stacked, so you can start a box within another box;
                usually  the  later  boxes  would be smaller than the containing
                box, but this is not enforced.  When using  [1mBOXSTART[22m,  the  left
                position  is the current indent minus the [1mINDENT [22min the command,
                and the right position is the left position  (calculated  above)
                plus the current line length and twice the indent.

                [1m.BOXSTOP[0m
                       takes no parameters.  It closes the most recently started
                       box  at  the  current  vertical position after adding its
                       [1mINDENT [22mspacing.

                Your [4mgroff[24m  documents  can  conditionally  exercise  the  [4msboxes[0m
                macros.  The register [1mGSBOX [22mis defined if the package is loaded,
                and  interpolates  a  true  value if the [1mpdf [22moutput device is in
                use.

                [4msboxes[24m furthermore hooks into the ]8;;man:groff_ms(7)\[4mgroff_ms[24m(7)]8;;\ package to receive
                notifications when footnotes are growing, so that it  can  close
                boxes  on a page before footnotes are printed.  When that condi‐
                tion obtains, [4msboxes[24m will close open boxes two points above  the
                footnote  separator  and  re‐open  them on the next page.  (This
                amount probably will not match the box’s [1mINDENT[22m.)

                See ]8;;file:///usr/share/doc/groff-1.24.1/msboxes.pdf\“Using PDF boxes with [4mgroff[24m and the [4mms[24m macros”]8;;\ for a  demon‐
                stration.

     [4mtrace[24m      aids  the  debugging  of [4mgroff[24m documents by tracing macro calls.
                See ]8;;man:groff_trace(7)\[4mgroff_trace[24m(7)]8;;\.

     [4mwww[24m        defines   macros   corresponding   to   HTML   elements.     See
                ]8;;man:groff_www(7)\[4mgroff_www[24m(7)]8;;\.

[1mNaming[0m
     AT&T  [4mnroff[24m and [4mtroff[24m were implemented before the conventions of the modern
     C ]8;;man:getopt(3)\[4mgetopt[24m(3)]8;;\ call evolved, and used a naming scheme for macro packages  that
     looks  oddly  terse to modern eyes.  The formatter’s [1m-m [22moption was the main
     means of loading a macro package, and its argument had  to  follow  immedi‐
     ately  without intervening space.  This looked like a long option name pre‐
     ceded by a single minus——a sensation in  the  computer  stone  age.   Macro
     packages  therefore  came to be known by names that started with the letter
     “m”, which was omitted from the name of the macro file as stored  on  disk.
     For  example,  the manuscript macro package was stored as [4mtmac.s[24m and loaded
     with the option [1m-ms[22m.  It has since become conventional in operating systems
     to use a suffixed file name extension to suggest a  file  type  or  format,
     thus we see [4mroff[24m documents with names ending in [4m.man[24m, [4m.me[24m, and so on.

     [4mgroff[24m commands permit space between an option and its argument.  The syntax
     “[1mgroff  -m  s[22m”  makes the macro file name more clear but may surprise users
     familiar with the original convention, unaware that  the  package’s  “real”
     name was “s” all along.  For such packages of long pedigree, [4mgroff[24m accommo‐
     dates  different  users’ expectations by supplying wrapper macro files that
     load the desired file with [1mmso [22mrequests.  Thus, all of “[1mgroff -m s[22m”, “[1mgroff[0m
     [1m-m ms[22m”, “[1mgroff -ms[22m”, and “[1mgroff -mms[22m” serve to load the manuscript macros.

[1mInclusion[0m
     The traditional method of employing a macro package is to specify  the  “[1m-m[0m
     [4mpackage[24m”  option  to  the  formatter, which then reads [4mpackage[24m’s macro file
     prior to any input.  Historically, [4mpackage[24m  was  sought  in  a  file  named
     [4mtmac.[24mpackage  (that  is,  with  a  “[1mtmac.[22m” prefix).  GNU [4mtroff[24m searches for
     package[4m.tmac[24m in the macro path; if not found, it looks for [4mtmac.[24mpackage in‐
     stead, and vice versa.

     Alternatively, one could include a macro file with the  request  “[1mso  [4m[22mfile‐[0m
     [4mname[24m”; the argument is resolved as ]8;;man:fopen(3)\[4mfopen[24m(3)]8;;\ would, from the current working
     directory  of  the formatter.  This approach was inadequate to locate macro
     packages, since systems stored them in varying locations.  GNU [4mtroff[24m offers
     an improved feature in the similar request “[1mmso  [4m[22mpackage‐file‐name[24m”,  which
     searches  the  macro path for [4mpackage‐file‐name[24m.  Because its argument is a
     file name, its “[1m.tmac[22m” component must be included for the file to be found.

     If a sourced file requires preprocessing, for example if  it  includes  [4mtbl[0m
     tables or [4meqn[24m equations, the preprocessor ]8;;man:soelim(1)\[4msoelim[24m(1)]8;;\ must be used.  This can
     be  achieved  with  a  pipeline or by specifying the [1m-s [22moption to ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\.
     ]8;;man:man(1)\[4mman[24m(1)]8;;\ librarian programs typically run [4msoelim[24m automatically.  (As a  rule,
     macro packages themselves do not require preprocessing.)

[1mWriting macros[0m
     A ]8;;man:roff(7)\[4mroff[24m(7)]8;;\ document is a text file that is enriched by predefined formatting
     constructs, such as requests, escape sequences, strings, numeric registers,
     and macros from a macro package.  ]8;;man:roff(7)\[4mroff[24m(7)]8;;\ describes these elements.

     To give a document a personal style, it is most useful to extend the exist‐
     ing  elements  by  defining some macros for repeating tasks; the best place
     for this is near the beginning of the document or in a separate file.

     Macros without arguments are just like strings.   But  the  full  power  of
     macros  occurs  when  arguments  are  passed with a macro call.  Within the
     macro definition, the arguments are available as the escape sequences  [1m\$1[22m,
     ...,  [1m\$9[22m, [1m\$[[22m...[1m][22m, [1m\$*[22m, and [1m\$@[22m, the name under which the macro was called
     is in [1m\$0[22m, and the number of arguments is in register [1m\n[.$][22m; see ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\.

   [1mDrafting macros[0m
     One approach temporarily disables escape sequences by  bracketing  a  macro
     definition with [1meo [22mand [1mec [22mrequests.

            .eo
            .ds midpart was called with the following
            .de print_args
            \f[I]\$0\f[] \*[midpart] \n[.$] arguments: \$*
            ..
            .ec

     The  above procedure has limitations; it is unsuitable for a macro that re‐
     quires certain interpolations at the time it is defined,  or  for  indirect
     definitions  of identifiers.  See section “Copy mode” of ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\.  In such
     cases, you might define and test the macro with the escape  character  dou‐
     bled  before  escape sequences that are interpreted even in copy mode, then
     bracket it with [1meo [22mand [1mec [22mrequests, un‐double the escape  characters,  then
     test again.

   [1mTips for macro definitions[0m
     •  Use  only control lines in macro definitions; that is, start every input
        line with a control character.  [4mgroff[24m’s [1mnop [22mrequest makes  use  of  text
        lines unnecessary.

               .de Text
               .  if (\\n[.$] == 0) \
               .    return
               .  nop \&\\$*\&
               ..

     •  Write  a  comment  macro  that  works in both draft and non‐draft modes;
        since the escape character is disabled in draft mode, trouble might  oc‐
        cur when comment escape sequences are used.

               .de c
               ..
               .c This is my comment.

     •  Comment lengthy macro definitions.

     •  Use empty requests, and indentation after control characters, to clarify
        a macro’s structure.

[1mAuthors[0m
     This document was written by ]8;;mailto:wl@gnu.org\Werner Lemberg]8;;\ and ]8;;mailto:g.branden.robinson@gmail.com\G. Branden Robinson]8;;\.

[1mSee also[0m
     [4mGroff:[24m  [4mThe[24m [4mGNU[24m [4mImplementation[24m [4mof[24m [4mtroff[24m, by Trent A. Fisher and Werner Lem‐
     berg, is the primary [4mgroff[24m manual.  You can browse  it  interactively  with
     “info groff”.

     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\          is an overview of the [4mgroff[24m system.

     ]8;;man:groff_man(7)\[4mgroff_man[24m(7)]8;;\,
     ]8;;man:groff_mdoc(7)\[4mgroff_mdoc[24m(7)]8;;\,
     ]8;;man:groff_me(7)\[4mgroff_me[24m(7)]8;;\,
     ]8;;man:groff_mm(7)\[4mgroff_mm[24m(7)]8;;\,
     ]8;;man:groff_mom(7)\[4mgroff_mom[24m(7)]8;;\,
     ]8;;man:groff_ms(7)\[4mgroff_ms[24m(7)]8;;\,
     ]8;;man:groff_rfc1345(7)\[4mgroff_rfc1345[24m(7)]8;;\,
     ]8;;man:groff_trace(7)\[4mgroff_trace[24m(7)]8;;\,
     and
     ]8;;man:groff_www(7)\[4mgroff_www[24m(7)]8;;\      are [4mgroff[24m macro packages.

     ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\          summarizes the language recognized by GNU [4mtroff[24m.

     ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\          documents the default macro file search path.

groff 1.24.1                       2026‐03‐20                      [4mgroff_tmac[24m(5)
────────────────────────────────────────────────────────────────────────────────
[4mgroff[24m(7)                Miscellaneous Information Manual                [4mgroff[24m(7)

[1mName[0m
     groff - GNU [4mroff[24m language reference

[1mDescription[0m
     [4mgroff[24m is short for GNU [4mroff[24m, a free reimplementation of the AT&T device‐in‐
     dependent  [4mtroff[24m typesetting system.  See ]8;;man:roff(7)\[4mroff[24m(7)]8;;\ for a survey of and back‐
     ground on [4mroff[24m systems.

     This document is intended as a reference.  The primary [4mgroff[24m manual, [4mGroff:[0m
     [4mThe[24m [4mGNU[24m [4mImplementation[24m [4mof[24m [4mtroff[24m, by Trent A. Fisher and Werner Lemberg,  is
     a  better  resource for learners, containing many examples and much discus‐
     sion.  It is written in Texinfo; you can browse it interactively with “info
     groff”.  Additional formats, including plain text, HTML, TeX DVI, and  PDF,
     may be available in [4m/usr/share/doc/groff-1.24.1[24m.

     We  apply  the term “groff” to the language documented here, the GNU imple‐
     mentation of the overall system, the project that develops that system, and
     the command of that name.  In the first sense, [4mgroff[24m is an extended dialect
     of the [4mroff[24m language, for which many similar implementations exist.

     GNU [4mtroff[24m, installed on this system as ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\, is the [4mformatter:[24m  a  pro‐
     gram  that  reads  device and font descriptions (]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\), interprets
     the [4mgroff[24m language expressed in input text, and translates it  into  a  de‐
     vice‐independent  page  description language (]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\) that is usually
     then post‐processed by an output driver to produce PostScript,  PDF,  HTML,
     DVI,  or  terminal output.  We speak of “the formatter” when describing be‐
     havior that is generally true of [4mtroff[24m and [4mnroff[24m programs.

[1mInput format[0m
     Organize input to GNU [4mtroff[24m into lines separated by the Unix newline  char‐
     acter  (U+000A),  using  the  character encoding it recognizes: ISO Latin‐1
     (8859‐1).  We recommend use of ISO  646:1991  IRV  (US‐ASCII)  or  (equiva‐
     lently) the Basic Latin subset of ISO 10646 (Unicode); see ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\.

     Some  control  characters (from the sets “C0 Controls” and “C1 Controls” as
     Unicode describes them) are invalid as input characters.   GNU  [4mtroff[24m  dis‐
     cards them upon reading.  (It also emits a warning in category “input”; see
     section  “Warnings” of ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\.)  It processes a character sequence “foo”,
     followed by an invalid character and then “bar”, as “foobar”.

     Invalid input characters comprise [1m0x00[22m,  [1m0x0B[22m,  [1m0x0D[22m–[1m0x1F[22m,  and  [1m0x80[22m–[1m0x9F[22m.
     (Historically,  control characters like ASCII STX, ETX, and BEL (Control+B,
     Control+C, and Control+G) respectively) have been observed  in  [4mroff[24m  docu‐
     ments, particularly in macro packages employing them as delimiters with the
     output  comparison  operator to try to avoid collisions with the content of
     arbitrary user‐supplied parameters  (see  subsection  “Conditional  expres‐
     sions”  below).   We discourage this expedient; in GNU [4mtroff[24m it is unneces‐
     sary (outside of compatibility mode) because the program  parses  delimited
     arguments  at  a different input level than their surrounding context.  See
     section “Miscellaneous” of ]8;;man:groff_diff(7)\[4mgroff_diff[24m(7)]8;;\.)  GNU [4mtroff[24m uses  some  of  these
     code  points for internal purposes, making non‐trivial the extension of the
     program to accept UTF‐8 or other encodings that use characters  from  these
     ranges.

[1mSyntax characters[0m
     Several  input characters are syntactically significant to [4mgroff[24m.  The most
     important of these distinguish [4mcontrol[24m [4mlines,[24m which instruct the formatter,
     from [4mtext[24m [4mlines[24m that are formatted as output.

     .   A dot at the beginning of an input line marks it as a control line.  It
         can also follow the [1mel [22mand [1mnop [22mrequests, and the condition in “[1mif[22m”, [1mie[22m,
         and “[1mwhile[22m” requests.  The control character invokes requests and calls
         macros by the name that follows it.  The [1mcc [22mrequest can change the con‐
         trol character.

     '   The neutral apostrophe is the [4mno‐break[24m  [4mcontrol[24m  [4mcharacter,[24m  recognized
         where  the  control  character is.  It suppresses the (first) break im‐
         plied by the [1mbp[22m, [1mce[22m, [1mcf[22m, [1mfi[22m, [1mfl[22m, “[1min[22m”, [1mnf[22m, [1mrj[22m,  [1msp[22m,  [1mti[22m,  and  [1mtrf  [22mre‐
         quests.   The  requested  operation takes effect at the next break.  It
         makes [1mbr [22mand [1mbrp [22mnilpotent.  The  no‐break  control  character  can  be
         changed  with  the [1mc2 [22mrequest.  When formatted, “[1m'[22m” may be typeset as a
         typographical quotation mark; use the [1m\[aq]  [22mspecial  character  escape
         sequence to format a neutral apostrophe glyph.

     "   The neutral double quote can be used to enclose arguments to macros and
         strings,  and is required if those arguments contain space or tab char‐
         acters.  The requests “[1mas[22m”, [1mas1[22m, [1mcf[22m, [1mchar[22m, [1mds[22m, [1mds1[22m, [1mfchar[22m, [1mfschar[22m, [1mmso[22m,
         [1mmsoquiet[22m, [1mnx[22m, “[1mopen[22m”, [1mopena[22m, [1mpi[22m, [1mschar[22m,  “[1mso[22m”,  [1msoquiet[22m,  [1msy[22m,  and  [1mtrf[0m
         strip  a leading neutral double quote from their final arguments to al‐
         low embedding of leading spaces.  All such arguments are “strings” in a
         general sense, representing character sequences, file names,  operating
         system  commands,  or parameters to an output device extension command.
         To include a double quote inside a quoted argument, use the [1m\[dq]  [22mspe‐
         cial  character escape sequence (which also serves to typeset the glyph
         in text).

     \   A backslash introduces an escape sequence.  The escape character can be
         changed with the [1mec [22mrequest; [1meo [22mdisables escape  sequence  recognition.
         Use  the  [1m\[rs] [22mspecial character escape sequence to format a backslash
         glyph, and [1m\e [22mto typeset the glyph of the current escape character.

     (   An opening parenthesis is special only  in  certain  escape  sequences;
         when  recognized,  it introduces an argument of exactly two characters.
         [4mgroff[24m offers the more flexible square bracket syntax.

     [   An opening bracket is special only in certain  escape  sequences;  when
         recognized, it introduces an argument (list) of any length, not includ‐
         ing a closing bracket.

     ]   A  closing  bracket  is  special  only when an escape sequence using an
         opening bracket as an argument delimiter is being interpreted.  It ends
         the argument (list).

     Additionally, the Control+A character (U+0001) in text is interpreted as  a
     [4mleader[24m (see below).

     Horizontal  whitespace  characters  are  significant to [4mgroff,[24m but trailing
     spaces on text lines are ignored.

     [4mspace[24m    On control lines and within  bracketed  escape  sequences,  spaces
              separate arguments.  On text lines, they separate words.  Multiple
              adjacent  space  characters in text cause [4mgroff[24m to attempt end‐of‐
              sentence detection on the preceding word  (and  trailing  punctua‐
              tion).   The  amount  of space between words and sentences is con‐
              trolled by the [1mss [22mrequest.  When filling is enabled (the default),
              a line may be broken at a space.  When adjustment is enabled  (the
              default),  inter‐word  spaces  are  expanded until the output line
              reaches the configured length.   An  adjustable  but  non‐breaking
              space  is  available  with [1m\~[22m.  To get a space of fixed width, use
              one of the escape sequences ‘[1m\ [22m’ (the escape character followed by
              a space), [1m\0[22m, [1m\|[22m, [1m\^[22m, or [1m\h[22m; see section “Escape sequences” below.

     [4mnewline[24m  On text lines, a newline formats an inter‐word space and, if fill‐
              ing is enabled, triggers end‐of‐sentence recognition on  the  pre‐
              ceding text.  See section “Line continuation” below.

     [4mtab[24m      A  tab character on a text line causes the drawing position to ad‐
              vance to the next defined tab stop.

[1mSentences[0m
     Configure the sets of characters that  potentially  end  sentences  or  are
     transparent  to  sentence  endings with the [1mcflags [22mrequest.  Use the [1mss [22mre‐
     quest to change——or eliminate——supplemental inter‐sentence space.

[1mTabs and leaders[0m
     The formatter interprets input horizontal tab characters (“tabs”) and  Con‐
     trol+A  characters  (“leaders”)  into movements to the next tab stop.  Tabs
     simply move to the next tab stop; leaders place enough periods to fill  the
     space.   Tab stops are by default located every half inch measured from the
     drawing position corresponding to the beginning of the input line; see sec‐
     tion “Page geometry” of ]8;;man:roff(7)\[4mroff[24m(7)]8;;\.  Tabs and leaders do not cause breaks  and
     therefore  do  not interrupt filling.  Tab stops can be configured with the
     [1mta [22mrequest, and tab and leader glyphs with the [1mtc [22mand [1mlc [22mrequests,  respec‐
     tively.

[1mLine continuation[0m
     When filling is enabled, input and output line breaks generally do not cor‐
     respond.   The  [4mroff[24m language therefore distinguishes input and output line
     continuation.

     A backslash [1m\ [22mimmediately followed by a  newline,  sometimes  discussed  as
     [1m\[4m[22mnewline[24m,  suppresses  the  effects of that newline on the input.  The next
     input line thus retains the classification of its predecessor as a  control
     or  text  line.   [1m\[4m[22mnewline[24m is useful for managing line lengths in the input
     during document maintenance; you can break an input line at a space, or  in
     the  middle  of a word, request invocation, macro call, or escape sequence.
     Input line continuation is invisible to the formatter, with two exceptions:
     the [1m| [22moperator recognizes the new input line, and the  input  line  counter
     register [1m.c [22mincrements.

     The [1m\c [22mescape sequence continues an [4moutput[24m line.  Nothing on the input line
     after it is formatted.  In contrast to [1m\[4m[22mnewline[24m, a line after [1m\c [22mis treated
     as a new input line, so a control character is recognized at its beginning.
     The  visual  results  depend on whether filling is enabled.  An intervening
     control line that causes a break overrides [1m\c[22m,  flushing  out  the  pending
     output  line  in  the usual way.  The register [1m.int [22minterpolates a positive
     value only if the pending output line has been continued with [1m\c[22m; this  da‐
     tum is associated with the environment.

[1mColors[0m
     [4mgroff[24m  supports  color  output  with a variety of color spaces and up to 16
     bits per channel.  Some devices, particularly terminals, may be  more  lim‐
     ited.   When  color support is enabled, two colors are current at any given
     time: the [4mstroke[24m [4mcolor,[24m with which glyphs, rules (lines), and geometric ob‐
     jects like circles and polygons are drawn, and the [4mfill[24m [4mcolor,[24m which can be
     used to paint the interior  of  a  closed  geometric  figure.   The  [1mcolor[22m,
     [1mdefcolor[22m,  [1mgcolor[22m,  and  [1mfcolor  [22mrequests;  [1m\m [22mand [1m\M [22mescape sequences; and
     [1m.color[22m, [1m.m[22m, and [1m.M [22mregisters exercise color support.

     Each output device has a color named “[1mdefault[22m”, which cannot be  redefined.
     A  device’s  default  stroke  and fill colors are not necessarily the same.
     For the [1mdvi[22m, [1mhtml[22m, [1mpdf[22m, [1mps[22m, and [1mxhtml [22moutput devices,  [4mtroff[24m  automatically
     loads a macro file defining many color names at startup.  By the same mech‐
     anism,  the  devices  supported  by  ]8;;man:grotty(1)\[4mgrotty[24m(1)]8;;\ recognize the eight standard
     ISO 6429/ECMA‐48 color names.  (These are known vulgarly as “ANSI”  colors,
     after its X3.64 standard, now withdrawn.)

[1mMeasurements[0m
     Express numeric parameters that specify measurements as integers or decimal
     fractions with an optional scaling unit suffixed.  A [4mscaling[24m [4munit[24m is a let‐
     ter  that immediately follows the magnitude of a measurement.  Digits after
     the decimal point are optional.

     The formatter scales measurements by the specified  scaling  unit,  storing
     them  internally  (with any fractional part discarded) in basic units.  The
     device resolution can therefore be obtained by storing a value of “[1m1i[22m” to a
     register, then reading the register.

     [1mu      [22mBasic unit; it is at least as small as any other unit.
     [1mi      [22mInch; defined as 2.54 centimeters.
     [1mc      [22mCentimeter.
     [1mp      [22mPoint; a typesetter’s unit used for measuring type size.  There  are
            72 points to an inch.
     [1mP      [22mPica;  another  typesetter’s unit.  There are 6 picas to an inch and
            12 points to a pica.
     [1mz      [22mTypographical point; like [1mp[22m, but used only with type sizes, to over‐
            come a limitation of AT&T [4mtroff[24m.
     [1ms      [22mScaled point.
     [1mf      [22mMultiplication by 65,536; scales decimal fractions in  the  interval
            [0, 1] to 16‐bit unsigned integers.

     The magnitudes of other scaling units depend on the text formatting parame‐
     ters in effect.

     [1mm      [22mEm; an em is equal to the current type size in points.
     [1mn      [22mEn;  on  typesetters,  an  en is one‐half em, but on terminals an en
            equals an em.
     [1mv      [22mVee; distance between text baselines.
     [1mM      [22mHundredth of an em.

   [1mMotion quanta[0m
     The basic unit [1mu [22mis not necessarily an output device’s smallest addressable
     length; [1mu [22mcan be smaller to avoid integer  rounding  errors.   The  minimum
     distances that a device can work with in the horizontal and vertical direc‐
     tions  are termed its [4mmotion[24m [4mquanta,[24m stored in the [1m.H [22mand [1m.V [22mregisters, re‐
     spectively.  The formatter rounds measurements to applicable motion quanta.
     Half‐quantum fractions round toward zero.

   [1mDefault units[0m
     A general‐purpose register (one created or updated with the [1mnr [22mrequest; see
     section “Registers” below) is implicitly dimensionless, or reckoned in  ba‐
     sic  units  if  interpreted in a measurement context.  But it is convenient
     for many requests and escape sequences to infer a scaling unit for an argu‐
     ment if none is specified.  An explicit scaling unit (not after  a  closing
     parenthesis) can override an undesirable default.  Effectively, the default
     unit  is  suffixed  to  the  expression  if  a  scaling unit is not already
     present.  GNU [4mtroff[24m’s use of  integer  arithmetic  in  numeric  expressions
     should also be kept in mind.

[1mNumeric expressions[0m
     When  evaluated,  a  [4mnumeric[24m [4mexpression[24m interpolates an integer.  GNU [4mtroff[0m
     recognizes the following operators.

           +   addition
           -   subtraction
           *   multiplication
           /   truncating division
           %   modulus
     ────────────────────────────────────────────
     unary +   assertion, motion, incrementation
     unary -   negation, motion, decrementation
     ────────────────────────────────────────────
           ;   scaling
          >?   maximum
          <?   minimum
     ────────────────────────────────────────────
           <   less than
           >   greater than
          <=   less than or equal
          >=   greater than or equal
           =   equal
          ==   equal
     ────────────────────────────────────────────
           &   logical conjunction (“and”)
           :   logical disjunction (“or”)
           !   logical complementation (“not”)
     ────────────────────────────────────────────
         ( )   precedence
     ────────────────────────────────────────────
           |   boundary‐relative measurement

     [4mtroff[24m provides a set of mathematical and logical operators familiar to pro‐
     grammers——as well as some unusual ones——but supports  only  integer  arith‐
     metic.  (Provision is made for interpreting and reporting decimal fractions
     in  certain  cases.)  The internal data type used for computing results de‐
     pends on the host machine but is at least a 32‐bit  signed  integer,  which
     suffices  to represent magnitudes within a range of ±2 billion.  (If that’s
     not enough, see ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\ for the [4m62bit.tmac[24m  macro  package.)   Arith‐
     metic  saturates.   (If  overflow would occur, GNU [4mtroff[24m emits a warning in
     category “[1mrange[22m”.  See section “Warnings” of ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\.)

     Arithmetic infix operators perform a function on the numeric expressions to
     their left and right; they are [1m+ [22m(addition), [1m- [22m(subtraction), [1m*  [22m(multipli‐
     cation),  [1m/  [22m(truncating  division),  and [1m% [22m(modulus).  [4mTruncating[24m [4mdivision[0m
     rounds to the integer nearer to zero, no matter how  large  the  fractional
     portion.  Division and modulus by zero are errors and abort evaluation of a
     numeric expression.

     Arithmetic  unary  operators  operate  on  the  numeric expression to their
     right; they are [1m- [22m(negation) and [1m+ [22m(assertion——for  completeness;  it  does
     nothing).   The  unary  minus  must often be used with parentheses to avoid
     confusion with the decrementation operator, discussed below.

     The sign of the modulus of operands of mixed signs  is  determined  by  the
     sign  of  the  first.  Division and modulus operators satisfy the following
     property: given a dividend [4ma[24m and a divisor [4mb[24m, a quotient [4mq[24m formed by “[1m(a  /[0m
     [1mb)[22m” and a remainder [4mr[24m by “[1m(a % b)[22m”, then [4mqb[24m + [4mr[24m = [4ma[24m.

     GNU  [4mtroff[24m’s  scaling operator, used with parentheses as [1m([4m[22mc[24m[1m;[4m[22me[24m[1m)[22m, evaluates a
     numeric expression [4me[24m using [4mc[24m as the default scaling unit.  If [4mc[24m is omitted,
     scaling units are ignored in the evaluation of [4me[24m.  GNU [4mtroff[24m also  provides
     a  pair  of operators to compute the extremum of two operands: [1m>? [22m(maximum)
     and [1m<? [22m(minimum).

     Comparison operators comprise [1m< [22m(less than), [1m>  [22m(greater  than),  [1m<=  [22m(less
     than  or  equal),  [1m>= [22m(greater than or equal), and [1m= [22m(equal, with a synonym
     [1m==[22m).  When evaluating a comparison, the formatter replaces it with  “[1m0[22m”  if
     it  is  false  and  “[1m1[22m” if true.  In the [4mroff[24m language, positive values are
     true, others false.

     Operate on truth values with the logical operators [1m&  [22m(logical  conjunction
     or “and”) and [1m: [22m(logical disjunction or “or”).  They evaluate as comparison
     operators  do.   A  logical complementation (“not”) operator, [1m!, [22mworks only
     within “[1mif[22m”, “[1mie[22m”, and “[1mwhile[22m” requests.  Furthermore, the formatter recog‐
     nizes [1m! [22monly at the beginning of a numeric expression not contained by  an‐
     other numeric expression.  In other words, [1m! [22mmust be the “outermost” opera‐
     tor.  Its presence elsewhere causes the expression to evaluate false.  (GNU
     [4mtroff[24m  emits  a  warning  in  category “[1mnumber[22m”.  See section “Warnings” of
     ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\.)  This unfortunate limitation maintains compatibility  with  AT&T
     [4mtroff[24m.   Test  a numeric expression for falsity within a complex expression
     by comparing it to a false value.

     The [4mroff[24m language has no operator  precedence:  expressions  are  evaluated
     strictly  from  left  to right, in contrast to schoolhouse arithmetic.  Use
     parentheses [1m( ) [22mto impose a desired precedence upon subexpressions.

     For many requests and escape sequences that cause motion on the  page,  the
     unary operators [1m+ [22mand [1m- [22mwork differently when leading a numeric expression.
     They  then  indicate a motion relative to the drawing position: positive is
     down in vertical contexts, right in horizontal ones.

     [1m+ [22mand [1m- [22mare also treated differently by the following requests  and  escape
     sequences:  [1mbp[22m, [1min[22m, [1mll[22m, [1mpl[22m, [1mpn[22m, [1mpo[22m, [1mps[22m, [1mpvs[22m, [1mrt[22m, [1mti[22m, [1m\H[22m, [1m\R[22m, and [1m\s[22m.  Here,
     leading plus and minus signs serve as incrementation and decrementation op‐
     erators, respectively.  To negate an expression in these contexts, subtract
     it from zero or include the unary minus in parentheses with its argument.

     A leading [1m| [22moperator indicates a motion relative not to the  drawing  posi‐
     tion  but to a boundary.  For horizontal motions, the measurement specifies
     a distance relative to a drawing position corresponding to the beginning of
     the [4minput[24m line.  By default, tab stops reckon movements in this way.   Most
     escape  sequences do not; [1m| [22mtells them to do so.  For vertical motions, the
     [1m| [22moperator specifies a distance from the first text baseline on the page or
     in the current diversion, using the current vertical spacing.

     The delimited escape sequence [1m\B [22mtests its argument for validity as  a  nu‐
     meric expression.

     A  register interpolated as an operand in a numeric expression must have an
     Arabic format; luckily, this is the default.

     Because spaces separate arguments to requests, spaces are  not  allowed  in
     numeric  expressions  unless  parentheses surround the (sub)expression con‐
     taining them.

[1mIdentifiers[0m
     An [4midentifier[24m labels a GNU [4mtroff[24m datum such as  a  register,  name  (macro,
     string,  or  diversion),  typeface,  color,  special character or character
     class, hyphenation language code, environment, or  stream.   Valid  identi‐
     fiers consist of one or more ordinary characters.  An [4mordinary[24m [4mcharacter[24m is
     any  Unicode  Basic  Latin character that is not a space and not the escape
     character; recall section “Input format” above.

     An identifier with a closing bracket (“]”) in its name  can’t  be  accessed
     with  bracket‐form  escape sequences that expect an identifier as a parame‐
     ter.  Similarly, the identifier  “(”  can’t  be  interpolated  [4mexcept[24m  with
     bracket forms.

     Beginning  a macro, string, or diversion name with the character “[” or “]”
     forecloses use of the ]8;;man:refer(1)\[4mrefer[24m(1)]8;;\ preprocessor, which recognizes  input  lines
     starting with “.[” and “.]”  as bibliographic reference delimiters.

     The  delimited  escape  sequence  [1m\A  [22mtests its argument for validity as an
     identifier.

     The formatter’s handling of  undefined  identifiers  is  context‐dependent.
     There  is no way to invoke an undefined request; such syntax is interpreted
     as a macro call instead.  If the identifier is  interpreted  as  a  string,
     macro,  or  diversion  name, the formatter defines it as empty and interpo‐
     lates nothing.  (GNU [4mtroff[24m emits a warning in category “[1mmac[22m”.  See  section
     “Warnings”  of ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\.)  Similarly, if the identifier is interpreted as a
     register name, the formatter initializes it to zero and  interpolates  that
     value.  GNU [4mtroff[24m emits a warning in category “[1mreg[22m”; see section “Warnings”
     in ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\, and subsection “Interpolating registers” and section “Strings”
     below.  Attempting to use an undefined typeface, special character or char‐
     acter  class, color, environment, hyphenation language code, or stream gen‐
     erally provokes an error diagnostic.

     Identifiers for requests, macros, strings, and diversions  share  one  name
     space;  special  characters and character classes another.  No other object
     types do.

[1mControl characters[0m
     The formatter recognizes a control character only at the  beginning  of  an
     input line, or at the beginning of a branch of a control structure request;
     see section “Control structures” below.

     A few requests cause a break implicitly; invoke them with the no‐break con‐
     trol  character to prevent the break.  Break suppression is its sole behav‐
     ioral distinction.  Employing the no‐break control character to invoke  re‐
     quests that don’t cause breaks is harmless but poor style.

     The  control  character  “[1m.[22m”  and the no‐break control character “[1m'[22m” can be
     changed with the [1mcc [22mand [1mc2 [22mrequests, respectively.  Within a macro  defini‐
     tion, register [1m.br [22mindicates the control character used to call it.

[1mInvoking requests[0m
     A  control  character is optionally followed by tabs and/or spaces and then
     an identifier naming a request or macro.  The invocation of an unrecognized
     request is interpreted as a macro call.  Defining a  macro  with  the  same
     name  as  a request replaces the request.  Deleting a request name with the
     [1mrm [22mrequest makes it unavailable.  The [1mals [22mrequest can alias requests,  per‐
     mitting  them  to  be  wrapped  or non‐destructively replaced.  See section
     “Strings” below.

     There is no inherent limit on argument length or quantity.   Most  requests
     take  one  or more arguments, and ignore any they do not expect.  A request
     may be separated from its arguments by tabs or spaces, but only spaces  can
     separate  an  argument  from  its successor.  Only one between arguments is
     necessary; any excess is ignored.  GNU [4mtroff[24m does not allow tabs for  argu‐
     ment separation.  (Plan 9 [4mtroff[24m does.)

     Generally,  a space [4mwithin[24m a request argument is not relevant, not meaning‐
     ful, or is supported by bespoke provisions, as with the [1mtl [22mrequest’s delim‐
     iters.  Some requests, like [1mds[22m, interpret the remainder of the control line
     as a single argument.  See section “Strings” below.

     Spaces and tabs immediately after a control character  are  ignored.   Com‐
     monly, authors use them to indent the source of documents or macro files.

[1mCalling macros[0m
     If  a  macro  of the desired name does not exist when called, the formatter
     creates it and assigns it an empty definition.  (GNU [4mtroff[24m emits a  warning
     in  category “[1mmac[22m”.  See section “Warnings” in ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\.)  Calling an unde‐
     fined macro [4mdoes[24m end a macro definition naming it as  its  end  macro  (see
     section “Writing macros” below).

     To  embed  spaces  [4mwithin[24m a macro argument, enclose the argument in neutral
     double quotes ‘[1m"[22m’.  Horizontal motion escape sequences are sometimes a bet‐
     ter choice for arguments to be formatted as text.

     The foregoing raises the question of how to embed neutral double quotes  or
     backslashes  in macro arguments when [4mthose[24m characters are desired as liter‐
     als.  In GNU [4mtroff[24m, the special character escape sequence [1m\[rs] [22mproduces  a
     backslash and [1m\[dq] [22ma neutral double quote.

     In  GNU  [4mtroff[24m’s AT&T compatibility mode, these characters remain available
     as [1m\(rs [22mand [1m\(dq[22m, respectively.  AT&T [4mtroff[24m  did  not  consistently  define
     these  special characters, but its descendants can be made to support them.
     See ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.  If even that is not feasible, see the “Calling  Macros”
     section  of the [4mgroff[24m Texinfo manual for the complex macro argument quoting
     rules of AT&T [4mtroff[24m.

[1mUsing escape sequences[0m
     Whereas requests must occur on control lines, escape  sequences  can  occur
     intermixed  with  text and may appear in arguments to requests, macros, and
     other escape sequences.  An escape sequence is  introduced  by  the  escape
     character,  a  backslash  [1m\[22m.  The next character selects the escape’s func‐
     tion.

     Escape sequences vary in length.  Some take an argument, and of those, some
     have different syntactical forms for a one‐character, two‐character, or ar‐
     bitrary‐length argument.  Others accept [4monly[24m an arbitrary‐length  argument.
     In the former scheme, a one‐character argument follows the function charac‐
     ter  immediately, an opening parenthesis “[1m([22m” introduces a two‐character ar‐
     gument (no closing parenthesis is  used),  and  an  argument  of  arbitrary
     length  is  enclosed  in brackets “[1m[][22m”.  In the latter scheme, the user se‐
     lects a delimiter character.  A few escape sequences are idiosyncratic, and
     support both of the foregoing conventions ([1m\s[22m), designate their own  termi‐
     nation sequence ([1m\?[22m), consume input until the next newline ([1m\![22m, [1m\"[22m, [1m\#[22m), or
     support  an  additional  modifier character ([1m\s [22magain, and [1m\n[22m).  In no case
     can an escape sequence parameter contain an unescaped newline.

     If the character that follows the escape character does not identify a  de‐
     fined  operation,  the  formatter ignores the escape character.  (GNU [4mtroff[0m
     emits a warning in category “[1mescape[22m”.  See section “Warnings” in ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\.)

     Escape sequence interpolation is of higher precedence than escape  sequence
     argument interpretation.  This rule affords flexibility in using escape se‐
     quences to construct parameters to other escape sequences.

     The  escape character can be interpolated ([1m\e[22m).  Requests permit the escape
     mechanism to be deactivated ([1meo[22m) and  restored,  or  the  escape  character
     changed ([1mec[22m), and to save and restore it ([1mecs [22mand [1mecr[22m).

[1mDelimiters[0m
     Some  escape sequences that require parameters use delimiters.  The neutral
     apostrophe [1m' [22mis a popular choice and shown in this document.   The  neutral
     double  quote [1m" [22mis also commonly seen.  Punctuation characters are the best
     choice (and most portable to other [4mtroff[24ms, except for those  meaningful  in
     numeric expressions; see below.

     The  following  escape sequences are not themselves delimited, and thus are
     allowed as delimiters: [1m\[4m[22mspace[24m, [1m\%[22m, [1m\|[22m, [1m\^[22m, [1m\{[22m, [1m\}[22m, [1m\'[22m, [1m\`[22m, [1m\-[22m, [1m\_[22m, [1m\![22m,  [1m\?[22m,
     [1m\)[22m,  [1m\/[22m,  [1m\,[22m, [1m\&[22m, [1m\:[22m, [1m\~[22m, [1m\0[22m, [1m\a[22m, [1m\c[22m, [1m\d[22m, [1m\e[22m, [1m\E[22m, [1m\p[22m, [1m\r[22m, [1m\t[22m, and [1m\u[22m.  How‐
     ever, we discourage using them this way; they can make the input  confusing
     to  read.   (The ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\ and ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\ preprocessors use parameterized but non‐
     delimited special character escape sequences [1m\( [22mand [1m\[ [22mto bracket  portions
     of  their  output.)   An invalid escape sequence is valid as a delimiter if
     the character after the escape character would be valid.

     The escape sequences [1m\D[22m, [1m\h[22m, [1m\H[22m, [1m\l[22m, [1m\L[22m, [1m\N[22m, [1m\R[22m, [1m\s[22m, [1m\S[22m, [1m\v[22m,  and  [1m\x  [22mpro‐
     hibit  delimiters  that are meaningful in numeric expressions, because they
     accept numeric expressions as (or within)  their  arguments.   For  consis‐
     tency,  GNU  [4mtroff[24m  prohibits the same delimiters in the argument to the [1mtl[0m
     request.  The “[1mif[22m”, [1mie[22m, and “[1mwhile[22m” requests each interpret their first ar‐
     gument as a conditional expression; only characters that are not meaningful
     as operators in that context can be used as output  comparison  delimiters.
     The following inputs are therefore invalid as delimiters in GNU [4mtroff[24m.

            •  the numerals 0–9 and the decimal point “[1m.[22m”

            •  the (single‐character) operators [1m+-/*%<>=&:()|[0m

            •  any  escape  sequences other than [1m\%[22m, [1m\:[22m, [1m\{[22m, [1m\}[22m, [1m\'[22m, [1m\`[22m, [1m\-[22m, [1m\_[22m,
               [1m\![22m, [1m\/[22m, [1m\c[22m, [1m\e[22m, and [1m\p[0m

     Delimiter syntax is flexible (and laborious to describe) primarily for his‐
     torical reasons; the foregoing restrictions need be  kept  in  mind  mainly
     when using GNU [4mtroff[24m in AT&T compatibility mode.  Normally, GNU [4mtroff[24m keeps
     track  of  the nesting depth of escape sequence interpolations, so the only
     characters you need to avoid using as delimiters are those that  appear  in
     the  arguments  you input, not those that result from interpolation.  Typi‐
     cally,  [1m'  [22mworks  fine.   See  section  “Implementation   differences”   in
     ]8;;man:groff_diff(7)\[4mgroff_diff[24m(7)]8;;\.

[1mDummy characters[0m
     As  discussed  in  ]8;;man:roff(7)\[4mroff[24m(7)]8;;\, the first character on an input line is treated
     specially.  Further, formatting a glyph has many consequences on  formatter
     state  (see section “Environments” below).  Occasionally, we want to escape
     this context or embrace some of those consequences without actually render‐
     ing a glyph to the output.  [1m\& [22minterpolates a  dummy  character,  which  is
     constitutive  of output but invisible.  Its presence alters the interpreta‐
     tion context of a subsequent input character, and enjoys  several  applica‐
     tions:  preventing  the  insertion  of extra space after an end‐of‐sentence
     character, preventing interpretation of a control character at  the  begin‐
     ning  of  an input line, preventing kerning between two glyphs, and permit‐
     ting the [1mtr [22mrequest to remap a character to  “nothing”.   [1m\)  [22mworks  as  [1m\&[0m
     does, except that it does not cancel a pending end‐of‐sentence state.

[1mPage control[0m
     Discretionary  page  breaks can prevent the unwanted separation of content.
     A new page number takes effect during page ejection;  see  subsection  “The
     implicit  page  trap”  below.  The [1mbp [22mrequest breaks the page, incrementing
     the page number by one (or setting it per the supplied argument).   The  [1mne[0m
     request forces a page break if insufficient vertical space is available (it
     asserts  “needed”  space).  [1msv [22mrequires vertical space as [1mne [22mdoes, but also
     [4msaves[24m it for later output by the [1mos [22mrequest.

     The [1mnl [22mregister interpolates the vertical drawing position as of  the  most
     recently typeset output line.  It does not necessarily (and often does not)
     represent  that  of the pending output line, because the formatter does not
     determine the position of its baseline until it  is  output.   Assigning  a
     value  to [1mnl [22msets the vertical drawing position in advance of further modi‐
     fications to baseline positioning arising from alterations  to  type  size,
     changes  to vertical spacing, or application of extra pre‐ or post‐vertical
     spacing.

     When the formatter starts, the transition to the first  page  has  not  yet
     happened——[1mnl  [22mis  negative.   If you plant a page location trap at vertical
     position “[1m0[22m” (idiomatically to format a header), you can assign a  negative
     value  to  [1mnl [22mto spring that trap even if the page has already started (see
     subsection “Page location traps” below).

[1mControl structures[0m
     [4mgroff[24m has “if” and “while” control structures like other  languages.   How‐
     ever,  the syntax for grouping multiple input lines in the branches or bod‐
     ies of these structures is unusual.

     They have a common form: the request name is (except for  [1mel  [22m“else”)  fol‐
     lowed by a conditional expression [4mcond‐expr[24m; the remainder of the line, [4min‐[0m
     [4mput[24m,  is  interpreted  as if it were an input line.  Any quantity of spaces
     between arguments to requests serves only to separate them; leading  spaces
     in  [4minput[24m  are therefore not seen.  [4minput[24m effectively [4mcannot[24m be omitted; if
     [4mcond‐expr[24m is true and [4minput[24m is empty, the newline at the end of the control
     line is interpreted as a blank line (and therefore a blank text line).

     It is frequently desirable for a control structure to govern more than  one
     request,  macro  call,  or text line, or combination of the foregoing.  The
     opening and closing brace escape sequences [1m\{ [22mand [1m\} [22mperform such grouping.
     Brace escape sequences outside of control structures have  no  meaning  and
     produce no output.

     [1m\{ [22mshould appear (after optional spaces and tabs) immediately subsequent to
     the  request’s  conditional  expression.   [1m\}  [22mshould appear on a line with
     other occurrences of itself as necessary to match [1m\{ [22msequences.  It can  be
     preceded  by  a control character, spaces, and tabs.  Input after any quan‐
     tity of [1m\} [22msequences on the same line is processed only if all the  preced‐
     ing  conditions to which they correspond are true.  Furthermore, a [1m\} [22mclos‐
     ing the body of a “[1mwhile[22m” request must be the last such escape sequence  on
     an input line.

     GNU  [4mtroff[24m  treats  the body of a “[1mwhile[22m” request similarly to that of a [1mde[0m
     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  con‐
     taining  a  “[1mwhile[22m”  request  can  slow significantly if its body is large.
     Each time GNU [4mtroff[24m interpolates  the  macro,  it  parses  and  stores  the
     “[1mwhile[22m”  body  again.   An  often  better  solution——and  one  that is more
     portable, since AT&T [4mtroff[24m lacked the “[1mwhile[22m” request——is to instead  write
     a  recursive macro, which is parsed only once (unless you redefine it).  To
     prevent infinite loops, GNU [4mtroff[24m limits the default  number  of  available
     recursion levels to 1,000 or somewhat less (because things other than macro
     calls can be on the input stack).  You can disable this protective measure,
     or  alter  the  limit, by setting the [1mslimit [22mregister.  See section “Debug‐
     ging” below.

   [1mConditional expressions[0m
     The “[1mif[22m”, [1mie[22m, and “[1mwhile[22m” requests test the truth values of numeric expres‐
     sions.  They also support several additional Boolean operators; the members
     of this expanded class are termed [4mconditional[24m [4mexpressions[24m; their truth val‐
     ues are as shown below.

     [4m[1mcond‐expr[24m...   ...is true if...[0m
     ───────────────────────────────────────────────────────────────────────────
          [1m'[4m[22ms1[24m[1m'[4m[22ms2[24m[1m'   [4m[22ms1[24m produces the same formatted output as [4ms2[24m.
              [1mc [4m[22mg[24m   a character [4mg[24m is defined.
              [1md [4m[22mm[24m   a string, macro, diversion, or request [4mm[24m is defined.
                [1me   [22mthe current page number is even.
              [1mF [4m[22mf[24m   a font named [4mf[24m is available.
              [1mm [4m[22mc[24m   a color named [4mc[24m is defined.
                [1mn   [22mthe formatter is in [4mnroff[24m mode.
                [1mo   [22mthe current page number is odd.
              [1mr [4m[22mn[24m   a register named [4mn[24m is defined.
              [1mS [4m[22ms[24m   a font style named [4ms[24m is available.
                [1mt   [22mthe formatter is in [4mtroff[24m mode.
                [1mv   [22mn/a (historical artifact; always false).

     If the first argument to an “[1mif[22m”, [1mie[22m, or “[1mwhile[22m” request begins with a non‐
     alphanumeric character apart from “[1m![22m” (see below) and is not a numeric  ex‐
     pression, the formatter performs an [4moutput[24m [4mcomparison[24m [4mtest.[24m  Shown first in
     the  table  above, the [4moutput[24m [4mcomparison[24m [4moperator[24m interpolates a true value
     if formatting its comparands [4ms1[24m and [4ms2[24m produces the same  output  commands.
     Other  delimiters can be used in place of the neutral apostrophes; see sec‐
     tion “Delimiters” above.  [4mtroff[24m formats  [4ms1[24m  and  [4ms2[24m  in  separate  scratch
     buffers;  after  comparison, it discards the resulting data.  The resulting
     glyph properties, including font  family,  style,  size,  and  slant,  must
     match, but not necessarily the requests and/or escape sequences used to ob‐
     tain  them.   Motions must match in orientation and magnitude to within the
     applicable horizontal or vertical  motion  quantum  of  the  device,  after
     rounding.

     Surround  the comparands with [1m\? [22mto avoid formatting them; this causes them
     to be compared character by character, as with string comparisons in  other
     programming  languages.  Since GNU [4mtroff[24m reads comparands protected with [1m\?[0m
     in copy mode, they need not be syntactically valid.  The  escape  character
     is still lexically recognized, however, and consumes the next character.

     The  above operators can’t be combined with most others, but a leading “[1m![22m”,
     not followed immediately by spaces  or  tabs,  complements  an  expression.
     Spaces and tabs are optional immediately after the “[1mc[22m”, “[1md[22m”, “[1mF[22m”, “[1mm[22m”, “[1mr[22m”,
     and “[1mS[22m” operators, but right after “[1m![22m”, they end the predicate and the con‐
     ditional  evaluates  true.   (This bizarre behavior maintains compatibility
     with AT&T [4mtroff[24m.)

     Conditional operators do not create [4mroff[24m language objects as interpolations
     with [1m\n [22mand [1m\* [22mescape sequences do.

[1mSyntax reference conventions[0m
     In the following request and escape sequence specifications, most  argument
     names were chosen to be descriptive.  GNU [4mtroff[24m reads arguments named [4mchar‐[0m
     [4macter‐sequence,[24m [4mcommand,[24m [4mcontents,[24m [4mfile,[24m and [4mmessage[24m in copy mode (see sec‐
     tion  “Copy  Mode” below) until the end of the input line.  A [4mcharacter‐se‐[0m
     [4mquence[24m comprises one or more  ordinary,  special,  or  indexed  characters;
     spaces;  or  escape sequences that interpolate only these.  We name the re‐
     maining arguments for clarity; they are also [4mcharacter‐sequences.[24m   A  neu‐
     tral  double quote ‘[1m"[22m’ can optionally prefix a [4mcharacter‐sequence;[24m the for‐
     matter discards one if present, permitting initial embedded spaces  in  the
     argument.   [4minput[24m  refers to arbitrary character sequences (up to a newline
     or delimiter) that GNU [4mtroff[24m fully interprets, in contrast to copy mode.

     A few denotations are more specific.

            [4mb[24m          is a numerical expression evaluated as a  Boolean;  posi‐
                       tive values are true, others false.
            [4mc[24m          denotes  a  single  character——ordinary,  special, or in‐
                       dexed.
            [4mcommand[24m    is an instance of [4mcontents[24m (see below) to  be  passed  to
                       the  system  as  a  command (potentially with arguments).
                       GNU [4mtroff[24m strips a leading neutral double quote, allowing
                       embedded leading spaces.
            [4mcontents[24m   is arbitrary input, excluding an unescaped newline,  read
                       in  copy mode.  GNU [4mtroff[24m strips a leading neutral double
                       quote, allowing embedded leading spaces.
            [4mdiv[24m        is a diversion identifier.
            [4menv[24m        is an environment identifier.
            [4mfile[24m       is an instance of [4mcontents[24m naming a file on  the  system.
                       GNU [4mtroff[24m strips a leading neutral double quote, allowing
                       embedded  leading spaces.  GNU [4mtroff[24m does not accept new‐
                       lines (line feeds) in file names supplied as arguments to
                       requests.
            [4mfont[24m       is a typeface specified as a font identifier, an abstract
                       style, or a mounting position.
            [4mident[24m      is a valid [4mgroff[24m identifier; its use often indicates that
                       the operation creates an object of  a  type  subsequently
                       referred to as [4mmac,[24m [4mreg,[24m [4mstr,[24m and so forth.
            [4mmac[24m        is a macro identifier.
            [4mmessage[24m    is  an instance of [4mcontents[24m to emit on the standard error
                       stream.  GNU [4mtroff[24m strips a leading neutral double quote,
                       allowing embedded leading spaces.
            [4mn[24m          is a numeric expression that evaluates to a  non‐negative
                       integer.
            [4m±N[24m         is  a  numeric expression with a meaning dependent on its
                       sign; see below.
            [4mname[24m       is a macro, string, or diversion identifier, or the  name
                       of a request.
            [4mnpl[24m        is  a  numeric  expression constituting a count of subse‐
                       quent [4mproductive[24m input lines; that  is,  those  that  di‐
                       rectly produce formatted output.  Text lines produce out‐
                       put,  as  do  control lines containing requests like “[1m.tl[0m
                       [1m//Page %//[22m” or escape  sequences  like  “[1m\l'1i'[22m”.   Macro
                       calls are not themselves productive, but their interpola‐
                       tions can be.
            [4mreg[24m        is a register identifier.
            [4mstr[24m        is a string identifier.
            [4mstream[24m     is an output stream identifier.

     If  a  numeric expression presented as [4m±N[24m starts with a ‘[1m+[22m’ sign, an incre‐
     ment in the amount of of [4mN[24m is applied to the value applicable  to  the  re‐
     quest  or  escape  sequence.   If it starts with a ‘[1m-[22m’ sign, a decrement of
     magnitude [4mN[24m is applied instead.  Without a sign, [4mN[24m  replaces  any  existing
     value.   A  [4mroff[24m formatter always interprets a leading minus sign in [4mN[24m as a
     decrementation operator, not an algebraic sign.  To  assign  a  register  a
     negative  value  or  the  negated  value of another interpolation, you must
     force the formatter to interpret “[1m-[22m” as a negation or  minus,  rather  than
     decrementation,  operator:  enclose the “[1m-[22m” with its operand in parentheses
     or subtract the expression of interest from zero.  If a  prior  value  does
     not exist——the register was undefined——an increment or decrement applies as
     if to 0.

[1mRequest short reference[0m
     Not  all details of request behavior are outlined here.  See the [4mgroff[24m Tex‐
     info manual or, for features new to GNU [4mtroff[24m, ]8;;man:groff_diff(7)\[4mgroff_diff[24m(7)]8;;\.

     [1m.ab        [22mAbort the formatter; exit with failure status.
     [1m.ab [4m[22mterminal‐message[0m
                Abort the formatter; write [4mterminal‐message[24m to the standard  er‐
                ror stream and exit with failure status.
     [1m.ad        [22mEnable  output  line  alignment  and  adjustment  using the mode
                stored in [1m\n[.j][22m.
     [1m.ad [4m[22mc[24m      Enable  output  line  alignment  and  adjustment   in   mode   [4mc[0m
                ([4mc[24m=[1mb[22m,[1mc[22m,[1ml[22m,[1mn[22m,[1mr[22m).  Sets [1m\n[.j][22m.
     [1m.af [4m[22mreg[24m [4mc[24m  Assign  format [4mc[24m to register [4mreg,[24m where [4mc[24m is “[1mi[22m”, “[1mI[22m”, “[1ma[22m”, “[1mA[22m”,
                or a sequence of decimal digits whose quantity denotes the mini‐
                mum width in digits to be used when  the  register  is  interpo‐
                lated.   “[1mi[22m” and “[1ma[22m” indicate Roman numerals and basic Latin al‐
                phabetics, respectively, in the lettercase specified.   The  de‐
                fault is [1m0[22m.
     [1m.aln [4m[22mnew‐register[24m [4mexisting‐register[0m
                Create  alias  (additional name) [4mnew‐register[24m of [4mexisting‐regis‐[0m
                [4mter[24m, causing the names to refer to the same stored  object.   If
                [4mexisting‐register[24m  is  undefined,  the formatter ignores the re‐
                quest.  GNU [4mtroff[24m emits a warning in category “[1mreg[22m”.
     [1m.als [4m[22mnew‐name[24m [4mexisting‐name[0m
                Create alias (additional  name)  [4mnew‐name[24m  of  request,  string,
                macro, or diversion [4mexisting‐name[24m, causing the names to refer to
                the same stored object.  If [4mexisting‐name[24m is undefined, the for‐
                matter  ignores the request.  GNU [4mtroff[24m emits a warning in cate‐
                gory “[1mmac[22m”.  If [4mnew‐name[24m already exists, its definition is  lost
                unless already aliased.
     [1m.am [4m[22mmac[24m    Append  to  macro  [4mmac[24m until encountering “[1m..[22m” at the start of a
                control line in the current conditional block.
     [1m.am [4m[22mmac[24m [4mend‐mac[0m
                Append to macro [4mmac[24m until [4mend‐mac[24m is called at the  start  of  a
                control line in the current conditional block.  [4mend‐mac[24m can be a
                request.
     [1m.am1 [4m[22mmac[24m   As ”[1mam[22m”, with compatibility mode disabled when the appendment to
                macro [4mmac[24m is interpreted.
     [1m.am1 [4m[22mmac[24m [4mend‐mac[0m
                As  “[1m.am [4m[22mmac[24m”, with compatibility mode disabled when the append‐
                ment to macro [4mmac[24m is interpreted.
     [1m.ami [4m[22mstr[24m   Append to a macro indirectly——its name is in  string  [4mstr[24m——until
                encountering “[1m..[22m”.
     [1m.ami [4m[22mstr[24m [4mend‐mac‐str[0m
                Append  to a macro indirectly.  As ”[1mam[22m”, but [4mstr[24m and [4mend‐mac‐str[0m
                contain the names of the macro to be appended to, and that whose
                call ends the appendment, respectively.
     [1m.ami1 [4m[22mstr[24m  As [1mami[22m, with compatibility mode disabled when the appendment  is
                interpreted.
     [1m.ami1 [4m[22mstr[24m [4mend‐mac‐str[0m
                As  [1mami[22m, with compatibility mode disabled when the appendment is
                interpreted.
     [1m.as [4m[22mident[24m  Create string [4mident[24m with empty contents; no operation  if  [4mident[0m
                already exists.
     [1m.as [4m[22mstr[24m [4mcontents[0m
                Append [4mcontents[24m to string [4mstr[24m.
     [1m.as1 [4m[22mident[0m
                As “[1m.as [4m[22mident[24m”.
     [1m.as1 [4m[22mstr[24m [4mcontents[0m
                As ”[1mas[22m”, with compatibility mode disabled when the appendment to
                string [4mstr[24m is interpreted.
     [1m.asciify [4m[22mdiv[0m
                Unformat  ordinary characters, spaces, and some escape sequences
                in diversion [4mdiv[24m.  When transforming a glyph node back  into  an
                input  sequence  that  demands expression as a special character
                escape sequence, GNU [4mtroff[24m uses the default escape character.
     [1m.backtrace[0m
                Write the state of the input stack to the standard error stream.
                See the [1m-b [22moption of ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\.
     [1m.bd [4m[22mfont[24m   Stop emboldening font [4mfont.[0m
     [1m.bd [4m[22mfont[24m [4mn[0m
                Embolden [4mfont[24m by overstriking its glyphs offset  by  [4mn[24m-1  units.
                See register [1m.b[22m.
     [1m.bd [4m[22mspecial‐font[24m [4mfont[0m
                Stop  emboldening  [4mspecial‐font[24m when [4mfont[24m is selected.  [4mspecial‐[0m
                [4mfont[24m must be a font name, not a mounting position.
     [1m.bd [4m[22mspecial‐font[24m [4mfont[24m [4mn[0m
                Embolden [4mspecial‐font,[24m overstriking its  glyphs  offset  by  [4mn[24m-1
                units when [4mfont[24m is selected.  See register [1m.b[22m.
     [1m.blm       [22mUnset  blank  line  macro  (trap).   Restore default handling of
                blank lines.
     [1m.blm [4m[22mmac[24m   Set blank line macro (trap) to [4mmac[24m.
     [1m.box       [22mStop directing output to current diversion; any  pending  output
                line is discarded.
     [1m.box [4m[22mident[0m
                Direct output to diversion [4mident[24m, omitting a partially collected
                line.
     [1m.boxa      [22mStop  appending  output to current diversion; any pending output
                line is discarded.
     [1m.boxa [4m[22mdiv[24m  Append output to diversion [4mdiv[24m, omitting a  partially  collected
                line.
     [1m.bp        [22mBreak page and start a new one.
     [1m.bp [4m[22m±N[24m     Break page, starting a new one numbered [4m±N[24m.
     [1m.br        [22mBreak output line.
     [1m.brp       [22mBreak  and  force  adjustment of the output line per the current
                adjustment mode.
     [1m.break     [22mBreak out of a ”[1mwhile[22m” loop.
     [1m.c2        [22mReset no‐break control character to “[1m'[22m”.
     [1m.c2 [4m[22mo[24m      Recognize ordinary character [4mo[24m as no‐break control character.
     [1m.cc        [22mReset control character to ‘[1m.[22m’.
     [1m.cc [4m[22mo[24m      Recognize ordinary character [4mo[24m as the control character.
     [1m.ce        [22mBreak, center the output of the next productive input line with‐
                out filling, and break again.
     [1m.ce [4m[22mnpl[24m    Break, center the output of the next [4mnpl[24m productive input  lines
                without filling, then break again.  If [4mnpl[24m ≤ 0, stop centering.
     [1m.cf [4m[22mfile[24m   Break  and  copy  contents  of [4mfile[24m as “throughput” to GNU [4mtroff[0m
                output (see ]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\).  Each line of [4mfile[24m is  output  as  if
                preceded by [1m\![22m, but is not interpreted by the formatter.  Unsafe
                request; disabled by default.
     [1m.cflags [4m[22mn[24m [4mc[24m...
                Assign  properties  encoded  by  non‐negative  integer [4mn[24m to each
                character or class [4mc[24m.  Spaces need not separate [4mc[24m arguments.
     [1m.ch [4m[22mmac[24m    Unplant page location trap [4mmac[24m.
     [1m.ch [4m[22mmac[24m [4mvertical‐position[0m
                Change page location trap [4mmac[24m planted by [1mwh [22mby moving its  loca‐
                tion to [4mvertical‐position[24m (default scaling unit [1mv[22m).
     [1m.char [4m[22mc[24m    Define an ordinary, special, or indexed character [4mc[24m as empty.
     [1m.char [4m[22mc[24m [4mcontents[0m
                Define an ordinary, special, or indexed character [4mc[24m as [4mcontents.[0m
     [1m.chop [4m[22mname[0m
                Remove  the  last character from the macro, string, or diversion
                [4mname.[0m
     [1m.class [4m[22mident[24m [4mc[24m ...
                Define a (character) class [4mident[24m comprising  the  characters  or
                range  expressions  [4mc[24m,  where each [4mc[24m is an ordinary, special, or
                indexed character; or a [4mrange[24m [4mexpression.[24m  A class thus  defined
                can  then  be referred to in a [1mcflags [22mrequest in lieu of listing
                all the characters within it.
     [1m.close [4m[22mstream[0m
                Close [4mstream[24m, making it unavailable for ”[1mwrite[22m” requests.
     [1m.color     [22mEnable output of color‐related  device‐independent  output  com‐
                mands.  It is enabled by default.
     [1m.color [4m[22mb[24m   Enable  or  disable  output  of color‐related device‐independent
                output commands per Boolean expression [4mb[24m.
     [1m.composite [4m[22mc[0m
                Remove composite character mapping for character [4mc.[0m
     [1m.composite [4m[22mc1[24m [4mc2[0m
                Map character [4mc1[24m to [4mc2[24m when [4mc1[24m is a  combining  component  in  a
                composite character.
     [1m.continue  [22mSkip the remainder of a “[1mwhile[22m” loop’s body, immediately retest‐
                ing its conditional expression.
     [1m.cp        [22mEnable  AT&T  [4mtroff[24m  compatibility  mode.  It is disabled by de‐
                fault.
     [1m.cp [4m[22mb[24m      Enable or disable AT&T [4mtroff[24m compatibility mode per Boolean  ex‐
                pression [4mb[24m.
     [1m.cs [4m[22mf[24m      Disable constant‐width glyph spacing mode for font [4mf.[0m
     [1m.cs [4m[22mf[24m [4mn[24m    Enable constant‐width glyph spacing mode for font [4mf[24m at [4mn[24m/36 ems.
     [1m.cs [4m[22mf[24m [4mn[24m [4mp[24m  Enable  constant‐width  glyph spacing mode for [4mfont[24m at [4mn[24m/36 ems,
                as if one em equals [4mp[24m scaled points.
     [1m.cu        [22mContinuously underline the output of the next  productive  input
                line.
     [1m.cu [4m[22mnpl[24m    Continuously underline the output of the next [4mnpl[24m productive in‐
                put lines.  If [4mnpl[24m=0, stop continuously underlining.
     [1m.da        [22mStop appending output to current diversion.
     [1m.da [4m[22mdiv[24m    Append output to diversion [4mdiv[24m.
     [1m.de [4m[22mident[24m  Define  macro  [4mident[24m until “[1m..[22m” occurs at the start of a control
                line in the current conditional block.
     [1m.de [4m[22mident[24m [4mend‐mac[0m
                Define macro [4mident[24m until [4mend‐mac[24m is called at  the  start  of  a
                control line in the current conditional block.  [4mend‐mac[24m can be a
                request.
     [1m.de1 [4m[22mident[0m
                As [1mde[22m, with compatibility mode disabled when [4mmac[24m is interpreted.
     [1m.de1 [4m[22mident[24m [4mend‐mac[0m
                As  “[1m.de  [4m[22mident[24m  [4mend‐mac[24m”, with compatibility mode disabled when
                [4mmac[24m is interpreted.
     [1m.defcolor [4m[22mident[24m [4mscheme[24m [4mcolor‐component[24m ...
                Define a color named [4mident.[24m  [4mscheme[24m identifies a color space and
                determines the number of required [4mcolor‐component[24ms; it  must  be
                one  of  “[1mrgb[22m” (three components), “[1mcmy[22m” (three), “[1mcmyk[22m” (four),
                or “[1mgray[22m” (one).  “[1mgrey[22m” is accepted as  a  synonym  of  “[1mgray[22m”.
                The  color  components  can  be  encoded as a single hexadecimal
                value starting with [1m# [22mor [1m##[22m.  The  former  indicates  that  each
                component  is  in  the  range 0–255 (0–FF), the latter the range
                0–65,535 (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 “[1mf[22m”, which multiplies its  value
                by 65,536 (but clamps it at 65,535).
     [1m.dei [4m[22mstr[24m   Define  macro  indirectly.  As [1mde[22m, but interpolate string [4mstr[24m to
                obtain the macro’s name.
     [1m.dei [4m[22mstr[24m [4mend‐mac‐str[0m
                Define macro indirectly.  As [1mde[22m, but [4mstr[24m and [4mend‐mac‐str[24m contain
                the names of the macro to be defined, and that whose  call  ends
                the definition, respectively.
     [1m.dei1 [4m[22mstr[24m  As  [1mdei[22m,  with compatibility mode disabled when the macro is in‐
                terpreted.
     [1m.dei1 [4m[22mstr[24m [4mend‐mac‐str[0m
                As [1mdei[22m, with compatibility mode disabled when the macro  is  in‐
                terpreted.
     [1m.device [4m[22mcharacter‐sequence[0m
                Embed  [4mcharacter‐sequence[24m into GNU [4mtroff[24m output as parameters to
                an “x[1mX” [22mdevice extension command; see ]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\.  The  output
                driver  or  other postprocessor interprets [4mcharacter‐sequence[24m as
                it sees fit.
     [1m.devicem [4m[22mname[0m
                Write contents of macro or string [4mname[24m to [4mtroff[24m  output  as  the
                argument to a device extension command.
     [1m.di        [22mStop directing output to current diversion.
     [1m.di [4m[22mident[24m  Direct output to diversion [4mident[24m.
     [1m.do [4m[22mname[24m [4margument[24m ...
                Interpret  the  string, request, diversion, or macro [4mname[24m (along
                with any further arguments) with  compatibility  mode  disabled.
                Compatibility  mode is restored (only if it was active) when the
                interpolation of [4mname[24m is interpreted.
     [1m.ds [4m[22mident[24m  Create empty string named [4mident[24m.
     [1m.ds [4m[22mident[24m [4mcontents[0m
                Create a string named [4mident[24m containing [4mcontents.[0m
     [1m.ds1 [4m[22mident[0m
     [1m.ds1 [4m[22mident[24m [4mcontents[0m
                As [1mds[22m, with compatibility mode disabled when the string  is  in‐
                terpreted.
     [1m.dt        [22mClear diversion trap.
     [1m.dt [4m[22mvertical‐position[24m [4mmac[0m
                Set  the  diversion  trap to macro [4mmac[24m at [4mvertical‐position[24m (de‐
                fault scaling unit [1mv[22m).
     [1m.ec        [22mRecognize [1m\ [22mas the escape character.
     [1m.ec [4m[22mo[24m      Recognize ordinary character [4mo[24m as the escape character.
     [1m.ecr       [22mRestore escape character saved with [1mecs[22m.
     [1m.ecs       [22mSave the escape character.
     [1m.el        [22mInterpolate a newline if the conditional expression of the  cor‐
                responding [1mie [22mrequest was false.
     [1m.el [4m[22minput[24m  Interpret  [4minput[24m  as if it were an input line if the conditional
                expression of the corresponding [1mie [22mrequest was false.
     [1m.em        [22mUnset end‐of‐input macro.
     [1m.em [4m[22mmac[24m    Call macro [4mmac[24m after the end of input.
     [1m.eo        [22mDisable the escape mechanism in interpretation mode.
     [1m.ev        [22mPop environment stack, returning to previous one.
     [1m.ev [4m[22menv[24m    Push current environment onto stack and switch to [4menv[24m,  creating
                it if necessary.
     [1m.evc [4m[22menv[24m   Copy environment [4menv[24m to the current one.
     [1m.ex        [22mExit the formatter.
     [1m.fam       [22mSet default font family to previous value.
     [1m.fam [4m[22mname[24m  Set default font family to [4mname[24m.
     [1m.fc        [22mDisable field mechanism.
     [1m.fc [4m[22mc[24m      Set field delimiter to [4mc[24m and pad glyph to space.
     [1m.fc [4m[22mc1[24m [4mc2[24m  Set field delimiter to [4mc1[24m and pad glyph to [4mc2[24m.
     [1m.fchar [4m[22mc[24m   Define fallback character [4mc[24m as empty.
     [1m.fchar [4m[22mc[24m [4mcontents[0m
                Define  fallback  character  [4mc[24m  as [4mcontents[24m.  As [1mchar[22m, but while
                that request hides a glyph with the same name  in  the  selected
                font,  [1mfchar [22mdefinitions are used only if the font lacks a glyph
                for [4mc[24m.  GNU [4mtroff[24m performs this test  before  searching  special
                fonts.
     [1m.fcolor    [22mRestore previous fill color, or the default if there is none.
     [1m.fcolor [4m[22mcol[0m
                Select [4mcol[24m as the fill color.
     [1m.fi        [22mEnable filling of output lines; a pending output line is broken.
                Sets [1m\n[.u][22m.
     [1m.fl        [22mFlush any pending output line.
     [1m.fp [4m[22mpos[24m [4mid[0m
                Mount  font  with  font description file name [4mid[24m at non‐negative
                position [4mpos[24m.
     [1m.fp [4m[22mpos[24m [4mid[24m [4mfont‐description‐file‐name[0m
                Mount font with [4mfont‐description‐file‐name[24m as name  [4mid[24m  at  non‐
                negative position [4mpos[24m.
     [1m.fschar [4m[22mf[24m [4mc[0m
                Define fallback character [4mc[24m specific to font [4mf[24m as empty.
     [1m.fschar [4m[22mf[24m [4mc[24m [4mcontents[0m
                Define  fallback character [4mc[24m specific to font [4mf[24m as [4mcontents[24m.  As
                [1mchar[22m, but GNU [4mtroff[24m locates a character defined by [1mfschar  [22mafter
                any  fonts  named  as arguments to the [1mfspecial [22mare searched and
                before those named as arguments to the “[1mspecial[22m” request.
     [1m.fspecial [4m[22mf[0m
                Empty the list of fonts treated as special when [4mf[24m is selected.
     [1m.fspecial [4m[22mf[24m [4ms[24m ...
                Declare each font [4ms[24m as special only when  font  [1mf  [22mis  selected.
                GNU [4mtroff[24m searches fonts specified as arguments to the “[1mspecial[22m”
                request after those given as arguments to the [1mfspecial [22mrequest.
     [1m.ft[0m
     [1m.ft P      [22mSelect  the typeface [4mfont.[24m  If [4mfont[24m is an integer, the formatter
                interprets it as a mounting position; the font mounted there  is
                selected.   If  that  position  refers to an abstract style, GNU
                [4mtroff[24m combines it with the default family (see [1mfam [22mabove and  [1m\F[0m
                below)  to make a resolved font name.  If [4mfont[24m is “[1mDESC[22m”, if the
                mounting position is not  an  abstract  style  and  no  font  is
                mounted  there,  or the mounting position is negative, GNU [4mtroff[0m
                ignores the request.  (It  also  emits  a  warning  in  category
                “[1mfont[22m”,  or  “[1mrange[22m”, as appropriate.  See section “Warnings” in
                ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\.)  Also see [1m\f .[0m
     [1m.ftr [4m[22mf[24m     Remove translation of font named [4mf[24m.
     [1m.ftr [4m[22mf1[24m [4mf2[0m
                Translate font name [4mf1[24m to [4mf2[24m.
     [1m.fzoom [4m[22mfont[24m [1m0[0m
                Stop magnifying [4mfont[24m.
     [1m.fzoom [4m[22mfont[24m [4mzoom[0m
                Set magnification of mounted [4mfont[24m to [4mzoom[24m, a multiplier  of  the
                current type size in thousandths (default: 1000).
     [1m.gcolor    [22mRestore previous stroke color, or the default if there is none.
     [1m.gcolor [4m[22mcol[0m
                Select [4mcol[24m as the stroke color.
     [1m.hc        [22mReset the hyphenation character to [1m\% [22m(the default).
     [1m.hc [4m[22mc[24m      Change the hyphenation character to [4mc[24m.
     [1m.hcode [4m[22mdst1[24m [4msrc1[24m [[4mdst2[24m [4msrc2[24m] ...
                Set  the hyphenation code of character [4mdst1[24m to that of [4msrc1[24m, and
                so on.
     [1m.hla       [22mClear the environment’s hyphenation  language  (disabling  auto‐
                matic hyphenation).
     [1m.hla [4m[22mident[0m
                Set the environment’s hyphenation language to [4mident[24m.
     [1m.hlm       [22mSet  the  consecutive  automatically hyphenated line limit to [1m-1[0m
                (the default), meaning “no limit”.
     [1m.hlm [4m[22mn[24m     Set the consecutive automatically hyphenated line limit to to [4mn.[0m
                A negative value means “no limit”.
     [1m.hpf [4m[22mfile[24m  Read hyphenation patterns from [4mfile[24m.
     [1m.hpfa [4m[22mfile[0m
                Append hyphenation patterns from [4mfile[24m.
     [1m.hpfcode [4m[22ma[24m [4mb[24m [[4mc[24m [4md[24m] ...
                [4mCaution:[24m This request will be withdrawn in a  future  [4mgroff[24m  re‐
                lease.  Use [1mhcode [22minstead.
                Define  mappings  for  character  codes  in  hyphenation pattern
                files.
     [1m.hw [4m[22mword[24m ...
                Define each argument [4mword[24m (comprising ordinary, special, or  in‐
                dexed characters) as a [4mhyphenation[24m [4mexception[24m [4mword[24m such that each
                occurrence of a hyphen‐minus “[1m-[22m” in [4mword[24m indicates a hyphenation
                point.
     [1m.hy        [22mSet  automatic  hyphenation  mode to the value of the [1m.hydefault[0m
                register.
     [1m.hy 0      [22mDisable automatic hyphenation; same as [1m.nh[22m.
     [1m.hy [4m[22mmode[24m   Set automatic hyphenation mode to  [4mmode[24m;  see  section  “Hyphen‐
                ation” below.
     [1m.hydefault [4m[22mmode[0m
                Set  hyphenation mode default to [4mmode[24m; see section “Hyphenation”
                below.
     [1m.hym       [22mSet the (right) hyphenation margin to [1m0 [22m(the default).
     [1m.hym [4m[22mlength[0m
                Set the (right) hyphenation margin to  [4mlength[24m  (default  scaling
                unit [1mm[22m).
     [1m.hys       [22mSet the hyphenation space to [1m0 [22m(the default).
     [1m.hys [4m[22mhyphenation‐space[0m
                Suppress automatic hyphenation in adjustment modes “[1mb[22m” or “[1mn[22m” if
                that  adjustment  can be achieved by adding no more than [4mhyphen‐[0m
                [4mation‐space[24m to each inter‐word space (default scaling unit [1mm[22m).
     [1m.ie [4m[22mcond‐expr[0m
                Interpolate a newline if [4mcond‐expr[24m is true, otherwise skip to  a
                corresponding [1mel [22mrequest.
     [1m.ie [4m[22mcond‐expr[24m [4minput[0m
                If  [4mcond‐expr[24m  is  true,  interpret [4minput[24m as if it were an input
                line, otherwise skip to a corresponding [1mel [22mrequest.
     [1m.if [4m[22mcond‐expr[0m
                Interpolate a newline if [4mcond‐expr[24m is true.
     [1m.if [4m[22mcond‐expr[24m [4minput[0m
                If [4mcond‐expr[24m is true, then interpret [4minput[24m as if it were an  in‐
                put line.
     [1m.ig        [22mIgnore input (except for side effects of [1m\R [22mon auto‐incrementing
                registers)  until  “[1m..[22m” occurs at the start of a control line in
                the current conditional block.
     [1m.ig [4m[22mend‐mac[0m
                Ignore input (except for side effects of [1m\R [22mon auto‐incrementing
                registers) until [4mend‐mac[24m is called at the  start  of  a  control
                line  in  the  current  conditional block.  [4mend‐mac[24m can be a re‐
                quest.
     [1m.in        [22mSet indentation amount to previous value.
     [1m.in [4m[22m±N[24m     Set indentation to [4m±N[24m (default scaling unit [1mm[22m).
     [1m.it        [22mCancel any pending input line trap.
     [1m.it [4m[22mnpl[24m [4mmac[0m
                Set (or replace) an input line trap in the environment,  calling
                [4mmac[24m  after  the  next [4mnpl[24m productive input lines have been read.
                Lines interrupted with the [1m\c [22mescape sequence are counted  sepa‐
                rately.
     [1m.itc       [22mCancel any pending input line trap.
     [1m.itc [4m[22mnpl[24m [4mmac[0m
                As  ”[1mit[22m”,  but  lines interrupted with the [1m\c [22mescape sequence do
                not apply to the line count.
     [1m.kern      [22mEnable pairwise kerning.
     [1m.kern [4m[22mb[24m    Enable or disable pairwise kerning per Boolean expression [4mb[24m.
     [1m.lc        [22mUnset leader repetition character.
     [1m.lc [4m[22mc[24m      Set leader repetition character to [4mc[24m (default: “[1m.[22m”).
     [1m.length [4m[22mreg[24m [4mcontents[0m
                Compute the number of characters in [4mcontents[24m and store the count
                in the register [4mreg[24m.
     [1m.linetabs  [22mActivate line‐tabs in the environment.  It is  disabled  by  de‐
                fault.
     [1m.linetabs [4m[22mb[0m
                Activate  or deactivate line‐tabs in the environment per Boolean
                expression [4mb[24m.
     [1m.lf [4m[22minput‐line‐number[0m
                Set the input line number the formatter uses when reporting  di‐
                agnostics.   The  argument  becomes the input line number of the
                [4mnext[24m line the formatter reads.
     [1m.lf [4m[22minput‐line‐number[24m [4mcharacter‐sequence[0m
                As [1mlf [22mwith one argument, but also update the reported file  name
                to [4mcharacter‐sequence[24m.
     [1m.lg        [22mEnable ligature mode [1m1[22m.
     [1m.lg [4m[22mm[24m      Set  ligature mode to [4mm[24m ([1m0 [22m= disable, [1m1 [22m= enable, [1m2 [22m= enable for
                two‐letter ligatures only).
     [1m.ll        [22mSet line length to previous value.  Does not  affect  a  pending
                output line.
     [1m.ll [4m[22m±N[24m     Set  line  length  to  [4m±N[24m  (default length 6.5[1mi[22m, default scaling
                unit [1mm[22m).  Does not affect a pending output line.
     [1m.lsm       [22mUnset the leading space macro (trap).  Restore default  handling
                of lines with leading spaces.
     [1m.lsm [4m[22mmac[24m   Set the leading space macro (trap) to [4mmac[24m.
     [1m.ls        [22mChange to the previous value of additional intra‐line skip.
     [1m.ls [4m[22mn[24m      Set additional intra‐line skip value to [4mn[24m, i.e., [4mn[24m-1 blank lines
                are inserted after each text output line.
     [1m.lt        [22mSet length of title lines to previous value.
     [1m.lt [4m[22m±N[24m     Set  length of title lines (default length 6.5[1mi[22m, default scaling
                unit [1mm[22m).
     [1m.mc        [22mCease writing margin character.
     [1m.mc [4m[22mc[24m      Begin writing margin character [4mc[24m to the  right  of  each  output
                line at a distance of 10[1mp[22m.
     [1m.mc [4m[22mc[24m [4md[24m    Begin  writing  margin  character  [4mc[24m on each output line at dis‐
                tance [4md[24m to the right of the right margin (default distance  10[1mp[22m,
                default scaling unit [1mm[22m).
     [1m.mk        [22mMark vertical drawing position in an internal register; see [1m.rt[22m.
     [1m.mk [4m[22mreg[24m    Mark vertical drawing position in register [4mreg[24m.
     [1m.mso [4m[22mfile[24m  As  ”[1mso[22m”,  except that GNU [4mtroff[24m searches for the specified [4mfile[0m
                in the same directories as macro files; see  [4mGROFF_TMAC_PATH[24m  in
                section “Environment” of ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ and [1m-m [22min section “Options” of
                the same page.
     [1m.msoquiet [4m[22mfile[0m
                As [1mmso[22m, but no warning is emitted if [4mfile[24m does not exist.
     [1m.na        [22mDisable output line adjustment.
     [1m.ne        [22mBreak  page  if distance to next page location trap is less than
                one vee.
     [1m.ne [4m[22md[24m      Break page if distance to next page location trap is  less  than
                distance [4md[24m (default scaling unit [1mv[22m).
     [1m.nf        [22mDisable  filling  of output lines; a pending output line is bro‐
                ken.  Clears [1m\n[.u][22m.
     [1m.nh        [22mDisable automatic hyphenation; same as “[1m.hy 0[22m”.
     [1m.nm        [22mDeactivate output line numbering.
     [1m.nm [4m[22m±N[0m
     [1m.nm [4m[22m±N[24m [4mm[0m
     [1m.nm [4m[22m±N[24m [4mm[24m [4ms[0m
     [1m.nm [4m[22m±N[24m [4mm[24m [4ms[24m [4mi[0m
                Activate output line numbering: number the next output line  [4m±N,[0m
                writing numbers every [4mm[24m lines (default 1), with [4ms[24m numeral widths
                ([1m\0[22m) between the line number and the output (default 1), and in‐
                denting the line number by [4mi[24m numeral widths (default 0).
     [1m.nn        [22mSuppress numbering of the next output line counted by [1mnm[22m.
     [1m.nn [4m[22mn[24m      Suppress numbering of the next [4mn[24m output lines counted by [1mnm[22m.  If
                [4mn[24m=0, cancel suppression.
     [1m.nop       [22mInterpolate a newline.
     [1m.nop [4m[22minput[0m
                Interpret [4minput[24m as if it were an input line.
     [1m.nr [4m[22mreg[24m [4m±N[0m
                Define or update register [4mreg[24m with value [4mN[24m.
     [1m.nr [4m[22mreg[24m [4m±N[24m [4mI[0m
                Define or update register [4mreg[24m with value [4mN[24m and auto‐increment [4mI[24m,
                which may be any integer.
     [1m.nroff     [22mMake the conditional expressions [1mn [22mtrue and [1mt [22mfalse.
     [1m.ns        [22mEnable  [4mno‐space[24m [4mmode[24m, ignoring [1m.sp [22mrequests until a glyph or [1m\D[0m
                primitive is output.  See [1m.rs[22m.
     [1m.nx        [22mStop processing the input file and read the next, if any.
     [1m.nx [4m[22mfile[24m   Stop processing the input file and read [4mfile[24m.
     [1m.open [4m[22mident[24m [4mfile[0m
                Open [4mfile[24m for writing and associate a stream  named  [4mident[24m  with
                it,  making  it available for ”[1mwrite[22m” requests.  Unsafe request;
                disabled by default.
     [1m.opena [4m[22mident[24m [4mfile[0m
                As “[1mopen[22m”, but if [4mfile[24m already exists, appends to it instead  of
                overwriting it.  Unsafe request; disabled by default.
     [1m.os        [22mOutput vertical space that was saved by the [1msv [22mrequest.
     [1m.output [4m[22mcharacter‐sequence[0m
                Emit  [4mcharacter‐sequence[24m  “transparently”  (directly) to [4mtroff[24m’s
                output.
     [1m.pc        [22mReset page number character to ‘[1m%[22m’.
     [1m.pc [4m[22mc[24m      Change the page number character used in titles to [4mc[24m.
     [1m.pchar [4m[22mc[24m ...
                Report, to the standard error  stream,  information  about  each
                character  (be  it  ordinary,  special, or indexed) or character
                class [4mc[24m.  A character defined by a request ([1mchar[22m, [1mfchar[22m, [1mfschar[22m,
                or [1mschar[22m) reports its contents as a JSON‐encoded string, but the
                output is not otherwise in JSON format.
     [1m.pcolor    [22mReport, to the standard error stream, each defined  color  name,
                its  color  space  identifier, and channel value assignments.  A
                device’s default stroke and/or fill colors, “default”,  are  not
                listed since they are immutable and their details unknown to the
                formatter.
     [1m.pcolor [4m[22mcol[24m ...
                Report,  to  the  standard  error  stream, the name, color space
                identifier, and channel value assignments of each color [4mcol[24m.
     [1m.pcomposite[0m
                Report, to the standard error stream,  the  list  of  configured
                composite character mappings.  See the “[1mcomposite[22m” request.  The
                “from” code point is listed first, followed by its “to” mapping.
     [1m.pev       [22mReport  the state of the current environment followed by that of
                all other environments to the standard error stream.
     [1m.pfp       [22mReport, to the standard error stream, the list of occupied  font
                mounting positions.  Occupied mounting positions are listed, one
                per line, in increasing order, followed by the typeface name; if
                the name corresponds to an abstract style, the entry ends there.
                Otherwise,  the name of the font description file and the font’s
                “internal name” datum, the meaning of which varies by output de‐
                vice, follow.
     [1m.pftr      [22mReport, to the standard error stream, the list of font  transla‐
                tions.
     [1m.phw       [22mReport,  to  the  standard error stream, the list of hyphenation
                exception words associated with  the  hyphenation  language  se‐
                lected  by the [1mhla [22mrequest.  A “[1m-[22m” marks each hyphenation point.
                A word prefixed with “[1m-[22m” is not hyphenated at all.   The  report
                suffixes  words  to which automatic hyphenation applies (meaning
                those defined in a hyphenation pattern file rather than with the
                [1mhw [22mrequest) with a tab and asterisk “[1m*[22m”.
     [1m.pi [4m[22mcommand[0m
                Pipe GNU [4mtroff[24m output through [4mcommand[24m (which  is  read  in  copy
                mode) by passing it to ]8;;man:popen(3)\[4mpopen[24m(3)]8;;\.  Multiple [1mpi [22mrequests construct
                a  multi‐stage  pipeline  in the same order as the formatter en‐
                counters the requests.  Unsafe request; disabled by default.
     [1m.pl        [22mSet page length to default 11[1mi[22m.   The  current  page  length  is
                stored in register [1m.p[22m.
     [1m.pl [4m[22m±N[24m     Change page length to [4m±N[24m (default scaling unit [1mv[22m).
     [1m.pline     [22mReport, in JSON syntax to the standard error stream, the list of
                output nodes corresponding to the pending output line.  In JSON,
                a  pair  of  empty  brackets  “[1m[ ][22m” represents an empty list.  A
                [4mpending[24m output line has not yet undergone adjustment, and  lacks
                a line number and margin character (all as applicable).
     [1m.pm        [22mReport,  to  the standard error stream, the names of all defined
                macros, strings, and diversions and their lengths in  characters
                or nodes.
     [1m.pm [4m[22mname[24m ...
                Report,  to the standard error stream, the JSON‐encoded name and
                contents of each macro, string, or diversion [4mname[24m.
     [1m.pn [4m[22m±N[24m     Set next page number.
     [1m.pnr       [22mReport the names,  values,  and  (as  applicable)  autoincrement
                amounts  and  assigned  formats  of all defined registers to the
                standard error stream.
     [1m.pnr [4m[22mreg[24m ...
                Report the name and value and, if its type is numeric,  the  au‐
                toincrement  amount and assigned format, of each register [4mreg[24m to
                the standard error stream.
     [1m.po        [22mChange to previous page offset.   The  current  page  offset  is
                available in register [1m.o[22m.
     [1m.po [4m[22m±N[24m     Alter page offset (default scaling unit [1mm[22m).
     [1m.ps        [22mRestore previous type size.
     [1m.ps [4m[22m±N[24m     Set/increase/decrease  the  type  size  to/by [4mN[24m scaled points (a
                non‐positive resulting type size  is  set  to  1  u);  also  see
                [1m\s[[4m[22m±N[24m[1m][22m.
     [1m.psbb [4m[22mpostscript‐file[0m
                Retrieve the bounding box of the PostScript image found in [4mpost‐[0m
                [4mscript‐file,[24m  which must conform to Adobe’s Document Structuring
                Conventions (DSC).  See registers [1mllx[22m, [1mlly[22m, [1murx[22m, [1mury[22m.
     [1m.pso [4m[22mcommand[0m
                As “[1mso[22m”, except that input comes from the standard output stream
                of [4mcommand[24m, which is passed to ]8;;man:popen(3)\[4mpopen[24m(3)]8;;\.  Unsafe  request;  dis‐
                abled by default.
     [1m.pstream   [22mReport, in JSON syntax to the standard error stream, the list of
                open  streams,  including the name of each open stream, the name
                of the file backing it, and its mode (writing or appending).
     [1m.pwh       [22mReport names and positions of all page  location  traps  to  the
                standard error stream.
     [1m.pvs       [22mChange to previous post‐vertical line spacing.
     [1m.pvs [4m[22m±N[24m    Change post‐vertical line spacing according to [4m±N[24m (default scal‐
                ing unit [1mp[22m).
     [1m.rchar [4m[22mc[24m...
                Remove  definition of each ordinary, special, or indexed charac‐
                ter [4mc[24m, undoing the effect of a [1mchar[22m, [1mfchar[22m,  or  [1mschar  [22mrequest.
                Spaces  need not separate [4mc[24m arguments.  The character definition
                removed (if any) is the  first  encountered  in  the  resolution
                process  documented in section “Using Symbols” of [4mGroff:[24m [4mThe[24m [4mGNU[0m
                [4mImplementation[24m [4mof[24m [4mtroff[24m.  Glyphs, which are defined by font  de‐
                scription files, cannot be removed.
     [1m.rd        [22mRead insertion from standard input stream, ringing terminal bell
                as prompt.
     [1m.rd [4m[22mterminal‐message[0m
                Read insertion from standard input stream, writing [4mterminal‐mes‐[0m
                [4msage[24m to standard error stream as prompt.
     [1m.return    [22mStop  interpreting an interpolated macro, skipping the remainder
                of its definition.
     [1m.return [4m[22minput[0m
                As [1mreturn[22m, but perform the skip twice——once within the macro be‐
                ing interpreted and once in an enclosing macro.
     [1m.rfschar [4m[22mf[24m [4mc[24m...
                Remove each fallback special character [4mc[24m  for  font  [4mf[24m.   Spaces
                need not separate [4mc[24m arguments.  See [1mfschar[22m.
     [1m.rj        [22mBreak,  right‐align the output of the next productive input line
                without filling, then break again.
     [1m.rj [4m[22mnpl[24m    Break, right‐align the output of the next [4mnpl[24m  productive  input
                lines  without  filling,  then  break  again.   If [4mnpl[24m ≤ 0, stop
                right‐aligning.
     [1m.rm [4m[22mname[24m ...
                Remove each request, macro, diversion, or string [4mname[24m.
     [1m.rn [4m[22mold[24m [4mnew[0m
                Rename request, macro, diversion, or string [4mold[24m to [4mnew[24m.
     [1m.rnn [4m[22mreg1[24m [4mreg2[0m
                Rename register [4mreg1[24m to [4mreg2[24m.
     [1m.rr [4m[22mreg[24m ...
                Remove each register [4mreg[24m.
     [1m.rs        [22mRestore spacing; disable no‐space mode.  See [1m.ns[22m.
     [1m.rt        [22mReturn [4m(upward[24m [4monly)[24m to vertical position marked by [1m.mk  [22mon  the
                current page.
     [1m.rt [4m[22mN[24m      Return  [4m(upward[24m  [4monly)[24m  to  vertical position [4mN[24m (default scaling
                unit [1mv[22m).
     [1m.schar [4m[22mc[24m   Define global fallback character [4mc[24m as empty.
     [1m.schar [4m[22mc[24m [4mcontents[0m
                Define global fallback character [4mc[24m as [4mcontents[24m.   As  [1mchar[22m,  but
                GNU [4mtroff[24m locates a character defined with [1mschar [22mafter any fonts
                named  as  arguments  to  the  “[1mspecial[22m”  request and before any
                mounted special fonts.
     [1m.shc       [22mReset the soft hyphen character to [1m\[hy][22m.
     [1m.shc [4m[22mc[24m     Set the soft hyphen character to [4mc[24m.
     [1m.shift     [22mShift macro or string parameters one place [4mn[24m places: argument  [4mi[0m
                becomes argument [4mi[24m-[4m1[24m; argument 1 becomes unavailable.
     [1m.shift [4m[22mn[24m   Shift  macro  or  string parameters [4mn[24m places: argument [4mi[24m becomes
                argument [4mi[24m-[4mn[24m; arguments 1 to [4mn[24m become unavailable.
     [1m.sizes [4m[22ms1[24m [4ms2[24m ... [4msn[24m [[1m0[22m]
                Set available type sizes to the list of values or  ranges;  each
                [4ms[24mi  is  interpreted  in  units  of scaled points ([1ms[22m).  GNU [4mtroff[0m
                strips a leading neutral double quote from [4ms1[24m; it reads each  [4ms[24mi
                in copy mode.
     [1m.so [4m[22mfile[24m   Replace  the  request’s  control line with the contents of [4mfile[24m,
                “sourcing” it.  GNU [4mtroff[24m searches for [4mfile[24m in  any  directories
                specified  by  [1m-I  [22mcommand‐line options, followed by the current
                working directory.  If [4mfile[24m does not exist,  the  formatter  ig‐
                nores  the  request.   (GNU  [4mtroff[24m  emits  a warning in category
                “[1mfile[22m”.)
     [1m.soquiet [4m[22mfile[0m
                As ”[1mso[22m”, but no warning is emitted if [4mfile[24m does not exist.
     [1m.sp        [22mBreak and move the next text baseline down by one vee, or  until
                springing  a  page  location trap.  If invoked with the no‐break
                control character, [1msp [22mmoves the text baseline applicable to  the
                entire pending output line.
     [1m.sp [4m[22mvertical‐distance[0m
                As  [1msp[22m,  but  move by [4mvertical‐distance[24m instead of [1m1v[22m.  Inside a
                diversion, the formatter ignores any argument.  A negative  [4mver‐[0m
                [4mtical‐distance[24m  cannot  reduce the position of the text baseline
                below zero.  Applying the boundary‐relative measurement operator
                [1m| [22moperator to [4mvertical‐distance,[24m as in “[1m|[4m[22mN[24m”, moves to a position
                relative to the page top for positive [4mN[24m, and the bottom if [4mN[24m  is
                negative.
     [1m.special   [22mEmpty  the list of special fonts designated by this request when
                given arguments.
     [1m.special [4m[22ms[24m ...
                Declare each font [4ms[24m as special, irrespective of its  description
                file,  populating  a  list that GNU [4mtroff[24m searches, in order, to
                find the glyph demanded.  GNU [4mtroff[24m searches fonts specified  as
                arguments  to  the  “[1mspecial[22m” request after those given as argu‐
                ments to the [1mfspecial [22mrequest.
     [1m.spreadwarn[0m
                Toggle the spread warning  on  and  off  (the  default)  without
                changing its value.
     [1m.spreadwarn [4m[22mN[0m
                Emit  a  [1mbreak [22mwarning if the additional space inserted for each
                space between words in an adjusted output line is  greater  than
                or equal to [4mN[24m.  A negative [4mN[24m is treated as 0.  The default scal‐
                ing unit is [1mm[22m.  At startup, [1mspreadwarn [22mis inactive and [4mN[24m is 3 m[1m.[0m
     [1m.ss [4m[22mn[24m      Set  minimum  inter‐word  space  and supplemental inter‐sentence
                space sizes to [4mn[24m 12ths of the selected font’s [1mspacewidth [22mparame‐
                ter (default: 12).
     [1m.ss [4m[22mn[24m [4mm[24m    As “[1m.ss [4m[22mn[24m”, but set supplemental inter‐sentence  space  size  to
                [4mm[24m 12ths of the selected font’s [1mspacewidth [22mparameter.
     [1m.stringdown [4m[22mstr[0m
                Replace  each  byte  in  the string named [4mstr[24m with its lowercase
                version.
     [1m.stringup [4m[22mstr[0m
                Replace each byte in the string named  [4mstr[24m  with  its  uppercase
                version.
     [1m.sty [4m[22mpos[24m [4mstyle[0m
                Associate abstract [4mstyle[24m with non‐negative font position [4mpos[24m.
     [1m.substring [4m[22mstr[24m [4mstart[24m [[4mend[24m]
                Replace  the  string named [4mstr[24m with its substring bounded by the
                indices [4mstart[24m and [4mend[24m, inclusive.  Negative indices count  back‐
                ward from the end of the string.
     [1m.sv        [22mAs [1mne[22m, but save 1 v for output with [1mos [22mrequest.
     [1m.sv [4m[22md[24m      As [1mne[22m, but save distance [4md[24m for later output with [1mos [22mrequest (de‐
                fault scaling unit [1mv[22m).
     [1m.sy [4m[22mcommand[0m
                Execute  [4mcommand[24m  (which  is read in copy mode) in the operating
                environment by passing it to ]8;;man:system(3)\[4msystem[24m(3)]8;;\.   See  register  [1msystat[22m.
                Unsafe request; disabled by default.
     [1m.ta        [22mClear tab stops.
     [1m.ta [4m[22mn1[24m [4mn2[24m ... [4mn[24mn [1mT [4m[22mr1[24m [4mr2[24m ... [4mr[24mn
                Set  tabs  at  positions  [4mn1[24m,  [4mn2[24m,  ...,  [4mn[24mn,  then  set tabs at
                [4mn[24mn+[4mm[24m×[4mr[24mn+[4mr1[24m through [4mn[24mn+[4mm[24m×[4mr[24mn+[4mr[24mn, where [4mm[24m increments from 0, 1,  2,
                ...  to the output line length.  Each [4mn[24m argument can be prefixed
                with a “[1m+[22m” to place the tab stop [4mni[24m at a  distance  relative  to
                the  previous,  [4mn[24m([4mi[24m-1).   Each argument [4mni[24m or [4mri[24m can be suffixed
                with a letter to align text within the tab column bounded by tab
                stops [4mi[24m and [4mi[24m+1; “[1mL[22m” for left‐aligned  (the  default),  “[1mC[22m”  for
                centered, and “[1mR[22m” for right‐aligned.
     [1m.tag       [22mReserved for internal use.
     [1m.taga      [22mReserved for internal use.
     [1m.tc        [22mUnset tab repetition character.
     [1m.tc [4m[22mc[24m      Set tab repetition character to [4mc[24m (default: none).
     [1m.ti [4m[22m±N[24m     Temporarily indent next output line (default scaling unit [1mm[22m).
     [1m.tkf [4m[22mfont[24m [4ms1[24m [4mn1[24m [4ms2[24m [4mn2[0m
                Enable track kerning for [4mfont[24m.
     [1m.tl '[4m[22mleft[24m[1m'[4m[22mcenter[24m[1m'[4m[22mright[24m[1m'[0m
                Format three‐part title.
     [1m.tm        [22mWrite a newline to the standard error stream.
     [1m.tm [4m[22mterminal‐message[0m
                Send  [4mterminal‐message[24m,  followed  by a newline, to the standard
                error stream.  The formatter reads the argument to  the  end  of
                the  input line in copy mode, but does [4mnot[24m remove a leading dou‐
                ble quote; contrast [1m.tm1[22m.
     [1m.tm1       [22mAs [1mtm[22m.
     [1m.tm1 [4m[22mmessage[0m
                As [1mtm[22m, but removes a leading neutral double quote ‘[1m"[22m’ from  [4mmes‐[0m
                [4msage[24m,  permitting initial embedded spaces in it, and reads it to
                the end of the input line in copy mode.
     [1m.tmc       [22mNo operation.
     [1m.tmc [4m[22mmessage[0m
                As [1mtm1[22m, but does not append a newline.
     [1m.tr [4m[22mabcd[24m...
                Translate ordinary or special characters [4ma[24m to [4mb[24m, [4mc[24m to [4md[24m, and  so
                on prior to output.
     [1m.trf [4m[22mfile[24m  Break  and  copy  contents  of [4mfile[24m as “throughput” to GNU [4mtroff[0m
                output (see ]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\).  Unlike [1mcf[22m, characters invalid as in‐
                put to GNU [4mtroff[24m are discarded.  If [4mfile[24m’s contents do  not  end
                with a newline, [1mtrf [22mappends one.
     [1m.trin [4m[22mabcd[24m...
                As [1mtr[22m, except that [1masciify [22mignores the translation when a diver‐
                sion is interpolated.
     [1m.trnt [4m[22mabcd[24m...
                As  [1mtr[22m,  except that translations are suppressed in the argument
                to [1m\![22m.
     [1m.troff     [22mMake the conditional expressions [1mt [22mtrue and [1mn [22mfalse.
     [1m.uf [4m[22mfont[24m   Set underline font used by [1mul [22mto [4mfont.[0m
     [1m.ul        [22mUnderline (italicize in [4mtroff[24m mode) the output of the next  pro‐
                ductive input line.
     [1m.ul [4m[22mnpl[24m    Underline  (italicize  in [4mtroff[24m mode) the output of the next [4mnpl[0m
                productive input line.  If [4mnpl[24m=0, stop underlining.
     [1m.unformat [4m[22mdiv[0m
                Unformat space characters and tabs in diversion [4mdiv[24m,  preserving
                font information.
     [1m.vpt       [22mEnable vertical position traps.  They are enabled by default.
     [1m.vpt [4m[22mb[24m     Enable or disable vertical position traps per Boolean expression
                [4mb[24m.
     [1m.vs        [22mChange to previous vertical spacing.
     [1m.vs [4m[22m±N[24m     Set vertical spacing to [4m±N[24m (default scaling unit [1mp[22m).
     [1m.warn      [22mEnable all warning categories.
     [1m.warn 0    [22mDisable all warning categories.
     [1m.warn [4m[22mn[24m    Enable  warnings  in  categories  whose  codes  sum  to  [4mn[24m;  see
                ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\.
     [1m.warnscale [4m[22mscaling‐unit[0m
                Select scaling unit used in certain warnings (one of [1mu[22m, [1mi[22m, [1mc[22m, [1mp[22m,
                or [1mP[22m; default: [1mi[22m).  Ignored on [4mnroff[24m‐mode  output  devices,  for
                which  these  diagnostics  report  the vertical page location in
                lines, and the horizontal page location in ens.
     [1m.wh [4m[22mvertical‐position[0m
                Remove visible page location trap at [4mvertical‐position[24m  (default
                scaling unit [1mv[22m).
     [1m.wh [4m[22mvertical‐position[24m [4mmac[0m
                Plant  macro [4mmac[24m as page location trap at [4mvertical‐position[24m (de‐
                fault scaling unit [1mv[22m), removing any visible trap already there.
     [1m.while [4m[22mcond‐expr[0m
                Interpolate newlines unless and until [4mcond‐expr[24m evaluates false.
     [1m.while [4m[22mcond‐expr[24m [4minput[0m
                Repeatedly execute [4minput[24m unless and  until  [4mcond‐expr[24m  evaluates
                false.
     [1m.write [4m[22mstream[24m [4mcharacter‐sequence[0m
                Write  [4mcharacter‐sequence[24m,  a  sequence  of ordinary characters,
                spaces, or tabs, to [4mstream[24m, which must previously have been  the
                subject  of an “[1mopen[22m” (or [1mopena[22m) request, followed by a newline.
                GNU [4mtroff[24m flushes the stream after writing to it.
     [1m.writec [4m[22mstream[24m [4mcharacter‐sequence[0m
                As ”[1mwrite[22m”, but does not write a newline to the output.
     [1m.writem [4m[22mstream[24m [4mname[0m
                Write the contents of the macro or string [4mname[24m to [4mstream[24m,  which
                must  previously  have  been the subject of an “[1mopen[22m” (or [1mopena[22m)
                request.  GNU [4mtroff[24m reads the contents of [4mname[24m in copy mode.

[1mEscape sequence short reference[0m
     The escape sequences [1m\"[22m, [1m\#[22m, [1m\$[22m, [1m\*[22m, [1m\?[22m, [1m\a[22m, [1m\e[22m, [1m\n[22m, [1m\t[22m, [1m\g[22m, [1m\V[22m, and  [1m\[4m[22mnew‐[0m
     [4mline[24m are interpreted even in copy mode.

     The  escape  sequences [1m\f[22m, [1m\F[22m, [1m\H[22m, [1m\m[22m, [1m\M[22m, [1m\R[22m, [1m\s[22m, and [1m\S [22mare not tokenized
     when GNU [4mtroff[24m reads its input.  [1m\R [22mupdates only the  formatter’s  register
     dictionary, and does not contribute (directly) to output.  The others alter
     the environment (see section “Environments” below).  See the “GNU troff In‐
     ternals” section of the [4mgroff[24m Texinfo manual.

     [1m\"     [22mComment;  read  everything  up  to the next newline in copy mode and
            discard it.
     [1m\#     [22mWhole‐line comment; read everything up to  and  including  the  next
            newline in copy mode and discard it.
     [1m\*[4m[22ms[24m    Interpolate string with one‐character name [4ms[24m.
     [1m\*([4m[22mst[24m  Interpolate string with two‐character name [4mst[24m.
     [1m\*[[4m[22mstring[24m[1m][0m
            Interpolate string with name [4mstring[24m (of arbitrary length).
     [1m\*[[4m[22mstring[24m [4marg[24m ...[1m][0m
            Interpolate  string  with  name [4mstring[24m (of arbitrary length), taking
            [4marg[24m ... as arguments.
     [1m\$0    [22mInterpolate name by which currently executing macro was invoked.
     [1m\$[4m[22mn[24m    Interpolate macro or string parameter numbered [4mn[24m (1≤[4mn[24m≤9).
     [1m\$([4m[22mnn[24m  Interpolate macro or string parameter numbered [4mnn[24m (01≤[4mnn[24m≤99).
     [1m\$[[4m[22mnnn[24m[1m][0m
            Interpolate macro or string parameter numbered [4mnnn[24m ([4mnnn[24m≥1).
     [1m\$*    [22mInterpolate catenation of all macro or string parameters,  separated
            by spaces.
     [1m\$@    [22mInterpolate  catenation of all macro or string parameters, with each
            surrounded by double quotes and separated by spaces.
     [1m\$^    [22mInterpolate catenation of all macro or string parameters as if  they
            were arguments to the [1mds [22mrequest.
     [1m\'     [22mis a synonym for [1m\[aa][22m, the acute accent special character.
     [1m\`     [22mis a synonym for [1m\[ga][22m, the grave accent special character.
     [1m\-     [22mis a synonym for [1m\[-][22m, the minus sign special character.
     [1m\_     [22mis a synonym for [1m\[ul][22m, the underrule special character.
     [1m\%     [22mMark a hyphenation point within a word.  At the beginning of a word,
            prevent it from being otherwise hyphenated.
     [1m\![4m[22mcharacter‐sequence[0m
            [4mTransparently[24m  embed [4mcharacter‐sequence[24m, up to and including the end
            of the line, into the current diversion, requests, macro calls,  and
            escape  sequences when reading them into a diversion.  Doing so pre‐
            vents them from taking effect until the diverted  text  is  actually
            output.
     [1m\?[4m[22mcharacter‐sequence[24m[1m\?[0m
            Transparently  embed  [4mcharacter‐sequence[24m,  up to its own next occur‐
            rence on the input line, into a diversion, or unformatted as an out‐
            put comparand in a conditional expression.  Ignored in the top‐level
            diversion.
     [1m\[4m[22mspace[24m  Move right one inter‐word space.
     [1m\~      [22mInsert an unbreakable, adjustable space.
     [1m\0      [22mMove right by the width of a numeral in the current font.
     [1m\|      [22mMove one‐sixth em to the right on typesetters.
     [1m\^      [22mMove one‐twelfth em to the right on typesetters.
     [1m\&      [22mInterpolate a dummy character.
     [1m\)      [22mInterpolate a dummy character that is  transparent  to  end‐of‐sen‐
             tence recognition.
     [1m\/      [22mApply  italic  correction.   Use  between  an  immediately adjacent
             oblique glyph on the left and an upright glyph on the right.
     [1m\,      [22mApply left italic correction.  Use between an immediately  adjacent
             upright glyph on the left and an oblique glyph on the right.
     [1m\:      [22mNon‐printing  break  point (similar to [1m\%[22m, but never produces a hy‐
             phen glyph).
     [1m\[4m[22mnewline[0m
             Continue current input line on the next.
     [1m\{      [22mBegin conditional input.
     [1m\}      [22mEnd conditional input.
     [1m\([4m[22msc[24m    Interpolate glyph of special character with  two‐character  identi‐
             fier [4msc[24m.
     [1m\[[4m[22mspchar[24m[1m][0m
             Interpolate  glyph  of special character with identifier [4mspchar[24m (of
             arbitrary length).
     [1m\[[4m[22mbase‐char[24m [4mcomp[24m ...[1m][0m
             Interpolate composite glyph constructed  from  [4mbase‐char[24m  and  each
             component [4mcomp[24m.
     [1m\[char[4m[22mnnn[24m[1m][0m
             Interpolate   glyph  of  eight‐bit  encoded  character  [4mnnn[24m,  where
             0≤[4mnnn[24m≤255.
     [1m\[u[4m[22mnnnn[24m[[4mn[24m[[4mn[24m]][1m][0m
             Interpolate glyph of Unicode character with code  point  [4mnnnn[24m[[4mn[24m[[4mn[24m]]
             in uppercase hexadecimal.
     [1m\[u[4m[22mbase‐char[24m[[1m_[4m[22mcombining‐component[24m]...[1m][0m
             Interpolate  composite  glyph  from Unicode character [4mbase‐char[24m and
             [4mcombining‐components[24m.
     [1m\a      [22mInterpolate a leader in copy mode.
     [1m\A'[4m[22minput[24m[1m'[0m
             Interpolate 1 if [4minput[24m is a valid identifier, and 0 otherwise.  Be‐
             cause GNU [4mtroff[24m ignores any input character with  an  invalid  code
             when  reading  it, invalid identifiers are empty or contain spaces,
             tabs, newlines, or  escape  sequences  that  interpolate  something
             other than a sequence of ordinary characters.
     [1m\b'[4m[22mstring[24m[1m'[0m
             Build  bracket:  pile  a  sequence  of glyphs corresponding to each
             character in [4mstring[24m vertically, and center  it  vertically  on  the
             output line.
     [1m\B'[4m[22minput[24m[1m'[0m
             Interpolate  1 if [4minput[24m is a valid numeric expression, and 0 other‐
             wise.
     [1m\c      [22mContinue output line at next input line.
     [1m\C'[4m[22mglyph[24m[1m'[0m
             As [1m\[[4m[22mglyph[24m[1m][22m, but compatible with other [4mtroff[24m implementations.
     [1m\d      [22mMove downward ½ em on typesetters.
     [1m\D'[4m[22mdrawing‐command[24m[1m'[0m
             See subsection “Drawing commands” below.
     [1m\e      [22mInterpolate the escape character.
     [1m\E      [22mAs [1m\e[22m, but not interpreted in copy mode.
     [1m\fP     [22mSelect previous font mounting position (abstract  style  or  font);
             same as “[1m.ft[22m” or “[1m.ft P[22m”.
     [1m\f[4m[22mF[24m     Select  font  mounting  position, abstract style, or font with one‐
             character name or one‐digit position [4mF[24m.  [4mF[24m cannot be [1mP[22m.
     [1m\f([4m[22mft[24m   Select font mounting position, abstract style, or  font  with  two‐
             character name or two‐digit position [4mft[24m.
     [1m\f[[4m[22mfont[24m[1m][0m
             Select  font  mounting position, abstract style, or font with arbi‐
             trarily long name or position [4mfont[24m.  [4mfont[24m cannot be [1mP[22m.
     [1m\f[]    [22mSelect previous font mounting position (abstract style or font).
     [1m\F[4m[22mf[24m     Set default font family to that with one‐character name [4mf[24m.
     [1m\F([4m[22mfm[24m   Set default font family to that with two‐character name [4mfm[24m.
     [1m\F[[4m[22mfam[24m[1m][0m
             Set default font family to that with arbitrarily long name [4mfam[24m.
     [1m\F[]    [22mSet default font family to previous value.
     [1m\g[4m[22mr[24m     Interpolate format of register with one‐character name [4mr[24m.
     [1m\g([4m[22mrg[24m   Interpolate format of register with two‐character name [4mrg[24m.
     [1m\g[[4m[22mreg[24m[1m][0m
             Interpolate format of register with arbitrarily long name [4mreg[24m.
     [1m\h'[4m[22mN[24m[1m'   [22mHorizontally move the drawing  position  by  [4mN[24m  ems  (or  specified
             units); [1m| [22mmay be used.  Positive motion is rightward.
     [1m\H'[4m[22mN[24m[1m'   [22mSet  (increment, decrement) the height of the current font, but not
             its width.  If [4mN[24m is zero, the formatter uses  the  font’s  inherent
             height for its type size default scaling unit [1mz[22m).
     [1m\k[4m[22mr[24m     Store the horizontal drawing position, relative to that correspond‐
             ing to the start of the input line (ignoring page offset and inden‐
             tation), in register name [4mr[24m.
     [1m\k([4m[22mrg[24m   Store the horizontal drawing position, relative to that correspond‐
             ing to the start of the input line (ignoring page offset and inden‐
             tation), in register name [4mrg[24m.
     [1m\k[[4m[22mreg[24m[1m][0m
             Store the horizontal drawing position, relative to that correspond‐
             ing to the start of the input line (ignoring page offset and inden‐
             tation), in register name [4mreg[24m.
     [1m\l'[4m[22mN[24m[[4mc[24m][1m'[0m
             Draw  horizontal line of length [4mN[24m with character [4mc[24m (default: [1m\[ru][22m;
             default scaling unit [1mm[22m).
     [1m\L'[4m[22mN[24m[[4mc[24m][1m'[0m
             Draw vertical line of length [4mN[24m with character  [4mc[24m  (default:  [1m\[br][22m;
             default scaling unit [1mv[22m).
     [1m\m[4m[22mc[24m     Select stroke color with one‐character name [4mc[24m.
     [1m\m([4m[22mcl[24m   Select stroke color with two‐character name [4mcl[24m.
     [1m\m[[4m[22mcolor[24m[1m][0m
             Select stroke color with arbitrarily long name [4mcolor[24m.
     [1m\m[]    [22mRestore previous stroke color.
     [1m\M[4m[22mc[24m     Select fill color with one‐character name [4mc[24m.
     [1m\M([4m[22mcl[24m   Select fill color with two‐character name [4mcl[24m.
     [1m\M[[4m[22mcolor[24m[1m][0m
             Select fill color with arbitrarily long name [4mcolor[24m.
     [1m\M[]    [22mRestore previous fill color.
     [1m\n[4m[22mr[24m     Interpolate value of register with one‐character name [4mr[24m.
     [1m\n([4m[22mrg[24m   Interpolate value of register with two‐character name [4mrg[24m.
     [1m\n[[4m[22mreg[24m[1m][0m
             Interpolate value of register with arbitrarily long name [4mreg[24m.
     [1m\N'[4m[22mn[24m[1m'   [22mFormat indexed character numbered [4mn[24m in the current font.
     [1m\o'[4m[22mabc[24m...[1m'[0m
             Overstrike centered glyphs of characters [4ma[24m, [4mb[24m, [4mc[24m, and so on.
     [1m\O0     [22mAt  the outermost suppression level, disable emission of glyphs and
             geometric objects to the output driver.
     [1m\O1     [22mAt the outermost suppression level, enable emission of  glyphs  and
             geometric objects to the output driver.
     [1m\O2     [22mAt  the  outermost  suppression  level,  enable glyph and geometric
             primitive emission to the output driver and write to  the  standard
             error stream the page number, four bounding box registers enclosing
             glyphs written since the previous [1m\O [22mescape sequence, the page off‐
             set, line length, image file name (if any), horizontal and vertical
             device motion quanta, and input file name.
     [1m\O3     [22mBegin a nested suppression level.
     [1m\O4     [22mEnd a nested suppression level.
     [1m\O[5[4m[22mPfile[24m[1m][0m
             At  the  outermost  suppression  level,  write the name [4mfile[24m to the
             standard error stream at position [4mP[24m, which must be one of [1ml[22m, [1mr[22m,  [1mc[22m,
             or [1mi[22m.
     [1m\p      [22mBreak output line at next word boundary; adjust if applicable.
     [1m\r      [22mMove “in reverse” (upward) 1 em.
     [1m\R'[4m[22mname[24m [4m±N[24m[1m'[0m
             Set, increment, or decrement register [4mname[24m by [4mN[24m.
     [1m\s[4m[22m±N[24m    Set/increase/decrease  the type size to/by [4mN[24m scaled points.  [4mN[24m must
             be a single digit.  If [4mn[24m is an unsigned “0”, restore  the  previous
             size.   (In  compatibility  mode  only, a non‐zero [4mN[24m must be in the
             range 4–39.)  Otherwise, as [1mps [22mrequest.
     [1m\s([4m[22m±N[0m
     [1m\s[4m[22m±[24m[1m([4m[22mN[24m   Set/increase/decrease the type size to/by [4mN[24m scaled points; [4mN[24m  is  a
             two‐digit  number ≥1.  If [4mn[24m is an unsigned “00”, restore the previ‐
             ous size.  Otherwise, as [1mps [22mrequest.
     [1m\s[[4m[22m±N[24m[1m][0m
     [1m\s[4m[22m±[24m[1m[[4m[22mN[24m[1m][0m
     [1m\s'[4m[22m±N[24m[1m'[0m
     [1m\s[4m[22m±[24m[1m'[4m[22mN[24m[1m'  [22mSet/increase/decrease the type size to/by [4mN[24m scaled points.  If [4mn[24m is
             an unsigned “0” (with any number of leading  zeroes),  restore  the
             previous size.  Otherwise, as [1mps [22mrequest.
     [1m\S'[4m[22mN[24m[1m'   [22mSlant the glyphs of the currently selected font by @var{N} degrees.
             Positive  values slant in the direction of text flow.  Only integer
             values are possible.
     [1m\t      [22mInterpolate a tab in copy mode.
     [1m\u      [22mMove upward ½ em on typesetters.
     [1m\v'[4m[22mN[24m[1m'   [22mVertically move the  drawing  position  by  [4mN[24m  vees  (or  specified
             units); [1m| [22mmay be used.  Positive motion is downward.
     [1m\V[4m[22me[24m     Interpolate value of system environment variable with one‐character
             name [4me[24m as returned by ]8;;man:getenv(3)\[4mgetenv[24m(3)]8;;\.
     [1m\V([4m[22mev[24m   Interpolate value of system environment variable with two‐character
             name [4mev[24m as returned by ]8;;man:getenv(3)\[4mgetenv[24m(3)]8;;\.
     [1m\V[[4m[22menv[24m[1m][0m
             Interpolate  value  of system environment variable with arbitrarily
             long name [4menv[24m as returned by ]8;;man:getenv(3)\[4mgetenv[24m(3)]8;;\.
     [1m\w'[4m[22minput[24m[1m'[0m
             Interpolate the width of [4minput[24m, as  interpreted,  in  basic  units.
             This  escape sequence allows several properties of formatted output
             to be measured without writing it out.  The formatter processes [4min‐[0m
             [4mput[24m in a dummy environment: this means  that  font  and  type  size
             changes,  for example, may occur within it without affecting subse‐
             quent output.
     [1m\x'[4m[22mN[24m[1m'   [22mIncrease vertical spacing of pending output  line  by  [4mN[24m  vees  (or
             specified units; negative before, positive after).
     [1m\X'[4m[22mcharacter‐sequence[24m[1m'[0m
             Write [4mcharacter‐sequence[24m to [4mtroff[24m output as a device extension com‐
             mand.   The [4mgroff[24m special character repertoire is unknown to output
             drivers outside of glyphs named in a device’s fonts, and even  then
             they  may  not possess complete coverage of the names documented in
             ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\.  Further, escape sequences that  produce  horizontal
             or  vertical motions, hyphenation breaks, or that are dummy charac‐
             ters may appear in strings or be converted to  nodes,  particularly
             in  diversions.   These are not representable when interpolated di‐
             rectly into device‐independent output, as might be done when  writ‐
             ing out tag names for PDF bookmarks, which can appear in a viewer’s
             navigation pane.

             So  that  documents  or  macro  packages do not have to laboriously
             “sanitize” strings destined for interpolation in  device  extension
             commands,  this escape sequence performs certain transformations on
             its argument.  For these  transformations,  character  translations
             and definitions are ignored.

             GNU [4mtroff[24m converts several ordinary characters that typeset as non‐
             basic  Latin  code points to code points outside that range so that
             they are used consistently whether they are formatted as glyphs  or
             used  in a device control command argument.  These ordinary charac‐
             ters are “[1m'[22m”, “[1m-[22m”, “[1m^[22m”, “[1m`[22m”, and “[1m~[22m”; others are written as‐is.

             Special characters that typeset as Unicode basic  Latin  characters
             are  translated to basic Latin characters accordingly.  So that any
             Unicode code point can be represented in device extension commands,
             for example in an author’s name in document metadata or as  a  use‐
             fully named bookmark or hyperlink anchor, GNU [4mtroff[24m maps other spe‐
             cial  characters  to  Unicode  special character notation.  Special
             characters without a Unicode representation, and  escape  sequences
             that do not interpolate a sequence of ordinary and/or special char‐
             acters, produce warnings in category “[1mchar[22m”.
     [1m\Y[4m[22mn[24m     Write contents of macro or string [4mn[24m to [4mtroff[24m output as a device ex‐
             tension command.
     [1m\Y([4m[22mnm[24m   Write  contents  of  macro or string [4mnm[24m to [4mtroff[24m output as a device
             extension command.
     [1m\Y[[4m[22mname[24m[1m][0m
             Write contents of macro or string [4mname[24m to [4mtroff[24m output as a  device
             extension command.
     [1m\z[4m[22mc[24m     Format  character  [4mc[24m with zero width——without advancing the drawing
             position.
     [1m\Z'[4m[22minput[24m[1m'[0m
             Save the drawing position, format  [4minput[24m,  then  restore  it.   GNU
             [4mtroff[24m ignores tabs and leaders in [4minput[24m with an error diagnostic.

   [1mDrawing commands[0m
     Drawing  commands  direct  the  output device to render geometrical objects
     rather than glyphs.  Specific devices may support only  a  subset,  or  may
     feature additional ones; consult the man page for the output driver in use.
     Terminals in particular implement almost none.

     Rendering  starts at the drawing position; when finished, the drawing posi‐
     tion is left at the rightmost point of the object, even for closed figures,
     except where noted.  GNU [4mtroff[24m draws stroked (outlined)  objects  with  the
     stroke  color,  and  shades  filled  ones with the fill color.  See section
     “Colors” above.  Coordinates [4mh[24m and [4mv[24m are horizontal  and  vertical  motions
     relative to the drawing position or previous point in the command.  The de‐
     fault  scaling  unit for horizontal measurements (and diameters of circles)
     is [1mm[22m; for vertical ones, [1mv[22m.

     Circles, ellipses, and polygons can be drawn stroked or filled.  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 al‐
     ways smaller than an outlined one because the former is drawn  only  within
     its defined area, whereas strokes have a line thickness (set with [1m\D't'[22m).

     [1m\D'~ [4m[22mh1[24m [4mv1[24m ... [4mhn[24m [4mvn[24m[1m'[0m
            Draw B‐spline to each point in sequence, leaving drawing position at
            ([4mhn[24m, [4mvn[24m).
     [1m\D'a [4m[22mhc[24m [4mvc[24m [4mh[24m [4mv[24m[1m'[0m
            Draw  circular  arc  centered  at ([4mhc[24m, [4mvc[24m) counterclockwise from the
            drawing position to a point ([4mh[24m, [4mv[24m) relative to the center.  ([4mhc[24m, [4mvc[24m)
            is adjusted to the point nearest the perpendicular bisector  of  the
            arc’s chord.
     [1m\D'c [4m[22md[24m[1m'[0m
            Draw circle of diameter [4md[24m with its leftmost point at the drawing po‐
            sition.
     [1m\D'C [4m[22md[24m[1m'[0m
            As [1m\D'C'[22m, but the circle is filled.
     [1m\D'e [4m[22mh[24m [4mv[24m[1m'[0m
            Draw  ellipse of width [4mh[24m and height [4mv[24m with its leftmost point at the
            drawing position.
     [1m\D'E [4m[22mh[24m [4mv[24m[1m'[0m
            As [1m\D'e'[22m, but the ellipse is filled.
     [1m\D'l [4m[22mh[24m [4mv[24m[1m'[0m
            Draw line from the drawing position to ([4mh[24m, [4mv[24m).
     [1m\D'p [4m[22mh1[24m [4mv1[24m ... [4mhn[24m [4mvn[24m[1m'[0m
            Draw polygon with vertices at the drawing position and each point in
            sequence.  GNU [4mtroff[24m closes the  polygon  by  drawing  a  line  from
            ([4mhn[24m, [4mvn[24m) back to the initial drawing position.  Afterward, the draw‐
            ing position is left at ([4mhn[24m, [4mvn[24m).
     [1m\D'P [4m[22mh1[24m [4mv1[24m ... [4mhn[24m [4mvn[24m[1m'[0m
            As [1m\D'p'[22m, but the polygon is filled.
     [1m\D't [4m[22mn[24m[1m'[0m
            Set  stroke  thickness  of geometric objects to to [4mn[24m basic units.  A
            zero [4mn[24m selects the minimum supported thickness.  A  negative  [4mn[24m  se‐
            lects  a  thickness  proportional  to the type size; this is the de‐
            fault.

[1mStrings[0m
     [4mgroff[24m supports strings primarily for user convenience.  Conventionally,  if
     one  would define a macro only to interpolate a small amount of text, with‐
     out invoking requests or calling any other macros, one defines a string in‐
     stead.  Only one string is predefined by the language.

     \*[[1m.T[22m]     Contains the name of the output device (for example,  “[1mutf8[22m”  or
                “[1mpdf[22m”[1m).[0m

     The [1mds [22mrequest creates a string with a specified name and contents.  If the
     identifier  named by [1mds [22malready exists as an alias, the target of the alias
     is redefined.  If [1mds [22mis invoked with only one argument,  the  named  string
     becomes  empty.   The  formatter removes a leading neutral double quote ‘[1m"[22m’
     from [4mcontents[24m to permit the embedding of leading spaces.  It interprets any
     other ‘[1m"[22m’ literally, but the wise author uses the special character  escape
     sequence  [1m\[dq]  [22minstead  if  the string might be interpolated as part of a
     macro argument; see section “Calling macros” above.

     The [1m\* [22mescape sequence dereferences a string’s name, interpolating its con‐
     tents.  If the name does not exist, the formatter defines it as empty,  in‐
     terpolates  nothing,  and  emits  a warning in category “[1mmac[22m”.  See section
     “Warnings” in ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\.  The bracketed interpolation form accepts arguments
     that are handled as macro  arguments  are;  see  section  “Calling  macros”
     above.   In  contrast  to  macro  calls,  an  argument containing a closing
     bracket [1m] [22mmust be enclosed in double quotes.  When defining strings,  argu‐
     ment  interpolations  must  be  escaped if they are to reference parameters
     from the calling context; see section “Parameters” below.  Any  non‐initial
     neutral  double quote [1m" [22mis interpreted literally, but it is wise to use the
     special character escape sequence [1m\[dq] [22minstead if the string might be  in‐
     terpolated as part of a macro argument; see section “Calling macros” above.
     Strings  are  not  limited  to a single input line of text.  [1m\[4m[22mnewline[24m works
     just as it does elsewhere.  The resulting string is stored [4mwithout[24m the new‐
     lines.  When filling is disabled, care is required to avoid overrunning the
     line length when interpolating strings.  Conversely, when  filling  is  en‐
     abled,  it  is not necessary to append [1m\c [22mto a string interpolation to pre‐
     vent a break afterward, as might be required in a macro argument.  Nor does
     a string require use of the GNU [4mtroff[24m [1mchop [22mrequest  to  excise  a  trailing
     newline  as  is  often done with diversions.  It is not possible to embed a
     newline in a string that will be interpreted as such when the string is in‐
     terpolated.  To achieve that effect, use [1m\* [22mto interpolate a macro instead;
     see section “Punning names” below.

     The “[1mas[22m” request is similar to [1mds [22mbut appends to a string  instead  of  re‐
     defining  it.   If  “[1mas[22m” is invoked with only one argument, no operation is
     performed (beyond dereferencing the string).

     Because strings are similar to macros, they too can be defined to  suppress
     AT&T  [4mtroff[24m  compatibility  mode  enablement when interpolated; see section
     “Compatibility mode” below.  The [1mds1 [22mrequest defines a string that suspends
     compatibility mode when the string is later interpolated.  [1mas1 [22mis  likewise
     similar  to  “[1mas[22m”, with compatibility mode suspended when the appended por‐
     tion of the string is later interpolated.

     [4mCaution:[24m These requests treat the remainder of the input line as their sec‐
     ond argument, including any spaces, up to a newline or comment  escape  se‐
     quence.   Ending  string definitions (and appendments) with a comment, even
     an empty one, prevents unwanted space from creeping into them during source
     document maintenance.  This rule and suggestion also applies to the  second
     argument of the “[1mlength[22m” request, to requests that define characters ([1mchar[22m,
     [1mfchar[22m, [1mfschar[22m, and [1mschar[22m), and to the file name or command arguments of the
     [1mcf[22m,  [1mhpf[22m,  [1mhpfa[22m,  [1mmso[22m, [1mmsoquiet[22m, [1mnx[22m, “[1mopen[22m”, [1mopena[22m, [1mpi[22m, [1mpso[22m, “[1mso[22m”, [1msoquiet[22m,
     and [1mtrf [22mrequests.

     Several requests exist to perform rudimentary string  operations.   Strings
     can   be   queried   ([1mlength[22m)  and  modified  ([1mchop[22m,  [1msubstring[22m,  [1mstringup[22m,
     [1mstringdown[22m), and their names can be manipulated through renaming,  removal,
     and aliasing ([1mrn[22m, [1mrm[22m, [1mals).[0m

     Redefinitions  and  appendments “write through” request, macro, string, and
     diversion names.  To replace an aliased object with  a  separately  defined
     one, you must use the [1mrm [22mrequest on its name first.

[1mRegisters[0m
     In  the [4mroff[24m language, numbers and measurements can be stored in [4mregisters.[0m
     Many built‐in registers exist, supplying anything from  components  of  the
     date to details of formatting parameters; some of these are read‐only.  You
     can  also  define  your own.  See section “Identifiers” above regarding the
     construction of valid names for registers.

     Each register (except read‐only ones) can be assigned a [4mformat[24m, causing its
     value to interpolate with leading zeroes, in Roman numerals, or  alphabeti‐
     cally.   Some  read‐only registers are string‐valued, meaning that they in‐
     terpolate text and lack a format.

     Define registers and update their values with the [1mnr [22mrequest or the [1m\R  [22mes‐
     cape sequence.

     User‐defined  registers can also be incremented or decremented by a config‐
     ured amount at the time they are interpolated.  The value of the  increment
     is  specified with a third argument to the [1mnr [22mrequest, and a special inter‐
     polation syntax, [1m\n[4m[22m±[24m, alters and then retrieves the register’s value.   To‐
     gether,  these features are called [4mauto‐increment[24m.  (A negative auto‐incre‐
     ment can be considered an “auto‐decrement”.)

     Many predefined registers are available.  The following  presentation  uses
     register  interpolation  syntax  [1m\n[[4m[22mname[24m[1m]  [22mto  refer  to a register [4mname[24m to
     clearly distinguish it from a string or request [4mname[24m; the symbols [1m\n[]  [22mare
     [4mnot[24m  part  of  the register name.  The register name space is separate from
     that used for requests, macros, strings, and diversions.

   [1mRead‐only registers[0m
     Predefined registers whose identifiers start  with  a  dot  are  read‐only.
     Many are Boolean‐valued.

     [4mCaution:[24m  Built‐in  registers  are subject to removal like others; once re‐
     moved, they can be recreated only as normal writable registers and will not
     otherwise reflect the configuration of the formatter.

     A register name is often associated with a request of the same name  (with‐
     out the dot); exceptions are noted.

     \n[[1m.$[22m]         Count of arguments passed to currently interpolated macro or
                    string.
     \n[[1m.a[22m]         Amount of extra post‐vertical line space; see [1m\x[22m.
     \n[[1m.A[22m]         Approximate  output is being formatted (Boolean‐valued); see
                    [4mtroff[24m [1m-a [22moption.
     \n[[1m.b[22m]         Font emboldening offset; see [1mbd[22m.
     \n[[1m.br[22m]        The normal control character was used to call the macro  be‐
                    ing interpreted (Boolean‐valued).
     \n[[1m.c[22m]         Input line number; see [1mlf [22mand register “[1mc.[22m”.
     \n[[1m.C[22m]         AT&T  [4mtroff[24m  compatibility mode is enabled (Boolean‐valued);
                    see [1mcp[22m.  Always false when  processing  ”[1mdo[22m”;  see  register
                    [1m.cp[22m.
     \n[[1m.cdp[22m]       Depth  of  last glyph formatted in the environment; positive
                    if glyph extends below the baseline.
     \n[[1m.ce[22m]        Count of input lines remaining to be centered in  the  envi‐
                    ronment.
     \n[[1m.cht[22m]       Height  of last glyph formatted in the environment; positive
                    if glyph extends above the baseline.
     \n[[1m.color[22m]     Color output is enabled (Boolean‐valued).
     \n[[1m.cp[22m]        Within ”[1mdo[22m”, the saved value of compatibility mode; see reg‐
                    ister [1m.C[22m.
     \n[[1m.csk[22m]       Skew of the last glyph formatted  in  the  environment;  see
                    register [1mskw[22m.
     \n[[1m.d[22m]         Vertical drawing position in diversion.
     \n[[1m.ev[22m]        Name of environment (string‐valued).
     \n[[1m.f[22m]         Mounting position of selected font; see [1mft [22mand [1m\f[22m.
     \n[[1m.F[22m]         Name of input file (string‐valued); see [1mlf[22m.
     \n[[1m.fam[22m]       Name  of  the environment’s default font family (string‐val‐
                    ued).
     \n[[1m.fn[22m]        Resolved name of font selected in the  environment  (string‐
                    valued); see [1mft [22mand [1m\f[22m.
     \n[[1m.fp[22m]        Next non‐zero free font mounting position index.
     \n[[1m.g[22m]         Always true in GNU [4mtroff[24m (Boolean‐valued).
     \n[[1m.h[22m]         Text baseline high‐water mark on page or in diversion.
     \n[[1m.H[22m]         Horizontal motion quantum of output device in basic units.
     \n[[1m.height[22m]    Height of the environment’s selected font; see [1m\H[22m.
     \n[[1m.hla[22m]       Hyphenation language in environment (string‐valued).
     \n[[1m.hlc[22m]       Count  of immediately preceding consecutive hyphenated lines
                    in environment.
     \n[[1m.hlm[22m]       Maximum quantity of consecutive hyphenated lines allowed  in
                    environment.
     \n[[1m.hy[22m]        Automatic hyphenation mode in environment.
     \n[[1m.hydefault[22m]
                    Hyphenation mode default in environment.
     \n[[1m.hym[22m]       Hyphenation margin in environment.
     \n[[1m.hys[22m]       Hyphenation space adjustment threshold in environment.
     \n[[1m.i[22m]         Environment’s indentation amount; see ”[1min[22m”.
     \n[[1m.in[22m]        Indentation  amount applicable to the output line pending in
                    the environment; see [1mti[22m.
     \n[[1m.int[22m]       The text most recently formatted in the environment was “in‐
                    terrupted” or continued with [1m\c [22m(Boolean‐valued).
     \n[[1m.it[22m]        Count of input lines remaining in the environment’s  pending
                    input trap.
     \n[[1m.itc[22m]       The environment’s pending input trap honors output line con‐
                    tinuation with [1m\c [22m(Boolean‐valued).
     \n[[1m.itm[22m]       Name  of  the  macro  associated with the pending input trap
                    (string‐valued).
     \n[[1m.j[22m]         The environment’s adjustment mode encoded as an integer; see
                    [1mad [22mand [1mna[22m.  Do not interpret or perform  arithmetic  on  its
                    value.
     \n[[1m.k[22m]         The  environment’s  horizontal  drawing position relative to
                    indentation.
     \n[[1m.kern[22m]      Pairwise kerning is enabled (Boolean‐valued).
     \n[[1m.l[22m]         Line length; see [1mll[22m.
     \n[[1m.L[22m]         Line spacing; see [1mls[22m.
     \n[[1m.lg[22m]        Ligature mode.
     \n[[1m.linetabs[22m]  Line‐tabs mode is enabled in the  environment  (Boolean‐val‐
                    ued).
     \n[[1m.ll[22m]        Line  length  applicable to the environment’s pending output
                    line.
     \n[[1m.lt[22m]        Environment’s title line length.
     \n[[1m.m[22m]         Stroke color (string‐valued); see [1mgcolor [22mand  [1m\m[22m.   The  de‐
                    fault stroke color is named “[1mdefault[22m”.
     \n[[1m.M[22m]         Fill  color (string‐valued); see [1mfcolor [22mand [1m\M[22m.  The default
                    fill color is named “[1mdefault[22m”.
     \n[[1m.n[22m]         Length of formatted output on previous output line.
     \n[[1m.ne[22m]        Amount of vertical space required by last [1mne [22mthat  caused  a
                    trap to be sprung; also see register [1m.trunc[22m.
     \n[[1m.nm[22m]        Output   line   numbering  is  enabled  in  the  environment
                    (Boolean‐valued).
     \n[[1m.nn[22m]        Count of lines remaining in the environment for  which  num‐
                    bering is suppressed while output line numbering is enabled.
     \n[[1m.ns[22m]        No‐space mode is enabled (Boolean‐valued).
     \n[[1m.o[22m]         Page offset; see [1mpo[22m.
     \n[[1m.O[22m]         Output suppression nesting level; see [1m\O[22m.
     \n[[1m.p[22m]         Page length; see [1mpl[22m.
     \n[[1m.P[22m]         The  page is selected for output (Boolean‐valued); see [4mtroff[0m
                    [1m-o [22moption.
     \n[[1m.pe[22m]        Page ejection is in progress (Boolean‐valued).
     \n[[1m.pn[22m]        Number of the next page.
     \n[[1m.ps[22m]        The environment’s type size in scaled points.
     \n[[1m.psr[22m]       The environment’s  most  recently  requested  type  size  in
                    scaled points; see [1mps [22mand [1m\s[22m.
     \n[[1m.pvs[22m]       The environment’s post‐vertical line spacing.
     \n[[1m.R[22m]         Maximum representable integer in GNU [4mtroff[24m.
     \n[[1m.rj[22m]        Count  of  input  lines remaining to be right‐aligned in the
                    environment.
     \n[[1m.s[22m]         The environment’s type size in points as a decimal  fraction
                    (string‐valued); see [1mps [22mand [1m\s[22m.
     \n[[1m.S[22m]         Reserved.   Plan 9 [4mtroff[24m uses this name for roughly the same
                    purpose as GNU [4mtroff[24m’s \n[[1m.tabs[22m]
     \n[[1m.slant[22m]     Slant in degrees of the environment’s selected font; see [1m\S[22m.
     \n[[1m.sr[22m]        The environment’s  most  recently  requested  type  size  in
                    points as a decimal fraction (string‐valued); see [1mps [22mand [1m\s[22m.
     \n[[1m.ss[22m]        Size  of  the  environment’s  minimum  inter‐word  space  in
                    twelfths of the space width of the selected font.
     \n[[1m.sss[22m]       Size of the environment’s supplemental inter‐sentence  space
                    in twelfths of the space width of the selected font.
     \n[[1m.sty[22m]       The  environment’s  selected abstract style (string‐valued);
                    see [1mft [22mand [1m\f[22m.
     \n[[1m.t[22m]         Distance to next vertical position trap; see [1mwh [22mand [1mch[22m.   If
                    no  such  traps  exist  between the drawing position and the
                    bottom of the page, [4mtroff[24m interpolates the distance  to  the
                    page bottom.  Within a diversion, in the absence of a diver‐
                    sion  trap,  this  distance is the maximum possible vertical
                    position supported by the output device.
     \n[[1m.T[22m]         An output device was explicitly  selected  (Boolean‐valued);
                    see [4mtroff[24m [1m-T [22moption.
     \n[[1m.tabs[22m]      The  environment’s  tab  stop settings (if any) suitable for
                    use as argument to [1mta [22m(string‐valued).
     \n[[1m.trap[22m]      Name of the next vertical position trap after  the  vertical
                    drawing position.  (string‐valued); see [1mwh[22m, [1mch[22m, and [1mdt[22m.
     \n[[1m.trunc[22m]     Amount  of  vertical  space  truncated  by the most recently
                    sprung vertical position trap, or, if the trap was sprung by
                    an [1mne[22m, minus the amount of vertical motion produced  by  [1mne[22m;
                    also see register [1m.ne[22m.
     \n[[1m.u[22m]         Filling  is enabled in the environment (Boolean‐valued); see
                    [1mfi [22mand [1mnf[22m.
     \n[[1m.U[22m]         Unsafe mode is enabled (Boolean‐valued); see  [4mtroff[24m  [1m-U  [22mop‐
                    tion.
     \n[[1m.v[22m]         The environment’s vertical line spacing; see [1mvs[22m.
     \n[[1m.V[22m]         Vertical motion quantum of the output device in basic units.
     \n[[1m.vpt[22m]       Vertical position traps are enabled (Boolean‐valued).
     \n[[1m.w[22m]         Width of last glyph formatted in the environment.
     \n[[1m.warn[22m]      Sum of the numeric codes of enabled warning categories.
     \n[[1m.x[22m]         Major version number of the running [4mtroff[24m formatter.
     \n[[1m.y[22m]         Minor version number of the running [4mtroff[24m formatter.
     \n[[1m.Y[22m]         Revision number of the running [4mtroff[24m formatter.
     \n[[1m.z[22m]         Name  of  diversion (string‐valued).  Empty if output is di‐
                    rected to the top‐level diversion.
     \n[[1m.zoom[22m]      Magnification of the environment’s selected font  (in  thou‐
                    sandths; zero if no magnification); see [1mfzoom[22m.

   [1mWritable predefined registers[0m
     Several registers are predefined but also modifiable; some are updated upon
     interpretation of certain requests or escape sequences.  Date‐ and time‐re‐
     lated  registers  are  set  to the local time as determined by ]8;;man:localtime(3)\[4mlocaltime[24m(3)]8;;\
     when the formatter launches.  This  initialization  can  be  overridden  by
     [4mSOURCE_DATE_EPOCH[24m and [4mTZ[24m; see section “Environment” of ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\.

     \n[[1m$$[22m]         Process ID of [4mtroff[24m.
     \n[[1m%[22m]          Page number.
     \n[[1mc.[22m]         Input line number.
     \n[[1mct[22m]         Union  of  character types of each glyph rendered into dummy
                    environment by [1m\w[22m.
     \n[[1mdl[22m]         Width of last closed diversion.
     \n[[1mdn[22m]         Height of last closed diversion.
     \n[[1mdw[22m]         Day of the week (1–7; 1 is Sunday).
     \n[[1mdy[22m]         Day of the month (1–31).
     \n[[1mhours[22m]      Count of hours elapsed since midnight (0–23).
     \n[[1mhp[22m]         Horizontal drawing position relative to that at the start of
                    the input line.
     \n[[1mllx[22m]        Lower‐left [4mx[24m coordinate (in PostScript units) of  PostScript
                    image; see [1mpsbb[22m.
     \n[[1mlly[22m]        Lower‐left  [4my[24m coordinate (in PostScript units) of PostScript
                    image; see [1mpsbb[22m.
     \n[[1mln[22m]         Output line number; see [1mnm[22m.
     \n[[1mlsn[22m]        Count of leading spaces on input line.
     \n[[1mlss[22m]        Amount of horizontal space corresponding to  leading  spaces
                    on input line.
     \n[[1mminutes[22m]    Count of minutes elapsed in the hour (0–59).
     \n[[1mmo[22m]         Month of the year (1–12).
     \n[[1mnl[22m]         Vertical drawing position.
     \n[[1mopmaxx[22m]
     \n[[1mopmaxy[22m]
     \n[[1mopminx[22m]
     \n[[1mopminy[22m]     These  four  registers  mark the top left‐ and bottom right‐
                    hand corners of a rectangle encompassing all formatted  out‐
                    put on the page.  They are reset to -1 by [1m\O0 [22mor [1m\O1[22m.
     \n[[1mrsb[22m]        As register [1msb[22m, adding maximum glyph height to measurement.
     \n[[1mrst[22m]        As register [1mst[22m, adding maximum glyph depth to measurement.
     \n[[1msb[22m]         Maximum displacement of text baseline below its original po‐
                    sition after rendering into dummy environment by [1m\w[22m.
     \n[[1mseconds[22m]    Count of seconds elapsed in the minute (0–60).
     \n[[1mskw[22m]        Skew of last glyph rendered into dummy environment by [1m\w[22m.
     \n[[1mslimit[22m]     The  maximum  depth of [4mtroff[24m’s internal input stack.  If ≤0,
                    there is no limit: recursion can  continue  until  available
                    memory is exhausted.  The default is 1,000.
     \n[[1mssc[22m]        Subscript correction of last glyph rendered into dummy envi‐
                    ronment by [1m\w[22m.
     \n[[1mst[22m]         Maximum displacement of text baseline above its original po‐
                    sition after rendering into dummy environment by [1m\w[22m.
     \n[[1msystat[22m]     Return value of ]8;;man:system(3)\[4msystem[24m(3)]8;;\; see [1msy[22m.
     \n[[1murx[22m]        Upper‐right [4mx[24m coordinate (in PostScript units) of PostScript
                    image; see [1mpsbb[22m.
     \n[[1mury[22m]        Upper‐right [4my[24m coordinate (in PostScript units) of PostScript
                    image; see [1mpsbb[22m.
     \n[[1myear[22m]       Gregorian year.
     \n[[1myr[22m]         Gregorian year minus 1900.

[1mUsing fonts[0m
     In  digital  typography, a [4mfont[24m is a collection of characters in a specific
     typeface that a device can render as glyphs at a desired size.   (Terminals
     and  some  typesetters have fonts that render at only one or two sizes.  As
     examples, take the [4mgroff[24m [1mlj4 [22mdevice’s Lineprinter, and  [1mlbp[22m’s  Courier  and
     Elite  faces.)   A  [4mroff[24m formatter can change typefaces at any point in the
     text.  The basic faces are a set of [4mstyles[24m combining  upright  and  slanted
     shapes with normal and heavy stroke weights: “[1mR[22m”, “[1mI[22m”, “[1mB[22m”, and “[1mBI[22m”——these
     stand  for  [4mroman,[24m [4mbold,[24m [4mitalic,[24m and [4mbold‐italic.[24m  For linguistic text, GNU
     [4mtroff[24m groups typefaces into  [4mfamilies[24m  containing  each  of  these  styles.
     (Font  designers prepare families such that the styles share esthetic prop‐
     erties.)  A [4mtext[24m [4mfont[24m is thus often a family combined with a style, but  it
     need  not  be:  consider the [1mps [22mand [1mpdf [22mdevices’ [1mZCMI [22m(Zapf Chancery Medium
     italic)——often, no other style of Zapf Chancery  Medium  is  provided.   On
     typesetters,  at  least  one [4mspecial[24m [4mfont[24m is available, comprising [4munstyled[0m
     glyphs for mathematical operators and other purposes.

     Like the AT&T [4mtroff[24m formatter, GNU [4mtroff[24m does not itself load or manipulate
     a digital font file; instead it works with a  [4mfont[24m  [4mdescription[24m  [4mfile[24m  that
     characterizes  it,  including  its glyph repertoire and the [4mmetrics[24m (dimen‐
     sions) of each glyph.  This information permits the formatter to accurately
     place glyphs with respect to each other.  Before using a font  description,
     the formatter associates it with a [4mmounting[24m [4mposition,[24m a place in an ordered
     list  of available typefaces.  So that a document need not be strongly cou‐
     pled to a specific font family, in GNU [4mtroff[24m 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 [4mresolved[24m [4mfont[0m
     [4mname.[24m  A user‐specified font name that combines family and style, or refers
     to a font that is not a member of a family, is already “resolved”.

     Fonts often have trademarked names, and even Free Software  fonts  can  re‐
     quire  renaming upon modification.  [4mgroff[24m maintains a convention that a de‐
     vice’s serif font family is given the name [1mT [22m(“Times”), its sans‐serif fam‐
     ily [1mH [22m(“Helvetica”), and its monospaced family [1mC  [22m(“Courier”).   Historical
     inertia  has  driven  [4mgroff[24m’s font identifiers to short uppercase abbrevia‐
     tions of font names, as with [1mTR[22m, [1mTB[22m, [1mTI[22m, [1mTBI[22m, and a special font [1mS[22m.

     The default family used with abstract styles can be changed  at  any  time;
     initially,  it  is [1mT[22m.  Typically, abstract styles are arranged in the first
     four mounting positions in the order shown above.  The default mounting po‐
     sition, and therefore style, is always [1m1 [22m([1mR[22m).  By issuing appropriate  for‐
     matter  instructions,  you can override these defaults before your document
     writes its first glyph.

     Terminals cannot change font families and lack special fonts.  They support
     style changes by overstriking, or by altering ISO 6429/ECMA‐48 [4mgraphic[24m [4mren‐[0m
     [4mditions[24m (character cell attributes).

     The [1mft [22mrequest and [1m\f [22mescape sequence select a typeface by  name,  abstract
     style,  or  mounting  position.  The [1mfam [22mrequest and [1m\F [22mescape sequence set
     the default font family.  The [1mftr [22mrequest translates one font name  to  an‐
     other;  [1mfzoom [22mmagnifies or reduces the typeface corresponding to a resolved
     one.  [1msty [22mand [1mfp [22massociate abstract styles and font names with mounting po‐
     sitions.

   [1mCharacters and glyphs[0m
     A glyph is a graphical representation of a character.  Whereas a  [4mcharacter[0m
     is  an abstraction of semantic information, a [4mglyph[24m is an intelligible mark
     visible on screen or paper.  A character has many  possible  representation
     forms;  for  example,  the  character  “A”  can be written in an upright or
     slanted typeface, producing distinct  glyphs.   Sometimes,  a  sequence  of
     characters  map to a single glyph:@: this is a [4mligature[24m——the most common is
     ‘fi’.

     Space characters never become glyphs in GNU [4mtroff[24m.  If  not  discarded  (as
     when trailing text lines), horizontal motions represent them in the output.

     The  formatter  supports  three  kinds of character.  An ordinary character
     (see section “Identifiers” above) is the most commonly used, has no special
     syntax, and typically represents itself.  (Depending on the breadth of  the
     output  device’s  glyph repertoire, the characters [1m'[22m, [1m-[22m, [1m^[22m, [1m`[22m, and [1m~ [22mcan be
     exceptions to this rule.  [1m" [22mand [1m\ [22mare not exceptions, but because they  are
     syntactically  meaningful  to the formatter, access to their glyphs may re‐
     quire use of special characters (or changing or disabling the escape  char‐
     acter).   See  ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\.   Interpolate  a  [4mspecial[24m  [4mcharacter[24m with the
     “[1m\[[4m[22mxxx[24m[1m] [22mor “[1m\C'[4m[22mxxx[24m[1m'[22m” escape sequence syntax, where [4mxxx[24m  is  an  identifier.
     An  [4mindexed[24m  [4mcharacter[24m  bypasses  most character‐to‐glyph resolution logic,
     uses the “[1m\N'[4m[22mi[24m[1m'[22msyntax, and selects a glyph from the currently selected font
     by its integer‐valued position [4mi[24m in the output device’s  representation  of
     that  font.   (A device’s fonts do not necessarily arrange their glyphs ac‐
     cording to a standard character encoding.)

     [4mUser‐defined[24m [4mcharacters[24m are similar  to  string  definitions  (see  section
     “Strings” above) and permit extension of or substitution within the charac‐
     ter  repertoire.   Any ordinary, special, or indexed character can be user‐
     defined.  The [1mchar[22m, [1mfchar[22m, [1mschar[22m, and [1mfschar [22mrequests  create  user‐defined
     characters  employed at various stages of the character‐to‐glyph resolution
     process.

     In a [4mtroff[24m system, a font description file lists all of the glyphs  a  par‐
     ticular  font  provides.  If the user requests a glyph not available in the
     currently selected font, the formatter looks it up an ordered list of  [4mspe‐[0m
     [4mcial[24m  [4mfonts.[24m   By  default,  the “[1mps[22m” (PostScript) and “[1mpdf[22m” output devices
     support the two special fonts “[1mSS[22m” (slanted symbol) and “[1mS[22m”  (symbol);  and
     these devices’ [4mDESC[24m files arrange them such that the formatter searches the
     former  before  the  latter.   Other output devices use different names for
     special fonts.  Fonts mounted with the [1mfonts [22mkeyword in the [4mDESC[24m  file  are
     globally  available.   GNU  [4mtroff[24m’s [1mspecial [22mand [1mfspecial [22mrequests alter the
     list of fonts treated as special on a general basis, or only when a certain
     font is currently selected, respectively.

     GNU [4mtroff[24m employs the following procedure to  resolve  an  input  character
     into  a glyph.  User‐defined characters make this resolution process recur‐
     sive.  The first step that succeeds ends the resolution procedure  for  the
     character being formatted, which may not be the last in the sequence inter‐
     polated by a user‐defined character.

     •      Interpolate  the definition of any character defined by the [1mchar [22mre‐
            quest and apply this procedure to each character in its definition.

     •      Check the current font for a glyph corresponding to the character.

     •      Interpolate the definition of any  user‐defined  character  matching
            defined  by the [1mfchar [22mrequest and apply this procedure to each char‐
            acter in its definition.

     •      Check whether the current font has a font‐specific list  of  special
            fonts;  if  so, check the each font therein, in the order determined
            by the last applicable [1mfspecial [22mrequest, for a  glyph  corresponding
            to the character.

     •      Interpolate  the  definition  of any character defined by the [1mfschar[0m
            request for the currently selected font, and apply this procedure to
            each character in its definition.

     •      Check each font in the list configured by the most  recently  issued
            [1mspecial [22mrequest for a glyph corresponding to the character.

     •      Interpolate  the  definition  of any character defined by the [1msschar[0m
            request and apply this procedure to each character  in  its  defini‐
            tion.

     •      Finally, iterate through the list of mounted fonts by position.  For
            each  mounted  font,  if  that font bears the [1mspecial [22mdirective (see
            ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\), check it for a glyph corresponding to the character.
            This stage of the resolution process can sometimes lead to  surpris‐
            ing  results  since  the [1mfonts [22mdirective in the [4mDESC[24m file often con‐
            tains empty positions that are filled by a macro  file  or  document
            employing the [1mfp [22mrequest after the formatter initializes.

   [1mSpecial fonts[0m
     Special  fonts  are those that the formatter searches, in mounting position
     order, when it cannot find a requested glyph in the selected  font.   Typi‐
     cally,   they  are  declared  as  such  in  their  description  files  (see
     ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\), and contain unstyled glyphs.  The “Symbol” and “Zapf  Ding‐
     bats”  fonts of the PostScript and PDF standards are examples.  Ordinarily,
     only typesetters have special fonts.

     GNU [4mtroff[24m’s [1mspecial [22mand [1mfspecial [22mrequests permit a document  to  supplement
     the  set  of fonts the device configures for glyph search without having to
     use the [1mfp [22mrequest to manipulate the list of mounting positions, which  can
     be tedious——by default, GNU [4mtroff[24m mounts 40 fonts at startup when using the
     [1mps [22mdevice.

[1mHyphenation[0m
     When  filling, [4mgroff[24m hyphenates words as needed at user‐specified and auto‐
     matically determined hyphenation points.  Explicitly hyphenated words  such
     as “mother‐in‐law” are always eligible for breaking after each of their hy‐
     phens.  The hyphenation character [1m\% [22mand non‐printing break point [1m\: [22mescape
     sequences may be used to control the hyphenation and breaking of individual
     words.   The  [1mhw [22mrequest sets user‐defined hyphenation points for specified
     words at any subsequent occurrence.  Otherwise,  [4mgroff[24m  determines  hyphen‐
     ation points automatically by default.

     Several  requests  influence  automatic  hyphenation.   Because conventions
     vary, a variety of hyphenation modes is available to the [1mhy [22mrequest;  these
     determine whether hyphenation will apply to a word prior to breaking a line
     at  the  end  of a page (more or less; see below for details), and at which
     positions within that word automatically determined hyphenation points  are
     permissible.   The  localization  macro files loaded by [4mtroffrc[24m configure a
     default hyphenation mode appropriate to the language.

     [1m0      [22mdisables hyphenation.

     [1m1      [22menables hyphenation except after the first and before the last char‐
            acter of a word.

     The remaining values “imply” [1m1[22m; that is, they enable hyphenation under  the
     same conditions as “[1m.hy 1[22m”, and then apply or lift restrictions relative to
     that basis.

     [1m2      [22mdisables  hyphenation of the last word on a page or column, even for
            explicitly hyphenated words.  (Hyphenation is prevented if the  next
            page  location  trap is closer to the vertical drawing position than
            the next text baseline would be.  See section “Traps” below.)

     [1m4      [22mdisables hyphenation before the last two characters of a word.

     [1m8      [22mdisables hyphenation after the first two characters of a word.

     [1m16     [22menables hyphenation before the last character of a word.

     [1m32     [22menables hyphenation after the first character of a word.

     Apart from value 2, restrictions imposed by the hyphenation  mode  are  [4mnot[0m
     respected for words whose hyphenations have been specified with the hyphen‐
     ation character (“[1m\%[22m” by default) or the [1m.hw [22mrequest.

     Nonzero  values are additive.  For example, mode 12 causes [4mgroff[24m to hyphen‐
     ate neither the last two nor the first two characters of a word.  Some val‐
     ues cannot be used together because they contradict; for instance, values 4
     and 16, and values 8 and 32.  As noted, it is superfluous to add 1  to  any
     non‐zero even mode.

     The  places  within a word that are eligible for hyphenation are determined
     by language‐specific data ([1mhla[22m, [1mhpf[22m, and [1mhpfa[22m) and lettercase relationships
     ([1mhcode [22mand [1mhpfcode[22m).  Furthermore, hyphenation of  a  word  might  be  sup‐
     pressed  due  to  a  limit on consecutive hyphenated lines ([1mhlm[22m), a minimum
     line length threshold ([1mhym[22m), or because the line can  instead  be  adjusted
     with additional inter‐word space ([1mhys[22m).

[1mLocalization[0m
     GNU  [4mtroff[24m ties the set of hyphenation patterns to the hyphenation language
     code selected by the [1mhla [22mrequest.  The [1mhpf [22mrequest is usually invoked by  a
     localization  file loaded by the [4mtroffrc[24m file.  [4mgroff[24m provides localization
     files for several languages;  See  subsection  “Localization  packages”  of
     ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\.   For  Western languages, the localization file sets the de‐
     fault hyphenation mode and loads hyphenation patterns and  exceptions.   By
     default, [4mtroffrc[24m loads the localization file for English.

[1mWriting macros[0m
     The  [1m.de  [22mrequest defines a macro named for its argument.  If that name al‐
     ready exists as an alias, the target of the alias is redefined; see section
     “Strings” above.  [4mtroff[24m enters “copy mode” (see below), storing  subsequent
     input  lines  as  the  definition.   If the optional second argument is not
     specified, the definition ends with the control line “[1m..[22m” (two dots).  Tabs
     and spaces are permitted between the dots.  Alternatively, a  second  argu‐
     ment  to  [1m.de [22mnames a macro whose call (or request whose invocation) syntax
     ends the definition; this [4mend[24m [4mmacro[24m is then interpreted  normally.   Spaces
     or  tabs  are  permitted after the first control character in the line con‐
     taining this ending token, but a tab immediately after the  token  prevents
     its recognition as the end of a macro definition.  Macro definitions can be
     nested if they use distinct end macros or if their ending tokens are suffi‐
     ciently  escaped.   An  end  macro  need not be defined until it is called.
     This fact enables a nested macro definition to begin inside one  macro  and
     end inside another.

     Variants of [1m.de [22mdisable compatibility mode and/or indirect the names of the
     macros  specified  for definition or termination: these are [1m.de1[22m, [1m.dei[22m, and
     [1m.dei1[22m.  Append to macro definitions with [1m.am[22m, [1m.am1[22m, [1m.ami[22m, and  [1m.ami1[22m.   The
     [1m.als[22m, [1m.rm[22m, and [1m.rn [22mrequests create an alias of, remove, and rename a macro,
     respectively.   [1m.return [22mstops the execution of a macro immediately, return‐
     ing to the enclosing context.

   [1mParameters[0m
     Macro call and string interpolation parameters can be accessed using escape
     sequences starting with “[1m\$[22m”.  The [1m\n[.$]  [22mread‐only  register  stores  the
     count  of  parameters available to a macro or string; change its value with
     the [1m.shift [22mrequest, which dequeues parameters from the current  list.   The
     [1m\$0 [22mescape sequence interpolates the name by which a macro was called.  Ap‐
     plying string interpolation to a macro does not change this name.

   [1mCopy mode[0m
     GNU [4mtroff[24m processes certain requests in [4mcopy[24m [4mmode:[24m it copies ordinary, spe‐
     cial,  and  indexed characters as‐is; interpolates the escape sequences [1m\n[22m,
     [1m\g[22m, [1m\$[22m, [1m\*[22m, [1m\V[22m, and [1m\? [22mnormally; discards comments [1m\" [22mand [1m\#[22m;  interpolates
     [1m\a[22m,  [1m\e[22m,  and  [1m\t[22m, as the current leader, escape, or tab character with re‐
     spectively; represents [1m\[4m[22mnewline[24m, [1m\&[22m, [1m\_[22m, [1m\|[22m, [1m\^[22m, [1m\{[22m, [1m\}[22m, [1m\`[22m,  [1m\'[22m,  [1m\-[22m,  [1m\![22m,
     [1m\c[22m, [1m\%[22m, [1m\[4m[22mspace[24m, [1m\E[22m, [1m\)[22m, [1m\~[22m, and [1m\: [22min an encoded form, and copies other es‐
     cape  sequences  as‐is.  The term “copy mode” reflects its most visible ap‐
     plication in requests that populate macros and strings, but other  requests
     also  use  it when interpreting arguments that can’t meaningfully represent
     typesetting operations.  For example, a font selection escape sequence  has
     no meaning in a hyphenation pattern file name ([1mhpf[22m) or a diagnostic message
     written  to the terminal ([1mtm[22m).  The complement of copy mode——a [4mroff[24m format‐
     ter’s behavior when not defining or appending to a macro, string, or diver‐
     sion——where all macros are interpolated, requests invoked, and valid escape
     sequences processed immediately upon recognition, can be termed [4minterpreta‐[0m
     [4mtion[24m [4mmode[24m.

     The escape character ([1m\ [22mby default) when used before itself [4mquotes[24m  an  es‐
     cape  character  for  later interpretation in an enclosing context.  Escape
     character quotation enables you to control whether the formatter interprets
     a given [1m\n[22m, [1m\g[22m, [1m\$[22m, [1m\*[22m, [1m\V[22m, or [1m\? [22mescape sequence at  the  time  the  macro
     containing it is defined, or later when the macro is called.

     You  can  think  of [1m\\ [22mas a “delayed” backslash; it is the escape character
     followed by a backslash from which the escape  character  has  removed  its
     special  meaning.   Consequently,  [1m\\  [22mis not best considered an escape se‐
     quence, but a quoted escape character.  In  any  escape  sequence  [1m\[4m[22mX[24m  that
     [4mtroff[24m  does  not recognize, the formatter discards the escape character and
     outputs [4mX.[24m  An unrecognized escape sequence causes a  warning  in  category
     “[1mescape[22m”, with two exceptions, [1m\\ [22mbeing one.  The other is [1m\.[22m, which quotes
     the  control  character.   It is used to permit nested macro definitions to
     end without a named macro call to conclude  them.   Without  a  syntax  for
     quoting the control character, this would not be possible.  Outside of copy
     mode,  [4mroff[24m documents should not use the [1m\\ [22mor [1m\. [22mcharacter sequences; they
     serve only to obfuscate the input.  Use [1m\e [22mto represent the escape  charac‐
     ter,  [1m\[rs]  [22mto obtain a backslash glyph, and [1m\& [22mbefore [1m. [22mand [1m' [22mwhere [4mtroff[0m
     expects them as control characters if you mean to use them literally.

     Macro definitions can be nested to arbitrary depth.  Given the input  char‐
     acter  sequence  “[1m\\[22m” in a macro or string definition, the formatter inter‐
     prets each escape character in multiple contexts; once, when populating the
     macro or string, where the first “[1m\[22m” serves  its  quotation  function——thus
     only  one  “[1m\[22m”  is stored in the definition.  (Verify this fact with the [1mpm[0m
     request.)  The formatter interprets the second “[1m\[22m” as an  escape  character
     (assuming  the  escape  character hasn’t been changed in the meantime) each
     time it interpolates the macro or string definition.  This  fact  leads  to
     exponential  growth  in the quantity of escape characters required to quote
     and thereby delay interpolation of [1m\n[22m, [1m\g[22m, [1m\$[22m, [1m\*[22m, [1m\V[22m, and [1m\? [22mat each nest‐
     ing level.  An alternative is to use [1m\E[22m, which represents an escape charac‐
     ter that is not interpreted in copy mode.  Because [1m\. [22mis not a true  escape
     sequence,  we can’t use [1m\E [22mto keep “[1m..[22m” from ending a macro definition pre‐
     maturely.  If the multiplicity of backslashes complicates maintenance,  use
     end macros.

[1mTraps[0m
     [4mTraps[24m  are  locations  in the output, or conditions on the input that, when
     reached or fulfilled, call a specified macro.   A  [4mvertical[24m  [4mposition[24m  [4mtrap[0m
     calls  a  macro  when  the formatter’s vertical drawing position reaches or
     passes, in the downward direction, a certain location on the output page or
     in a diversion.  Its applications include setting page headers and footers,
     body text in multiple columns, and footnotes.  These traps can occur  at  a
     given  location  either  on  the  page ([1mwh[22m, [1mch[22m) or in the current diversion
     ([1mdt[22m)——together, these are known as vertical position traps,  which  can  be
     disabled and reënabled ([1mvpt[22m).

     A diversion is not formatted in the context of a page, so it lacks page lo‐
     cation  traps;  instead  it  can have a [4mdiversion[24m [4mtrap.[24m  There can exist at
     most one such vertical position trap per diversion.

     Other kinds of trap can be planted at a blank line ([1mblm[22m); at  a  line  with
     leading  space characters ([1mlsm[22m); after a certain number of productive input
     lines ([1mit[22m, [1mitc[22m); or at the end of input ([1mem[22m).

     Setting a trap is also called [4mplanting[24m one.  It is  said  that  a  trap  is
     [4msprung[24m if its condition is fulfilled.

     The formatter passes no arguments to macros called by traps.

     Registers  associated  with  trap management include vertical position trap
     enablement status ([1m\n[.vpt][22m), distance to the next trap ([1m\n[.t][22m),  and  the
     name  of that trap ([1m\n[.trap][22m); the count of lines remaining in the pending
     input trap ([1m\n[.it][22m), the name of the macro associated with it  ([1m\n[.itm][22m),
     and  whether  that input trap honors the [1m\c [22moutput line continuation escape
     sequence ([1m\n[.itc][22m); amount of needed ([1m.ne[22m‐requested) space that caused the
     most recent vertical position trap to be sprung ([1m\n[.ne][22m), amount of needed
     space truncated from the amount requested ([1m\n[.trunc][22m); page ejection  sta‐
     tus  ([1m\n[.pe][22m);  and  leading  space count ([1m\n[lsn][22m) with its corresponding
     amount of motion ([1m\n[lss][22m).

   [1mPage location traps[0m
     A [4mpage[24m [4mlocation[24m [4mtrap[24m is a vertical position trap that applies to the  page;
     that is, to the top‐level diversion.  Many can be present; manage them with
     the  [1mwh  [22mand  [1mch  [22mrequests.  Non‐negative page locations given to these re‐
     quests set the trap relative to the top of the page;  negative  values  set
     the trap relative to the bottom of the page.  It is not possible to plant a
     trap  less  than one basic unit from the page bottom: a location of “-0” is
     interpreted as “0”, the top of the page.  An existing [4mvisible[24m trap (see be‐
     low) at the same location is removed; this is [1mwh[22m’s  sole  function  if  its
     second argument is missing.

     A trap is sprung only if it is [4mvisible,[24m meaning that its location is reach‐
     able  on the page and it is not hidden by another trap at the same location
     already planted there.  (A trap planted at “20i”  or  “-30i”  will  not  be
     sprung on a page of length “11i”.)

     A trap above the top or at or below the bottom of the page can be made vis‐
     ible  by  either moving it into the page area or increasing the page length
     so that the trap is on the page.  A negative trap  value  always  uses  the
     [4mcurrent[24m  page length; the formatter does not convert it to an absolute ver‐
     tical position.  We can use the [1mpwh [22mrequest to dump page location traps  to
     the  standard  error  stream; see section “Debugging” below.  GNU [4mtroff[24m re‐
     ports their positions in basic units, and includes empty slots in the list,
     where a trap had been planted but subsequently (re)moved, because they  can
     affect the visibility of subsequently planted traps.

   [1mThe implicit page trap[0m
     An [4mimplicit[24m [4mpage[24m [4mtrap[24m always exists in the top‐level diversion (see below);
     its  purpose is to eject the current page and start the next one.  It works
     like a trap in some ways but not others.  It has no name, so it  cannot  be
     moved or deleted with [1mwh [22mor [1mch [22mrequests.  You cannot hide it by placing an‐
     other  trap  at  its  location, and can move it only by redefining the page
     length with [1mpl[22m.  Its operation is suppressed when vertical page  traps  are
     disabled with GNU [4mtroff’s[24m [1mvpt [22mrequest.

[1mDiversions[0m
     In [4mroff[24m systems it is possible to format text as if for output, but instead
     of  writing  it immediately, one can [4mdivert[24m the formatted text into a named
     storage area.  It is retrieved later by specifying its name after a control
     character.  The formatter uses the same name space for such  [4mdiversions[24m  as
     for  strings  and  macros;  see  section “Identifiers” above.  Such text is
     sometimes said to be “stored in a macro”, but this coinage obscures the im‐
     portant distinction between macros and strings on one hand  and  diversions
     on  the other; the former store [4munformatted[24m input text, and the latter cap‐
     ture [4mformatted[24m output.  Diversions also do not interpret arguments.  Appli‐
     cations of diversions include footnotes, tables of contents,  indices,  and
     “keeps” (preventing a page break from occurring at an inconvenient place by
     forcing  a set of output lines to be set as a group).  For orthogonality it
     is said that GNU [4mtroff[24m populates the [4mtop‐level[24m [4mdiversion[24m if no diversion is
     active (that is, formatted output is being “diverted” directly to the  out‐
     put device).  The top‐level diversion has no name.

     Dereferencing  an  undefined  diversion  creates an empty one of that name.
     (GNU [4mtroff[24m also emits a warning in category “mac”; see  section  “Warnings”
     of  ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\.)   A diversion does not exist for the purpose of testing with
     the [1md [22mconditional expression operator until its  initial  definition  ends;
     see subsection “Conditional expressions” above.

     The [1mdi [22mrequest creates a diversion, including any partially collected line.
     [1mda  [22mappends  to a diversion, creating one if it does not already exist.  If
     the diversion’s name already exists as an alias, the target of the alias is
     replaced or appended to; see section “Strings” above.  The  pending  output
     line  is  diverted  as well.  Switching to another environment (with the [1mev[0m
     request) before invoking [1mdi [22mor [1mda [22mavoids including any pending output  line
     in the diversion.  (See section “Environments[” below.)

     Invoking  [1mdi [22mor [1mda [22mwithout an argument stops diverting output to the diver‐
     sion named by the most recent corresponding request.   Invoking  [1mdi  [22mor  [1mda[0m
     without  an  argument  when  no  diversion is being populated does nothing.
     (GNU [4mtroff[24m emits a warning in category  “di”;  see  section  “Warnings”  of
     ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\.)

     [1mbox  [22mand  [1mboxa  [22mwork similarly, but ignore partially collected lines.  Call
     any of these macros again without an argument to end the diversion.

     Diversion requests can be nested.  The registers [1m.d [22mand [1m.z [22mreport  informa‐
     tion  about  the  current  diversion, and [1mdn [22mand [1mdl [22mabout the most recently
     closed one.  [1m.h [22mis meaningful in diversions, including the top‐level one.

     After output to a (named) diversion stops, the formatter stores its  verti‐
     cal  and  horizontal  sizes,  to  the writable registers [1mdn [22mand [1mdl[22m, respec‐
     tively.  Only the lines just processed are counted: for the computation  of
     [1mdn  [22mand  [1mdl[22m, the requests [1mda [22mand [1mboxa [22mare handled as if [1mdi [22mand [1mbox [22mhad been
     used, respectively——lines that have been already stored  in  the  diversion
     (box) are not taken into account.

     The  [1m\! [22mand [1m\? [22mescape sequences and [1moutput [22mrequest escape from a diversion,
     the first two to the enclosing level and the last to the top  level.   This
     facility is termed [4mtransparent[24m [4membedding[24m.

     The [1masciify [22mand “[1munformat[22m” requests reprocess diversions.

[1mPunning names[0m
     Macros,  strings,  and  diversions share a name space; see section “Identi‐
     fiers” above.  Internally, the same mechanism is used to store  them.   You
     can thus call a macro with string interpolation syntax and vice versa.  In‐
     terpolating a string does not hide existing macro arguments.  Place the se‐
     quence [1m\\ [22mat the end of a line in a macro definition or, within a macro de‐
     finition,  immediately  after  the interpolation of a macro as a string, to
     suppress the effect of a newline.

[1mEnvironments[0m
     Environments store most of the parameters that control text processing.   A
     default  environment named “[1m0[22m” (zero) exists when exists when the formatter
     starts up; formatting‐related requests  and  escape  sequences  modify  its
     properties.

     You can create new environments and switch among them.  Only one is current
     at  any  given time.  Active environments are managed using a [4mstack,[24m a data
     structure supporting “push” and “pop” operations.  The current  environment
     is  at  the top of the stack.  The same environment name can be pushed onto
     the stack multiple times, possibly interleaved with  others.   Popping  the
     environment  stack does not destroy the current environment; it remains ac‐
     cessible by name and can be made current again by pushing it at  any  time.
     Environments  cannot  be  renamed or deleted, and can only be modified when
     current.  To inspect the environment stack, use the [1mpev [22mrequest;  see  sec‐
     tion “Debugging” below.

     Environments store the following information.

     •  a partially collected line, if any

     •  data  about  the  most  recently  output glyph and line (registers [1m.cdp[22m,
        [1m.cht[22m, [1m.csk[22m, [1m.n[22m, [1m.w[22m)

     •  typeface parameters (size, family, style, height and  slant,  inter‐word
        and inter‐sentence space sizes)

     •  page parameters (line length, title length, vertical spacing, line spac‐
        ing,  indentation, line numbering, centering, right‐alignment, underlin‐
        ing, hyphenation parameters)

     •  filling enablement; adjustment enablement and mode

     •  tab stops; tab, leader, escape, control, no‐break control,  hyphenation,
        and margin characters

     •  input line traps

     •  stroke and fill colors

     The [1mev [22mrequest (with an argument) pushes to and (without) pops from the en‐
     vironment  stack,  while [1mevc [22mcopies a named environment’s parameters to the
     current one.

[1mPostprocessor access[0m
     Beyond the [1mcf [22mand [1mtrf [22mrequests, two escape sequences and two  requests  en‐
     able  documents to pass information directly to a postprocessor.  These are
     useful for exercising device‐specific capabilities that the [4mgroff[24m  language
     does  not  abstract or generalize; examples include the embedding of hyper‐
     links and image files.  Device‐specific functions are  documented  in  each
     output driver’s man page, such as ]8;;man:gropdf(1)\[4mgropdf[24m(1)]8;;\, ]8;;man:grops(1)\[4mgrops[24m(1)]8;;\, or ]8;;man:grotty(1)\[4mgrotty[24m(1)]8;;\.

     The  “[1mdevice[22m” request and [1m\X [22mescape sequence embed their arguments into GNU
     [4mtroff[24m output as parameters to  an  “[1mx  X[22m”  device  extension  command  (see
     ]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\).   The interpretation of such parameters is determined by the
     output driver or other postprocessor.

     GNU [4mtroff[24m also permits the interpolation of macro or string contents  as  a
     device  extension command.  The [1mdevicem [22mrequest and [1m\Y [22mescape sequence cor‐
     respond to “[1m.device \*[[4m[22mname[24m[1m][22m” and “[1m\X'\*[[4m[22mname[24m[1m][22m”, respectively.  They differ
     from their counterparts in that GNU [4mtroff[24m does not interpret  the  contents
     of  the string or macro [4mname[24m; further, [4mname[24m may be a macro and thus contain
     newlines.  (There is no way to embed a newline in the arguments to “[1mdevice[22m”
     or [1m\X[22m.)  The inclusion of newlines requires an extension to the AT&T  [4mtroff[0m
     device‐independent  page  description language, and their presence confuses
     drivers that do not know about it (see subsection “Device control commands”
     of ]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\).

     Use of device extension commands early in a document (before the first text
     is formatted) can interfere with processing of page location traps.  If you
     experience problems when placing them early, precede the first with a dummy
     character escape sequence “[1m\&[22m”; recall section “Dummy Characters” above.

     The [1mtag [22mand [1mtaga [22mrequests are reserved for internal use.

[1mUnderlining[0m
     In [4mRUNOFF[24m  (see  ]8;;man:roff(7)\[4mroff[24m(7)]8;;\),  underlining,  even  of  lengthy  passages,  was
     straightforward  because  only  fixed‐pitch printing devices were targeted.
     Typesetter output posed a greater challenge.  There exists a [4mgroff[24m  request
     [1m.ul  [22m(see  above) that underlines subsequent source lines on terminals, but
     on typesetters, it selects an italic font  style  instead.   The  [4mms[24m  macro
     package  (see  ]8;;man:groff_ms(7)\[4mgroff_ms[24m(7)]8;;\) offers a macro [1m.UL[22m, but it too produces the de‐
     sired effect only on typesetters, and has other limitations.

     One could adapt [4mms[24m’s approach to the construction of a macro as follows.
            .de UNDERLINE
            . ie n \\$1\f[I]\\$2\f[P]\\$3
            . el \\$1\Z'\\$2'\v'.25m'\D'l \w'\\$2'u 0'\v'-.25m'\\$3
            ..
     If ]8;;man:doclifter(1)\[4mdoclifter[24m(1)]8;;\ makes trouble, change the macro name  [1mUNDERLINE  [22minto  some
     2‐letter  word,  like  [1mUl[22m.  Moreover, change the form of the font selection
     escape sequence from [1m\f[P] [22mto [1m\fP[22m.

   [1mUnderlining without macro definitions[0m
     If one does not want to use macro definitions, e.g.,  when  [4mdoclifter[24m  gets
     lost, use the following.
            .ds u1 before
            .ds u2 in
            .ds u3 after
            .ie n \*[u1]\f[I]\*[u2]\f[P]\*[u3]
            .el \*[u1]\Z'\*[u2]'\v'.25m'\D'l \w'\*[u2]'u 0'\v'-.25m'\*[u3]
     When  using [4mdoclifter[24m, it might be necessary to change syntax forms such as
     [1m\[xy] [22mand [1m\*[xy] [22mto those supported by AT&T [4mtroff[24m: [1m\*(xy [22mand [1m\(xy[22m,  and  so
     on.

     Then these lines could look like
            .ds u1 before
            .ds u2 in
            .ds u3 after
            .ie n \*[u1]\fI\*(u2\fP\*(u3
            .el \*(u1\Z'\*(u2'\v'.25m'\D'l \w'\*(u2'u 0'\v'-.25m'\*(u3

     The result looks like
            before _i_n after

   [1mUnderlining by overstriking with \(ul[0m
     The  [1m\z  [22mescape sequence writes a glyph without advancing the drawing posi‐
     tion, enabling overstriking.  Thus, [1m\z[4m[22mc[24m[1m\(ul [22mformats  [4mc[24m  with  an  underrule
     glyph  on  top of it.  Video terminals implement the underrule by setting a
     character cell’s underline attribute, so this technique works in both [4mnroff[0m
     and [4mtroff[24m modes.

     Long words may then look intimidating in the input; a  clarifying  approach
     might  be  to  use  the input line continuation escape sequence [1m\[4m[22mnewline[24m to
     place each underlined character on its own input line.  Thus,
            .nf
            \&\fB: ${\fIvar\fR\c
            \zo\(ul\
            \zp\(ul\c
            \&\fIvalue\fB}
            .fi
     produces
            [1m: ${[4m[22mvar[24mo_p_[4mvalue[24m[1m}[0m
     as output.

[1mCompatibility mode[0m
     ]8;;man:groff_diff(7)\[4mgroff_diff[24m(7)]8;;\ documents differences between the [4mroff[24m language recognized by
     GNU [4mtroff[24m and that of AT&T [4mtroff[24m, as well as the device, font, and  device‐
     independent page description formats described by CSTR #54.  GNU [4mtroff[24m pro‐
     vides  an  AT&T  [4mtroff[24m compatibility mode.  The [1mcp [22mrequest and registers [1m.C[0m
     and [1m.cp [22mset and test the enablement of this mode.

[1mDebugging[0m
     Preprocessors use the [1mlf [22mrequest to preserve the identities of line numbers
     and names of input files.  [4mgroff[24m emits a variety of error  diagnostics  and
     supports  several  categories of warning; the output of these can be selec‐
     tively suppressed with “[1mwarn[22m” (and see  the  [1m-E[22m,  [1m-w[22m,  and  [1m-W  [22moptions  of
     ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\).   A trace of the formatter’s input processing stack can be emit‐
     ted when errors or warnings occur by means of ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\’s [1m-b [22moption, or pro‐
     duced on demand with the [1mbacktrace [22mrequest.  [1mtm[22m, [1mtmc[22m, and [1mtm1 [22mcan  be  used
     to  emit  customized diagnostic messages or for instrumentation while trou‐
     bleshooting.  [1mex [22mand [1mab [22mcause early termination with successful  and  error
     exit  codes  respectively, to halt further processing when continuing would
     be fruitless.  Examine the state of the formatter with requests that  write
     lists  of  defined names——macros, strings, and diversions——([1mpm[22m); characters
     ([1mpchar[22m; experimental); colors ([1mpcolor[22m); composite character mappings ([1mpcom‐[0m
     [1mposite[22m); environments ([1mpev[22m); occupied font mounting positions  ([1mpfp[22m);  font
     translations  ([1mpftr[22m);  automatic  hyphenation  codes ([1mpchar[22m) and exceptions
     ([1mphw[22m); registers ([1mpnr[22m); open streams ([1mpstream[22m);  and  page  location  traps
     ([1mpwh[22m).   Requests can also disclose to the standard error stream the inter‐
     nal properties and  representations  of  characters  and  classes  ([1mpchar[22m),
     macros (and strings and diversions) ([1mpm[22m), and the list of output nodes cor‐
     responding to the pending input line ([1mpline[22m).

[1mAuthors[0m
     This  document was written by Trent A. Fisher, ]8;;mailto:wl@gnu.org\Werner Lemberg]8;;\, and ]8;;mailto:g.branden.robinson@gmail.com\G. Bran‐
     den Robinson]8;;\.  Section “Underlining” was primarily written by ]8;;mailto:groff-bernd.warken-72@web.de\Bernd Warken]8;;\.

[1mSee also[0m
     [4mGroff:[24m [4mThe[24m [4mGNU[24m [4mImplementation[24m [4mof[24m [4mtroff[24m, by Trent A. Fisher and Werner  Lem‐
     berg,  is  the  primary [4mgroff[24m 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 device‐independent page description lan‐
     guage referred to collectively in [4mgroff[24m documentation as “AT&T [4mtroff[24m”.

     “A  Typesetter‐independent  TROFF”  by  Brian W. Kernighan, 1982, AT&T Bell
     Laboratories Computing Science Technical Report No. 97 (CSTR #97), provides
     additional insights into the device and font description file  formats  and
     device‐independent page description language.

     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\
            is  the  preferred  interface  to  the  [4mgroff[24m system; it manages the
            pipeline that carries a source document through  preprocessors,  the
            [4mtroff[24m formatter, and an output driver to viewable or printable form.
            It  also exhaustively lists the man pages provided with the GNU [4mroff[0m
            system.

     ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\
            discusses character encoding issues and escape sequences  that  pro‐
            duce glyphs.

     ]8;;man:groff_diff(7)\[4mgroff_diff[24m(7)]8;;\
            covers  differences  between the GNU [4mtroff[24m formatter, its device and
            font description file formats, its device‐independent page  descrip‐
            tion language, and those of AT&T [4mtroff[24m.

     ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\
            describes  the formats of the files that describe devices ([4mDESC[24m) and
            fonts.

     ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\
            surveys macro packages provided with [4mgroff[24m, describes how  documents
            can  take  advantage of them, offers guidance on writing macro pack‐
            ages and using diversions, and includes historical information.

     ]8;;man:roff(7)\[4mroff[24m(7)]8;;\
            presents a detailed history of [4mroff[24m systems and summarizes  concepts
            common to them.

groff 1.24.1                       2026‐03‐20                           [4mgroff[24m(7)
────────────────────────────────────────────────────────────────────────────────
[4mgroff_char[24m(7)           Miscellaneous Information Manual           [4mgroff_char[24m(7)

[1mName[0m
     groff_char - GNU [4mroff[24m special character and glyph repertoire

[1mDescription[0m
     The  GNU  [4mroff[24m typesetting system has a large glyph repertoire suitable for
     production of varied literary, professional,  technical,  and  mathematical
     documents.   [4mgroff[24m  works with [4mcharacters;[24m an output device renders [4mglyphs.[0m
     [4mgroff[24m’s  input  character  set  is  restricted  to  that  defined  by   the
     ISO  Latin‐1  (ISO  8859‐1)  standard.  For ease of document maintenance in
     UTF‐8 environments, it is advisable to use only  the  Unicode  basic  Latin
     code  points;  these correspond to ISO 646:1991 IRV (US‐ASCII), a subset of
     all of the foregoing which has only 94 visible, printable code points.   In
     [4mgroff,[24m  these are termed [4mordinary[24m [4mcharacters.[24m  Often, many more are desired
     in output.

     AT&T [4mtroff[24m in the 1970s faced a similar problem: the available typesetter’s
     glyph repertoire differed from that of the computers  that  controlled  it.
     [4mtroff[24m’s solution was a form of escape sequence known as a [4mspecial[24m [4mcharacter[0m
     to  access  several dozen additional glyphs available in the fonts prepared
     for mounting in the phototypesetter.  These glyphs were mapped onto a  two‐
     character name space for a degree of mnemonic convenience; for example, the
     escape sequence [1m\(aa [22mencoded an acute accent and [1m\(sc [22ma section sign.

     [4mgroff[24m  has  lifted  historical  [4mroff[24m  limitations on special character name
     lengths, but recognizes  and  retains  compatibility  with  the  historical
     names.   [4mgroff[24m  expands the lexicon of glyphs available by name and permits
     users to define their own special character escape sequences with the  [1mchar[0m
     request.  Special character names are [4mgroff[24m identifiers; see section “Iden‐
     tifiers” in ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\.  Our discussion uses the terms “glyph name” and “spe‐
     cial  character  name” interchangeably; we assume no character translations
     or redefinitions.

     This document lists all of the glyph names predefined by [4mgroff[24m’s  font  de‐
     scription  files  and  presents the systematic notation by which it enables
     access to arbitrary Unicode  code  points  and  construction  of  composite
     glyphs.   Glyphs  listed may be unavailable, or may vary in appearance, de‐
     pending on the output device and font chosen when the page  was  formatted.
     This page was rendered for device [1mutf8 [22mprimarily using font [1mR[22m.

     A  few  escape sequences that are not [4mgroff[24m special characters also produce
     glyphs; these exist for syntactical or historical reasons.  [1m\'[22m, [1m\`[22m, [1m\-[22m, and
     [1m\_ [22mare translated on input to the special character escape sequences [1m\[aa][22m,
     [1m\[ga][22m, [1m\[-][22m, and [1m\[ul][22m, respectively.  Others include  [1m\\[22m,  [1m\.  [22m(backslash‐
     dot), and [1m\e[22m; see ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\.  A small number of special characters represent
     glyphs  that are not encoded in Unicode; examples include the baseline rule
     [1m\[ru] [22mand the Bell System logo [1m\[bs].[0m

     In [4mgroff[24m, test support for any character (ordinary  or  special)  with  the
     conditional expression operator “[1mc[22m”.
            .ie c \[bs] \{Welcome to the \[bs] Bell System;
            did you get the Wehrmacht helmet or the Death Star?\}
            .el No Bell System logo.

     While  [4mgroff[24m  accepts eight‐bit encoded input, not all such code points are
     valid as input.  Character codes 0, 11, 13–31,  and  128–159  are  invalid.
     (This  is  all  C0  and C1 controls except for SOH through LF [Control+A to
     Control+J], and FF [Control+L].)  Some of these code  points  are  used  by
     [4mgroff[24m  for internal purposes, which is one reason it does not support UTF‐8
     natively.

   [1mFundamental character set[0m
     The ordinary characters catalogued above, plus the space, tab, newline, and
     leader (Control+A), form the fundamental character  set  for  [4mgroff[24m  input;
     anything in the language, even over one million code points in Unicode, can
     be  expressed  using it.  Code points in the range 33–126 comprise a common
     set of printable glyphs in all of the aforementioned ISO character encoding
     standards.  It is this character set and (with some noteworthy  exceptions)
     the corresponding glyph repertoire for which AT&T [4mtroff[24m was implemented.

     All of the following characters map to glyphs as you would expect.
           ┌───────────────────────────────────────────────────────────┐
           │ ! # $ % & ( ) * + , . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ? @ │
           │ A B C D E F G H I J K L M N O P Q R S T U V W X Y Z [ ] _ │
           │ a b c d e f g h i j k l m n o p q r s t u v w x y z { | } │
           └───────────────────────────────────────────────────────────┘
     The remaining ordinary characters surprise computing professionals and oth‐
     ers  intimately  familiar with the ISO character encodings.  The developers
     of AT&T [4mtroff[24m chose mappings for them that would be useful for  typesetting
     technical  literature in a broad range of scientific disciplines: Bell Labs
     used the system to prepare AT&T’s patent filings with the U.S.  government.
     Further,   the   prevailing  character  encoding  standard  in  the  1970s,
     USAS X3.4‐1968 (ASCII), deliberately supported semantic ambiguity  at  some
     code  points,  and outright substitution at several others, to suit the lo‐
     calization demands of various national standards bodies.

     The table below presents the seven exceptional code points with their typi‐
     cal keycap engravings, their glyph mappings and semantics in [4mroff[24m  systems,
     and  the  escape sequences producing the Unicode basic Latin character they
     replace.  The first, the neutral double quote, is a partial  exception  be‐
     cause it does represent itself, but since the [4mroff[24m language also uses it to
     quote  macro  arguments, [4mgroff[24m supports a special character escape sequence
     as an alternative form so that the glyph can be easily  included  in  macro
     arguments  without requiring the user to master the quoting rules that AT&T
     [4mtroff[24m required in that context.  (Some requests, like [1mds[22m, also treat [1m" [22mnon‐
     literally at the beginning of an argument.)  Furthermore, not  all  of  the
     special  character  escape  sequences are portable to AT&T [4mtroff[24m and all of
     its descendants; these [4mgroff[24m extensions are  presented  using  its  special
     character form [1m\[][22m, whereas portable special character escape sequences are
     shown  in  the  traditional  [1m\(  [22mform.  [1m\- [22mand [1m\e [22mare portable to all known
     [4mtroff[24ms.  [1m\e [22mmeans “the glyph of the current escape character”; it therefore
     can produce unexpected output if the [1mec [22mrequest is used.  On devices with a
     limited glyph repertoire, glyphs in the “keycap” and  “appearance”  columns
     on  the  same  row  of the table may look identical; except for the neutral
     double quote, this will [4mnot[24m be the case on  more‐capable  devices.   Review
     your document using as many different output devices as possible.

       ┌───────────────────────────────────────────────────────────────────┐
       │ Keycap   Appearance and meaning   Special character and meaning   │
       ├───────────────────────────────────────────────────────────────────┤
       │ "        " neutral double quote   \[dq] neutral double quote      │
       │ '        ’ closing single quote   \[aq] neutral apostrophe        │
       │ -        ‐ hyphen                 \- or \[-] minus sign/Unix dash │
       │ \        (escape character)       \e or \[rs] reverse solidus     │
       │ ^        ˆ modifier circumflex    \[ha] circumflex/caret/“hat”    │
       │ `        ‘ opening single quote   \(ga grave accent               │
       │ ~        ˜ modifier tilde         \[ti] tilde                     │
       └───────────────────────────────────────────────────────────────────┘

     The  hyphen‐minus  is  a particularly unfortunate case of overloading.  Its
     awkward name in ISO 8859 and later standards reflects the many distinguish‐
     able purposes to which it had already been put by the  1980s,  including  a
     hyphen,  a  minus  sign,  and  (alone  or  in repetition) dashes of varying
     widths.  For best results in [4mroff[24m systems, use the “[1m-[22m” character  in  input
     outside  an  escape sequence [4monly[24m to mean a hyphen, as in the phrase “long‐
     term”.  For a minus sign in running text or a Unix file  name  or  command‐
     line option dash, use [1m\- [22m(or [1m\[-] [22min [4mgroff[24m if you find it helps the clarity
     of  the source document).  (Another minus sign, for use in mathematical ex‐
     pressions, is available as [1m\(mi[22m.)  AT&T [4mtroff[24m supported em‐dashes as  [1m\(em[22m,
     as does [4mgroff[24m.

     The  special character escape sequence for the apostrophe as a neutral sin‐
     gle quote is typically needed only in technical content; typing words  like
     “can’t” and “Anne’s” in a natural way will render correctly, because in or‐
     dinary  prose an apostrophe is typeset either as a closing single quotation
     mark or as a neutral single quote, depending on  the  capabilities  of  the
     output  device.   By contrast, special character escape sequences should be
     used for quotation marks unless portability to limited or historical  [4mtroff[0m
     implementations  is necessary; on those systems, the input convention is to
     pair the grave accent with the apostrophe for single quotes, and to  double
     both  characters  for double quotes.  AT&T [4mtroff[24m defined no special charac‐
     ters for  quotation  marks  or  the  apostrophe.   Repeated  single  quotes
     (‘‘thus’’)  will be visually distinguishable from double quotes (“thus”) on
     terminal devices, and perhaps on others (depending on the font selected and
     its kerning configuration).
        ┌─────────────────────────────────────────────────────────────────┐
        │ AT&T [4mtroff[24m input          recommended [4mgroff[24m input               │
        ├─────────────────────────────────────────────────────────────────┤
        │ A Winter's Tale           A Winter's Tale                       │
        │ `U.K. outer quotes'       \[oq]U.K. outer quotes\[cq]           │
        │ `U.K. ``inner'' quotes'   \[oq]U.K. \[lq]inner\[rq] quotes\[cq] │
        │ ``U.S. outer quotes''     \[lq]U.S. outer quotes\[rq]           │
        │ ``U.S. `inner' quotes''   \[lq]U.S. \[oq]inner\[cq] quotes\[rq] │
        └─────────────────────────────────────────────────────────────────┘
     If you frequently require quotation marks in  your  document,  see  if  the
     macro  package you’re using supplies strings or macros to facilitate quota‐
     tion, or define them yourself (except in man pages).

     Using Unicode basic Latin characters to compose boxes and lines is  ill‐ad‐
     vised.   [4mroff[24m  systems  have  dedicated features for drawing horizontal and
     vertical lines, the [1m\l[22m, [1m\L[22m, and [1m\D [22mescape sequences.  Also  see  subsection
     “Rules  and  lines” below.  Preprocessors like ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\ and ]8;;man:pic(1)\[4mpic[24m(1)]8;;\ draw boxes
     and will produce the best possible output for the device, falling  back  to
     basic Latin glyphs only when necessary.

   [1mEight‐bit encodings and Latin‐1 supplement[0m
     ISO  646  is a seven‐bit code encoding 128 code points; eight‐bit codes are
     twice the size.  ISO Latin‐1 (8859‐1) allocated  the  additional  space  to
     what Unicode calls “C1 controls” (control characters) and the “Latin‐1 sup‐
     plement”.   The  C1  controls are neither printable nor usable as GNU [4mtroff[0m
     input.

     GNU [4mtroff[24m handles two Latin‐1 supplement characters  specially,  and  never
     produces them as output.

     NBSP   encodes a no‐break space; it maps to [1m\~[22m, the adjustable non‐breaking
            space escape sequence.

     SHY    encodes a soft hyphen; it maps to [1m\%[22m, the hyphenation control escape
            sequence.

     The  remaining  characters  in the Latin‐1 supplement represent themselves.
     Although they can be specified directly with the keyboard on  systems  con‐
     figured to use Latin‐1 as the character encoding, it is more portable, both
     to other [4mroff[24m systems and to UTF‐8 environments, to use their special char‐
     acter  escape  sequences,  shown  below.  The glyph descriptions we use are
     non‐standard in some cases, for brevity.

     ¡  \[r!] inverted exclamation mark     Ñ  \[~N] N tilde
     ¢  \[ct] cent sign                     Ò  \[`O] O grave
     £  \[Po] pound sign                    Ó  \['O] O acute
     ¤  \[Cs] currency sign                 Ô  \[^O] O circumflex
     ¥  \[Ye] yen sign                      Õ  \[~O] O tilde
     ¦  \[bb] broken bar                    Ö  \[:O] O dieresis
     §  \[sc] section sign                  ×  \[mu] multiplication sign
     ¨  \[ad] dieresis accent               Ø  \[/O] O slash
     ©  \[co] copyright sign                Ù  \[`U] U grave
     ª  \[Of] feminine ordinal indicator    Ú  \['U] U acute
     «  \[Fo] left double chevron           Û  \[^U] U circumflex
     ¬  \[no] logical not                   Ü  \[:U] U dieresis
     ®  \[rg] registered sign               Ý  \['Y] Y acute
     ¯  \[a-] macron accent                 Þ  \[TP] uppercase thorn
     °  \[de] degree sign                   ß  \[ss] lowercase sharp s
     ±  \[+-] plus‐minus                    à  \[`a] a grave
     ²  \[S2] superscript two               á  \['a] a acute
     ³  \[S3] superscript three             â  \[^a] a circumflex
     ´  \[aa] acute accent                  ã  \[~a] a tilde
     µ  \[mc] micro sign                    ä  \[:a] a dieresis
     ¶  \[ps] pilcrow sign                  å  \[oa] a ring
     ·  \[pc] centered period               æ  \[ae] ae ligature
     ¸  \[ac] cedilla accent                ç  \[,c] c cedilla
     ¹  \[S1] superscript one               è  \[`e] e grave
     º  \[Om] masculine ordinal indicator   é  \['e] e acute
     »  \[Fc] right double chevron          ê  \[^e] e circumflex
     ¼  \[14] one quarter symbol            ë  \[:e] e dieresis
     ½  \[12] one half symbol               ì  \[`i] i grave
     ¾  \[34] three quarters symbol         í  \['i] e acute
     ¿  \[r?] inverted question mark        î  \[^i] i circumflex
     À  \[`A] A grave                       ï  \[:i] i dieresis
     Á  \['A] A acute                       ð  \[Sd] lowercase eth
     Â  \[^A] A circumflex                  ñ  \[~n] n tilde
     Ã  \[~A] A tilde                       ò  \[`o] o grave
     Ä  \[:A] A dieresis                    ó  \['o] o acute
     Å  \[oA] A ring                        ô  \[^o] o circumflex
     Æ  \[AE] AE ligature                   õ  \[~o] o tilde
     Ç  \[,C] C cedilla                     ö  \[:o] o dieresis
     È  \[`E] E grave                       ÷  \[di] division sign
     É  \['E] E acute                       ø  \[/o] o slash
     Ê  \[^E] E circumflex                  ù  \[`u] u grave
     Ë  \[:E] E dieresis                    ú  \['u] u acute
     Ì  \[`I] I grave                       û  \[^u] u circumflex
     Í  \['I] I acute                       ü  \[:u] u dieresis
     Î  \[^I] I circumflex                  ý  \['y] y acute
     Ï  \[:I] I dieresis                    þ  \[Tp] lowercase thorn
     Ð  \[-D] uppercase eth                 ÿ  \[:y] y dieresis

   [1mSpecial character escape forms[0m
     Glyphs that lack a character code in the basic Latin repertoire to directly
     represent them are entered by  one  of  several  special  character  escape
     forms.  Such glyphs can be simple or composite, and accessed either by name
     or numerically by code point.  Code points and combining properties are de‐
     termined  by character encoding standards, whereas glyph names as used here
     originated in AT&T [4mtroff[24m special character  escape  sequences.   Predefined
     glyph names use only characters in the basic Latin repertoire.

     [1m\([4m[22mgl[24m   is  a  special character escape sequence for the glyph with the two‐
            character name [4mgl[24m.  This is the original syntax  form  supported  by
            AT&T [4mtroff[24m.  The acute accent, [1m\(aa[22m, is an example.

     [1m\C'[4m[22mglyph‐name[24m[1m'[0m
            is  a special character escape sequence for [4mglyph‐name[24m, which can be
            of arbitrary length.  The delimiter, shown here as a  neutral  apos‐
            trophe, can be any character not occurring in [4mglyph‐name[24m.  This syn‐
            tax form was introduced in later versions of AT&T device‐independent
            [4mtroff[24m.   The  foregoing  acute  accent  example  can be expressed as
            [1m\C'aa'[22m.

     [1m\[[4m[22mglyph‐name[24m[1m][0m
            is a special character escape sequence for [4mglyph‐name[24m, which can  be
            of  arbitrary  length  but must not contain a closing square bracket
            “[1m][22m”.  (No glyph names predefined by [4mgroff[24m employ “[1m][22m”.)  The  forego‐
            ing acute accent example can be expressed in in GNU [4mtroff[24m as [1m\[aa][22m.

     [1m\C'[4m[22mc[24m[1m' [22mand [1m\[[4m[22mc[24m[1m] [22mare not synonyms for the ordinary character “[4mc[24m”, but request
     the  special  character  named  “[1m\[4m[22mc[24m”.   For example, “[1m\[a][22m” is not “a”, but
     rather a special character with the internal glyph name (used in  font  de‐
     scription  files and diagnostic messages) [1m\a[22m, which is typically undefined.
     The only such glyph name [4mgroff[24m predefines is  the  minus  sign,  which  can
     therefore be accessed as [1m\C'-' [22mor [1m\[-][22m.

     [1m\[[4m[22mbase‐char[24m [4mcomposite‐1[24m [4mcomposite‐2[24m ... [4mcomposite‐n[24m[1m][0m
            is a composite glyph.  Glyphs like a lowercase “e” with an acute ac‐
            cent, as in the word “café”, can be expressed as [1m\[e aa][22m.

     Normally,  the formatter advances the drawing position after setting a spe‐
     cial character, as it does for ordinary ones.   [4mgroff[24m’s  [1mcomposite  [22mrequest
     designates a special character as combining, suppressing advancement.

     You can obtain a report of mappings defined by the [1mcomposite [22mrequest on the
     standard  error  stream  with  the  [1mpcomposite [22mrequest.  The [4mcomposite.tmac[0m
     macro file, loaded automatically by the default [4mtroffrc[24m, maps certain  spe‐
     cial  characters  to  combining characters as shown in subsection “Accents”
     below.

     Unicode encodes far more characters than [4mgroff[24m has names for; special char‐
     acter escape forms based on numerical code points enable access to  any  of
     them.   Frequently  used  glyphs  or  glyph  combinations  can be stored in
     strings, and new glyph names can be created [4mad[24m [4mhoc[24m with the  [1mchar  [22mrequest;
     see ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\.

     [1m\[u[4m[22mnnnn[24m[[4mn[24m[[4mn[24m]][1m][0m
            is a Unicode numeric special character escape sequence.  Any Unicode
            code point can be accessed with four to six hexadecimal digits, with
            hexadecimal letters accepted in uppercase form only.  Thus, [1m\[u02DA][0m
            accesses the (spacing) ring accent, producing “˚”.

     Unicode  code  points can be composed as well; when they are, GNU [4mtroff[24m re‐
     quires NFD (Normalization Form D), where all Unicode glyphs  are  maximally
     decomposed.   (Exception:  precomposed characters in the Latin‐1 supplement
     described above are also accepted.  Do not count on this exception  remain‐
     ing  in  a  future GNU [4mtroff[24m that accepts UTF‐8 input directly.)  Thus, GNU
     [4mtroff[24m accepts “caf[1m\['e][22m”, “caf[1m\[e aa][22m”, and “caf[1m\[u0065_0301][22m”, as ways  to
     input  “café”.  (Due to its legacy 8‐bit encoding compatibility, at present
     it also accepts “caf[1m\[u00E9][22m” on ISO Latin‐1 systems.)

     [1m\[u[4m[22mbase‐char[24m[[1m_[4m[22mcombining‐component[24m]...]
            constructs a composite glyph from Unicode numeric special  character
            escape sequences.  The code points of the base glyph and the combin‐
            ing components are each expressed in hexadecimal, with an underscore
            ([1m_[22m) separating each component.  Thus, [1m\[u006E_0303] [22mproduces “ñ”.

     [1m\[char[4m[22mnnn[24m[1m][0m
            expresses an eight‐bit code point where [4mnnn[24m is the code point of the
            character,  a  decimal  number between 0 and 255 without leading ze‐
            roes.  This legacy numeric special character escape sequence is used
            to map characters onto glyphs via the [1mtrin [22mrequest  in  macro  files
            loaded by ]8;;man:grotty(1)\[4mgrotty[24m(1)]8;;\.

[1mGlyph tables[0m
     In  this  section,  [4mgroff[24m’s  glyph  name repertoire is presented in tabular
     form.  The meanings of the columns are as follows.

     [1mOutput   [22mshows the glyph as it appears on the device used  to  render  this
              document;  although it can have a notably different shape on other
              devices (and is subject to user‐directed translation and  replace‐
              ment),  [4mgroff[24m  attempts  reasonable  equivalency on all output de‐
              vices.

     [1mInput    [22mshows the [4mgroff[24m character (ordinary or special) that normally pro‐
              duces the glyph.  Some code points have multiple glyph names.

     [1mUnicode  [22mis the code point notation for the glyph or  combining  glyph  se‐
              quence as described in subsection “Special character escape forms”
              above.   It corresponds to the standard notation for Unicode short
              identifiers such that [4mgroff[24m’s [1mu[4m[22mnnnn[24m  is  equivalent  to  Unicode’s
              U+[4mnnnn[24m.

     [1mNotes    [22mdescribes  the  glyph, elucidating the mnemonic value of the glyph
              name where possible.

              A plus sign “+” indicates that the glyph name appears in the  AT&T
              [4mtroff[24m  user’s  manual,  CSTR  #54 (1992 revision).  When using the
              AT&T special character syntax [1m\([4m[22mxx[24m, widespread portability can  be
              expected from such names.

              Entries marked with “***” denote glyphs used for mathematical pur‐
              poses.   On  typesetting  devices, such glyphs are typically drawn
              from a [4mspecial[24m font (see ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\).  Often, such glyphs  lack
              bold  or  italic style forms or have metrics that look incongruous
              in ordinary prose.  A few that are not uncommon  in  running  text
              have  “text  variants”,  which should work better in that context.
              Conversely, a handful of glyphs that are  normally  drawn  from  a
              text  font may be required in mathematical expressions.  Both sets
              of exceptions are noted in the tables where they appear  (“Logical
              symbols” and “Mathematical symbols”).

   [1mBasic Latin[0m
     Apart  from basic Latin characters with special mappings, described in sub‐
     section “Fundamental character set” above, a few others in that range  have
     special  character  glyph  names.   These were defined for ease of input on
     non‐U.S. keyboards lacking keycaps for them, or  for  symmetry  with  other
     special character glyph names serving a similar purpose.

     The  vertical  bar  is overloaded; the [1m\[ba] [22mand [1m\[or] [22mescape sequences may
     render differently.  See subsection “Mathematical symbols”  below  for  un‐
     styled  variants  of  the plus, minus, and equals signs normally drawn from
     this range.

     Output   Input   Unicode   Notes
     ───────────────────────────────────────────────────────────────────────────
     "        \[dq]   u0022     neutral double quote
     #        \[sh]   u0023     number sign
     $        \[Do]   u0024     dollar sign
     '        \[aq]   u0027     apostrophe, neutral single quote
     /        \[sl]   u002F     slash, solidus +
     @        \[at]   u0040     at sign
     [        \[lB]   u005B     left square bracket
     \        \[rs]   u005C     reverse solidus
     ]        \[rB]   u005D     right square bracket
     ^        \[ha]   u005E     circumflex, caret, “hat”
     {        \[lC]   u007B     left brace
     |        |       u007C     bar +
     |        \[ba]   u007C     bar
     |        \[or]   u007C     bitwise or +
     }        \[rC]   u007D     right brace
     ~        \[ti]   u007E     tilde

   [1mSupplementary Latin letters[0m
     Historically, [1m\[ss] [22mdeveloped from a ligature of “sz”.  An  uppercase  form
     is  available  as [1m\[u1E9E][22m, but in the German language it is of specialized
     use; ß does [4mnot[24m normally uppercase‐transform to it,  but  rather  to  “SS”.
     “Lowercase  f  with hook” is also used as a function symbol; see subsection
     “Mathematical symbols” below.

     Output   Input   Unicode   Notes
     ───────────────────────────────────────────────────────────────────────────
     Ð        \[-D]   u00D0     uppercase eth
     ð        \[Sd]   u00F0     lowercase eth
     Þ        \[TP]   u00DE     uppercase thorn
     þ        \[Tp]   u00FE     lowercase thorn
     ß        \[ss]   u00DF     lowercase sharp s
     ı        \[.i]   u0131     i without tittle
     ȷ        \[.j]   u0237     j without tittle
     ƒ        \[Fn]   u0192     lowercase f with hook, function
     Ł        \[/L]   u0141     L with stroke
     ł        \[/l]   u0142     l with stroke
     Ø        \[/O]   u00D8     O with stroke
     ø        \[/o]   u00F8     o with stroke

   [1mLigatures and digraphs[0m
     Output   Input   Unicode           Notes
     ───────────────────────────────────────────────────────────────────────────
     ff       \[ff]   u0066_0066        ff ligature +
     fi       \[fi]   u0066_0069        fi ligature +
     fl       \[fl]   u0066_006C        fl ligature +
     ffi      \[Fi]   u0066_0066_0069   ffi ligature +
     ffl      \[Fl]   u0066_0066_006C   ffl ligature +
     Æ        \[AE]   u00C6             AE ligature
     æ        \[ae]   u00E6             ae ligature
     Œ        \[OE]   u0152             OE ligature
     œ        \[oe]   u0153             oe ligature
     Ĳ        \[IJ]   u0132             IJ digraph
     ĳ        \[ij]   u0133             ij digraph

   [1mAccents[0m
     The non‐combining code point in parentheses is used when the special  char‐
     acter occurs in isolation (compare “[1mcaf\[e aa][22m” and “[1mcaf\[aa]e[22m”).

     Output   Input   Unicode         Notes
     ───────────────────────────────────────────────────────────────────────────
     ˝        \[a"]   u030B (u02DD)   double acute accent
     ¯        \[a-]   u0304 (u00AF)   macron accent
     ˙        \[a.]   u0307 (u02D9)   dot accent
     ^        \[a^]   u0302 (u005E)   circumflex accent
     ´        \[aa]   u0301 (u00B4)   acute accent +
     `        \[ga]   u0300 (u0060)   grave accent +
     ˘        \[ab]   u0306 (u02D8)   breve accent
     ¸        \[ac]   u0327 (u00B8)   cedilla accent
     ¨        \[ad]   u0308 (u00A8)   dieresis accent
     ˇ        \[ah]   u030C (u02C7)   caron accent
     ˚        \[ao]   u030A (u02DA)   ring accent
     ~        \[a~]   u0303 (u007E)   tilde accent
     ˛        \[ho]   u0328 (u02DB)   hook accent

   [1mAccented characters[0m
     All  of  these  glyphs  can  be composed using combining glyph names as de‐
     scribed in subsection “Special character escape forms” above; the names be‐
     low are short aliases for convenience.

     Output   Input   Unicode      Notes
     ───────────────────────────────────────────────────────────────────────────
     Á        \['A]   u0041_0301   A acute
     Ć        \['C]   u0043_0301   C acute
     É        \['E]   u0045_0301   E acute
     Í        \['I]   u0049_0301   I acute
     Ó        \['O]   u004F_0301   O acute
     Ú        \['U]   u0055_0301   U acute
     Ý        \['Y]   u0059_0301   Y acute
     á        \['a]   u0061_0301   a acute
     ć        \['c]   u0063_0301   c acute
     é        \['e]   u0065_0301   e acute
     í        \['i]   u0069_0301   i acute
     ó        \['o]   u006F_0301   o acute
     ú        \['u]   u0075_0301   u acute
     ý        \['y]   u0079_0301   y acute

     Ä        \[:A]   u0041_0308   A dieresis
     Ë        \[:E]   u0045_0308   E dieresis
     Ï        \[:I]   u0049_0308   I dieresis
     Ö        \[:O]   u004F_0308   O dieresis
     Ü        \[:U]   u0055_0308   U dieresis
     Ÿ        \[:Y]   u0059_0308   Y dieresis
     ä        \[:a]   u0061_0308   a dieresis
     ë        \[:e]   u0065_0308   e dieresis
     ï        \[:i]   u0069_0308   i dieresis
     ö        \[:o]   u006F_0308   o dieresis
     ü        \[:u]   u0075_0308   u dieresis
     ÿ        \[:y]   u0079_0308   y dieresis

     Â        \[^A]   u0041_0302   A circumflex
     Ê        \[^E]   u0045_0302   E circumflex
     Î        \[^I]   u0049_0302   I circumflex
     Ô        \[^O]   u004F_0302   O circumflex
     Û        \[^U]   u0055_0302   U circumflex
     â        \[^a]   u0061_0302   a circumflex
     ê        \[^e]   u0065_0302   e circumflex
     î        \[^i]   u0069_0302   i circumflex
     ô        \[^o]   u006F_0302   o circumflex
     û        \[^u]   u0075_0302   u circumflex

     À        \[`A]   u0041_0300   A grave
     È        \[`E]   u0045_0300   E grave
     Ì        \[`I]   u0049_0300   I grave
     Ò        \[`O]   u004F_0300   O grave
     Ù        \[`U]   u0055_0300   U grave
     à        \[`a]   u0061_0300   a grave
     è        \[`e]   u0065_0300   e grave
     ì        \[`i]   u0069_0300   i grave
     ò        \[`o]   u006F_0300   o grave
     ù        \[`u]   u0075_0300   u grave

     Ã        \[~A]   u0041_0303   A tilde
     Ñ        \[~N]   u004E_0303   N tilde
     Õ        \[~O]   u004F_0303   O tilde
     ã        \[~a]   u0061_0303   a tilde
     ñ        \[~n]   u006E_0303   n tilde
     õ        \[~o]   u006F_0303   o tilde

     Š        \[vS]   u0053_030C   S caron
     š        \[vs]   u0073_030C   s caron
     Ž        \[vZ]   u005A_030C   Z caron
     ž        \[vz]   u007A_030C   z caron

     Ç        \[,C]   u0043_0327   C cedilla
     ç        \[,c]   u0063_0327   c cedilla

     Å        \[oA]   u0041_030A   A ring
     å        \[oa]   u0061_030A   a ring

   [1mQuotation marks[0m
     The neutral double quote, useful in documenting programming  languages,  is
     also available as a special character for convenient embedding in macro ar‐
     guments; see subsection “Fundamental character set” above.

     Output   Input   Unicode   Notes
     ───────────────────────────────────────────────────────────────────────────
     „        \[Bq]   u201E     low double comma quote
     ‚        \[bq]   u201A     low single comma quote
     “        \[lq]   u201C     left double quote
     ”        \[rq]   u201D     right double quote
     ‘        \[oq]   u2018     single opening (left) quote
     ’        \[cq]   u2019     single closing (right) quote
     '        \[aq]   u0027     apostrophe, neutral single quote
     "        "       u0022     neutral double quote
     "        \[dq]   u0022     neutral double quote
     «        \[Fo]   u00AB     left double chevron
     »        \[Fc]   u00BB     right double chevron
     ‹        \[fo]   u2039     left single chevron
     ›        \[fc]   u203A     right single chevron

   [1mPunctuation[0m
     The Unicode name for U+00B7 is “middle dot”, which is unfortunately confus‐
     able with the [4mgroff[24m mnemonic for the visually similar but semantically dis‐
     tinct multiplication dot; see subsection “Mathematical symbols” below.

     Output   Input   Unicode   Notes
     ───────────────────────────────────────────────────────────────────────────
     ¡        \[r!]   u00A1     inverted exclamation mark
     ¿        \[r?]   u00BF     inverted question mark
     ·        \[pc]   u00B7     centered period
     ——       \[em]   u2014     em‐dash +
     –        \[en]   u2013     en‐dash
     ‐        -       u2010     hyphen +
     ‐        \[hy]   u2010     hyphen +

   [1mBrackets[0m
     On  typesetting  devices, the bracket extensions are font‐invariant glyphs;
     that is, they are rendered the same way regardless of font (with a  drawing
     escape  sequence).   On  terminals, they are [4mnot[24m font‐invariant; [4mgroff[24m maps
     them arbitrarily to U+23AA (“curly bracket  extension”).   In  AT&T  [4mtroff[24m,
     only  one  glyph  was  available to vertically extend brackets, braces, and
     parentheses: [1m\(bv[22m.

     Not all devices supply bracket pieces that can be piled up with [1m\b  [22mdue  to
     the  restrictions of the formatter’s piling algorithm.  The following macro
     offers a more general bracket‐building solution.
            .\" Make a pile centered vertically 0.5em above the baseline.
            .\" The first argument is placed at the top.
            .\" The pile is returned in string 'pile'.
            .eo
            .de pile-make
            .  nr pile-wd 0
            .  nr pile-ht 0
            .  ds pile-args
            .
            .  nr pile-# \n[.$]
            .  while \n[pile-#] \{\
            .    nr pile-wd (\n[pile-wd] >? \w'\$[\n[pile-#]]')
            .    nr pile-ht +(\n[rst] - \n[rsb])
            .    as pile-args \v'\n[rsb]u'\"
            .    as pile-args \Z'\$[\n[pile-#]]'\"
            .    as pile-args \v'-\n[rst]u'\"
            .    nr pile-# -1
            .  \}
            .
            .  ds pile \v'(-0.5m + (\n[pile-ht]u / 2u))'\"
            .  as pile \*[pile-args]\"
            .  as pile \v'((\n[pile-ht]u / 2u) + 0.5m)'\"
            .  as pile \h'\n[pile-wd]u'\"
            ..
            .ec

     Further complicating matters  is  that  some  glyphs  representing  bracket
     pieces  in  AT&T  [4mtroff[24m can be used for other mathematical symbols as well;
     for example, [1m\(lf [22mand [1m\(rf [22mprovide the floor  operator.   Some  output  de‐
     vices,  such  as [1mdvi[22m, don’t unify such glyphs.  For this reason, the glyphs
     [1m\[lf][22m, [1m\[rf][22m, [1m\[lc][22m, and [1m\[rc] [22mare not unified with similar‐looking bracket
     pieces.  In [4mgroff[24m, only glyphs with long names are guaranteed  to  pile  up
     correctly for all devices——provided those glyphs are available.

     Output   Input               Unicode   Notes
     ───────────────────────────────────────────────────────────────────────────
     [        [                   u005B     left square bracket
     [        \[lB]               u005B     left square bracket
     ]        ]                   u005D     right square bracket
     ]        \[rB]               u005D     right square bracket
     {        {                   u007B     left brace
     {        \[lC]               u007B     left brace
     }        }                   u007D     right brace
     }        \[rC]               u007D     right brace
     ⟨        \[la]               u27E8     left angle bracket
     ⟩        \[ra]               u27E9     right angle bracket
     ⎪        \[bv]               u23AA     brace vertical extension + ***
     ⎪        \[braceex]          u23AA     brace vertical extension

     ⎡        \[bracketlefttp]    u23A1     left square bracket top
     ⎢        \[bracketleftex]    u23A2     left square bracket extension
     ⎣        \[bracketleftbt]    u23A3     left square bracket bottom

     ⎤        \[bracketrighttp]   u23A4     right square bracket top
     ⎥        \[bracketrightex]   u23A5     right square bracket extension
     ⎦        \[bracketrightbt]   u23A6     right square bracket bottom

     ⎧        \[lt]               u23A7     left brace top +
     ⎨        \[lk]               u23A8     left brace middle +
     ⎩        \[lb]               u23A9     left brace bottom +
     ⎧        \[bracelefttp]      u23A7     left brace top
     ⎨        \[braceleftmid]     u23A8     left brace middle
     ⎩        \[braceleftbt]      u23A9     left brace bottom
     ⎪        \[braceleftex]      u23AA     left brace extension

     ⎫        \[rt]               u23AB     right brace top +
     ⎬        \[rk]               u23AC     right brace middle +
     ⎭        \[rb]               u23AD     right brace bottom +
     ⎫        \[bracerighttp]     u23AB     right brace top
     ⎬        \[bracerightmid]    u23AC     right brace middle
     ⎭        \[bracerightbt]     u23AD     right brace bottom
     ⎪        \[bracerightex]     u23AA     right brace extension

     ⎛        \[parenlefttp]      u239B     left parenthesis top
     ⎜        \[parenleftex]      u239C     left parenthesis extension
     ⎝        \[parenleftbt]      u239D     left parenthesis bottom
     ⎞        \[parenrighttp]     u239E     right parenthesis top
     ⎟        \[parenrightex]     u239F     right parenthesis extension
     ⎠        \[parenrightbt]     u23A0     right parenthesis bottom

   [1mArrows[0m
     Output   Input   Unicode   Notes
     ───────────────────────────────────────────────────────────────────────────
     ←        \[<-]   u2190     horizontal arrow left +
     →        \[->]   u2192     horizontal arrow right +
     ↔        \[<>]   u2194     bidirectional horizontal arrow
     ↓        \[da]   u2193     vertical arrow down +
     ↑        \[ua]   u2191     vertical arrow up +
     ↕        \[va]   u2195     bidirectional vertical arrow
     ⇐        \[lA]   u21D0     horizontal double arrow left
     ⇒        \[rA]   u21D2     horizontal double arrow right
     ⇔        \[hA]   u21D4     bidirectional horizontal double arrow
     ⇓        \[dA]   u21D3     vertical double arrow down
     ⇑        \[uA]   u21D1     vertical double arrow up
     ⇕        \[vA]   u21D5     bidirectional vertical double arrow
     ⎯        \[an]   u23AF     horizontal arrow extension

   [1mRules and lines[0m
     On  typesetting  devices, the font‐invariant glyphs (see subsection “Brack‐
     ets” above) [1m\[br][22m, [1m\[ul][22m, and [1m\[rn] [22mform corners when adjacent; they can be
     used to build boxes.  On terminal devices, they are mapped as shown in  the
     table.  The Unicode‐derived names of these three glyphs are approximations.

     The ordinary character [1m_ [22maccesses the underscore glyph in a font; [1m\[ul][22m, by
     contrast, may be font‐invariant on typesetting devices.

     The  baseline  rule  [1m\[ru] [22mis a font‐invariant glyph, namely a rule of one‐
     half em.

     In AT&T [4mtroff[24m, [1m\[rn] [22malso served as a one en extension of the  square  root
     symbol.  [4mgroff[24m favors [1m\[radicalex] [22mfor this purpose; see subsection “Mathe‐
     matical symbols” below.

     Output   Input   Unicode   Notes
     ───────────────────────────────────────────────────────────────────────────
     |        |       u007C     bar
     |        \[ba]   u007C     bar
     │        \[br]   u2502     box rule +
     _        _       u005F     underscore, low line +
     _        \[ul]   ‐‐‐       underrule +
     ‾        \[rn]   u203E     overline +
     _        \[ru]   ‐‐‐       baseline rule +
     ¦        \[bb]   u00A6     broken bar
     /        /       u002F     slash, solidus +
     /        \[sl]   u002F     slash, solidus +
     \        \[rs]   u005C     reverse solidus

   [1mText markers[0m
     Output   Input   Unicode   Notes
     ───────────────────────────────────────────────────────────────────────────
     ○        \[ci]   u25CB     circle +
     •        \[bu]   u2022     bullet +
     †        \[dg]   u2020     dagger +
     ‡        \[dd]   u2021     double dagger +
     ◊        \[lz]   u25CA     lozenge, diamond
     □        \[sq]   u25A1     square +
     ¶        \[ps]   u00B6     pilcrow sign
     §        \[sc]   u00A7     section sign +
     ☜        \[lh]   u261C     hand pointing left +
     ☞        \[rh]   u261E     hand pointing right +
     @        @       u0040     at sign
     @        \[at]   u0040     at sign
     #        #       u0023     number sign
     #        \[sh]   u0023     number sign
     ↵        \[CR]   u21B5     carriage return
     ✓        \[OK]   u2713     check mark

   [1mLegal symbols[0m
     The Bell System logo is not supported in [4mgroff[24m.

     Output   Input   Unicode   Notes
     ───────────────────────────────────────────────────────────────────────────
     ©        \[co]   u00A9     copyright sign +
     ®        \[rg]   u00AE     registered sign +
     ™        \[tm]   u2122     trade mark sign
              \[bs]   ‐‐‐       Bell System logo +

   [1mCurrency symbols[0m
     Output   Input   Unicode   Notes
     ───────────────────────────────────────────────────────────────────────────
     $        $       u0024     dollar sign
     $        \[Do]   u0024     dollar sign
     ¢        \[ct]   u00A2     cent sign +
     €        \[eu]   u20AC     Euro sign
     €        \[Eu]   u20AC     variant Euro sign
     ¥        \[Ye]   u00A5     yen sign
     £        \[Po]   u00A3     pound sign
     ¤        \[Cs]   u00A4     currency sign

   [1mUnits[0m
     Output   Input   Unicode   Notes
     ───────────────────────────────────────────────────────────────────────────
     °        \[de]   u00B0     degree sign +
     ‰        \[%0]   u2030     per thousand, per mille sign
     ′        \[fm]   u2032     arc minute sign, foot mark +
     ″        \[sd]   u2033     arc second sign
     µ        \[mc]   u00B5     micro sign
     ª        \[Of]   u00AA     feminine ordinal indicator
     º        \[Om]   u00BA     masculine ordinal indicator

   [1mLogical symbols[0m
     The  variants of the not sign may differ in appearance or spacing depending
     on the device and font selected.  Unicode does not encode a discrete  “bit‐
     wise  or”  sign:  on typesetting devices, it is drawn shorter than the bar,
     about the same height as a capital letter.  Terminal  devices  unify  [1m\[ba][0m
     and [1m\[or][22m.

     Output   Input    Unicode   Notes
     ───────────────────────────────────────────────────────────────────────────
     ∧        \[AN]    u2227     logical and
     ∨        \[OR]    u2228     logical or
     ¬        \[no]    u00AC     logical not + ***
     ¬        \[tno]   u00AC     text variant of [1m\[no][0m
     ∃        \[te]    u2203     there exists
     ∀        \[fa]    u2200     for all
     ∋        \[st]    u220B     such that
     ∴        \[3d]    u2234     therefore
     ∴        \[tf]    u2234     therefore
     |        |        u007C     bar +
     |        \[or]    u007C     bitwise or +

   [1mMathematical symbols[0m
     [1m\[Fn]  [22malso appears in subsection “Supplementary Latin letters” above.  The
     plus‐minus, multiplication, and division signs, [1m\[+-][22m,  [1m\[mu][22m,  and  [1m\[di][22m,
     are normally drawn from the special font, but have text font variants.  The
     plus,  minus, and equals signs are normally drawn from text fonts, but have
     special font variants.  Variants may differ in appearance  or  spacing  de‐
     pending on the device and font selected.

     In AT&T [4mtroff[24m, [1m\(rn [22m(“root en extender”) served as the horizontal extension
     of  the  radical  (square  root)  sign,  [1m\(sr[22m, and was drawn at the maximum
     height of the typeface’s bounding box, enabling it to double as an overline
     (see subsection “Rules and lines” above).  A  contemporary  font’s  radical
     sign  might  not  ascend to such an extreme.  In [4mgroff[24m, you can instead use
     [1m\[radicalex] [22mto continue the radical sign [1m\[sr][22m; these  special  characters
     are  intended for use with text fonts.  [1m\[sqrt] [22mand [1m\[sqrtex] [22mare their un‐
     styled counterparts.

     Output   Input          Unicode      Notes
     ───────────────────────────────────────────────────────────────────────────
     ½        \[12]          u00BD        one half symbol +
     ¼        \[14]          u00BC        one quarter symbol +
     ¾        \[34]          u00BE        three quarters symbol +
     ⅛        \[18]          u215B        one eighth symbol
     ⅜        \[38]          u215C        three eighths symbol
     ⅝        \[58]          u215D        five eighths symbol
     ⅞        \[78]          u215E        seven eighths symbol
     ¹        \[S1]          u00B9        superscript one
     ²        \[S2]          u00B2        superscript two
     ³        \[S3]          u00B3        superscript three

     +        +              u002B        plus
     +        \[pl]          u002B        special variant of plus + ***
     -        \[-]           u002D        minus
     −        \[mi]          u2212        special variant of minus + ***
     ∓        \[-+]          u2213        minus‐plus
     ±        \[+-]          u00B1        plus‐minus + ***
     ±        \[t+-]         u00B1        text variant of [1m\[+-][0m
     ⋅        \[md]          u22C5        multiplication dot
     ×        \[mu]          u00D7        multiplication sign + ***
     ×        \[tmu]         u00D7        text variant of [1m\[mu][0m
     ⊗        \[c*]          u2297        circled times
     ⊕        \[c+]          u2295        circled plus
     ÷        \[di]          u00F7        division sign, obelus + ***
     ÷        \[tdi]         u00F7        text variant of [1m\[di][0m
     ⁄        \[f/]          u2044        fraction slash
     *        *              u002A        asterisk
     ∗        \[**]          u2217        mathematical asterisk +

     ≤        \[<=]          u2264        less than or equal to +
     ≥        \[>=]          u2265        greater than or equal to +
     ≪        \[<<]          u226A        much less than
     ≫        \[>>]          u226B        much greater than
     =        =              u003D        equals
     =        \[eq]          u003D        special variant of equals + ***
     ≠        \[!=]          u003D_0338   not equals +
     ≡        \[==]          u2261        equivalent +
     ≢        \[ne]          u2261_0338   not equivalent
     ≅        \[=~]          u2245        approximately equal to
     ≃        \[|=]          u2243        asymptotically equal to +
     ~        \[ti]          u007E        tilde +
     ∼        \[ap]          u223C        similar to, tilde operator +
     ≈        \[~~]          u2248        almost equal to
     ≈        \[~=]          u2248        almost equal to
     ∝        \[pt]          u221D        proportional to +

     ∅        \[es]          u2205        empty set +
     ∈        \[mo]          u2208        element of a set +
     ∉        \[nm]          u2208_0338   not element of set
     ⊂        \[sb]          u2282        proper subset +
     ⊄        \[nb]          u2282_0338   not subset
     ⊃        \[sp]          u2283        proper superset +
     ⊅        \[nc]          u2283_0338   not superset
     ⊆        \[ib]          u2286        subset or equal +
     ⊇        \[ip]          u2287        superset or equal +
     ∩        \[ca]          u2229        intersection, cap +
     ∪        \[cu]          u222A        union, cup +

     ∠        \[/_]          u2220        angle
     ⊥        \[pp]          u22A5        perpendicular
     ∫        \[is]          u222B        integral +
     ∫        \[integral]    u222B        integral ***
     ∑        \[sum]         u2211        summation ***
     ∏        \[product]     u220F        product ***
     ∐        \[coproduct]   u2210        coproduct ***
     ∇        \[gr]          u2207        gradient +
     √        \[sr]          u221A        radical sign, square root +
     ‾        \[rn]          u203E        overline +
     ‾        \[radicalex]   ‐‐‐          radical extension
     √        \[sqrt]        u221A        radical sign, square root ***
     ‾        \[sqrtex]      ‐‐‐          radical extension ***

     ⌈        \[lc]          u2308        left ceiling +
     ⌉        \[rc]          u2309        right ceiling +
     ⌊        \[lf]          u230A        left floor +
     ⌋        \[rf]          u230B        right floor +

     ∞        \[if]          u221E        infinity +
     ℵ        \[Ah]          u2135        aleph symbol
     ƒ        \[Fn]          u0192        lowercase f with hook, function
     ℑ        \[Im]          u2111        blackletter I, imaginary part
     ℜ        \[Re]          u211C        blackletter R, real part
     ℘        \[wp]          u2118        Weierstrass p
     ∂        \[pd]          u2202        partial differential
     ℏ        \[-h]          u210F        h bar
     ℏ        \[hbar]        u210F        h bar

   [1mGreek glyphs[0m
     These glyphs are intended for technical use, not for typesetting Greek lan‐
     guage text; normally, the uppercase letters have  upright  shape,  and  the
     lowercase  ones are slanted.  For the latter, we include in parentheses un‐
     der “Unicode” more appropriate code points from the  Mathematical  Alphanu‐
     meric Symbols block of the Supplementary Multilingual Plane.

     Output   Input   Unicode          Notes
     ───────────────────────────────────────────────────────────────────────────
     Α        \[*A]   u0391            uppercase alpha +
     Β        \[*B]   u0392            uppercase beta +
     Γ        \[*G]   u0393            uppercase gamma +
     Δ        \[*D]   u0394            uppercase delta +
     Ε        \[*E]   u0395            uppercase epsilon +
     Ζ        \[*Z]   u0396            uppercase zeta +
     Η        \[*Y]   u0397            uppercase eta +
     Θ        \[*H]   u0398            uppercase theta +
     Ι        \[*I]   u0399            uppercase iota +
     Κ        \[*K]   u039A            uppercase kappa +
     Λ        \[*L]   u039B            uppercase lambda +
     Μ        \[*M]   u039C            uppercase mu +
     Ν        \[*N]   u039D            uppercase nu +
     Ξ        \[*C]   u039E            uppercase xi +
     Ο        \[*O]   u039F            uppercase omicron +
     Π        \[*P]   u03A0            uppercase pi +
     Ρ        \[*R]   u03A1            uppercase rho +
     Σ        \[*S]   u03A3            uppercase sigma +
     Τ        \[*T]   u03A4            uppercase tau +
     Υ        \[*U]   u03A5            uppercase upsilon +
     Φ        \[*F]   u03A6            uppercase phi +
     Χ        \[*X]   u03A7            uppercase chi +
     Ψ        \[*Q]   u03A8            uppercase psi +
     Ω        \[*W]   u03A9            uppercase omega +

     α        \[*a]   u03B1 (u1D6FC)   lowercase alpha +
     β        \[*b]   u03B2 (u1D6FD)   lowercase beta +
     γ        \[*g]   u03B3 (u1D6FE)   lowercase gamma +
     δ        \[*d]   u03B4 (u1D6FF)   lowercase delta +
     ε        \[*e]   u03B5 (u1D700)   lowercase epsilon +
     ζ        \[*z]   u03B6 (u1D701)   lowercase zeta +
     η        \[*y]   u03B7 (u1D702)   lowercase eta +
     θ        \[*h]   u03B8 (u1D703)   lowercase theta +
     ι        \[*i]   u03B9 (u1D704)   lowercase iota +
     κ        \[*k]   u03BA (u1D705)   lowercase kappa +
     λ        \[*l]   u03BB (u1D706)   lowercase lambda +
     μ        \[*m]   u03BC (u1D707)   lowercase mu +
     ν        \[*n]   u03BD (u1D708)   lowercase nu +
     ξ        \[*c]   u03BE (u1D709)   lowercase xi +
     ο        \[*o]   u03BF (u1D70A)   lowercase omicron +
     π        \[*p]   u03C0 (u1D70B)   lowercase pi +
     ρ        \[*r]   u03C1 (u1D70C)   lowercase rho +
     σ        \[*s]   u03C3 (u1D70E)   lowercase sigma +
     τ        \[*t]   u03C4 (u1D70F)   lowercase tau +
     υ        \[*u]   u03C5 (u1D710)   lowercase upsilon +
     ϕ        \[*f]   u03D5 (u1D717)   lowercase phi +
     χ        \[*x]   u03C7 (u1D712)   lowercase chi +
     ψ        \[*q]   u03C8 (u1D713)   lowercase psi +
     ω        \[*w]   u03C9 (u1D714)   lowercase omega +

     ϵ        \[+e]   u03F5 (u1D716)   variant epsilon (lunate)
     ϑ        \[+h]   u03D1 (u1D717)   variant theta (cursive form)
     ϖ        \[+p]   u03D6 (u1D717)   variant pi (similar to omega)
     φ        \[+f]   u03C6 (u1D71B)   variant phi (curly shape)
     ς        \[ts]   u03C2 (u1D70D)   terminal lowercase sigma +

   [1mPlaying card symbols[0m
     Output   Input   Unicode   Notes
     ───────────────────────────────────────────────────────────────────────────
     ♣        \[CL]   u2663     solid club suit
     ♠        \[SP]   u2660     solid spade suit
     ♥        \[HE]   u2665     solid heart suit
     ♦        \[DI]   u2666     solid diamond suit

[1mHistory[0m
     A  consideration  of  the  typefaces originally available to AT&T [4mnroff[24m and
     [4mtroff[24m illuminates many conventions that one might regard  as  idiosyncratic
     fifty  years  afterward.   (See  section “History” of ]8;;man:roff(7)\[4mroff[24m(7)]8;;\ for more con‐
     text.)  The face used by the Teletype Model 37 terminals of the Murray Hill
     Unix Room was based on ASCII, but assigned  multiple  meanings  to  several
     code  points,  as  suggested  by that standard.  Decimal 34 ([1m"[22m) served as a
     dieresis accent and neutral double quotation mark; decimal  39  ([1m'[22m)  as  an
     acute  accent, apostrophe, and closing (right) single quotation mark; deci‐
     mal 45 ([1m-[22m) as a hyphen and a minus sign; decimal 94 ([1m^[22m) as a circumflex ac‐
     cent and caret; decimal 96 ([1m`[22m) as a grave accent and opening (left)  single
     quotation mark; and decimal 126 ([1m~[22m) as a tilde accent and (with a half‐line
     motion)  swung  dash.  The Model 37 bore an optional extended character set
     offering upright Greek letters and several mathematical symbols; these were
     documented as early as the [4mkbd[24m(VII) man page of the  (First  Edition)  [4mUnix[0m
     [4mProgrammer’s[24m [4mManual.[0m

     At  the  time  Graphic Systems delivered the C/A/T phototypesetter to AT&T,
     the ASCII character set was not considered a standard  basis  for  a  glyph
     repertoire  by traditional typographers.  In the stock Times roman, italic,
     and bold styles available, several ASCII characters  were  not  present  at
     all,  nor  was most of the Teletype’s extended character set.  AT&T commis‐
     sioned a “special” font to retain their accustomed repertoire.

     A representation of the coverage of the C/A/T’s text  fonts  follows.   The
     glyph  resembling  an  underscore is a baseline rule, and that resembling a
     vertical line is a box rule.  In italics, the box rule was not slanted.  We
     also observe that the hyphen and minus sign were  already  “de‐unified”  by
     the fonts provided; a decision whither to map an input “-” therefore had to
     be taken.

              ┌─────────────────────────────────────────────────────┐
              │ A B C D E F G H I J K L M N O P Q R S T U V W X Y Z │
              │ a b c d e f g h i j k l m n o p q r s t u v w x y z │
              │ 0 1 2 3 4 5 6 7 8 9 fi fl ffi ffl                   │
              │ ! $ % & ( ) ‘ ’ * + - . , / : ; = ? [ ] │           │
              │ • □ —— ‐ _ ¼ ½ ¾ ° † ′ ¢ ® ©                        │
              └─────────────────────────────────────────────────────┘

     The  special  font supplied the missing ASCII and Teletype extended glyphs,
     among several others.  The plus, minus, and equals signs  appeared  in  the
     special font despite availability in text fonts “to insulate the appearance
     of  equations  from  the choice of standard [read: text] fonts”——a priority
     since [4mtroff[24m was turned to the task of mathematical typesetting as  soon  as
     it was developed.

     We  note  that  AT&T  took the opportunity to de‐unify the apostrophe/right
     single quotation mark from the acute accent (a choice ISO later  duplicated
     in  its 8859 series of standards).  A slash intended to be mirror‐symmetric
     with the backslash was also included, as was the Bell System  logo;  we  do
     not attempt to depict the latter.

           ┌───────────────────────────────────────────────────────────┐
           │ [4mα[24m [4mβ[24m [4mγ[24m [4mδ[24m [4mε[24m [4mζ[24m [4mη[24m [4mθ[24m [4mι[24m [4mκ[24m [4mλ[24m [4mμ[24m [4mν[24m [4mξ[24m [4mο[24m [4mπ[24m [4mρ[24m [4mσ[24m [4mς[24m [4mτ[24m [4mυ[24m [4mϕ[24m [4mχ[24m [4mψ[24m [4mω[24m         │
           │ Γ Δ Θ Λ Ξ Π Σ Υ Φ Ψ Ω                                     │
           │ " ´ \ ^ _ ` ~ / < > { } # @ + − = ∗                       │
           │ ≥ ≤ ≡ ≈ ∼ ≠ ↑ ↓ ← → × ÷ ± ∞ ∂ ∇ ¬ ∫ ∝ √ ‾ ∪ ∩ ⊂ ⊃ ⊆ ⊇ ∅ ∈ │
           │ § ‡ ☜ ☞ | ○ ⎧ ⎩ ⎫ ⎭ ⎨ ⎬ ⎪ ⌊ ⌋ ⌈ ⌉                         │
           └───────────────────────────────────────────────────────────┘

     One  ASCII  character as rendered by the Model 37 was apparently abandoned.
     That device printed decimal 124 (|) as a broken vertical line, like Unicode
     U+00A6 (¦).  No equivalent was available on the C/A/T; the box rule  [1m\[br][22m,
     brace  vertical  extension [1m\[bv][22m, and “or” operator [1m\[or] [22mwere used as con‐
     textually appropriate.

     Devices supported by AT&T device‐independent [4mtroff[24m exhibited  some  differ‐
     ences  in  glyph detail.  For example, on the Autologic APS‐5 phototypeset‐
     ter, the square [1m\(sq [22mbecame filled in the Times bold face.

[1mFiles[0m
     The files below are loaded automatically by the default [4mtroffrc[24m.

     [4m/usr/share/groff/1.24.1/tmac/composite.tmac[0m
            assigns alternate mappings for identifiers after the first in a com‐
            posite special character escape sequence.  See subsection  “Accents”
            above.

     [4m/usr/share/groff/1.24.1/tmac/fallbacks.tmac[0m
            defines fallback mappings for Unicode code points such as the incre‐
            ment sign (U+2206) and upper‐ and lowercase Roman numerals.

[1mAuthors[0m
     This  document was written by ]8;;mailto:jjc@jclark.com\James Clark]8;;\, with additions by ]8;;mailto:wl@gnu.org\Werner Lemberg]8;;\
     and ]8;;mailto:groff-bernd.warken-72@web.de\Bernd Warken]8;;\, revised to use ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\ by ]8;;mailto:esr@thyrsus.com\Eric  S.  Raymond]8;;\,  and  largely
     rewritten by ]8;;mailto:g.branden.robinson@gmail.com\G. Branden Robinson]8;;\.

[1mSee also[0m
     [4mGroff:[24m  [4mThe[24m [4mGNU[24m [4mImplementation[24m [4mof[24m [4mtroff[24m, by Trent A. Fisher and Werner Lem‐
     berg, is the primary [4mgroff[24m manual.  Section “Using Symbols” may be of  par‐
     ticular  note.   You  can browse it interactively with “info '(groff) Using
     Symbols'”.

     “An extension to the [4mtroff[24m character set for Europe”, E.G. Keizer, K.J. Si‐
     monsen, J. Akkerhuis; EUUG Newsletter, Volume 9, No. 2, Summer 1989

     ]8;;http://www.unicode.org\The Unicode Standard]8;;\

     ]8;;https://www.aivosto.com/articles/charsets-7bit.html\“7‐bit Character Sets”]8;;\ by Tuomas Salste documents  the  inherent  ambiguity
     and configurable code points of the ASCII encoding standard.

     “Nroff/Troff User’s Manual” by Joseph F. Ossanna, 1976, AT&T Bell Laborato‐
     ries  Computing  Science  Technical Report No. 54, features two tables that
     throw light on the glyph repertoire available to “typesetter [4mroff[24m” when  it
     was first written.  Be careful of re‐typeset versions of this document that
     can  be found on the Internet.  Some do not accurately represent the origi‐
     nal document: several glyphs are obviously missing.  More subtly, lowercase
     Greek letters are rendered upright, not slanted as  they  appeared  in  the
     C/A/T’s special font and as expected by [4mtroff[24m users.

     ]8;;man:groff_rfc1345(7)\[4mgroff_rfc1345[24m(7)]8;;\  describes  an  alternative set of special character glyph
     names, which extends and in some cases  overrides  the  definitions  listed
     above.

     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\, ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\

groff 1.24.1                       2026‐03‐20                      [4mgroff_char[24m(7)
────────────────────────────────────────────────────────────────────────────────
[4mgroff_diff[24m(7)           Miscellaneous Information Manual           [4mgroff_diff[24m(7)

[1mName[0m
     groff_diff - differences between GNU [4mroff[24m and AT&T [4mtroff[0m

[1mDescription[0m
     The  GNU  [4mroff[24m text processing system, [4mgroff[24m, is a reimplementation and ex‐
     tension of AT&T [4mtroff[24m, the typesetting system originating in  Unix  systems
     of  the 1970s.  [4mgroff[24m removes many arbitrary limitations and adds features,
     both to the input language and to the page description language  output  by
     the  [4mtroff[24m  formatter.   We also note here differences arising from [4mgroff[24m’s
     implementation of AT&T [4mtroff[24m features.  The  following  discussion  assumes
     familiarity with those features; see ]8;;man:roff(7)\[4mroff[24m(7)]8;;\ for background.  GNU [4mtroff[24m can
     operate  in  a manner that increases support for documents written for AT&T
     [4mtroff[24m; see section “Compatibility mode” below.

[1mLanguage[0m
     GNU [4mtroff[24m features identifiers of arbitrary length; supports color  output,
     non‐integral type sizes, user‐defined characters, and automatic hyphenation
     in  languages  other  than English; adds more conditional expression opera‐
     tors; recognizes additional scaling units and arithmetic operators; enables
     general file I/O (in “unsafe mode” only); and exposes more formatter state.

   [1mLong names[0m
     GNU [4mtroff[24m introduces many new requests; with three exceptions ([1mcp[22m, [1mdo[22m, [1mrj[22m),
     they have names longer than two characters.  The names of registers, fonts,
     strings/macros/diversions,  environments,  special  characters,   character
     classes,  streams,  hyphenation  language  codes,  and colors can be of any
     length.  Anywhere AT&T [4mtroff[24m supports a parameterized escape sequence  that
     uses  an  opening  parenthesis  “(”  to introduce a two‐character argument,
     [4mgroff[24m supports a square‐bracketed form “[]” where the argument  within  can
     be of arbitrary length.

   [1mFont families, abstract styles, and translation[0m
     GNU [4mtroff[24m can group text typefaces into [4mfamilies.[24m  For example, [4mgroff[24m ships
     with  support for families containing each of the styles “[1mR[22m”, “[1mI[22m”, “[1mB[22m”, and
     “[1mBI[22m” (roman [upright], bold, italic [slanted], and bold‐italic).  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 combine with a style dynamically, producing a [4mre‐[0m
     [4msolved[24m [4mfont[24m [4mname.[24m  A document can [4mtranslate,[24m or remap, font names with  the
     [1mftr [22mrequest.

     Applying the requests [1mcs[22m, [1mbd[22m, [1mtkf[22m, [1muf[22m, or [1mfspecial [22mto an abstract style af‐
     fects  the  member  of the default family corresponding to that style.  The
     default family can be set with the [1mfam [22mrequest or [1m-f  [22mcommand‐line  option.
     The [1mstyles [22mdirective in the output device’s [4mDESC[24m file controls which mount‐
     ing positions (if any) are initially associated with abstract styles rather
     than fonts, and the [1msty [22mrequest can update this association.

   [1mColors[0m
     [4mgroff[24m  supports  color  output  with a variety of color spaces and up to 16
     bits per channel.  Some devices, particularly terminals, may be  more  lim‐
     ited.   When  color support is enabled, two colors are current at any given
     time: the [4mstroke[24m [4mcolor,[24m with which glyphs,  rules  (lines),  and  geometric
     figures  are drawn, and the [4mfill[24m [4mcolor,[24m which paints the interior of filled
     geometric figures.  The [1mcolor[22m, [1mdefcolor[22m, [1mgcolor[22m, and  [1mfcolor  [22mrequests;  [1m\m[0m
     and  [1m\M  [22mescape  sequences; and [1m.color[22m, [1m.m[22m, and [1m.M [22mregisters exercise color
     support.

   [1mHyphenation[0m
     GNU [4mtroff[24m uses a hyphenation algorithm and language‐specific pattern  files
     (based  on  TeX’s) to decide which words can be hyphenated and where.  AT&T
     [4mtroff[24m’s hyphenation system (“suftab”) was specific to English.

     New requests permit finer control over hyphenation breaking; hyphenation of
     a word might be suppressed due to a limit on consecutive  hyphenated  lines
     ([1mhlm[22m),  a  minimum line length threshold ([1mhym[22m), or because the line can in‐
     stead be adjusted with additional inter‐word space ([1mhys[22m).  The [1mhla  [22mrequest
     selects  a hyphenation language, whereas [1mhpf [22mand [1mhpfa [22mrespectively load and
     append to the language’s hyphenation patterns.  If no hyphenation  language
     is  set or no patterns are loaded, GNU [4mtroff[24m does not perform automatic hy‐
     phenation.

     For automatic hyphenation to work, the formatter must  know  which  letters
     are  equivalent.   For  example,  the letter “E” behaves like “e”; only the
     latter typically appears in hyphenation pattern files.  GNU  [4mtroff[24m  expects
     characters that participate in automatic hyphenation to be assigned [4mhyphen‐[0m
     [4mation[24m  [4mcodes[24m  that define these equivalence classes.  At startup, GNU [4mtroff[0m
     assigns hyphenation codes to the letters “a”–“z”, applies the same codes to
     “A”–“Z” in one‐to‐one correspondence, and assigns a code  of  zero  to  all
     other characters.

     The  [1mhcode  [22mrequest  enables application of hyphenation codes to characters
     outside the Unicode basic Latin set; without  doing  so,  words  containing
     such letters won’t hyphenate properly even if the corresponding hyphenation
     patterns  contain them.  Localization files for the input character set and
     language configure hyphenation codes; see ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\.

     GNU [4mtroff[24m’s [1m\: [22mescape sequence works like [1m\% [22mbut produces no hyphen if  the
     word breaks at that location.

   [1mFractional type sizes and new scaling units[0m
     When configuring the type size, AT&T [4mtroff[24m ignored scaling units and inter‐
     preted  all 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 [4mtroff[24m an output device can select a scaling factor that
     subdivides  a  point into “scaled points”.  A type size expressed in scaled
     points can thus represent a non‐integral size in points.

     A [4mscaled[24m [4mpoint,[24m scaling unit [1ms[22m, is equal to 1/[4msizescale[24m points,  where  the
     device  description  file, [4mDESC[24m, specifies [4msizescale[24m and otherwise defaults
     to 1; see ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.  GNU [4mtroff[24m also defines the  [4mtypographical[24m  [4mpoint,[0m
     scaling  unit [1mz[22m, which explicitly specifies a type size of potentially non‐
     integral measure.  The program multiplies typographical points by [4msizescale[0m
     and converts the value to an integer.  Arguments GNU [4mtroff[24m interprets in  [1mz[0m
     units  by  default comprise those to the escape sequences [1m\H [22mand [1m\s[22m, to the
     request [1mps[22m, the third argument to the [1mcs [22mrequest, and the second and fourth
     arguments to the [1mtkf [22mrequest.  In GNU [4mtroff[24m, the register  [1m\n[.s]  [22minterpo‐
     lates  the  type  size  in  typographical  points ([1mz[22m), whereas the register
     [1m\n[.ps] [22minterpolates it in scaled points ([1ms[22m).  “[1m\n[.ps]s[22m”,  “[1m\n[.s]z[22m”,  and
     “[1m1m[22m” are co‐equal by definition.

     For example, if [4msizescale[24m is 1000, then a scaled point is one thousandth of
     a point.  Consequently, “[1m.ps 10.5[22m” is synonymous with “[1m.ps 10.5z[22m”; both set
     the type size to 10,500 scaled points or 10.5 typographical points.

     It makes no sense to use the “[1mz[22m” scaling unit in a numeric expression whose
     default  scaling  unit is neither “[1mu[22m” nor “[1mz[22m”, so GNU [4mtroff[24m disallows this.
     Similarly, it is nonsensical to use scaling units other than “[1mp[22m”, “[1ms[22m”, “[1mz[22m”,
     or “[1mu[22m”, in a numeric expression whose default scaling unit is “[1mz[22m”,  and  so
     GNU [4mtroff[24m disallows those as well.

     Output  devices  may  be limited in the type sizes they can employ.  The [1m.s[0m
     and [1m.ps [22mregisters represent the type size selected by the formatter  as  it
     understands  a  device’s  capability.   the  read‐only  registers  [1m.psr [22mand
     (string‐valued) [1m.sr [22minterpolate the last [4mrequested[24m in scaled points and  in
     points  as  a  decimal fraction, respectively.  Like the actual current and
     previous type size, the requested ones are properties of an environment.

     For example, if a document requests a type size of 10.95  points,  and  the
     nearest size permitted by a [1msizes [22mrequest (or by the [1msizes [22mor [1msizescale [22mdi‐
     rectives  in  the  device’s  [4mDESC[24m file) is 11 points, [4mgroff[24m uses the latter
     value.

     A further two new measurement units available in [4mgroff[24m are “[1mM[22m”, which indi‐
     cates hundredths of an em, and “[1mf[22m”, which multiplies by 65,536.  The latter
     provides convenient fractions for color definitions with the  [1mdefcolor  [22mre‐
     quest.  For example, 0.5f equals 32768u.

   [1mSpecial fonts[0m
     GNU [4mtroff[24m’s “[1mspecial[22m” and [1mfspecial [22mrequests permit a document to supplement
     the  set  of fonts the device configures for glyph search without having to
     use the [1mfp [22mrequest to manipulate the list of mounting positions, which  can
     be tedious——by default, GNU [4mtroff[24m mounts 40 fonts at startup when using the
     [1mps [22mdevice.

   [1mNumeric expressions[0m
     GNU  [4mtroff[24m  permits  spaces in a numeric expression within parentheses, and
     offers three new operators.

     [4me1[24m[1m>?[4m[22me2[24m  Interpolate the greater of expressions [4me1[24m and [4me2[24m.

     [4me1[24m[1m<?[4m[22me2[24m  Interpolate the lesser of expressions [4me1[24m and [4me2[24m.

     [1m([4m[22mc[24m[1m;[4m[22me[24m[1m)   [22mInterpolate expression [4me[24m using [4mc[24m as the default scaling  unit,  ig‐
             noring scaling units in [4me[24m if [4mc[24m is empty.

     Arithmetic in GNU [4mtroff[24m saturates instead of wrapping.

   [1mConditional expressions[0m
     More conditions can be tested with the “[1mif[22m” and [1mie [22mrequests, as well as the
     new “[1mwhile[22m” request.

     [1mc [4m[22mchr[24m  True  if  a character [4mchr[24m is available; [4mchr[24m is an ordinary, special,
            or indexed character, whether defined by a font description file  or
            a request.

     [1md [4m[22mnam[24m  True if a string, macro, diversion, or request [4mnam[24m is defined.

     [1mF [4m[22mfnt[24m  True  if  a font [4mfnt[24m is available; [4mfnt[24m can be an abstract style or a
            font name.  [4mfnt[24m is handled as if it were an argument to the  [1mft  [22mre‐
            quest  (that  is,  the  default  family is combined with an abstract
            style and font translation is applied), but [4mfnt[24m cannot be a mounting
            position, and no font is mounted.

     [1mm [4m[22mcol[24m  True if a color [4mcol[24m is defined.

     [1mr [4m[22mreg[24m  True if a register [4mreg[24m is defined.

     [1mS [4m[22msty[24m  True if an abstract style [4msty[24m is registered.  Font translations  ap‐
            ply.

     [1mv      [22mAlways  false.  This condition exists for compatibility with certain
            other [4mtroff[24m implementations.  (We refer to [4mvtroff[24m, a translator that
            converted the C/A/T command stream produced  by  early‐vintage  AT&T
            [4mtroff[24m to a form suitable for Versatec and Benson‐Varian plotters.)

   [1mDrawing commands[0m
     GNU  [4mtroff[24m  extends  the [1m\D [22mescape sequence with 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 command.  A filled
     figure is smaller than a stroked one using the same parameters because  the
     former  is  drawn only within its defined area, whereas strokes have a line
     thickness, set with another new drawing command.

   [1mNotational conventions[0m
     In the request and escape sequence descriptions below, GNU [4mtroff[24m reads  ar‐
     guments  named  [4mcharacter‐sequence,[24m [4mcommand,[24m [4mcontents,[24m [4mfile,[24m and [4mmessage[24m in
     copy mode until the end of the input line.  A [4mcharacter‐sequence[24m  comprises
     one or more ordinary, special, or indexed characters; spaces; or escape se‐
     quences  that  interpolate only these.  We name the remaining arguments for
     clarity; they are also [4mcharacter‐sequences.[24m  A neutral double quote ‘[1m"[22m’ can
     optionally prefix a  [4mcharacter‐sequence;[24m  the  formatter  discards  one  if
     present, permitting initial embedded spaces in the argument.

     [4minput[24m  refers  to  arbitrary character sequences (up to a newline or delim‐
     iter) that GNU [4mtroff[24m fully interprets, in contrast to copy mode.

   [1mEscape sequences[0m
     [4mgroff[24m introduces several new escape sequences, extends the  syntax  of  the
     AT&T  [4mtroff[24m escape sequences [1m\D[22m, [1m\f[22m, [1m\k[22m, [1m\n[22m, [1m\s[22m, [1m\$[22m, and [1m\*[22m, and alters the
     behavior of [1m\X[22m.  The following list collates  escape  sequences  alphabeti‐
     cally  at  first,  and  then by symbol roughly in Unicode code point order.
     Neutral apostrophes [1m' [22millustrate escape sequences  with  a  user‐selectable
     delimiter.   Many  others are available; see subsection “Miscellaneous” and
     section “Compatibility Mode” below.

     [1m\A'[4m[22minput[24m[1m'[0m
               Interpolate 1 if [4minput[24m is a valid identifier,  and  0  otherwise.
               Because  GNU  [4mtroff[24m  ignores  any input character with an invalid
               code when reading it, invalid identifiers are  empty  or  contain
               spaces,  tabs,  newlines,  or  escape  sequences that interpolate
               something other than a sequence of ordinary characters.  You  can
               employ  [1m\A  [22mto  validate a macro argument before using it to con‐
               struct another escape sequence or identifier.

     [1m\B'[4m[22minput[24m[1m'[0m
               Interpolate 1 if [4minput[24m is a valid numeric expression, and 0  oth‐
               erwise.   You  might use [1m\B [22malong with the “[1mif[22m” request to filter
               out invalid macro arguments.

     [1m\D'C [4m[22md[24m[1m'   [22mDraw filled circle of diameter [4md[24m with its leftmost point  at  the
               drawing position.

     [1m\D'E [4m[22mh[24m [4mv[24m[1m'[0m
               Draw  filled  ellipse  of axis lengths [4mh[24m and [4mv[24m, with its leftmost
               point at the drawing position.

     [1m\D'p [4m[22mh1[24m [4mv1[24m ... [4mhn[24m [4mvn[24m[1m'[0m
               Draw polygon with vertices at the drawing position and each point
               in sequence.  GNU [4mtroff[24m closes the polygon by drawing a line from
               ([4mhn[24m, [4mvn[24m) back to the initial drawing position; DWB  and  Heirloom
               [4mtroff[24ms  do  not.   Afterward,  the  drawing  position  is left at
               ([4mhn[24m, [4mvn[24m).

     [1m\D'P [4m[22mh1[24m [4mv1[24m ... [4mhn[24m [4mvn[24m[1m'[0m
               As [1m\D'p'[22m, but the polygon is filled.  [4mgroff[24m does not specify  how
               the  output  device  must fill concave or self‐intersecting poly‐
               gons.

     [1m\D't [4m[22mn[24m[1m'   [22mSet line thickness of geometric objects to [4mn[24m basic units.  A zero
               [4mn[24m selects the minimum supported thickness.  A negative [4mn[24m (the de‐
               fault) selects a thickness proportional to the type size.

     [1m\E        [22mEmbed an escape character that is not interpreted  in  copy  mode
               (compare  with [1m\a [22mand [1m\t[22m).  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 that  will  be
               interpolated at varying macro nesting depths.

     [1m\f[[4m[22mfnt[24m[1m]   [22mSelect  typeface  [4mfnt[24m, which may be a mounting position, abstract
               style, or font name.  [1m\f[][22m, [1m\f[P][22m, and [1m\fP [22mare synonyms; we  rec‐
               ommend the first.

     [1m\F[4m[22mf[0m
     [1m\F([4m[22mfm[0m
     [1m\F[[4m[22mfml[24m[1m]   [22mSelect  default font family.  [1m\F[] [22mmakes the previous font family
               the default.  [1m\FP [22mis unlike [1m\fP[22m; it selects font  family  “P”  as
               the default.  See the [1mfam [22mrequest below.

     [1m\k([4m[22mrg[0m
     [1m\k[[4m[22mreg[24m[1m]   [22mStore  the  horizontal  drawing position, relative to that corre‐
               sponding to the start of the input line (ignoring page offset and
               indentation), in two‐character register name [4mrg[24m or arbitrary reg‐
               ister name [4mreg[24m.

     [1m\m[4m[22mc[0m
     [1m\m([4m[22mcl[0m
     [1m\m[[4m[22mcol[24m[1m]   [22mSet stroke color to  [4mcol[24m.   [1m\m[]  [22mrestores  the  previous  stroke
               color, or the default if there is none.

     [1m\M[4m[22mc[0m
     [1m\M([4m[22mcl[0m
     [1m\M[[4m[22mcol[24m[1m]   [22mSet fill color to [4mcol[24m.  [1m\M[] [22mrestores the previous fill color, or
               the default if there is none.

     [1m\n[[4m[22mreg[24m[1m]   [22mInterpolate register [4mreg[24m.

     [1m\O[4m[22mn[0m
     [1m\O[[4m[22mn[24m[1m]     [22mSuppress  [4mtroff[24m  output of glyphs and geometric objects.  The se‐
               quences [1m\O2[22m, [1m\O3[22m, [1m\O4[22m, and [1m\O5 [22mare intended for internal  use  by
               ]8;;man:grohtml(1)\[4mgrohtml[24m(1)]8;;\.

               [1m\O0[0m
               [1m\O1    [22mDisable  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 [1m\O3 [22mand [1m\O4[22m).  Horizontal  motions  corresponding  to
                      non‐overstruck  glyph widths still occur.  These sequences
                      also reset the registers [1mopminx[22m, [1mopminy[22m, [1mopmaxx[22m,  and  [1mop‐[0m
                      [1mmaxy  [22mto  -1.   These four registers mark the top left and
                      bottom right hand corners of a box encompassing all  writ‐
                      ten or drawn output.

               [1m\O2    [22mAt  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 afore‐
                      mentioned  registers encompassing glyphs written since the
                      last interpolation of a [1m\O [22msequence, 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.

               [1m\O3[0m
               [1m\O4    [22mBegin  and  end  a nested suppression level, respectively.
                      [4mgrohtml[24m uses this mechanism to  create  images  of  output
                      preprocessed with [4mpic[24m, [4meqn[24m, and [4mtbl[24m.  At startup, [4mtroff[24m is
                      at the outermost suppression level.  [4mpre-grohtml[24m generates
                      these  sequences when processing the document, using [4mtroff[0m
                      with the [1mps [22moutput device, Ghostscript, and the PNM  tools
                      to  produce images in PNG format.  These sequences start a
                      new page if the device is not [1mhtml [22mor [1mxhtml[22m, to reduce the
                      number of images crossing a page boundary.

               [1m\O5[[4m[22mPfile[24m[1m][0m
                      At the outermost suppression level, write the name [4mfile[24m to
                      the standard error stream at position [4mP[24m, which must be one
                      of [1ml[22m, [1mr[22m, [1mc[22m, or [1mi[22m, corresponding to left, right,  centered,
                      and  inline  alignments within the document, respectively.
                      [4mfile[24m is a name associated with the production of the  next
                      image.

     [1m\R'[4m[22mname[24m [4m±n[24m[1m'[0m
               Synonymous with “[1m.nr [4m[22mname[24m [4m±n[24m”.

     [1m\s[0][0m
     [1m\s'0'     [22mRestore the previous type size; no operation if there is none.

     [1m\s[[4m[22m±n[24m[1m][0m
     [1m\s[4m[22m±[24m[1m[[4m[22mn[24m[1m][0m
     [1m\s'[4m[22m±n[24m[1m'[0m
     [1m\s[4m[22m±[24m[1m'[4m[22mn[24m[1m'    [22mSet  the  type  size to, or increment or decrement it by, [4mn[24m typo‐
               graphical points.

     [1m\V[4m[22me[0m
     [1m\V([4m[22mev[0m
     [1m\V[[4m[22menv[24m[1m]   [22mInterpolate contents of the system environment variable [4menv[24m (one‐
               character  name  [4me[24m,  two‐character  name  [4mev)[24m  as   returned   by
               ]8;;man:getenv(3)\[4mgetenv[24m(3)]8;;\.  [1m\V [22mis interpreted even in copy mode.

     [1m\X'[4m[22mcharacter‐sequence[24m[1m'[0m
               Unlike  AT&T [4mtroff[24m, GNU [4mtroff[24m performs some limited processing of
               the sequence of  ordinary  characters,  special  characters,  and
               spaces in [4mcharacter‐sequence[24m.

               The formatter’s special character repertoire is unknown to output
               drivers  outside  of  glyphs  named in a device’s fonts, and even
               then they may not possess complete coverage of  the  names  docu‐
               mented  in ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\.  Further, escape sequences that produce
               horizontal or vertical motions, hyphenation breaks, or  that  are
               dummy  characters may appear in strings or be converted to nodes,
               particularly in diversions.  When they occur in a  device  exten‐
               sion  command,  they  produce warnings in category “[1mchar[22m”.  These
               are not representable when interpolated directly into  device‐in‐
               dependent output, as might be done when writing out tag names for
               PDF  bookmarks,  which  can appear in a viewer’s navigation pane.
               This is also the case for a small number of  special  characters,
               such as [1m\[ru][22m, the baseline rule, that lack a Unicode definition.

               So  that  any Unicode code point can be represented in device ex‐
               tension commands, for example in an  author’s  name  in  document
               metadata or as a usefully named bookmark or hyperlink anchor, GNU
               [4mtroff[24m transforms its argument to represent characters outside the
               Unicode  Basic  Latin  range  as Unicode code points expressed in
               [4mgroff[24m’s notation for these, “[1m\[u[4m[22mXXXX[24m[1m][22m”; see  ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\.   For
               these  transformations,  the formatter ignores character transla‐
               tions and definitions.

               GNU [4mtroff[24m converts several ordinary characters  that  typeset  as
               non‐basic  Latin code points to code points outside that range so
               that they are used consistently whether  they  are  formatted  as
               glyphs or used in a device extension command argument.  These or‐
               dinary  characters  are  “[1m'[22m”,  “[1m-[22m”, “[1m^[22m”, “[1m`[22m”, and “[1m~[22m”; others are
               written as‐is.  Thus, “[1m'[22m” transforms to “[1m\[u2019][22m”.

               Contrariwise, GNU [4mtroff[24m translates special characters that  type‐
               set  as  Unicode basic Latin characters to basic Latin characters
               accordingly.  Thus, “[1m\[ga][22m” transforms to “[1m`[22m”,  “[1m\[Do][22m”  to  “[1m$[22m”,
               and so on.

     [1m\Y[4m[22mm[0m
     [1m\Y([4m[22mma[0m
     [1m\Y[[4m[22mmac[24m[1m]   [22mInterpolate  a macro or string as a device extension command.  As
               [1m\X'\*[[4m[22mmac[24m[1m]'[22m, except that GNU [4mtroff[24m does not  interpret  the  con‐
               tents  of  [4mmac[24m; further, [4mmac[24m can be a macro and thus contain new‐
               lines, unlike the argument to [1m\X .  [22mThis  inclusion  of  newlines
               requires  an  extension to the AT&T [4mtroff[24m device‐independent page
               description language, and their presence confuses drivers that do
               not know about it (see subsection “Device  control  commands”  of
               ]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\).

     [1m\Z'[4m[22minput[24m[1m'[0m
               Save  the  drawing  position, format [4minput[24m, then restore it.  GNU
               [4mtroff[24m ignores tabs and leaders in [4minput[24m with an error diagnostic.

     [1m\#        [22mRead everything up to and including the next newline in copy mode
               and discard it.  [1m\# [22mis like [1m\"[22m, except that [1m\" [22mdoes 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.

     [1m\$0       [22mInterpolate the name by which the  macro  being  interpreted  was
               called.  In GNU [4mtroff[24m this name can vary; see the [1mals [22mrequest.

     [1m\$([4m[22mnn[0m
     [1m\$[[4m[22mnnn[24m[1m]   [22mIn  a  macro  or string definition, interpolate the [4mnn[24mth or [4mnnn[24mth
               argument.  In GNU [4mtroff[24m, macros and strings can have an unlimited
               number of arguments.

     [1m\$*       [22mIn a macro or string definition, interpolate  the  catenation  of
               all arguments, separated by spaces.

     [1m\$@       [22mIn  a  macro  or string definition, interpolate the catenation of
               all arguments, with each surrounded by double  quotes  and  sepa‐
               rated by spaces.

     [1m\$^       [22mIn  a  macro  or string definition, interpolate the catenation of
               all arguments constructed in a form suitable for passage  to  the
               [1mds [22mrequest.

     [1m\)        [22mInterpolate a [4mtransparent[24m dummy character——one that is ignored by
               end‐of‐sentence  detection.   It behaves as [1m\&[22m, except that [1m\& [22mis
               treated as letters and numerals normally are after “.”, “?”,  and
               “!”; [1m\& [22mcancels end‐of‐sentence detection, and [1m\) [22mdoes not.

     [1m\*[[4m[22mstring[24m [[4marg[24m ...][1m][0m
               Interpolate [4mstring,[24m passing it [4marg[24m ... as arguments.

     [1m\/        [22mApply  an  [4mitalic[24m [4mcorrection[24m: 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 of the right parenthesis, which is ugly.   Inserting  [1m\/  [22mbe‐
               tween  them  avoids  this  problem.  Consider using [1m\/ [22mwhenever a
               slanted glyph is immediately followed by an upright glyph without
               any intervening space.

     [1m\,        [22mApply a [4mleft[24m [4mitalic[24m [4mcorrection[24m: modify the spacing of the follow‐
               ing 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 [1m\,[0m
               between them avoids this problem.  Consider using [1m\, [22mwhenever  an
               upright  glyph is followed immediately by a slanted glyph without
               any intervening space.

     [1m\:        [22mInsert 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 “[1m\%[22m”).   The  remainder  of  the
               word is subject to hyphenation as normal.

     [1m\?[4m[22mcharacter‐sequence[24m[1m\?[0m
               Suppress  formatting of [4mcharacter‐sequence.[24m  This feature has two
               applications.

               Surround operands to the output comparison operator  with  [1m\?  [22mto
               compare them by character rather than as formatted output.  Since
               GNU  [4mtroff[24m  reads comparands protected with [1m\? [22min copy mode, they
               need not even be valid [4mgroff[24m syntax.   The  escape  character  is
               still  lexically recognized, however, and consumes the next char‐
               acter.

               When used in a diversion, [1m\? [22mtransparently embeds input, read  in
               copy  mode, until its own next occurrence on the input line.  Use
               [1m\! [22mif you want to embed newlines in a diversion.  Unlike  [1m\![22m,  [1m\?[0m
               is interpreted even in copy mode, and a [4mcharacter‐sequence[24m in the
               top‐level diversion is not sent to device‐independent output.

     [1m\[[4m[22mchar[24m[1m]   [22mTypeset the special character [4mchar[24m.  See ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\.

     [1m\[[4m[22mbase‐char[24m [4mcombining‐component[24m ...[1m][0m
               Typeset  a  composite glyph consisting of [4mbase‐char[24m overlaid with
               one or more [4mcombining‐component[24ms.  For example, “[1m\[A  ho][22m”  is  a
               capital  letter  “A”  with  a  “hook  accent”  (ogonek).  See the
               [1mcomposite [22mrequest below; [4mGroff:[24m [4mThe[24m [4mGNU[24m [4mImplementation[24m [4mof[24m  [4mtroff[24m,
               the  [4mgroff[24m  Texinfo  manual,  for details of composite glyph name
               construction; and ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\ for a list of components used  in
               composite glyph names.

     [1m\~        [22mInsert  an  adjustable,  unbreakable  space.   As  with  ordinary
               spaces, GNU [4mtroff[24m discards any sequence of these at the end of an
               output line if a break occurs.

   [1mRestricted requests[0m
     To mitigate risks from untrusted input documents, GNU  [4mtroff[24m  disables  the
     [1mcf[22m,  [1mpi[22m,  and [1msy [22mrequests by default.  Its [1m-U [22moption enables “unsafe mode”,
     restoring their function (and enabling additional [4mgroff[24m extension requests,
     “[1mopen[22m”, [1mopena[22m, and [1mpso[22m).

   [1mAltered requests[0m
     [1m.bd [4m[22mspecial‐font[24m [4mfont[0m
            Stop emboldening [4mspecial‐font[24m when [4mfont[24m is  selected.   [4mspecial‐font[0m
            must be a font name, not a mounting position.

     [1m.cf [22m[[1m"[22m][4mfile[0m
            Break  and  copy the contents of [4mfile[24m as “throughput” to GNU [4mtroff[24m’s
            output.  If a diversion is in use, GNU [4mtroff[24m performs the copy  only
            when  the diversion is emitted.  In AT&T [4mtroff[24m, the contents of [4mfile[0m
            are immediately copied to the output regardless of whether a  diver‐
            sion is being written to; this behavior is so anomalous that it must
            be considered a bug.

            GNU  [4mtroff[24m removes a leading neutral double quote ‘[1m"[22m’ from the argu‐
            ment, permitting initial embedded spaces in it, and reads it to  the
            end  of  the  input line in copy mode.  If [4mfile[24m does not exist or is
            not readable, a warning in category “[1mfile[22m” is emitted  and  the  re‐
            quest has no other effect.

     [1m.de [4m[22mname[24m [[4mend‐name[24m]
     [1m.am [4m[22mname[24m [[4mend‐name[24m]
     [1m.ds [4m[22mname[24m [[[1m"[22m][4mcontents[24m]
     [1m.as [4m[22mname[24m [[[1m"[22m][4mcontents[24m]
            In  compatibility  mode, these requests behave as [1mde1[22m, [1mam1[22m, [1mds1[22m, and
            [1mas1[22m, respectively: GNU [4mtroff[24m inserts a [4mcompatibility[24m [4msave[24m  token  at
            the beginning of the macro, string, or appendment thereto as applic‐
            able and a [4mcompatibility[24m [4mrestore[24m token at its end, enabling compati‐
            bility  mode  during  its interpolation.  Thus they work as expected
            even if the interpolation context disables compatibility mode.

     [1m.hy [4m[22mn[24m  New values 16 and 32 are available; the former  enables  hyphenation
            before  the last character in a word, and the latter enables hyphen‐
            ation after the first character in a word.  If  invoked  without  an
            argument, the mode configured by the [1mhydefault [22mrequest is selected.

     [1m.lf [4m[22minput‐line‐number[24m [[[1m"[22m][4mfile‐identifier[24m]
            In GNU [4mtroff[24m the first argument becomes the input line number of the
            [4mnext[24m  line  the  formatter reads.  It also removes a leading neutral
            double quote ‘[1m"[22m’ from [4mfile‐identifier,[24m permitting  initial  embedded
            spaces  in  it,  and  reads  it to the end of the input line in copy
            mode.

     [1m.nx [22m[[[1m"[22m][4mfile[24m]
            GNU [4mtroff[24m removes a leading neutral double quote ‘[1m"[22m’ from [4mfile[24m, per‐
            mitting initial embedded spaces in it, and reads it to  the  end  of
            the input line in copy mode.

     [1m.pi [22m[[1m"[22m][4mcommand[0m
            GNU  [4mtroff[24m  strips a leading neutral double quote from the argument,
            permitting initial embedded spaces in it.

     [1m.pm [4m[22mname[24m ...
            GNU [4mtroff[24m reports, to the standard error  stream,  the  JSON‐encoded
            name and contents of each macro, string, or diversion [4mname[24m.

     [1m.so [22m[[1m"[22m][4mfile[0m
            GNU [4mtroff[24m removes a leading neutral double quote ‘[1m"[22m’ from [4mfile[24m, per‐
            mitting  initial  embedded  spaces in it, and reads it to the end of
            the input line in copy mode.  GNU [4mtroff[24m searches for [4mfile[24m in any di‐
            rectories specified by [1m-I [22mcommand‐line options, followed by the cur‐
            rent working directory.  If [4mfile[24m does not exist or is not  readable,
            GNU [4mtroff[24m emits a warning in category “[1mfile[22m”.

     [1m.ss [4m[22mword‐space‐size[24m [[4madditional‐sentence‐space‐size[24m]
            A  second  argument  sets  the amount of additional space separating
            sentences on the same output line.  If omitted, this amount  is  set
            to  [4mword‐space‐size[24m.   Both  arguments  are  in  twelfths of current
            font’s space width (typically one‐fourth to one‐third em for Western
            scripts; see ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\).  The default for both parameters is 12.
            Negative values are erroneous.

     [1m.sy [22m[[1m"[22m][4mcommand[0m
            GNU [4mtroff[24m strips a leading neutral double quote from  the  argument,
            permitting initial embedded spaces in it.

     [1m.ta [22m[[[4mn1[24m [4mn2[24m ... [4mnn[24m ][1mT [4m[22mr1[24m [4mr2[24m ... [4mrn[24m]
            GNU [4mtroff[24m supports an extended syntax to specify repeating tab stops
            after  the “[1mT[22m” mark.  These values are always taken as relative dis‐
            tances from the previous tab stop.  This is  the  idiomatic  way  to
            specify  tab stops at equal intervals in [4mgroff[24m.  GNU [4mtroff[24m’s startup
            value is “[1mT 0.5i[22m”.

            The syntax summary above instructs [4mgroff[24m to set  tabs  at  positions
            [4mn1[24m, [4mn2[24m, ..., [4mnn[24m, then at [4mnn[24m+[4mr1[24m, [4mnn[24m+[4mr2[24m, ..., [4mnn[24m+[4mrn[24m, then at [4mnn[24m+[4mrn[24m+[4mr1[24m,
            [4mnn[24m+[4mrn[24m+[4mr2[24m, ..., [4mnn[24m+[4mrn[24m+[4mrn[24m, and so on.

   [1mNew requests[0m
     Several GNU [4mtroff[24m requests work like AT&T [4mtroff[24m’s “[1mas[22m” and [1mds [22mrequests, ac‐
     cepting  an optional leading neutral double quote, notated ‘[[1m"[22m]’, in an ar‐
     gument that the formatter reads in copy mode to the end of the input  line,
     permitting inclusion of leading spaces.

     [1m.aln [4m[22mnew‐register[24m [4mexisting‐register[0m
             Create  alias  (additional name) [4mnew‐register[24m of [4mexisting‐register[24m,
             causing the names to refer to the same stored object.  If [4mexisting‐[0m
             [4mregister[24m is undefined, the  formatter  ignores  the  request.   GNU
             [4mtroff[24m produces a warning in category “[1mreg[22m”.  See section “Warnings”
             of  ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\  regarding the enablement and suppression of warnings.
             To remove a register alias, invoke [1mrr [22mon its  name.   A  register’s
             contents do not become inaccessible until it has no more names.

     [1m.als [4m[22mnew‐name[24m [4mexisting‐name[0m
             Create  alias (additional name) [4mnew‐name[24m of request, string, macro,
             or diversion [4mexisting‐name[24m, causing the names to refer to the  same
             stored  object.   If  [4mexisting‐name[24m is undefined, the formatter ig‐
             nores the request.  GNU [4mtroff[24m produces a warning in category “[1mmac[22m”.
             If [4mnew‐name[24m already exists, its contents are  lost  unless  already
             aliased.   See section “Warnings” of ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ regarding the enable‐
             ment and suppression of warnings.  To remove an alias, invoke [1mrm [22mon
             its name.  The object itself is not destroyed until it has no  more
             names.

             When  a  request, macro, string, or diversion is aliased, redefini‐
             tions and appendments “write through” alias names.  To  replace  an
             alias with a separately defined object, remove its name first.

     [1m.am1 [4m[22mname[24m [[4mend‐name[24m]
             As “[1mam[22m”, but GNU [4mtroff[24m disables compatibility mode while interpret‐
             ing  the  appendment to [4mname:[24m it inserts a [4mcompatibility[24m [4msave[24m token
             at the beginning of the appendment, and a [4mcompatibility[24m [4mrestore[24m to‐
             ken at its end.  The requests “[1mam[22m”, [1mam1[22m, [1mde[22m, and [1mde1  [22mcan  thus  be
             intermixed  freely  since the compatibility save/restore tokens af‐
             fect only the parts of the macro populated by [1mam1 [22mand [1mde1[22m.

     [1m.ami [4m[22mname[24m [[4mend‐name[24m]
             Append to macro indirectly.  See [1mdei [22mbelow.

     [1m.ami1 [4m[22mname[24m [[4mend‐name[24m]
             As [1mami[22m, but GNU [4mtroff[24m disables compatibility mode while  interpret‐
             ing  the  appendment  to  the macro named by the contents of string
             [4mname;[24m see [1mam1 [22mabove.

     [1m.as1 [4m[22mname[24m [[[1m"[22m][4mcontents[24m]
             As “[1mas[22m”, but GNU [4mtroff[24m disables compatibility mode while interpret‐
             ing the appendment to the string [4mname:[24m it inserts  a  [4mcompatibility[0m
             [4msave[24m  token at the beginning of the appendment, and a [4mcompatibility[0m
             [4mrestore[24m token at its end.  The requests “[1mas[22m”, [1mas1[22m, [1mds[22m, and [1mds1  [22mcan
             thus  be intermixed freely since the compatibility save/restore to‐
             kens affect only the portions of the string populated  by  [1mas1  [22mand
             [1mds1[22m.

     [1m.asciify [4m[22mdiv[0m
             [4mUnformat[24m  the  diversion [4mdiv[24m in a way such that Unicode basic Latin
             (US‐ASCII) characters, characters translated with the [1mtrin [22mrequest,
             space characters, and some escape sequences that were formatted  in
             the  diversion  [4mdiv[24m are treated like ordinary input characters when
             [4mdiv[24m is interpolated.  Doing so can be useful  in  conjunction  with
             the [1mwritem [22mrequest.

             When transforming a glyph node back into an input sequence that de‐
             mands  expression as a special character escape sequence, GNU [4mtroff[0m
             uses the default escape character.

             [1masciify [22mcannot return all nodes in  a  diversion  to  their  source
             equivalents:  those  produced by indexed characters ([1m\N[22m), for exam‐
             ple, remain nodes, so the result cannot be guaranteed to be a char‐
             acter sequence as a macro or string is.  Give the diversion name as
             an argument to the [1mpm [22mrequest to  inspect  its  contents  and  node
             list.  Glyph parameters such as the type face and size are not pre‐
             served; use “[1munformat[22m” to achieve that.

     [1m.backtrace[0m
             Write  backtrace  of input stack to the standard error stream.  See
             the [1m-b [22moption of ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\.

     [1m.blm [22m[[4mname[24m]
             Set a blank line macro (trap).  If a blank line macro is  thus  de‐
             fined,  [4mgroff[24m executes [4mname[24m when a blank line is encountered in the
             input, 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‐)es‐
             tablished.

     [1m.box [22m[[4mname[24m]
     [1m.boxa [22m[[4mname[24m]
             Divert  (or  append) output to [4mname,[24m similarly to the [1mdi [22mand [1mda [22mre‐
             quests, respectively.  Any pending output line is [4mnot[24m  included  in
             the  diversion.   Without  an  argument, stop diverting output; any
             pending output line inside the diversion is discarded.

     [1m.break  [22mExit a “[1mwhile[22m” loop.  Do not confuse this request with a typograph‐
             ical break or the [1mbr [22mrequest.  See “[1mcontinue[22m”.

     [1m.brp    [22mBreak and force adjustment of the output line per the  current  ad‐
             justment  mode.   Like  [1mbr[22m, it does nothing if invoked with the no‐
             break control character.

     [1m.cflags [4m[22mn[24m [4mc[24m...
             Assign properties encoded by non‐negative integer [4mn[24m to each charac‐
             ter or class [4mc[24m.  Spaces need not separate [4mc[24m arguments.

             [4mn[24m is the sum of any of the following.  Some combinations  are  non‐
             sensical, such as “[1m33[22m” (1 + 32).

             1      Recognize  the character as ending a sentence if followed by
                    a newline or two spaces.  Initially, characters  “[1m.?![22m”  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
                    “[1m-\[hy]\[em][22m” have this property.

             8      Mark the glyph associated with this character as overlapping
                    other instances of itself horizontally.  Initially,  charac‐
                    ters  “[1m\[ul]\[rn]\[ru]\[radicalex]\[sqrtex][22m” have this prop‐
                    erty.

             16     Mark the glyph associated with this character as overlapping
                    other instances of itself vertically.  Initially, the  char‐
                    acter “[1m\[br][22m” 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
                    “[1m'")]*\[dg]\[dd]\[rq]\[cq][22m” have this property.

             64     Ignore hyphenation codes of the surrounding characters.  Use
                    this value in combination with values 2 and  4.   Initially,
                    no characters have this property.

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

             128    Prohibit a break before the character, but allow a break af‐
                    ter the character.  This works only in combination with val‐
                    ues  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  be‐
                    fore  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  ef‐
                    fect  otherwise.   Initially,  no characters have this prop‐
                    erty.

             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.

     [1m.char [4m[22mc[24m [[[1m"[22m][4mcontents[24m]
             Define an ordinary, special, or indexed character  [4mc[24m  as  [4mcontents.[0m
             Omitting [4mcontents[24m gives [4mc[24m an empty definition.

             Defining  (or  redefining) a character [4mc[24m creates a formatter object
             that GNU [4mtroff[24m recognizes like any other ordinary, special, or  in‐
             dexed  character  on  input, and produces [4mcontents[24m on output.  When
             formatting [4mc[24m, GNU [4mtroff[24m processes [4mcontents[24m in a temporary  environ‐
             ment  and encapsulates the result in a node (see section “GNU troff
             Internals” in [4mGroff:[24m [4mThe[24m [4mGNU[24m [4mImplementation[24m  [4mof[24m  [4mtroff[24m,  the  [4mgroff[0m
             Texinfo  manual);  disabling compatibility mode and setting the es‐
             cape character to to [1m\ [22mwhile interpreting [4mcontents.[24m  Any  embolden‐
             ing,  constant  spacing,  or  track  kerning applies to this object
             rather than to individual glyphs resulting from the  formatting  of
             [4mcontents.[0m

             A  character defined by [1mchar [22mcan be used just like a glyph provided
             by the output device.   In  particular,  other  characters  can  be
             translated  to  it  with  the [1mtr [22mrequest; it can be made the tab or
             leader fill character with the [1mtc [22mand [1mlc [22mrequests; sequences of  it
             can be drawn with the [1m\l [22mand [1m\L [22mescape sequences; and, if the [1mhcode[0m
             request is used on [4mc[24m, it is subject to automatic hyphenation.

             However,  a  user‐defined  character  [4mc[24m does not participate at its
             boundaries in kerning adjustments or italic corrections.

             The formatter prevents infinite recursion by treating an occurrence
             of a character in its own definition as if it were undefined;  when
             interpolating  such a character, GNU [4mtroff[24m emits a warning in cate‐
             gory “[1mchar[22m”.  (Mutually recursive character definitions are handled
             similarly.)

             The [1mtr [22mand [1mtrin [22mrequests take precedence if [1mchar [22malso applies to [4mc[24m.
             The [1mrchar [22mrequest removes character definitions.

     [1m.chop [4m[22mname[0m
             Remove the last character from  the  macro,  string,  or  diversion
             [4mname[24m.   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 [4mname[24m; see section “GNU troff  Inter‐
             nals”  in [4mGroff:[24m [4mThe[24m [4mGNU[24m [4mImplementation[24m [4mof[24m [4mtroff[24m, the [4mgroff[24m Texinfo
             manual, for discussion of nodes inserted by [4mgroff[24m.

     [1m.class [4m[22mident[24m [4mc[24m ...
             Define a character class (or simply “class”) [4mident[24m  comprising  the
             members  [4mc[24m...,  where  each  [4mc[24m  is an ordinary, special, or indexed
             character; or a [4mrange[24m [4mexpression.[24m  A class thus defined can then be
             referred to in a [1mcflags [22mrequest in lieu of listing all the  charac‐
             ters within it.

             Since  class and special character names share the same name space,
             we recommend starting and ending the class name with “[1m[[22m”  and  “[1m][22m”,
             respectively,  to  avoid collisions with existing special character
             names defined by GNU [4mtroff[24m or the user (with [1mchar [22mand  related  re‐
             quests).   This  practice  applies the presence of “[1m][22m” in the class
             name to prevent the usage of  the  special  character  escape  form
             “[1m\[[22m...[1m][22m”,  you  must therefore access a class thus named via the [1m\C[0m
             escape sequence.

             An argument [4mc[24m can alternatively be a [4mrange[24m [4mexpression[24m consisting of
             a start character followed by “[1m-[22m” and then an end  character.   In‐
             ternally,  GNU  [4mtroff[24m converts these two character names to Unicode
             code points (according to the [4mgroff[24m glyph list [GGL]), which deter‐
             mine the start and end values of the  range.   If  that  conversion
             fails, GNU [4mtroff[24m skips the range expression and any remaining argu‐
             ments.

     [1m.close [4m[22mstream[0m
             Close  the  named  [4mstream[24m,  invalidating  it  as an argument to the
             “[1mwrite[22m” request.  See “[1mopen[22m”.

     [1m.composite [4m[22mc1[24m [4mc2[0m
             Map ordinary or special character [4mc1[24m to [4mc2[24m when [4mc1[24m is  a  combining
             component  in  a composite character.  Typically, [1mcomposite [22mis used
             to map a spacing character to a combining one.  See ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\.

     [1m.continue[0m
             Skip the remainder of a “[1mwhile[22m” loop’s body, immediately  retesting
             its conditional expression.  See “[1mbreak[22m” above.

     [1m.color [22m[[4mb[24m]
             Enable or disable output of color‐related device‐independent output
             commands  per  Boolean expression [4mb[24m.  It is enabled by default, and
             if [4mb[24m is omitted.

     [1m.cp [22m[[4mb[24m]
             Enable or disable AT&T [4mtroff[24m compatibility mode per Boolean expres‐
             sion [4mb[24m.  It is disabled by default, and enabled if  [4mb[24m  is  omitted.
             In  compatibility  mode, long names are not recognized, and the in‐
             compatibilities they cause do not arise.

     [1m.defcolor [4m[22mident[24m [4mscheme[24m [4mcolor‐component[24m ...
             Define a color named [4mident.[24m  [4mscheme[24m identifies a  color  space  and
             determines  the number of required [4mcolor‐component[24ms; it must be one
             of “[1mrgb[22m” (three components), “[1mcmy[22m” (three components), “[1mcmyk[22m” (four
             components), or “[1mgray[22m” (one component).  “[1mgrey[22m” is  accepted  as  a
             synonym  of “[1mgray[22m”.  Each color component can be encoded as a hexa‐
             decimal value starting with [1m# [22mor [1m##[22m.   The  former  indicates  that
             each  component  is in the range 0–255 (0–FF), the latter the range
             0–65535 (0–FFFF).  Alternatively, a component can be specified as a
             decimal fraction in the range  0–1,  interpreted  using  a  default
             scaling  unit  of  “[1mf[22m”,  which  multiplies its value by 65,536 (but
             clamps it at 65,535).

             Each output device has a color named “[1mdefault[22m”, which cannot be re‐
             defined.  A device’s default stroke and fill colors are not  neces‐
             sarily the same.

     [1m.de1 [4m[22mident[24m [[4mend‐name[24m]
             As “[1mde[22m”, but GNU [4mtroff[24m disables compatibility mode while interpret‐
             ing [4mname:[24m it inserts a [4mcompatibility[24m [4msave[24m token at the beginning of
             the macro definition, and a [4mcompatibility[24m [4mrestore[24m token at its end.
             See [1m.am1 [22mabove.

     [1m.dei [4m[22mname[24m [[4mend‐name[24m]
             Define  macro  indirectly, with the name of the macro to be defined
             in string [4mname[24m and the name of the end macro terminating its defin‐
             ition in string [4mend‐name[24m.

     [1m.dei1 [4m[22mname[24m [[4mend‐name[24m]
             As [1mdei[22m, but GNU [4mtroff[24m disables compatibility mode while  interpret‐
             ing  the  macro  named by the contents of string [4mname.[24m  See [1mam1 [22mand
             [1mde1 [22mabove.

     [1m.device [22m[[[1m"[22m][4mcharacter‐sequence[24m]
             Embed [4mcharacter‐sequence[24m into GNU [4mtroff[24m output as parameters to  an
             “x[1mX” [22mdevice extension command; see ]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\.  The output driver
             or  other  postprocessor  interprets  [4mcharacter‐sequence[24m as it sees
             fit.

     [1m.devicem [4m[22mname[0m
             Write contents of macro or string [4mname[24m to [4mtroff[24m output as the argu‐
             ment to a device extension command.

     [1m.do [4m[22mname[24m [[4margument[24m ...]
             Interpret the string, request, diversion, or macro [4mname[24m (along with
             any further arguments) with compatibility mode disabled.   Compati‐
             bility mode is restored (only if it was active) when the interpola‐
             tion  of  [4mname[24m  is interpreted; that is, the restored compatibility
             state applies to the request or contents of the macro,  string,  or
             diversion [4mname[24m, its arguments, and data read from files or pipes if
             [4mname[24m is the “[1mso[22m”, [1msoquiet[22m, [1mmso[22m, [1mmsoquiet[22m, or [1mpso [22mrequest.

     [1m.ds1 [4m[22mname[24m [[[1m"[22m][4mcontents[24m]
             As  [1mds[22m, but GNU [4mtroff[24m disables AT&T compatibility mode while inter‐
             preting [4mname[24m: it inserts a “compatibility save” token at the begin‐
             ning of [4mcontents[24m, and a “compatibility restore” token after it.

     [1m.ecr    [22mRestore the escape character saved with [1mecs[22m, or set escape  charac‐
             ter to “[1m\[22m” if none has been saved.

     [1m.ecs    [22mSave the current escape character.

     [1m.evc [4m[22menv[0m
             Copy  the properties of environment [4menv[24m to the current environment,
             except for:

             •  a partially collected line, if present;

             •  the interruption status of the previous input line (due  to  use
                of the [1m\c [22mescape sequence);

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

             •  the activation status of temporary indentation;

             •  input traps and their associated data;

             •  the  activation  status  of line numbering (which can be reacti‐
                vated with “[1m.nm +0[22m”); and

             •  the count of consecutive hyphenated lines (set to zero).

             Copying an environment to itself discards the foregoing data.

     [1m.fam [22m[[4mfml[24m]
             Set default font family to [4mfml[24m.  With  no  argument,  the  previous
             font  family is selected, and if none, the formatter’s default fam‐
             ily.  This default is “T” (Times), but can  be  overridden  by  the
             output device——see ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.  The default font family is asso‐
             ciated with the environment.  See [1m\F[22m.

     [1m.fchar [4m[22mc[24m [[[1m"[22m][4mcontents[24m]
             Define  fallback  character [4mc[24m as [4mcontents[24m.  As [1mchar[22m, but while that
             request hides a glyph with the same  name  in  the  selected  font,
             [1mfchar  [22mdefinitions  are  used only if the font lacks a glyph for [4mc[24m.
             GNU [4mtroff[24m performs this test before searching special fonts.

     [1m.fcolor [22m[[4mcol[24m]
             Select [4mcol[24m as the environment’s fill color, or,  without  an  argu‐
             ment,  restore  the previous fill color, or the default if there is
             none.

     [1m.fschar [4m[22mf[24m [4mc[24m [[[1m"[22m][4mcontents[24m]
             Define fallback special character [4mc[24m for font  [4mf[24m  as  [4mcontents[24m.   As
             [1mchar[22m, but GNU [4mtroff[24m locates a character defined by [1mfschar [22mafter any
             fonts  named  as  arguments to the [1mfspecial [22mare searched and before
             those named as arguments to the “[1mspecial[22m” request.

     [1m.fspecial [4m[22mf[24m [[4ms[24m ...]
             Declare each font [4ms[24m as special only when font [1mf [22mis selected.   Ini‐
             tially,  a  font  [4mf[24m’s list of associated special fonts is empty for
             all [4mf.[24m  GNU [4mtroff[24m searches fonts  specified  as  arguments  to  the
             “[1mspecial[22m”  request  after  those given as arguments to the [1mfspecial[0m
             request.  See “[1mspecial[22m”.

     [1m.ftr [4m[22mf[24m [[4mg[24m]
             Translate font [4mf[24m to [4mg[24m.  Whenever a font named [4mf[24m is referred  to  in
             an [1m\f [22mescape sequence, in the [1mF [22mand [1mS [22mconditional expression opera‐
             tors,  or  in  the [1mft[22m, [1mul[22m, [1mbd[22m, [1mcs[22m, [1mtkf[22m, “[1mspecial[22m”, [1mfspecial[22m, [1mfp[22m, or
             [1msty [22mrequests, font [4mg[24m is used.  If [4mg[24m is missing or identical  to  [4mf[24m,
             then font [4mf[24m is not translated.

     [1m.fzoom [4m[22mf[24m [[4mzoom[24m]
             Set zoom factor [4mzoom[24m for font [4mf[24m.  [4mzoom[24m must be a non‐negative inte‐
             ger;  it scales the magnification by thousandths with 1000 as a ba‐
             sis.  If [4mzoom[24m is missing or equal to zero or 1000, font  [4mf[24m  is  not
             magnified.   [4mf[24m  must be a resolved font name, not an abstract style
             or mounting position.

     [1m.gcolor [22m[[4mcol[24m]
             Select [4mcol[24m as the environment’s stroke color, or, without an  argu‐
             ment, restore the previous stroke color, or the default if there is
             none.

     [1m.hcode [4m[22mdst1[24m [4msrc1[24m [[4mdst2[24m [4msrc2[24m] ...
             Set  the hyphenation code of character [4mdst1[24m to that of [4msrc1[24m, and so
             on.  [4mdst1[24m must be an ordinary character (other than a numeral) or a
             special character, and [4msrc1[24m must be an  ordinary  character  (other
             than  a numeral) or a special character to which a hyphenation code
             has already been applied.  Assigning the code of an ordinary  char‐
             acter  to  itself  effectively  creates  a  unique hyphenation code
             (which can then be copied to others).  [1mhcode [22mignores spaces between
             arguments.  If any argument is invalid, [1mhcode [22mreports an error  and
             stops reading them.

     [1m.hla [22m[[4mlang[24m]
             Set  the  hyphenation  language to [4mlang[24m, or clear it if there is no
             argument.  Hyphenation exceptions specified with the [1mhw [22mrequest and
             hyphenation patterns and exceptions specified with the [1mhpf [22mand [1mhpfa[0m
             requests are associated with the hyphenation language.  The [1mhla [22mre‐
             quest is usually invoked by a localization file, which is  in  turn
             loaded  by the [4mtroffrc[24m or [4mtroffrc-end[24m file; see the [1mhpf [22mrequest be‐
             low.

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

     [1m.hpf [22m[[1m"[22m][4mpattern‐file[0m
             Read hyphenation patterns from [4mpattern‐file[24m.  This file  is  sought
             in the same way that macro files are with the [1mmso [22mrequest.

             The  [4mpattern‐file[24m  should have the same format as (simple) TeX pat‐
             tern 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 [1m\$ [22mare not supported.

             •  “[1m^^[4m[22mxx[24m” (where each [4mx[24m is 0–9 or a–f) and [1m^^[4m[22mc[24m (character [4mc[24m in  the
                code  point range 0–127 decimal) are recognized; other uses of [1m^[0m
                cause an error.

             •  No macro expansion is performed.

             •  [1mhpf [22mchecks for  the  expression  [1m\patterns{[22m...[1m}  [22m(possibly  with
                whitespace  before or after the braces).  Everything between the
                braces is taken as hyphenation patterns.  Consequently, “[1m{[22m”  and
                “[1m}[22m” are not allowed in patterns.

             •  Similarly,  [1m\hyphenation{[22m...[1m} [22mgives a list of hyphenation excep‐
                tions.

             •  [1m\endinput [22mis recognized also.

             •  For backward compatibility, if [1m\patterns [22mis missing,  the  whole
                file  is  treated as a list of hyphenation patterns (but the “[1m%[22m”
                character is still recognized as the start of a comment).

             Use the [1mhcode [22mrequest (see above) to map the encoding used  in  hy‐
             phenation pattern files to [4mgroff[24m’s input encoding.

             GNU  [4mtroff[24m  ties the set of hyphenation patterns to the hyphenation
             language code selected by the [1mhla [22mrequest.  The [1mhpf [22mrequest is usu‐
             ally invoked by a localization file loaded  by  the  [4mtroffrc[24m  file.
             [4mgroff[24m  provides  localization files for several languages; See sub‐
             section “Localization packages” of ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\.  For Western lan‐
             guages, the localization file sets the default hyphenation mode and
             loads hyphenation patterns and  exceptions.   By  default,  [4mtroffrc[0m
             loads the localization file for English.

             A  second call to [1mhpf [22m(for the same language) replaces the old pat‐
             terns with the new ones.

             Invoking [1mhpf [22mcauses an error if there is no hyphenation language.

             If no [1mhpf [22mrequest is specified (either in the document, in  a  file
             loaded at startup, or in a macro package), GNU [4mtroff[24m won’t automat‐
             ically hyphenate at all.

     [1m.hpfa [22m[[1m"[22m][4mpattern‐file[0m
             As  [1mhpf[22m,  except  that the hyphenation patterns and exceptions from
             [4mpattern‐file[24m are appended to the patterns already  applied  to  the
             hyphenation language of the environment.

     [1m.hpfcode [4m[22ma[24m [4mb[24m [[4mc[24m [4md[24m] ...
             [4mCaution:[24m  This request will be withdrawn in a future [4mgroff[24m release.
             Use [1mhcode [22minstead.

             Define mapping values for character codes in pattern files.  [1mhpf [22mor
             [1mhpfa [22mapply the mapping after reading or  appending  to  the  active
             list  of patterns.  Its arguments are pairs of character codes——in‐
             tegers from 0 to 255.  The request maps character code [4ma[24m to code [4mb[24m,
             code [4mc[24m to code [4md[24m, and so on.  Character codes that would  otherwise
             be  invalid  in GNU [4mtroff[24m 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”.

     [1m.hydefault [4m[22mmode[0m
             Set  hyphenation  mode default to [4mmode.[24m  When the [1mhy [22mrequest is in‐
             voked without an argument, this mode is selected.  The  hyphenation
             mode  default  is associated with the environment.  The formatter’s
             default is [1m1 [22mfor AT&T [4mtroff[24m compatibility.  [4mgroff[24m locale files gen‐
             erally set a more appropriate one; see ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\.

     [1m.hym [22m[[4mlength[24m]
             Set the (right) hyphenation margin to [4mlength[24m.   If  the  adjustment
             mode is not “[1mb[22m” or “[1mn[22m”, the line is not hyphenated if it is shorter
             than  [4mlength[24m.   Without an argument, the default hyphenation margin
             is reset to its default value, 0.  The default scaling unit is “[1mm[22m”.
             The hyphenation margin is associated with the environment.  A nega‐
             tive argument resets the hyphenation margin  to  zero,  emitting  a
             warning in category “[1mrange[22m”.

     [1m.hys [22m[[4mhyphenation‐space[24m]
             Suppress hyphenation of the line in adjustment modes “[1mb[22m” or “[1mn[22m”, if
             that adjustment can be achieved by adding no more than [4mhyphenation‐[0m
             [4mspace[24m  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 “[1mm[22m”.  The hyphenation space
             adjustment threshold is associated with the environment.   A  nega‐
             tive  argument resets the hyphenation space adjustment threshold to
             zero, emitting a warning in category “[1mrange[22m”.

     [1m.itc [22mn [[4mmac[24m]
             As “[1mit[22m”, but lines interrupted with the [1m\c [22mescape sequence  do  not
             apply to the line count.

     [1m.kern [22m[[4mb[24m]
             Enable or disable pairwise kerning of glyphs in the environment per
             Boolean  expression [4mb[24m.  It is enabled by default, and if [4mb[24m is omit‐
             ted.

     [1m.length [4m[22mreg[24m [[[1m"[22m][4mcontents[24m]
             Compute the number of characters in [4mcontents[24m and store the count in
             the register [4mreg[24m.  If [4mreg[24m doesn’t exist, GNU [4mtroff[24m creates it.

             [4mCaution:[24m If you interpolate a macro or diversion in  [4mcontents[24m  (see
             section  “Punning  Names”  in  ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\), the [1mlength [22mrequest counts
             characters (or nodes) only up to the first newline, and leaves  the
             rest  on  the  input  stream.   In conventional circumstances, that
             means the remainder is interpreted, and may be formatted.  To  dis‐
             cover the length of any string, macro, or diversion, use the [1mpm [22mre‐
             quest.  See section “Debugging” below.

     [1m.linetabs [22m[[4mb[24m]
             Activate or deactivate line‐tabs in the environment per Boolean ex‐
             pression  [4mb[24m.   They  are inactive by default, and activated if [4mb[24m is
             omitted.  When line‐tabs are active, tab stops are  computed  rela‐
             tive to the start of the pending output line instead of the drawing
             position corresponding to the start of the input line.

     [1m.lsm [22m[[4mname[24m]
             Set a leading space trap, calling the macro [4mname[24m when GNU [4mtroff[24m en‐
             counters  leading  spaces  on  a text line; the implicit line break
             that normally happens in this case is  suppressed.   The  formatter
             stores  the  count  of  leading spaces on the text line in register
             [1mlsn[22m, and the amount of corresponding horizontal motion in  register
             [1mlss[22m,  irrespective of whether a leading space trap is set.  When it
             is, GNU [4mtroff[24m removes the leading spaces from the  input  line  and
             produces no motion before calling [4mname[24m.

             If  no  argument  is  supplied, GNU [4mtroff[24m reëstablishes the default
             handling of leading spaces on text lines (breaking  the  line  when
             filling,  and  formatting  a  horizontal  motion  of  [1m\n[lsn]  [22mword
             spaces).

     [1m.mso [22m[[1m"[22m][4mfile[0m
             As “[1mso[22m”, except that GNU [4mtroff[24m searches for the specified  [4mfile[24m  in
             the same directories as macro files; see [4mGROFF_TMAC_PATH[24m in section
             “Environment”  of  ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ and [1m-m [22min section “Options” of the same
             page.  If [4mfile[24m does not exist or is not readable, a warning in cat‐
             egory “[1mfile[22m” is emitted and the request has no other effect.

     [1m.msoquiet [22m[[1m"[22m][4mfile[0m
             As [1mmso[22m, but no warning is emitted if [4mfile[24m does not exist.

     [1m.nop [22m[[4minput[24m]
             Interpret [4minput[24m as if it were an input line.   [1mnop  [22mresembles  “[1m.if[0m
             [1m1[22m”;  it puts a break on the output if [4minput[24m is empty.  Unlike “[1mif[22m”,
             it cannot govern conditional blocks.  Its application is  to  main‐
             tain consistent indentation within macro definitions even when for‐
             matting output.

     [1m.nroff  [22mMake  the  [1mn [22mconditional expression evaluate true and [1mt [22mfalse.  See
             [1mtroff[22m.

     [1m.open [4m[22mident[24m [[1m"[22m][4mfile[0m
             Open [4mfile[24m for writing and associate a stream named [4mident[24m  with  it,
             making it available for “[1mwrite[22m” requests.  Unsafe request; disabled
             by default.  Also see [1mwritec [22mand “[1mclose[22m”.

     [1m.opena [4m[22mident[24m [[1m"[22m][4mfile[0m
             As  “[1mopen[22m”,  but  appends  to  [4mfile[24m if it already exists instead of
             overwriting it.

     [1m.output [22m[[1m"[22m][4mcharacter‐sequence[0m
             Emit [4mcharacter‐sequence[24m, transparently to GNU  [4mtroff[24m  output;  this
             usage  is similar to that of [1m\! [22mwhen it occurs in the top‐level di‐
             version.

     [1m.pchar [4m[22mc[24m ...
             Report, to the standard error stream, information about each  char‐
             acter  (be  it ordinary, special, or indexed) or character class [4mc[24m.
             A character defined by a request ([1mchar[22m, [1mfchar[22m,  [1mfschar[22m,  or  [1mschar[22m)
             reports  its  contents  as a JSON‐encoded string, but the output is
             not otherwise in JSON format.

     [1m.pcolor [22m[[4mcol[24m ...]
             Report, to the standard error stream, each defined color named [4mcol[24m,
             its color space identifier,  and  channel  value  assignments,  or,
             without arguments, those of all defined colors.  A device’s default
             stroke and/or fill colors, “default”, are not listed since they are
             immutable and their details unknown to the formatter.

     [1m.pcomposite[0m
             Report,  to  the standard error stream, the list of configured com‐
             posite character mappings.  See “[1mcomposite[22m” above.  The “from” code
             point is listed first, followed by its “to” mapping.

     [1m.pev    [22mReport the state of the current environment followed by that of all
             other environments to the standard error stream.

     [1m.pfp    [22mReport, to the standard error stream, the  list  of  occupied  font
             mounting  positions.   Occupied  mounting positions are listed, one
             per line, in increasing order, followed by the  typeface  name;  if
             the  name  corresponds  to an abstract style, the entry ends there.
             Otherwise, the name of the font description  file  and  the  font’s
             “internal  name”  datum,  the meaning of which varies by output de‐
             vice, follow.

     [1m.pftr   [22mReport, to the standard error stream, the  list  of  font  transla‐
             tions.   See  [1mpftr  [22mabove.   The  “from”  font identifier is listed
             first, followed by its “to” translation.

     [1m.phw    [22mReport, to the standard error stream, the list of  hyphenation  ex‐
             ception  words associated with the hyphenation language selected by
             the [1mhla [22mrequest.  A “[1m-[22m” marks each hyphenation point.  A word  pre‐
             fixed with “[1m-[22m” is not hyphenated at all.  The report suffixes words
             to  which automatic hyphenation applies (meaning those defined in a
             hyphenation pattern file rather than with the [1mhw  [22mrequest)  with  a
             tab and asterisk “[1m*[22m”.

     [1m.pline  [22mReport,  in  JSON  syntax to the standard error stream, the list of
             output nodes corresponding to the pending output line.  In JSON,  a
             pair  of  empty brackets “[1m[ ][22m” represents an empty list.  A [4mpending[0m
             output line has not yet undergone adjustment, and lacks a line num‐
             ber and margin character (all as applicable).

     [1m.pnr [22m[[4mreg[24m ...]
             Report the name and value and, if its type is numeric, the  autoin‐
             crement  amount and assigned format of each register [4mreg[24m, or, with‐
             out arguments, those of all defined registers, to the standard  er‐
             ror stream.

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

     [1m.pso [22m[[1m"[22m][4mcommand[0m
             As “[1mso[22m”, except that input comes from the standard output stream of
             [4mcommand[24m, which is passed to ]8;;man:popen(3)\[4mpopen[24m(3)]8;;\.

     [1m.pstream[0m
             Report, in JSON syntax to the standard error stream,  the  list  of
             open  streams,  including the name of each open stream, the name of
             the file backing it, and its mode (writing or appending).

     [1m.pwh    [22mReport the names and vertical positions, in  basic  units,  of  all
             page  location  traps  to the standard error stream.  GNU [4mtroff[24m re‐
             ports empty slots in the list, where a trap had  been  planted  but
             subsequently  (re)moved,  because they can affect the visibility of
             subsequently planted traps.

     [1m.pvs [4m[22m±n[0m
             Set the post‐vertical line  spacing  to  [4mn[24m;  default  scaling  unit
             is  “[1mp[22m”.   With no argument, the post‐vertical line space is set to
             its previous value.

             In GNU [4mtroff[24m, the distance between text baselines consists  of  the
             extra  pre‐vertical  line spacing set by the most negative [1m\x [22margu‐
             ment on the pending output line, the vertical spacing ([1mvs[22m), the ex‐
             tra post‐vertical line spacing set by the most positive [1m\x [22margument
             on the pending output line, and the post‐vertical line spacing  set
             by this request.

     [1m.rchar [4m[22mc[24m...
             Remove  definition  of each ordinary, special, or indexed character
             [4mc[24m, undoing the effect of a [1mchar[22m, [1mfchar[22m, or [1mschar  [22mrequest.   Spaces
             need  not  separate  [4mc[24m arguments.  The character definition removed
             (if any) is the first encountered in the resolution  process  docu‐
             mented  in section “Using Symbols” of [4mGroff:[24m [4mThe[24m [4mGNU[24m [4mImplementation[0m
             [4mof[24m [4mtroff[24m.  Glyphs, which are defined  by  font  description  files,
             cannot be removed.

     [1m.return [22m[[4minput[24m]
             Stop interpreting an interpolated macro, skipping to the end of its
             definition.   Do  not  confuse “[1mreturn[22m” with [1mrt[22m.  If called with an
             argument [4minput,[24m GNU [4mtroff[24m performs the skip twice——once within  the
             macro  being interpreted and once in an enclosing macro, permitting
             a macro to wrap the request (as [4mtrace.tmac[24m does).

     [1m.rfschar [4m[22mf[24m [4mc[24m ...
             Remove each fallback special character [4mc[24m for font [4mf[24m.   Spaces  need
             not separate [4mc[24m arguments.  See [1mfschar[22m.

     [1m.rj [22m[[4mn[24m]
             Break,  right‐align the next [4mn[24m (default: 1) input lines, then break
             again.  [1mrj [22mimplies “[1m.ce 0[22m”, and [1mce [22mimplies “[1m.rj 0[22m”.   Invoking  the
             request  with  the  no‐break control character suppresses the first
             break.

     [1m.rnn [4m[22mr1[24m [4mr2[0m
             Rename register [4mr1[24m to [4mr2[24m.  If [4mr1[24m doesn’t exist, the request is  ig‐
             nored.

     [1m.schar [4m[22mc[24m [[[1m"[22m][4mcontents[24m]
             Define  global  fallback character [4mc[24m as [4mcontents[24m.  As [1mchar[22m, but GNU
             [4mtroff[24m locates a character defined with [1mschar [22mafter any fonts  named
             as  arguments  to the “[1mspecial[22m” request and before any mounted spe‐
             cial fonts.

     [1m.shc [22m[[4mc[24m]
             Set the soft hyphen character, inserted when a word  is  hyphenated
             automatically  or  at a hyphenation character, to [4mc[24m.  If [4mc[24m is omit‐
             ted, the soft hyphen character is set to the  default,  [1m\[hy][22m.   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.  Nei‐
             ther  character definitions ([1mchar [22mand similar) nor translations ([1mtr[0m
             and similar) are considered when assigning the soft hyphen  charac‐
             ter.

     [1m.shift [22m[[4mn[24m]
             Shift  macro or string parameters [4mn[24m places (by 1 if [4mn[24m omitted): ar‐
             gument [4mi[24m becomes argument [4mi[24m-[4mn[24m; arguments 1 to [4mn[24m become unavailable.
             Shifting by a non‐positive amount, or outside of a macro or  string
             definition,  performs  no  operation.   The register [1m.$ [22madjusts its
             value accordingly.

     [1m.sizes [4m[22ms1[24m [4ms2[24m ... [4msn[24m [[1m0[22m]
             Set the available type sizes to [4ms1[24m, [4ms2[24m, ... [4msn[24m scaled points.   The
             list  of  sizes  can be terminated by an optional “[1m0[22m”.  Each [4msi[24m can
             also be a range [4mm[24m–[4mn[24m.  In contrast to the  device  description  file
             directive  of  the same name (see ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\), the argument list
             can’t extend over more than one line.

     [1m.soquiet [22m[[1m"[22m][4mfile[0m
             As “[1mso[22m”, but no warning is emitted if [4mfile[24m does not exist.

     [1m.special [22m[[4ms[24m ...]
             Declare each font [4ms[24m as special,  irrespective  of  its  description
             file,  populating a list that GNU [4mtroff[24m searches, in order, to find
             the glyph demanded.   GNU  [4mtroff[24m  mounts  each  font  [4ms.[24m   Invoking
             [1mspecial [22mwithout arguments empties the list.  A font is not automat‐
             ically  unmounted  if  a subsequent [1mspecial [22mrequest removes it from
             the list.  Initially, the list is empty.  GNU [4mtroff[24m searches  fonts
             specified  as  arguments to the “[1mspecial[22m” request after those given
             as arguments to the [1mfspecial [22mrequest.

     [1m.spreadwarn [22m[[4mlimit[24m]
             Emit a “[1mbreak[22m” warning if the additional space  inserted  for  each
             space between words in an output line adjusted to both margins with
             “[1m.ad  b[22m”  is  larger  than  or equal to [4mlimit[24m.  A negative value is
             treated as zero; an absent argument toggles the warning on and  off
             without  changing  [4mlimit[24m.   The  default  scaling  unit  is  [1mm[22m.  At
             startup, [1mspreadwarn [22mis inactive and [4mlimit[24m is 3 m.

             For example, “[1m.spreadwarn 0.2m[22m” warns if [4mtroff[24m must add  0.2  m  or
             more to each inter‐word space in a line.

     [1m.stringdown [4m[22mstr[0m
     [1m.stringup [4m[22mstr[0m
             Alter  the string named [4mstr[24m by replacing each of its bytes with its
             lowercase ([1mdown[22m) or uppercase ([1mup[22m) version (if one  exists).   Spe‐
             cial characters (see ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\) will often transform in the ex‐
             pected  way due to the regular naming convention for accented char‐
             acters.  When they do not, use substrings and/or catenation.

     [1m.sty [4m[22mpos[24m [4mstyle[0m
             Associate abstract [4mstyle[24m  with  non‐negative  font  mounting  posi‐
             tion [4mpos[24m.

     [1m.substring [4m[22mstr[24m [4mstart[24m [[4mend[24m]
             Replace  the string named [4mstr[24m with its substring bounded by the in‐
             dices [4mstart[24m and [4mend[24m,  inclusively.   The  first  character  in  the
             string  has  index 0.  Negative indices count backward from the end
             of the string: the last character has index -1, the  character  be‐
             fore  the  last  has index -2, and so on.  If [4mend[24m is omitted, [1m-1 [22mis
             implied.

     [1m.tkf [4m[22mf[24m [4ms1[24m [4mn1[24m [4ms2[24m [4mn2[0m
             Enable track kerning for font [4mf[24m.  When the current font is  [4mf[24m,  the
             width  of  every glyph is increased by an amount between [4mn1[24m and [4mn2[24m;
             when the current type size is less than or equal to [4ms1[24m,  the  width
             is  increased  by  [4mn1[24m;  when it is greater than or equal to [4ms2[24m, the
             width is increased by [4mn2[24m; when the type size  is  greater  than  or
             equal  to [4ms1[24m and less than or equal to [4ms2[24m, the increase in width is
             a linear function of the type size.

     [1m.tm1 [22m[[[1m"[22m][4mmessage[24m]
             As [1mtm[22m, but removes a leading neutral double quote ‘[1m"[22m’ from [4mmessage[24m,
             permitting initial embedded spaces in it.

     [1m.tmc [22m[[[1m"[22m][4mmessage[24m]
             As [1mtm1[22m, but does not append a newline.

     [1m.trf [4m[22mfile[0m
             Break and copy [4mfile[24m as “throughput” to GNU [4mtroff[24m output, discarding
             characters that are invalid as input; contrast with [1mcf[22m.  Each  line
             of  [4mfile[24m  is output as if preceded by [1m\![22m, but is not interpreted by
             the formatter.  If [4mfile[24m does not end with a  newline,  [1mtrf  [22mappends
             one.  Invoking the request with the no‐break control character sup‐
             presses the break.

     [1m.trin [4m[22mabcd[0m
             As  the [1mtr [22mrequest, but the [1masciify [22mrequest uses the character code
             (if any) before the character translation.

     [1m.trnt [4m[22mabcd[0m
             As the [1mtr [22mrequest, but the translations do not apply to  text  that
             is transparently throughput into a diversion with [1m\![22m.

     [1m.troff  [22mMake  the  [1mt [22mconditional expression evaluate true and [1mn [22mfalse.  See
             [1mnroff[22m.

     [1m.unformat [4m[22mdiv[0m
             Unformat the diversion [4mdiv[24m.   Unlike  [1masciify[22m,  “[1munformat[22m”  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.

     [1m.vpt [22m[[4mb[24m]
             Enable or disable vertical position traps per Boolean expression [4mb[24m.
             They  are  enabled by default, and if [4mb[24m is omitted.  Vertical posi‐
             tion traps are those set by the [1mch[22m, [1mwh[22m, and [1mdt [22mrequests.   Vertical
             position trap enablement is global.

     [1m.warn [22m[[4mn[24m]
             Select  categories of warnings to be reported.  [4mn[24m 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
             ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\.  For example, “[1m.warn 0[22m” disables all warnings, and “[1m.warn[0m
             [1m1[22m”  disables all warnings except those about missing glyphs.  If no
             argument is given, all warning categories are enabled.

     [1m.warnscale [4m[22mscaling‐unit[0m
             Select scaling unit used in certain warnings (one of [1mu[22m, [1mi[22m, [1mc[22m, [1mp[22m, or
             [1mP[22m; default: [1mi[22m).  Ignored on [4mnroff[24m‐mode output  devices,  for  which
             these  diagnostics  report the vertical page location in lines, and
             the horizontal page location in ens.

     [1m.while [4m[22mcond‐expr[24m [4minput[0m
             Evaluate the conditional expression [4mcond‐expr[24m, and repeatedly  exe‐
             cute  [4minput[24m  unless  and  until  [4mcond‐expr[24m evaluates false.  [4minput,[0m
             which is often a conditional block, is referred to as  the  “[1mwhile[22m”
             request’s [4mbody.[0m

             GNU [4mtroff[24m treats the body of a “[1mwhile[22m” request similarly to that of
             a  [1mde [22mrequest (albeit one not read in copy mode), but stores it un‐
             der an internal name and deletes it when the  loop  finishes.   The
             operation of a macro containing a “[1mwhile[22m” request can slow signifi‐
             cantly  if its body is large.  Each time GNU [4mtroff[24m interpolates the
             macro, it parses and stores the “[1mwhile[22m” body again.  An often  bet‐
             ter  solution——and  one  that  is  more  portable, since AT&T [4mtroff[0m
             lacked the “[1mwhile[22m” request——is to instead write a recursive  macro,
             which is parsed only once (unless you redefine it).  To prevent in‐
             finite  loops, GNU [4mtroff[24m limits the default number of available re‐
             cursion levels to 1,000 or somewhat less (because things other than
             macro calls can be on the input stack).  You can disable this  pro‐
             tective  measure,  or alter the limit, by setting the [1mslimit [22mregis‐
             ter.  See section “Debugging” below.

             If a “[1mwhile[22m” body begins with  a  conditional  block,  its  closing
             brace must end an input line.

             The  “[1mbreak[22m” and “[1mcontinue[22m” requests alter a “[1mwhile[22m” loop’s flow of
             control.

     [1m.write [4m[22mstream[24m [[[1m"[22m][4mcharacter‐sequence[24m]
             Write  [4mcharacter‐sequence[24m,  a  sequence  of  ordinary   characters,
             spaces, or tabs read in copy mode, to [4mstream[24m, which must previously
             have  been the subject of an “[1mopen[22m” (or [1mopena[22m) request, followed by
             a newline.  GNU [4mtroff[24m flushes the stream after writing to it.

     [1m.writec [4m[22mstream[24m [[[1m"[22m][4mcharacter‐sequence[24m]
             As “[1mwrite[22m”, but does not append a newline to [4mcontents[24m.

     [1m.writem [4m[22mstream[24m [4mname[0m
             Write the contents of the macro or string  [4mname[24m  to  [4mstream[24m,  which
             must  previously  have been the subject of an “[1mopen[22m” (or [1mopena[22m) re‐
             quest.  GNU [4mtroff[24m reads the contents of [4mname[24m in copy mode.

   [1mAltered registers[0m
     GNU [4mtroff[24m alters the semantics of two AT&T [4mtroff[24m registers and imparts  se‐
     mantics to two others that CSTR #54 documented as “reserved”.

     [1m\n[.R][0m
            Because  GNU  [4mtroff[24m  dynamically manages register storage, it repur‐
            poses the [1m.R [22mregister to  interpolate  the  maximum  integer  repre‐
            sentable in the formatter.  Favor its use over numeric literals with
            many zeroes or nines to indicate an arbitrary large quantity.

     [1m\n[.s][0m
            In  GNU [4mtroff[24m, the [1m.s [22mregister is string‐valued; it interpolates the
            type size in typographical points, which can  be  represented  as  a
            decimal fraction.

     [1m\n[.x][0m
            Interpolate  major  version  number  of the running [4mtroff[24m formatter.
            For example, if the version  number  is  1.23.0,  then  [1m\n[.x]  [22mcon‐
            tains 1.

     [1m\n[.y][0m
            Interpolate  minor  version  number  of the running [4mtroff[24m formatter.
            For example, if the version  number  is  1.23.0,  then  [1m\n[.y]  [22mcon‐
            tains 23.  Also see [1m\n[.Y] [22mbelow.

   [1mNew registers[0m
     GNU  [4mtroff[24m  exposes  more formatter state via many new read‐only registers.
     Their names often correspond to the requests that affect them.

     [1m\n[.br]       [22mWithin a macro definition, interpolate  1  if  the  macro  is
                   called  with the “normal” control character (“.” by default),
                   and 0 otherwise.  This facility allows requests to  be  reli‐
                   ably wrapped by a macro.  Interpolating the [1m.br [22mregister out‐
                   side of a macro definition makes no sense.

     [1m\n[.C]        [22mInterpolate  1 if AT&T [4mtroff[24m compatibility mode is in effect,
                   0 otherwise.  See [1mcp[22m.

     [1m\n[.cdp]      [22mInterpolate depth of last glyph added to the environment.  It
                   is positive if the glyph extends below the baseline.

     [1m\n[.ce]       [22mInterpolate count of input lines remaining to be centered  in
                   the environment.

     [1m\n[.cht]      [22mInterpolate  height  of  last glyph added to the environment.
                   It is positive if the glyph extends above the baseline.

     [1m\n[.color]    [22mInterpolate 1 if color output is enabled, 0 otherwise.

     [1m\n[.cp]       [22mWithin a “[1mdo[22m” request, interpolate the saved value of compat‐
                   ibility mode (see [1m\n[.C] [22mabove).

     [1m\n[.csk]      [22mInterpolate skew of last glyph added to the environment.  The
                   [4mskew[24m of a glyph is how far to the right of the  center  of  a
                   glyph  the  center  of  an  accent  over  that glyph is to be
                   placed.

     [1m\n[.ev]       [22mInterpolate name of current environment.  This is  a  string‐
                   valued register.

     [1m\n[.fam]      [22mInterpolate  name  of  the environment’s default font family.
                   This is a string‐valued register.

     [1m\n[.fn]       [22mInterpolate resolved name of the font selected in  the  envi‐
                   ronment.  This is a string‐valued register.

     [1m\n[.fp]       [22mInterpolate next free non‐zero font mounting position.

     [1m\n[.g]        [22mInterpolate  1.   Test  with  “[1mif[22m” or [1mie [22mto check whether GNU
                   [4mtroff[24m is the formatter.

     [1m\n[.height]   [22mInterpolate the rescaled height of the environment’s selected
                   font, in scaled points.  It is zero if the font height is not
                   rescaled.  See [1m\H[22m.

     [1m\n[.hla]      [22mInterpolate hyphenation language of the environment.  This is
                   a string‐valued register.

     [1m\n[.hlc]      [22mInterpolate count of immediately  preceding  consecutive  hy‐
                   phenated lines in the environment.

     [1m\n[.hlm]      [22mInterpolate  maximum  number  of consecutive hyphenated lines
                   allowed in the environment.

     [1m\n[.hy]       [22mInterpolate automatic hyphenation mode of the environment.

     [1m\n[.hydefault][0m
                   Interpolate hyphenation mode default of the environment.

     [1m\n[.hym]      [22mInteprolate hyphenation margin of the environment.

     [1m\n[.hys]      [22mInterpolate hyphenation space adjustment threshold of the en‐
                   vironment.

     [1m\n[.in]       [22mInterpolate indentation amount applicable to the output  line
                   pending in the environment.

     [1m\n[.int]      [22mInterpolate  1 if the text most recently formatted in the en‐
                   vironment was “interrupted” or continued with  [1m\c[22m,  0  other‐
                   wise.

     [1m\n[.it]       [22mInterpolate  count  of  input lines remaining in the environ‐
                   ment’s pending input trap.

     [1m\n[.itc]      [22mInterpolate 1 if the environment’s pending input trap  honors
                   the  output  line continuation escape sequence ([1m\c[22m), 0 other‐
                   wise.

     [1m\n[.itm]      [22mInterpolate the name of the macro associated with  the  envi‐
                   ronment’s pending input trap.  This is a string‐valued regis‐
                   ter.

     [1m\n[.kern]     [22mInterpolate 1 if pairwise kerning is enabled, 0 otherwise.

     [1m\n[.lg]       [22mInterpolate ligature mode.

     [1m\n[.linetabs][0m
                   Interpolate  1  if  line‐tabs mode is enabled in the environ‐
                   ment, 0 otherwise.

     [1m\n[.ll]       [22mInterpolate line length applicable to the environment’s pend‐
                   ing output line.

     [1m\n[.lt]       [22mInterpolate the environment’s title line length.

     [1m\n[.m]        [22mInterpolate name of the environment’s selected stroke  color.
                   This is a string‐valued register.

     [1m\n[.M]        [22mInterpolate  name  of  the environment’s selected fill color.
                   This is a string‐valued register.

     [1m\n[.ne]       [22mInterpolate amount of space demanded by the  most  recent  [1mne[0m
                   request that sprang a page location trap.  See [1m\n[.trunc][22m.

     [1m\n[.nm]       [22mInterpolate  1 if output line numbering is enabled in the en‐
                   vironment (even if temporarily suppressed), 0 otherwise.

     [1m\n[.nn]       [22mInterpolate count of lines remaining in the  environment  for
                   which  numbering is suppressed while output line numbering is
                   enabled.

     [1m\n[.ns]       [22mInterpolate 1 if no‐space mode is enabled, 0 otherwise.

     [1m\n[.O]        [22mInterpolate output suppression level.  See [1m\O[22m.

     [1m\n[.P]        [22mInterpolate 1 if the current page  is  selected  for  output,
                   0 otherwise.  See [1m-o [22mcommand‐line option to ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\.

     [1m\n[.pe]       [22mInterpolate 1 during page ejection, 0 otherwise.

     [1m\n[.pn]       [22mInterpolate  next page number (either that set by [1mpn[22m, or that
                   of the current page plus 1).

     [1m\n[.ps]       [22mInterpolate the environment’s type size in scaled points.

     [1m\n[.psr]      [22mInterpolate the environment’s most  recently  requested  type
                   size in scaled points.

     [1m\n[.pvs]      [22mInterpolate  the  environment’s  post‐vertical  line  spacing
                   amount.

     [1m\n[.rj]       [22mInterpolate count of  input  lines  remaining  to  be  right‐
                   aligned in the environment.

     [1m\n[.slant]    [22mInterpolate  slant  in  degrees of the environment’s selected
                   font.  See [1m\S[22m.

     [1m\n[.sr]       [22mInterpolate the environment’s most  recently  requested  type
                   size in typographical points.  This is a string‐valued regis‐
                   ter.

     [1m\n[.ss][0m
     [1m\n[.sss]      [22mInterpolate  values  of  the environment’s minimum inter‐word
                   space and supplemental inter‐sentence space, respectively, in
                   twelfths of the space width of the selected font.

     [1m\n[.sty]      [22mInterpolate the environment’s selected abstract  font  style,
                   if any.  This is a string‐valued register.

     [1m\n[.tabs]     [22mInterpolate the environment’s tab stop settings (if any) in a
                   form  suitable  for  passage  to  the  [1mta [22mrequest.  This is a
                   string‐valued register.

     [1m\n[.trap]     [22mInterpolate the name of the next vertical position trap after
                   the vertical drawing position.  This is a string‐valued  reg‐
                   ister.

     [1m\n[.trunc]    [22mInterpolate  amount  of  vertical space truncated by the most
                   recently sprung page location  trap,  or,  if  the  trap  was
                   sprung  by an [1mne [22mrequest, minus the amount of vertical motion
                   produced by the [1mne [22mrequest.  In other words, at the  point  a
                   trap  is sprung, [1m\n[.trunc] [22mrepresents the difference of what
                   the vertical position would have been but for the  trap,  and
                   what the vertical position actually is.  See [1m\n[.ne][22m.

     [1m\n[.U]        [22mInterpolate  1  if  in unsafe mode, 0 otherwise.  See [1m-U [22mcom‐
                   mand‐line option to ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\.

     [1m\n[.vpt]      [22mInterpolate 1 if vertical position traps are enabled, 0  oth‐
                   erwise.

     [1m\n[.warn]     [22mInterpolate   warning   mask.    See  section  “Warnings”  of
                   ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\.

     [1m\n[.Y]        [22mInterpolate revision number of the running  [4mtroff[24m  formatter.
                   For  example,  if  the  version number is 1.23.0, then [1m\n[.Y][0m
                   contains 0.  Also see [1m\n[.x] [22mand [1m\n[.y] [22mabove.

     [1m\n[.zoom]     [22mInterpolate magnification of the environment’s selected font,
                   in thousandths, or 0 if magnification unused.  See [1mfzoom[22m.

     The following (writable) registers are set by the [1mpsbb [22mrequest.

     [1m\n[llx][0m
     [1m\n[lly][0m
     [1m\n[urx][0m
     [1m\n[ury]  [22mInterpolate 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 [1m\w [22mescape sequence.

     [1m\n[rst][0m
     [1m\n[rsb]  [22mLike [1m\n[st] [22mand [1m\n[sb][22m, but taking  account  of  the  heights  and
              depths of glyphs.  In other words, these registers store the high‐
              est and lowest vertical positions attained by the argument format‐
              ted  by  the  [1m\w [22mescape sequence, doing what AT&T [4mtroff[24m documented
              [1m\n[st] [22mand [1m\n[sb] [22mas doing.

     [1m\n[ssc]  [22mThe amount of (possibly negative) horizontal space to add  to  the
              last glyph before a subscript.

     [1m\n[skw]  [22mHow  far  to right of the center of the last glyph in the [1m\w [22margu‐
              ment, to place the center of an accent from a roman font over that
              glyph.

     Other writable registers are as follows.  Those relating to date  and  time
     are initialized using ]8;;man:localtime(3)\[4mlocaltime[24m(3)]8;;\ at formatter startup.

     [1m\n[c.]      [22mInterpolate  input line number.  [1m\n[.c] [22mis a read‐only alias of
                 this register.

     [1m\n[hours]   [22mInterpolate number of hours elapsed since midnight.

     [1m\n[hp]      [22mInterpolate horizontal position relative to that at  the  start
                 of the input line.

     [1m\n[lsn][0m
     [1m\n[lss]     [22mInterpolate count of leading spaces on input line and amount of
                 corresponding horizontal motion, respectively.

     [1m\n[minutes][0m
                 Interpolate number of minutes elapsed in the hour.

     [1m\n[seconds][0m
                 Interpolate number of seconds elapsed in the minute.

     [1m\n[systat]  [22mInterpolate return value of ]8;;man:system(3)\[4msystem[24m(3)]8;;\ function executed by most
                 recent [1msy [22mrequest.

     [1m\n[slimit]  [22mInterpolates  maximum  quantity  of objects on [4mtroff[24m’s internal
                 input stack (default: 1000).   If  non‐positive,  there  is  no
                 limit:  recursion  can  continue  until  program  memory is ex‐
                 hausted.

     [1m\n[year]    [22mInterpolate Gregorian year.  AT&T [4mtroff[24m’s  [1m\n[yr]  [22minterpolates
                 the Gregorian year minus 1900.

   [1mDelimiters[0m
     AT&T  [4mtroff[24m  recognized  slightly varying sets of delimiters when expecting
     numerical expressions (as with the [1m\h [22mescape sequence), string  expressions
     (as with the [1m\w [22mescape sequence and [1mtl [22mrequest), and output comparisons (as
     in  “[1m.if #foo#bar# .tm match[22m”).  GNU [4mtroff[24m, when not in compatibility mode,
     recognizes a single consistent set of delimiters.  Compatibility mode  emu‐
     lates AT&T [4mtroff[24m only up to a point.  GNU [4mtroff[24m accepts leaders and tabs as
     delimiters, as well as Control+D (EOT or EOF), Control+H (BS or backspace),
     and  Control+L  (FF  or  form feed), all of which, when used as delimiters,
     cause AT&T [4mtroff[24m to behave in ways difficult to predict.

   [1mMiscellaneous[0m
     A font not listed in the output device’s [4mDESC[24m file’s [1mfonts [22mdirective is au‐
     tomatically mounted at the next available font  position  when  it  is  se‐
     lected.   If you mount a font explicitly with the [1mfp [22mrequest, you should do
     so on the first unused position, which can be found in the [1m.fp [22mregister.

     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,
            [1m.[4m[22mxx[24m [1m\\$@[0m
     is more efficiently done with
            [1m\\*[[4m[22mxx[24m[1m]\\[0m
     (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 ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\.

     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 [1m\& [22mbetween them.

     GNU [4mtroff[24m keeps track of the nesting depth of  escape  sequence  interpola‐
     tions  and  other  uses  of delimiters, as in the [1mtl [22mrequest and the output
     comparison operator (that is, input like [1m'foo'bar' [22mas a conditional expres‐
     sion), 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 in‐
     terpolation.  Typically, [1m' [22mworks fine.  Use visible  characters  as  delim‐
     iters in GNU [4mtroff[24m, not US‐ASCII controls like BEL (Control+G).  The imple‐
     mentation of [1m\$@ [22mensures that the double quotes surrounding an argument ap‐
     pear  at  an interpolation depth different from that of the arguments them‐
     selves.  Similarly, in bracket‐form escape sequences like [1m\f[ZCMI], [22ma right
     bracket [1m] [22mdoes not end the sequence unless it occurs at the same interpola‐
     tion depth as the opening [1m[[22m.  In compatibility mode, no attention  is  paid
     to the interpolation depth.

     In  GNU  [4mtroff[24m,  the [1mtr [22mrequest can map characters to the unbreakable space
     escape sequence [1m\~ [22mas a special case ([1mtr [22mnormally operates only on  [4mcharac‐[0m
     [4mters[24m).   This feature replaces the odd‐parity [1mtr [22mmapping trick used in AT&T
     [4mtroff[24m documents, where a character, often [1m~[22m, 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 [4mtroff,[24m which supported the
     [1m\[4m[22mspace[24m escape sequence by 1976.)  Often, it makes more  sense  to  use  GNU
     [4mtroff[24m’s  [1m\~  [22mescape sequence instead, which has been adopted by every other
     active [4mtroff[24m implementation except that of Illumos, as well as by the  non[4m‐[0m
     [4mtroff[24m  [4mmandoc[24m.   Translation of a character to [1m\~ [22mis generally unnecessary,
     but might be employed to obtain an unbreakable space when the escape  char‐
     acter will subsequently be disabled.

     GNU  [4mtroff[24m  permits  tabs  and spaces after the first dot on a control line
     that ends a macro definition.

[1mFormatter output[0m
     The page description language output by GNU [4mtroff[24m  is  modeled  after  that
     used by AT&T [4mtroff[24m once the latter adopted a device‐independent approach in
     the  early  1980s.  Only the differences are documented here.  For a fuller
     discussion, see ]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\.

     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
     [4mtroff[24m, drivers need not search special fonts to find a glyph.

   [1mUnits[0m
     The argument to the [1ms [22mcommand is in scaled points (units of points/[4mn[24m, where
     [4mn[24m is the argument to the [1msizescale [22mcommand in the [4mDESC[24m file).  The argument
     to the “[1mx H[22m” command is also in scaled points.

   [1mSimple commands[0m
     If  the [1mtcommand [22mdirective is present in the output device’s [4mDESC[24m file, GNU
     [4mtroff[24m employs the following two commands.

     [1mt [4m[22mxyz[24m...
            Typeset word [4mxyz[24m; that is, set a sequence of ordinary  glyphs  named
            [4mx[24m,  [4my[24m,  [4mz[24m, ..., 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 [1mC [22mcommand
            to emplace glyphs of special characters.

     [1mu [4m[22mn[24m [4mxyz[24m...
            Typeset word [4mxyz[24m with track kerning.  As [1mt[22m, but after  placing  each
            glyph,  the  drawing  position is further advanced horizontally by [4mn[0m
            basic units.

     New commands implement color support.

     [1mmc [4m[22mcyan[24m [4mmagenta[24m [4myellow[0m
     [1mmd[0m
     [1mmg [4m[22mgray[0m
     [1mmk [4m[22mcyan[24m [4mmagenta[24m [4myellow[24m [4mblack[0m
     [1mmr [4m[22mred[24m [4mgreen[24m [4mblue[0m
            Set the components of the stroke color with respect to various color
            spaces.  [1mmd [22mresets the stroke color to the default value.  The argu‐
            ments are integers in the range 0 to 65535.

     A new device control subcommand is available.

     [1mx u [4m[22mn[24m  If [4mn[24m is 1, start underlining of spaces.  If [4mn[24m is 0, stop underlining
            of spaces.  This facility is needed for the [1mcu [22mrequest in [4mnroff[24m mode
            and is ignored otherwise.

   [1mExtended drawing commands[0m
     GNU [4mpic[24m does not produce [4mtroff[24m escape sequences employing these  extensions
     if its [1m-n [22moption is given.

     [1mDf [4m[22mn[24m    Set  the  shade  of gray used to fill geometric objects to [4mn[24m, 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.   Nor‐
             mally  the  default is black, but some drivers may provide a way of
             changing this.  [1mDf [22mis obsolete since 2002, superseded by [1mDFg [22mbelow.

             The corresponding [1m\D'f' [22mescape sequence should not be used: its ar‐
             gument is rounded to an integer multiple of the  horizontal  motion
             quantum, which can limit the precision of [4mn[24m.

     [1mDC [4m[22md[24m    Draw  a  filled circle of diameter [4md[24m with its leftmost point at the
             drawing position.

     [1mDE [4m[22mh[24m [4mv[24m  Draw a filled ellipse, of horizontal axis [4mh[24m and  vertical  axis  [4mv[24m,
             with its leftmost point at the drawing position.

     [1mDp [4m[22mdx[24m1[4mdy[24m1...[4mdxndyn[0m
             Draw a polygon with, for [4mi[24m=1,...,[4mn[24m+1, its [4mi[24mth vertex at the drawing
             position  +[4mij[24m−=Σ11([4mdxj[24m,[4mdyj[24m).   [4mgroff[24m output drivers automatically close
             polygons, drawing a line from ([4mdxn[24m,[4mdyn[24m)  back  to  ([4mdx[24m1,[4mdy[24m1).   The
             drawing position is left at the last [4mspecified[24m vertex, but this may
             change  in a future version of GNU [4mtroff[24m.  Heirloom Doctools [4mtroff[24m,
             like DWB [4mtroff[24m, by default does not  close  the  polygon.   In  its
             [4mgroff[24m  compatibility  mode,  Heirloom closes the polygon but leaves
             the drawing position [4munchanged[24m——that is, at the  polygon’s  [4minitial[0m
             drawing position.

     [1mDP [4m[22mdx[24m1[4mdy[24m1...[4mdxndyn[0m
             As [1mDp[22m, but draw a filled rather than a stroked polygon.

     [1mDt [4m[22mn[24m    Set the line thickness to [4mn[24m basic units.  AT&T [4mtroff[24m output drivers
             use  a  thickness  proportional  to  the type size; this is the GNU
             [4mtroff[24m default.  A negative [4mn[24m requests this  explicitly.   An  [4mn[24m  of
             zero selects the smallest available line thickness.

     A difficulty arises in how the drawing position should be changed after the
     execution  of  these  commands.   This has little importance to most users,
     since the output of GNU [4mgrn[24m and [4mpic[24m does not depend on it.  Given a drawing
     command of the form [1mD[4m[22mz[24m [4mx[24m1[4my[24m1...[4mxnyn[24m, where [4mz[24m is  not  [1mc  [22mor  [1me[22m,  AT&T  [4mtroff[0m
     treats  each  [4mxi[24m  as  a  horizontal  motion, each [4myi[24m as a vertical one, and
     therefore assumes that the width of the drawn  object  is  [4min[24m=Σ1[4mxi[24m,  and  its
     height  is  [4min[24m=Σ1[4myi[24m.  (Verify its assumption about height by examining the [1mst[0m
     and [1msb [22mregisters after using such a drawing command  in  a  [1m\w  [22mescape  se‐
     quence).   Thus after executing a [1mD [22mcommand of the form [1mD[4m[22mz[24m [4mx[24m1[4my[24m1...[4mxnyn[24m, the
     drawing position increases by ([4min[24m=Σ1[4mxi[24m,[4min[24m=Σ1[4myi[24m).  For the sake  of  compatibil‐
     ity,  GNU  [4mtroff[24m follows this rule, even though it frustrates extensions to
     the [1mD [22mcommand that set drawing parameters rather  than  rendering  objects,
     producing ugly results in the case of [1mDt [22mand [1mDf[22m, or otherwise don’t parame‐
     terize objects as a series of vertices, as with GNU [4mtroff[24m’s filled ellipse,
     [1mDE[22m.   In a future release, GNU [4mtroff[24m and its output drivers may abandon the
     application of this assumption to drawing commands not explicitly specified
     in the AT&T “Troff User’s Manual”.  You can ensure  predictable  output  by
     enclosing drawing commands in the zero‐motion escape sequence [1m\Z[22m.

     GNU [4mtroff[24m implements fill color selection with another set of extensions.

     [1mDFc [4m[22mcyan[24m [4mmagenta[24m [4myellow[0m
     [1mDFd[0m
     [1mDFg [4m[22mgray[0m
     [1mDFk [4m[22mcyan[24m [4mmagenta[24m [4myellow[24m [4mblack[0m
     [1mDFr [4m[22mred[24m [4mgreen[24m [4mblue[0m
            Set  the  components of the fill color as described under the [1m\M [22mes‐
            cape sequence above.  [1mDFd [22mrestores the device’s default fill  color.
            The drawing position is not updated, in contrast to [1mDf[22m.

   [1mDevice control syntax extension[0m
     GNU  [4mtroff[24m  introduces a line continuation convention, permitting the argu‐
     ment to the [1mx X [22mcommand to contain newlines.  A newline  in  the  input  is
     transformed  to the sequence “[4mnewline[24m[1m+[22m”.  When interpreting an [1mx X [22mcommand,
     a postprocessor should therefore be prepared for a plus sign after  a  new‐
     line;  if  it occurs, preserve the newline, discard the plus sign, and con‐
     tinue to collect the input into the argument of the [1mx X [22mcommand.  A newline
     [4mnot[24m followed by a plus sign terminates the [1mx X [22mcommand.  An application  of
     this feature is the embedding of PostScript or PDF language command streams
     into [4mtroff[24m output.

     GNU  [4mtroff[24m  guarantees that the first three output commands it emits are as
     follows.

            x T [4mdevice[0m
            x res [4mn[24m [4mh[24m [4mv[0m
            x init

[1mDebugging[0m
     In addition to AT&T [4mtroff[24m’s debugging features, GNU [4mtroff[24m emits more  error
     diagnostics  when  syntactical or semantic nonsense is encountered and sup‐
     ports several warning categories; the output of these can be selected  with
     “[1mwarn[22m”.  Also see the [1m-E[22m, [1m-w[22m, and [1m-W [22moptions of ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\.

     A  trace  of the formatter’s input processing stack can be emitted when er‐
     rors or warnings occur by means of GNU [4mtroff[24m [1m-b [22moption, or produced on  de‐
     mand with the [1mbacktrace [22mrequest.

     [4mgroff[24m  also  adds  more  flexible diagnostic output requests ([1mtmc [22mand [1mtm1[22m).
     Examine the state of the formatter with requests that write  lists  of  de‐
     fined  colors ([1mpcolor[22m), composite character mappings ([1mpcomposite[22m), environ‐
     ments ([1mpev[22m), font translations ([1mpftr[22m), automatic hyphenation codes  ([1mpchar[22m)
     and exceptions ([1mphw[22m), registers ([1mpnr[22m), open streams ([1mpstream[22m), and page lo‐
     cation  traps  ([1mpwh[22m).   Requests  can  also  disclose to the standard error
     stream the  internal  properties  and  representations  of  characters  and
     classes  ([1mpchar[22m), macros (and strings and diversions) ([1mpm[22m), and the list of
     output nodes corresponding to the pending input line ([1mpline[22m).

[1mCompatibility mode[0m
     Some syntactical and behavioral differences between AT&T and GNU [4mtroff[24ms are
     thought too important to neglect; GNU [4mtroff[24m  therefore  makes  available  a
     [4mcompatibility[24m  [4mmode[24m  in an effort to keep documents prepared for AT&T [4mtroff[0m
     rendering well.

     Identifiers of arbitrary length may be GNU [4mtroff[24m’s most obvious innovation.
     AT&T [4mtroff[24m interprets “[1m.dsabcd[22m” as defining a  string  “[1mab[22m”  with  contents
     “[1mcd[22m”.   Normally,  GNU [4mtroff[24m interprets this input as calling a macro named
     “[1mdsabcd[22m”.  AT&T [4mtroff[24m also interprets [1m\*[ [22mand [1m\n[ [22mas interpolating a string
     or register, respectively, named “[1m[[22m”.  GNU [4mtroff[24m, however, normally  inter‐
     prets  “[1m[[22m” as bracketing a long name (with “[1m][22m” at the distal end).  In com‐
     patibility mode, GNU [4mtroff[24m interprets names in the  traditional  way,  they
     thus  can  be  two  characters long at most.  See the [1m-C [22moption in ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\
     and, above, the [1m.C [22mand [1m.cp [22mregisters, and [1mcp [22mand “[1mdo[22m” requests, for more on
     compatibility mode.

     The register [1m\n[.cp] [22mis specialized and may require a statement  of  ratio‐
     nale.  When writing macro packages or documents that use GNU [4mtroff[24m 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 “[1mso[22m” or [1mmso[0m
     requests——you may desire correct operation regardless of compatibility mode
     enablement in the surrounding context.  It may occur to you to save the ex‐
     isting value of [1m\n(.C [22minto a register, say, [1m_C[22m, at the  beginning  of  your
     file,  turn  compatibility mode off with “[1m.cp 0[22m”, then restore it from that
     register at the end with “[1m.cp \n(_C[22m”.  At the same time, a  modular  design
     of  a  document  or macro package may lead you to multiple layers of inclu‐
     sion.  You cannot use the same register name everywhere lest you  “clobber”
     the  value from a preceding or enclosing context.  The two‐character regis‐
     ter name space of AT&T [4mtroff[24m is confining, but employing GNU  [4mtroff[24m’s  more
     capacious one, as with “[1m.nr _my_saved_C \n(.C[22m” does not work in compatibil‐
     ity  mode; the register name is too long.  Employing the “[1mdo[22m” request is no
     help: “[1m.do nr _my_saved_C \n(.C[22m” always saves zero to the register, because
     “[1mdo[22m” turns compatibility mode [4moff[24m while it interprets its argument list.

     GNU [4mtroff[24m normally tracks the interpolation depth of escape sequence  para‐
     meters  and other delimited structures, but not in compatibility mode.  See
     section “Miscellaneous” above.

     The escape sequences [1m\f[22m, [1m\H[22m, [1m\m[22m, [1m\M[22m, [1m\R[22m, [1m\s[22m, and [1m\S [22mare transparent to con‐
     trol character recognition at the beginning of an input line, or after  the
     conditional  expression  of  an  “[1mif[22m”  or [1mie [22mrequest, only in compatibility
     mode.  That is, upon interpreting them, GNU [4mtroff[24m normally no longer recog‐
     nizes a control character on the input line; but in compatibility mode,  it
     does, just like AT&T [4mtroff.[0m

     Normally, the syntax form [1m\s[4m[22mn[24m accepts only a single character (a digit) for
     [4mn[24m,  consistently  with  other forms that originated in AT&T [4mtroff[24m, like [1m\*[22m,
     [1m\$[22m, [1m\f[22m, [1m\g[22m, [1m\k[22m, [1m\n[22m, and [1m\z[22m.  In compatibility mode only, a non‐zero [4mn[24m  must
     be  in the range 4–39.  Legacy documents relying upon this quirk of parsing
     should migrate to another [1m\s [22mform.  [Background: The Graphic Systems  C/A/T
     phototypesetter  (the original device target for AT&T [4mtroff[24m) 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”.]

[1mOther differences[0m
     GNU  [4mtroff[24m  does not emit output if it has nothing to format.  For example,
     it treats an input document consisting solely of  [1mnr  [22mand  [1mtm  [22mrequests  as
     empty,  and  produces  nothing  on  its standard output stream.  AT&T [4mtroff[0m
     does, creating a blank page.

     Use of C0 control characters  in  identifiers  is  not  portable;  Solaris,
     Plan  9,  and  Heirloom  Doctools  [4mtroff[24ms accept Control+B, Control+C, Con‐
     trol+E, Control+F, and Control+G (only); DWB 3.3 [4mtroff[24m does not.  GNU [4mtroff[0m
     rejects C0 controls in identifiers with an error diagnostic.

     Formatters that don’t implement GNU [4mtroff[24m extension request names  tend  to
     ignore  them,  and  if  they don’t support a GNU [4mtroff[24m extension escape se‐
     quence, they are liable to format its function selector character as  text.
     For  example, the adjustable, non‐breaking space escape sequence [1m\~ [22mis also
     supported by Heirloom Doctools [4mtroff[24m 050915 (September 2005), [4mmandoc[24m  1.9.5
     (2009‐09‐21), [4mneatroff[24m (commit 1c6ab0f6e, 2016‐09‐13), and Plan 9 from User
     Space  [4mtroff[24m  (commit  93f8143600, 2022‐08‐12), but not by Solaris or Docu‐
     menter’s Workbench [4mtroff[24ms, which both render it as “[1m~[22m”.  The [1m\A [22mescape  se‐
     quence (see subsection “Escape sequences” above) may be helpful in avoiding
     their use.

     AT&T  [4mtroff[24m  discards trailing spaces from input lines, like GNU [4mtroff[24m, but
     when it does so, AT&T [4mtroff[24m also cancels end‐of‐sentence detection.  Use of
     the dummy character escape sequence [1m\& [22mis more portable.

     When adjusting output lines to both margins, AT&T [4mtroff[24m  at  first  adjusts
     spaces  starting  from the right; GNU [4mtroff[24m begins from the left.  Both im‐
     plementations adjust spaces from opposite ends on alternating output  lines
     in this adjustment mode to prevent “rivers” in the text.

     GNU [4mtroff[24m does not always hyphenate words as AT&T [4mtroff[24m does.  The AT&T im‐
     plementation uses a set of hard‐coded rules specific to U.S. English, while
     GNU  [4mtroff[24m  uses  language‐specific  hyphenation pattern files derived from
     TeX.  Some versions of [4mtroff[24m reserved meager storage for hyphenation excep‐
     tion words (arguments to the [1mhw [22mrequest); GNU [4mtroff[24m has  no  such  restric‐
     tion.   When  the [1mhy [22mrequest is invoked without an argument, GNU [4mtroff[24m sets
     the automatic hyphenation mode to the value of the [1m.hydefault [22mregister; the
     AT&T implementation sets it to “[1m1[22m”, which is not suitable in GNU [4mtroff[24m  for
     some languages, including English.

     Unlike  GNU [4mtroff[24m, AT&T [4mtroff[24m does not recognize an occurrence of [1m\% [22mat the
     beginning of a word as suppressing its hyphenation; instead, it (uselessly)
     marks the start of the word as a potential  hyphenation  point,  permitting
     output lines to end with hyphens that are not interior to a word.

     GNU  [4mtroff[24m  handles the dummy character [1m\& [22mdifferently from AT&T [4mtroff[24m when
     it is followed by the hyphenation control escape sequence [1m\% [22mat the  begin‐
     ning  of  a word.  GNU [4mtroff[24m does not regard the dummy character as “start‐
     ing” the word; AT&T [4mtroff[24m does.  Further, Heirloom Doctools [4mtroff[24m does  not
     honor  an  explicit  hyphenation  point marked with [1m\% [22mafter a word‐initial
     one.

     GNU [4mtroff[24m interprets request arguments representing file names  and  system
     commands  in  the same way it does the [4mcontents[24m argument to the [1mds [22mand “[1mas[22m”
     requests: it removes a leading neutral double quote ‘[1m"[22m’ from  the  argument
     to  the  [1mcf[22m,  [1mnx[22m,  [1mpi[22m,  “[1mso[22m”,  and [1msy [22mrequests, and the second argument (if
     present) to the [1mlf [22mrequest, permitting initial embedded spaces in  it,  and
     reads  it  to the end of the input line in copy mode.  This difference per‐
     mits the formatter to handle files with spaces in their names, but requires
     more care with trailing comments, and doubling of an initial neutral double
     quote “[1m"[22m” if the file name has one.

     The existence of the [1m.T [22mstring is a common  feature  of  device‐independent
     [4mtroff[24ms——DWB  3.3,  Solaris, Heirloom Doctools, and Plan 9 [4mtroff[24m all support
     it——but valid values are specific to each implementation.

     The (read‐only) register [1m.T [22minterpolates 1 if GNU [4mtroff[24m is run with the  [1m-T[0m
     option,  and  0  otherwise.  In contrast, AT&T [4mtroff[24m interpolated 1 only if
     [4mnroff[24m was the formatter and was run with [1m-T[22m.

     AT&T [4mtroff[24m ignored attempts to remove read‐only registers; GNU [4mtroff[24m honors
     such requests.

     The [1mlf [22mrequest sets the number of the [4mcurrent[24m input line in AT&T [4mtroff[24m, and
     the [4mnext[24m in GNU [4mtroff[24m.

     AT&T [4mtroff[24m had only environments named “[1m0[22m”, “[1m1[22m”, and “[1m2[22m”.   In  GNU  [4mtroff[24m,
     any number of environments may exist, using any valid identifiers for their
     names.

     As  noted  above  in  “Fractional  type  sizes and new scaling units”, AT&T
     [4mtroff[24m’s [1mps [22mrequest ignores scaling units and thus “[1m.ps 10u[22m” sets  the  type
     size  to 10 points, whereas in GNU [4mtroff[24m it sets the type size to 10 [4mscaled[0m
     points, possibly a much smaller measurement.  AT&T’s  behavior  also  means
     that “[1m.ps 10p[22m” and “[1m.ps 10z[22m” are portable.

     The  [1mab [22mrequest differs from AT&T [4mtroff[24m: GNU [4mtroff[24m writes no message to the
     standard error stream if no arguments are given, and it exits with a  fail‐
     ure status instead of a successful one.

     The [1mbp [22mrequest differs from AT&T [4mtroff[24m: GNU [4mtroff[24m does not accept a scaling
     unit on the argument, a page number; the former does (uselessly).

     In  AT&T [4mtroff[24m the [1mpm [22mrequest 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 [4mtroff[24m reports their lengths in characters
     or  nodes if given no arguments, and otherwise dumps the JSON‐encoded name,
     contents, and other properties of each named argument.

     AT&T [4mtroff[24m ignores the [1mss [22mrequest if the output is a terminal  device;  GNU
     [4mtroff[24m  rounds  down  the values of minimum inter‐word and additional inter‐
     sentence space each to the nearest multiple of 12.

     GNU [4mtroff[24m distinguishes characters from glyphs.  Characters  can  be  ordi‐
     nary, special, or indexed, and populate strings and macros.  Characters [4mper[0m
     [4mse[24m  have not (yet) been formatted.  Glyphs represent graphemes (supplied by
     the output device) and populate diversions.  Formatting converts characters
     into (sequences of) glyphs.  GNU [4mtroff[24m stores properties of the environment
     that affect how a glyph is rendered with the glyph node’s data.  Thus, sub‐
     sequent formatting operations do not affect it, including [1mbd[22m, [1mcs[22m, [1mtkf[22m,  [1mtr[22m,
     and [1mfp [22mrequests.  Normally, a macro or string contains only a list of char‐
     acters  and  a  diversion contains only a list of nodes.  However, applying
     the [1masciify [22mor [1munformat [22mrequests to a diversion converts some of its  nodes
     back  into  characters.   Where  the formatter cannot recover the character
     representation of a node, it stores a null character in the character  list
     corresponding  to  a  single  node in the node list.  Consequently, a glyph
     node does not behave as a character does in macro  interpolation:  it  does
     not  inherit  special  properties that the character from which it was con‐
     structed might have had.

     One way to format a backslash in most documents is with the [1m\e  [22mescape  se‐
     quence;  this formats the glyph of the current escape character, regardless
     of whether it is used in a diversion; it also works in both GNU  [4mtroff[24m  and
     AT&T  [4mtroff[24m.   (Naturally, if you’ve changed the escape character, you need
     to prefix the “[1me[22m” 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 back‐
     slash’s common use as a [4mroff[24m escape  character——perhaps  in  discussion  of
     character sets or other programming languages——is the special character es‐
     cape  sequence  [1m\(rs  [22mor [1m\[rs][22m, for “reverse solidus”, from its name in the
     ECMA‐6 and ISO 10646 standards.  [AT&T [4mtroff[24m [4m’s[24m font description files  did
     not  define  the [1mrs [22mspecial character, but those of its descendant Heirloom
     Doctools [4mtroff[24m do, as of its 060716 release (July 2006).]

     To store an escape sequence in a diversion that is interpreted when the di‐
     version is interpolated, either use the traditional [1m\!  [22mtransparent  output
     facility,  or, if this is unsuitable, the new [1m\? [22mescape sequence.  See sub‐
     section “Escape sequences” above and sections “Diversions” and  “GNU  troff
     Internals”  in  [4mGroff:[24m  [4mThe[24m  [4mGNU[24m [4mImplementation[24m [4mof[24m [4mtroff[24m, the [4mgroff[24m Texinfo
     manual.

     Like AT&T [4mtroff,[24m GNU [4mtroff[24m maintains a buffer of device‐independent  output
     commands, populating the buffer as formatted output accumulates.  GNU [4mtroff[0m
     always  flushes this buffer when processing a break; AT&T [4mtroff[24m does so ac‐
     cording to no obvious schedule (perhaps, if the buffer is  of  fixed  size,
     the formatter performs the flush when the buffer runs out of room).

     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 [4mtroff[24m outputs a partially collected but
     otherwise empty line (as if “[1m\c[22m” were in the top‐level  diversion)  at  the
     end of input; GNU [4mtroff[24m does not.

   [1mFormatter output incompatibilities[0m
     Its  extensions  notwithstanding, GNU [4mtroff[24m’s page description language has
     some incompatibilities with that of AT&T [4mtroff[24m, but better compatibility is
     sought; problem reports and patches are welcome.  The following  incompati‐
     bilities are known.

     •  The  drawing position after rendering polygons is inconsistent with AT&T
        [4mtroff[24m practice.  Other implementations have diverged on  this  point  as
        well.

     •  The  output  cannot  be easily rescaled to other devices as AT&T [4mtroff[24m’s
        could.

[1mAuthors[0m
     This document was written by ]8;;mailto:jjc@jclark.com\James Clark]8;;\, ]8;;mailto:wl@gnu.org\Werner Lemberg]8;;\, ]8;;mailto:groff-bernd.warken-72@web.de\Bernd Warken]8;;\, and
     ]8;;mailto:g.branden.robinson@gmail.com\G. Branden Robinson]8;;\.

[1mSee also[0m
     [4mGroff:[24m [4mThe[24m [4mGNU[24m [4mImplementation[24m [4mof[24m [4mtroff[24m, by Trent A. Fisher and Werner  Lem‐
     berg,  is  the  primary [4mgroff[24m 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 page description language referred to
     collectively in [4mgroff[24m documentation as AT&T [4mtroff[24m.

     “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 page de‐
     scription language.

     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\, ]8;;man:roff(7)\[4mroff[24m(7)]8;;\

groff 1.24.1                       2026‐03‐20                      [4mgroff_diff[24m(7)
────────────────────────────────────────────────────────────────────────────────
[4mgroff_hdtbl[24m(7)          Miscellaneous Information Manual          [4mgroff_hdtbl[24m(7)

[1mName[0m
     groff_hdtbl - Heidelberger table macros for GNU [4mroff[0m

[1mDescription[0m
     The [4mhdtbl[24m macros consist of four base and three optional macros, controlled
     by about twenty arguments.  The syntax is simple and similar  to  the  HTML
     table  model  and  nearly  as  flexible:  you can write sequences of tokens
     (macro calls with their arguments and content data),  separated  by  blanks
     and  beginning  with  a  macro  call, into the same line to get compact and
     cleanly arranged input.  An advantage of [4mhdtbl[24m is that the tables are  con‐
     structed  without  calling  a preprocessor; this means that ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\’s full
     macro capabilities are available.  On the other hand, table processing with
     [4mhdtbl[24m is much slower than using the ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\ preprocessor.  A further  advan‐
     tage  is  that  the  HTML‐like  syntax of [4mhdtbl[24m will be easily converted to
     HTML; this is not implemented yet.

[1mUsage[0m
     In this and the next section, we present examples to help users  understand
     the  basic  workflow  of [4mhdtbl[24m.  First of all, you must load the [4mhdtbl.tmac[0m
     file.  As with nearly all other [4mgroff[24m macro packages, there are two  possi‐
     bilities to do so: Either add the line

            .mso hdtbl.tmac

     to  your [4mroff[24m file before using any macros of the [4mhdtbl[24m package, or add the
     option

            -m hdtbl

     to the command line of groff (before the document file which contains [4mhdtbl[0m
     macros).  Then you can include on or more tables in  your  document,  where
     each  one  must be started and ended with the .TBL and .ETB macros, respec‐
     tively.

     In this man page, we approximate the result of  each  example  as  terminal
     output to be as generic as possible since [4mhdtbl[24m currently only supports the
     [1mps [22mand [1mpdf [22moutput drivers.

     The  simplest  well‐formed  table consists of just single calls to the four
     base table macros in the right order.  Here we construct a table with  only
     one cell.

            .TBL
            .TR
            .TD
            [4mcontents[24m [4mof[24m [4mthe[24m [4mtable[24m [4mcell[0m
            .ETB

     A terminal representation is

            +------------------------------------------------------+
            | [4mcontents-of-the-table-cell[24m                           |
            +------------------------------------------------------+

     Equivalent to the above is the following notation.

            .TBL .TR .TD "[4mcontents[24m [4mof[24m [4mthe[24m [4mtable[24m [4mcell[24m" .ETB

     By  default,  the  formatted table is inserted into the surrounding text at
     the place of its definition.  If the vertical space isn’t sufficient, it is
     placed at the top of the next page.  Tables can also be  stored  for  later
     insertion.

     Using  ‘[4mrow‐number[24m*[4mcolumn‐number[24m’  as the data for the table cells, a table
     with two rows and two columns can be written as

            .TBL cols=2
            .  TR .TD 1*1 .TD 1*2
            .  TR .TD 2*1 .TD 2*2
            .ETB

     A terminal representation is

            +--------------------------+---------------------------+
            | 1*1                      | 1*2                       |
            +--------------------------+---------------------------+
            | 2*1                      | 2*2                       |
            +--------------------------+---------------------------+

     Here we see a difference from HTML tables: The number of  columns  must  be
     explicitly  specified  using  the  ‘cols=[4mm[24m’ argument (or indirectly via the
     ‘width’ argument, see below).

     The contents of a table cell is arbitrary; for example, it can  be  another
     table,  without restriction to the nesting depth.  A given table layout can
     be either constructed with suitably nested tables or with proper  arguments
     to  .TD  and .TH, controlling column and row spanning.  Note, however, that
     this table

            .TBL
            .  TR
            .    TD
            .      nop 1*1 1*2
            .  TR
            .    TD
            .      TBL cols=2 border=
            .        TR
            .          TD
            .            nop 2*1
            .          TD
            .            nop 2*2
            .      ETB
            .ETB

     and this table

            .TBL cols=2
            .  TR
            .    TD colspan=2
            .      nop 1*1 1*2
            .  TR
            .    TD
            .      nop 2*1
            .    TD
            .      nop 2*2
            .ETB

     are similar but not identical (the use of .nop is purely  cosmetic  to  get
     proper indentation).

     The first table looks like

            +------------------------------------------------------+
            | 1*1 1*2                                              |
            +------------------------------------------------------+
            |                                                      |
            | 2*1                         2*2                      |
            |                                                      |
            +------------------------------------------------------+

     and the second one like

            +------------------------------------------------------+
            | 1*1 1*2                                              |
            +---------------------------+--------------------------+
            | 2*1                       | 2*2                      |
            +---------------------------+--------------------------+

     Here is the latter table in a more compact form.

            .TBL cols=2 .TR ".TD colspan=2" 1*1 1*2
            .            TR .TD 2*1 .TD 2*2 .ETB

     If  a macro has one or more arguments (see below), and it is not starting a
     line, everything belonging to this macro including the macro itself must be
     enclosed in double quotes.

[1mMacros and arguments[0m
     The order of macro calls and other tokens follows the HTML model.   In  the
     following  list,  valid predecessors and successors of all [4mhdtbl[24m macros are
     given, together with the possible arguments.

     Macro arguments are separated by blanks.  The order of arguments  is  arbi‐
     trary; they are of the form

            key=[4mvalue[0m

     or

            key='[4mvalue1[24m [[4mvalue2[24m [...]]'

     with  the  only exception of the optional argument of the macro .ETB, which
     is the string ‘hold’.  Another possible form is

            "key=[4mvalue1[24m [[4mvalue2[24m [...]]"

     However, this is limited to the case where the macro is the  first  one  in
     the line and not already enclosed in double quotes.

     Argument values specified below as [4mc[24m are colors predefined by [4mgroff[24m or col‐
     ors  defined by the user with the .defcolor request.  Argument values [4md[24m are
     decimal numbers with or without decimal point.  Argument values [4mm[24m are  nat‐
     ural  numbers.  Argument values [4mn[24m are numerical values with the usual [4mgroff[0m
     scaling indicators.  Some of the arguments  are  specific  to  one  or  two
     macros,  but  most  of  them can be specified with .TBL, .TR, .TD, and .TH.
     These common arguments are explained in the next subsection.

     Most of the argument default values can be changed by the user  by  setting
     corresponding default registers or strings, as listed below.

     [1m.TBL [22m[[4margs[24m]
            Begin a new table.

            [1mpredecessor: [22m.TD, .TH, .ETB, cell contents
            [1msuccessor: [22m.CPTN, .TR
            [1marguments:[0m

                   border=[[4mn[24m]
                          Thickness  of  the  surrounding box border.  ‘border=’
                          (no value) means neither a surrounding box border  nor
                          any horizontal or vertical separator lines between the
                          table  rows and cells.  ‘border=0’ suppresses the sur‐
                          rounding box border, but still allows separator  lines
                          between cells and rows.
                          [1mDefault: [22m‘border=.1n’ (register ‘t*b’).

                   bc=[4mc[24m   Border color.
                          [1mDefault: [22m‘bc=red4’ (string ‘t*bc’).

                   cols=[4mm[0m
                          Number  of  table columns.  This argument is necessary
                          if more than one column is in the table and no ‘width’
                          arguments are present.
                          [1mDefault: [22m‘cols=1’ (register ‘t*cols’).

                   cpd=[4mn[24m  Cell padding, i.e., the extra space between  the  cell
                          space border and the cell contents.
                          [1mDefault: [22m‘cpd=.5n’ (register ‘t*cpd’).

                   csp=[4mn[24m  Cell  spacing, i.e., the extra space between the table
                          border or vertical or horizontal lines  between  cells
                          and the cellspace.
                          [1mDefault: [22m‘csp=.5n’ (register ‘t*csp’).

                   tal=l|c|r
                          Horizontal  alignment  of  the table, if it is smaller
                          than  the  line  width.   ‘tal=l’:   left   alignment.
                          ‘tal=c’:  centered  alignment.   ‘tal=r’: right align‐
                          ment.
                          [1mDefault: [22m‘tal=l’ (register ‘t*tal’).

                   width='[4mw1[24m [[4mw2[24m [...]]'
                          Widths of table cells.  [4mw1[24m, [4mw2[24m, ... are either numbers
                          of type [4mn[24m or natural numbers with  the  pseudo‐scaling
                          indicator ‘%’, with the meaning “percent of the actual
                          line  length  (or  column length for inner tables, re‐
                          spectively)”.  If there are less width values than ta‐
                          ble columns, the last width value is used for the  re‐
                          maining cells.  The argument

                                 width='1.5i 10%'

                          for   example  indicates  that  the  first  column  is
                          1.5 inches wide; the remaining columns  take  1/10  of
                          the column length each.
                          [1mDefault:  [22mThe table width equals the outer line length
                          or column length; the columns have equal widths.

                   height=[4mn[0m
                          Height of the table.  If the table with  its  contents
                          is  lower  than  [4mn[24m,  the last row is stretched to this
                          value.

     [1m.CPTN [22m[[4margs[24m]
            Text of caption.

            The (optionally numbered) table caption.  .CPTN is optional.

            [1mpredecessor: [22m.TBL
            [1msuccessor: [22m.TR
            [1marguments:[0m

                   val=t|b
                          Vertical alignment of the table caption.  ‘val=t’: The
                          caption is placed above the table.  ‘val=b’: The  cap‐
                          tion is placed below the table.
                          [1mDefault: [22m‘val=t’ (string ‘t*cptn’).

     [1m.TR [22m[[4margs[24m]
            Begin a new table row.

            [1mpredecessor: [22m.TBL, .CPTN, .TD, .TH, .ETB, cell contents
            [1msuccessor: [22m.TD, .TH
            [1marguments:[0m

                   height=[4mn[0m
                          The height of the row.  If a cell in the row is higher
                          than  [4mn[24m,  this  value  is  ignored;  otherwise the row
                          height is stretched to [4mn[24m.

     [1m.TD [22m[[4margs[24m [[4mcell[24m [4mcontents[24m]]
            Begin a table data cell.
     [1m.TH [22m[[4margs[24m [[4mcell[24m [4mcontents[24m]]
            Begin a table header cell.

            Arguments and cell contents can be mixed.  The macro .TH is not  re‐
            ally  necessary and differs from .TD only in three default settings,
            similar to the <TH> and <TD> HTML tags: The contents of .TH is hori‐
            zontally and vertically centered and typeset in boldface.

            [1mpredecessor: [22m.TR, .TD, .TH, .ETB, cell contents
            [1msuccessor: [22m.TD, .TH, .TR, .ETB, cell contents
            [1marguments:[0m

                   colspan=[4mm[0m
                          The width of this cell is the sum  of  the  widths  of
                          the [4mm[24m cells above and below this row.

                   rowspan=[4mm[0m
                          The  height  of this cell is the sum of the heights of
                          the [4mm[24m cells left and right of this column.

                          [1mRemark: [22mOverlapping of column and row spanning, as  in
                          the  following table fragment (the overlapping happens
                          in the second cell in the second row), is invalid  and
                          causes incorrect results.

                                 .TR .TD 1*1 ".TD 1*2 rowspan=2" .TD 1*3
                                 .TR ".TD 2*1 colspan=2"         .TD 2*3

                   A working example for headers and cells with [1mcolspan [22mis

                          .TBL cols=3
                          .  TR ".TH colspan=2" header1+2 .TH header3
                          .  TR .TD 1*1 .TD 1*2 .TD 1*3
                          .  TR .TD 2*1 ".TD colspan=2" 2*2+3
                          .ETB

                   This looks like

                          +------------------------------+---------------+
                          |          header1+2           |    header3    |
                          +--------------+---------------+---------------+
                          | 1*1          | 1*2           | 1*3           |
                          +--------------+---------------+---------------+
                          | 2*1          | 2*2+3                         |
                          +--------------+-------------------------------+

                   A working example with [1mrowspan [22mis

                          .TBL cols=3
                          .  TR
                          .  TD 1*1
                          .  TD rowspan=2 1+2*2
                          .  TD 1*3
                          .
                          .  TR
                          .  TD 2*1
                          .  TD 2*3
                          .ETB

                   which looks like

                          +--------------+---------------+---------------+
                          | 1*1          | 1+2*2         | 1*3           |
                          +--------------+               +---------------+
                          | 2*1          |               | 2*3           |
                          +--------------+---------------+---------------+

     [1m.ETB [22m[[1mhold[22m]
            End of the table.

            This  macro  finishes  a  table.  It causes one of the following ac‐
            tions.

            •  If the argument ‘hold’ is given, the table is held  until  it  is
               freed  by calling the macro .t*free, which in turn prints the ta‐
               ble immediately, either at the current position or at the top  of
               the next page if its height is larger than the remaining space on
               the page.

            •  Otherwise, if the table is higher than the remaining space on the
               page, it is printed at the top of the next page.

            •  If  neither  of  the  two  above  constraints  hold, the table is
               printed immediately at the place of its definition.

            [1mpredecessor: [22m.TD, .TH, .ETB, cell contents
            [1msuccessor: [22m.TBL, .TR, .TD, .TH, .ETB, cell contents
            [1marguments:[0m

                   hold   Prevent the table from being printed until it is freed
                          by calling the macro .t*free.  This  argument  is  ig‐
                          nored for inner (nested) tables.

     [1m.t*free [22m[[4mn[24m]
            Free  the next held table or [4mn[24m held tables.  Call this utility macro
            to print tables which are held by using the ‘hold’ argument  of  the
            .ETB macro.

   [1mArguments common to .TBL, .TR, .TD, and .TH[0m
     The  arguments described in this section can be specified with the .TBL and
     .TR macros, but they are eventually passed on to the table cells.  If omit‐
     ted, the defaults take place, which the user can change by setting the cor‐
     responding default registers or strings, as documented below.   Setting  an
     argument with the .TBL macro has the same effect as setting it for all rows
     in  the table.  Setting an argument with a .TR macro has the same effect as
     setting it for all the .TH or .TD macro in this row.

     bgc=[[4mc[24m]
            The background color of the table cells.   This  includes  the  area
            specified  with  the ‘csp’ argument.  The argument ‘bgc=’ (no value)
            suppresses a background color; this makes the  background  transpar‐
            ent.
            [1mDefault: [22m‘bgc=bisque’ (string ‘t*bgc’).

     fgc=[4mc[24m  The foreground color of the cell contents.
            [1mDefault: [22m‘fgc=red4’ (string ‘t*fgc’).

     ff=[4mname[0m
            The  font family for the table.  [4mname[24m is a [4mgroff[24m font family identi‐
            fier, such as A for Avant Garde or HN for Helvetica Narrow.
            [1mDefault: [22mThe font family found before the table (string ‘t*ff’).

     fst=[4mstyle[0m
            The font style for the table.  One of R, B,  I,  or  BI  for  roman,
            [1mbold[22m,  [4mitalic[24m, or [4m[1mbold[24m [4mitalic[24m[22m, respectively.  As with [4mroff[24m’s [1m.ft [22mre‐
            quest, the ‘fst’ argument can be used to specify the font family and
            font style together, for example ‘fst=HNBI’ instead of  ‘ff=HN’  and
            ‘fst=BI’.
            [1mDefault:  [22mThe  font  style  in  use  right  before the table (string
            ‘t*fst’).

     fsz='[4md1[24m [[4md2[24m]'
            A decimal or fractional factor [4md1[24m, by which the point size  for  the
            table  is  changed,  and  [4md2[24m,  by which the vertical line spacing is
            changed.  If [4md2[24m is omitted, value [4md1[24m is taken for both.
            [1mDefault: [22m‘fsz='1.0 1.0'’ (string ‘t*fsz’).

     hal=l|c|b|r
            Horizontal alignment of the cell contents in  the  table.   ‘hal=l’:
            left  alignment.   ‘hal=c’: centered alignment.  ‘hal=b’: both (left
            and right) alignment.  ‘hal=r’: right alignment.
            [1mDefault: [22m‘hal=b’ (string ‘t*hal’).

     val=t|m|b
            Vertical alignment of the cell contents in the table for cells lower
            than the current row.  ‘val=t’: alignment below the top of the cell.
            ‘val=m’: alignment in the middle of the  cell.   ‘val=b’:  alignment
            above the cell bottom.
            [1mDefault: [22m‘val=t’ (string ‘t*val’).

     hl=[s|d]
            Horizontal line between the rows.  If specified with .TD or .TH this
            is a separator line to the cell below.  ‘hl=’ (no value): no separa‐
            tor  line.   ‘hl=s’:  a  single  separator  line  between  the rows.
            ‘hl=d’: a double separator line.

            The thickness of the separator lines  is  the  half  of  the  border
            thickness, but at least 0.1 inches.  The distance between the double
            lines is equal to the line thickness.

            [1mRemark:  [22mTogether with ‘border=0’ for proper formatting the value of
            ‘csp’ must be at least .05 inches for  single  separator  lines  and
            .15 inches for double separator lines.
            [1mDefault: [22m‘hl=s’ (string ‘t*hl’).

     vl=[s|d]
            Vertical separator line between the cells.  If specified with .TD or
            .TH  this  is  a separator line to the cell on the right.  ‘vl=s’: a
            single separator line between the cells.  ‘vl=d’: a double separator
            line.  ‘vl=’ (no value): no vertical cell separator lines.  For more
            information see the documentation of the ‘hl’ argument above.
            [1mDefault: [22m‘vl=s’ (string ‘t*vl’).

[4m[1mhdtbl[24m customization[0m
     Before creating the first table, you should  configure  default  values  to
     minimize  the  markup  needed in each table.  The following example sets up
     defaults suitable for typical papers:

            .ds t*bgc white\" background color
            .ds t*fgc black\" foreground color
            .ds t*bc black\"  border color
            .nr t*cpd 0.1n\"  cell padding

     The  file  [4m/usr/share/doc/groff-1.24.1/examples/hdtbl/common.roff[24m  provides
     another example setup in the “minimal Page setup” section.

     A  table which does not fit on a partially filled page is printed automati‐
     cally on the top of the next page if you append the  little  utility  macro
     t*hm  to  the page header macro of your document’s main macro package.  For
     example, say

            .am pg@top
            .  t*hm
            ..

     if you use the [4mms[24m macro package.

     The macro t*EM checks for held or kept tables, and for missing  ETB  macros
     (table not closed).  You can call this macro by appending it the to end‐of‐
     input  macro  of  the  main, or “full‐service”, macro package your document
     uses.  For example, try
            .am pg@end-text
            .  t*EM
            ..
     if you use the [4mms[24m package.

[1mBugs and suggestions[0m
     Please send your comments to the ]8;;mailto:groff@gnu.org\[4mgroff[24m mailing list]8;;\ or directly to the  au‐
     thor.

[1mAuthors[0m
     The [4mhdtbl[24m macro package was written by ]8;;mailto:Joachim.Walsdorff@urz.uni-heidelberg.de\Joachim Walsdorff]8;;\.

[1mSee also[0m
     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\
            provides  an overview of GNU [4mroff[24m and details how to invoke [4mgroff[24m at
            the command line.

     ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\
            summarizes the [4mroff[24m language and GNU extensions to it.

     ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\
            describes the traditional [4mroff[24m preprocessor for tables.

groff 1.24.1                       2026‐03‐20                     [4mgroff_hdtbl[24m(7)
────────────────────────────────────────────────────────────────────────────────
[4mgroff_man[24m(7)            Miscellaneous Information Manual            [4mgroff_man[24m(7)

[1mName[0m
     groff_man - compose manual pages with GNU [4mroff[0m

[1mSynopsis[0m
     [1mgroff -man [22m[[4moption[24m ...] [[4mfile[24m ...]
     [1mgroff -m man [22m[[4moption[24m ...] [[4mfile[24m ...]

[1mDescription[0m
     The GNU implementation of the [4mman[24m macro package is part of the [4mgroff[24m  docu‐
     ment  formatting  system.  It is used to compose manual pages (“man pages”)
     like the one you are reading.  This document presents the  macros  themati‐
     cally;  for those needing only a quick reference, the following table lists
     them alphabetically, with references to appropriate subsections below.

     Readers  who  are  not  already  experienced  [4mgroff[24m  users  should  consult
     ]8;;man:groff_man_style(7)\[4mgroff_man_style[24m(7)]8;;\,  an  expanded  version of this document, for additional
     explanations and advice.  It covers only those concepts  required  for  man
     page  document  maintenance, and not the full breadth of the [4mgroff[24m typeset‐
     ting system.

     Macro   Meaning                      Subsection
     ───────────────────────────────────────────────────────────────
     [1m.B      [22mBold                         Font style macros
     [1m.BI     [22mBold, italic alternating     Font style macros
     [1m.BR     [22mBold, roman alternating      Font style macros
     [1m.EE     [22mExample end                  Document structure macros
     [1m.EX     [22mExample begin                Document structure macros
     [1m.HP     [22mBegin hanging paragraph      Paragraphing macros
     [1m.I      [22mItalic                       Font style macros
     [1m.IB     [22mItalic, bold alternating     Font style macros
     [1m.IP     [22mIndented paragraph           Paragraphing macros
     [1m.IR     [22mItalic, roman alternating    Font style macros
     [1m.LP     [22mBegin paragraph              Paragraphing macros
     [1m.ME     [22mMail‐to end                  Hyperlink macros
     [1m.MR     [22mMan page cross reference     Hyperlink macros
     [1m.MT     [22mMail‐to start                Hyperlink macros
     [1m.P      [22mBegin paragraph              Paragraphing macros
     [1m.PP     [22mBegin paragraph              Paragraphing macros
     [1m.RB     [22mRoman, bold alternating      Font style macros
     [1m.RE     [22mRelative inset end           Document structure macros
     [1m.RI     [22mRoman, italic alternating    Font style macros
     [1m.RS     [22mRelative inset start         Document structure macros
     [1m.SH     [22mSection heading              Document structure macros
     [1m.SM     [22mSmall                        Font style macros
     [1m.SS     [22mSubsection heading           Document structure macros
     [1m.SY     [22mSynopsis start               Synopsis macros
     [1m.TH     [22mTitle heading                Document structure macros
     [1m.TP     [22mTagged paragraph             Paragraphing macros
     [1m.TQ     [22mSupplemental paragraph tag   Paragraphing macros
     [1m.UE     [22mURI end                      Hyperlink macros
     [1m.UR     [22mURI start                    Hyperlink macros
     [1m.YS     [22mSynopsis end                 Synopsis macros

     We discuss other macros ([1mAT[22m, [1mDT[22m, [1mOP[22m, [1mPD[22m, [1mSB[22m, and [1mUC[22m) in subsection  “Depre‐
     cated features” below.

     Throughout  Unix  documentation,  a manual entry is referred to simply as a
     “man page”, regardless of its length, without gendered implication, and ir‐
     respective of the macro package selected for its composition.

   [1mMacro reference preliminaries[0m
     A tagged paragraph describes each macro.   We  present  coupled  pairs  to‐
     gether, as with [1mEX [22mand [1mEE[22m.  If you require an empty macro argument, specify
     it  as a pair of neutral double quotes ([1m""[22m).  Most macro arguments are for‐
     matted as text in the output; exceptions are noted.

   [1mDocument structure macros[0m
     Document structure macros organize a man page’s content.  All of them break
     the output line.  [1mTH [22m(title heading) identifies the document as a man  page
     and configures the page headers and footers.  Section headings ([1mSH[22m), one of
     which  is  mandatory and many of which are conventionally expected, facili‐
     tate location of material by the reader and aid the man page writer to dis‐
     cuss all essential aspects of the topics  presented.   Subsection  headings
     ([1mSS[22m)  are  optional and permit sections that grow long to develop in a con‐
     trolled way.  Many technical discussions  benefit  from  examples;  lengthy
     ones, especially those reflecting multiple lines of input to or output from
     the  system, are usefully bracketed by [1mEX [22mand [1mEE[22m.  When none of the forego‐
     ing meets a structural demand,  use  [1mRS[22m/[1mRE  [22mto  inset  a  region  within  a
     (sub)section.

     [1m.TH [4m[22midentifier[24m [4msection[24m [[4mfooter‐middle[24m [[4mfooter‐inside[24m [[4mheader‐middle[24m]]]
            Break  the  page, reset the page number to 1 (unless the [1m-rC1 [22moption
            is given), and use the arguments to populate  the  page  header  and
            footer.  Together, [4midentifier[24m and the [4msection[24m of the manual to which
            it  belongs can uniquely identify a [4mman[24m document on the system.  See
            ]8;;man:man(1)\[4mman[24m(1)]8;;\ or ]8;;man:intro(1)\[4mintro[24m(1)]8;;\ for the manual sectioning applicable to your sys‐
            tem.  [4midentifier[24m and [4msection[24m are positioned at the left and right in
            the header; the latter is set after the former, in  parentheses  and
            without  space.   [4mfooter‐middle[24m  is  centered in the footer.  By de‐
            fault, [4mfooter‐inside[24m is positioned at the bottom left.  Use  of  the
            double‐sided  layout  option [1m-rD1 [22mplaces [4mfooter‐inside[24m at the bottom
            left on recto (odd‐numbered) pages, and the bottom  right  on  verso
            (even‐numbered)  pages.   By default, the outside footer is the page
            number.  Use of the continuous‐rendering option [1m-rcR=1  [22mreplaces  it
            with  [4midentifier[24m  and  [4msection,[24m  as in the header.  [4mheader‐middle[24m is
            centered in the header.  If [4msection[24m is an integer between  1  and  9
            (inclusive), there is no need to specify [4mheader‐middle;[24m [4man.tmac[24m sup‐
            plies text for it.  If [4midentifier[24m or [4mfooter‐inside[24m would overrun the
            space available in the header and/or footer, this package may abbre‐
            viate  them with ellipses.  [4mgroff[24m [4mman[24m suppresses headers and footers
            in HTML output.

            A valid [4mman[24m document calls [1mTH [22monly once, early in the file, prior to
            any other macro calls.

     [1m.SH [22m[[4mheading‐text[24m]
            Set [4mheading‐text[24m as a section heading.  Given no argument, [1mSH [22mplants
            a one‐line input trap; text on the next line  becomes  [4mheading‐text.[0m
            The heading text is set in bold (or the font specified by the string
            [1mHF[22m),  and,  on typesetters, slightly larger than the base type size.
            If the heading font [1m\*[HF] [22mis bold, use of an italic style in  [4mhead‐[0m
            [4ming‐text[24m is mapped to the bold‐italic style if available in the font
            family.   The  inset level is reset to 1; see subsection “Horizontal
            and vertical spacing” below.  Text lines after the call are  set  as
            an ordinary paragraph ([1mP[22m).

            The  content  of [4mheading‐text[24m and ordering of sections follows a set
            of common practices, as does much of the layout of  material  within
            sections.   For  example, a section called “Name” or “NAME” must ex‐
            ist, must be the first section after the [1mTH [22mcall, and  must  contain
            only text of the form
                   [4mtopic[24m[[1m, [4m[22manother‐topic[24m]... \- [4msummary‐description[0m
            for tools like ]8;;man:makewhatis(8)\[4mmakewhatis[24m(8)]8;;\ or ]8;;man:mandb(8)\[4mmandb[24m(8)]8;;\ to index them.

     [1m.SS [22m[[4msubheading‐text[24m]
            Set  [4msubheading‐text[24m as a subsection heading indented between a sec‐
            tion heading and an ordinary paragraph ([1mP[22m).  Given no  argument,  [1mSS[0m
            plants a one‐line input trap; text on the next line becomes [4msubhead‐[0m
            [4ming‐text.[24m  The subheading text is set in bold (or the font specified
            by  the  string  [1mHF[22m).  If the heading font [1m\*[HF] [22mis bold, use of an
            italic style in [4msubheading‐text[24m is mapped to the  bold‐italic  style
            if available in the font family.  The inset level is reset to 1; see
            subsection  “Horizontal and vertical spacing” below.  Text lines af‐
            ter the call are set as an ordinary paragraph ([1mP[22m).

     [1m.EX[0m
     [1m.EE    [22mBegin and end example.  After [1mEX[22m, filling is disabled (and, on type‐
            setters, a monospaced font family is selected).  Calling [1mEE  [22menables
            filling (and restores the previous family).

            Ninth  Edition  Unix  introduced  the  [1mEX  [22mand [1mEE [22mextensions.  Docu‐
            menter’s Workbench (DWB), Heirloom Doctools, and Plan 9 [4mtroff[24ms,  and
            [4mmandoc[24m (since 1.12.2) support them.  Solaris [4mtroff[24m does not.

     [1m.RS [22m[[4minset‐amount[24m]
            Start  new  relative  inset.  [4mman[24m saves any current inset amount and
            moves right by: [4minset‐amount,[24m if specified; the  [4mindentation[24m  amount
            of  the preceding [1mIP[22m, [1mTP[22m, or [1mHP [22mmacro call if no (sub‐)sectioning or
            ordinary paragraphing macro has intervened; or the amount of the  [1mIN[0m
            register.  [1mRS [22mcalls can nest; each increments by 1 the [4mlevel[24m used by
            [1mRE[22m.  The level prior to any [1mRS [22mcall is 1.

     [1m.RE [22m[[4minset‐level[24m]
            End a relative inset, reducing it to that of [4minset‐level[24m (or by 1 if
            not specified) and restoring the corresponding inset amount.

   [1mParagraphing macros[0m
     These  macros break the output line.  An [4mordinary[24m paragraph ([1mP[22m) indents all
     output lines by the same amount.  A hanging paragraph ([1mHP[22m)  is  a  cosmetic
     variant  of  [1mP [22mwith a hanging indent.  Definition lists frequently occur in
     man pages; these can be set as [4mtagged[24m [4mparagraphs,[24m which have  one  ([1mTP[22m)  or
     more  ([1mTQ[22m)  leading tags followed by a paragraph that has an additional in‐
     dentation.  The indented paragraph ([1mIP[22m) macro  can  continue  the  indented
     content  of  a narrative started with [1mTP[22m, or present an itemized or ordered
     list.  If a paragraphing macro has been called since [1mSH [22mor [1mSS[22m,  all  except
     [1mTQ  [22mfollow  the  break  with vertical space (in an amount configured by the
     deprecated [1mPD [22mmacro); see subsection “Horizontal and vertical spacing”  be‐
     low.  Except for [1mTQ[22m, these macros reset the type size, hyphenation, and ad‐
     justment to (configured) defaults, and the font style to roman.

     [1m.P[0m
     [1m.LP[0m
     [1m.PP    [22mBegin a new paragraph; these macros are synonymous.  Any indentation
            from use of [1mIP[22m, [1mTP[22m, or [1mHP [22mis cleared.  The inset amount, as affected
            by [1mRS [22mand [1mRE[22m, is not.

     [1m.HP [22m[[4mindentation[24m]
            Set  a  paragraph  with a hanging indentation.  Text on output lines
            after the first is indented by [4mindentation,[24m if specified, and by the
            amount of the [1mIN [22mregister otherwise.

            [4mCaution:[24m A hanging indentation  cannot  be  expressed  naturally  in
            (pure)  HTML, a hanging paragraph is not distinguishable from an or‐
            dinary one if it formats on only one output line, and non‐[4mroff[24m‐based
            man page interpreters may treat [1mHP [22mas an ordinary paragraph  anyway.
            Thus,  information or distinctions you mean to express with indenta‐
            tion may be lost.

     [1m.TP [22m[[4mindentation[24m]
            Set an indented paragraph with a leading unindented tag.  The  macro
            plants  a  one‐line  input  trap that honors the [1m\c [22mescape sequence;
            text on the next line becomes  the  tag,  set  without  indentation.
            Text  on  subsequent lines is indented by [4mindentation,[24m if specified,
            and by the amount of the [1mIN [22mregister otherwise.  If  the  tag,  plus
            the  “tag  spacing” stored in the [1mTS [22mregister (see section “Options”
            below) is wider than the indentation, the package  breaks  the  line
            after the tag.

     [1m.TQ    [22mSet  an  additional  tag  for a paragraph tagged with [1mTP[22m, planting a
            one‐line input trap as with [1mTP[22m.

            [1mTQ [22mis a GNU extension supported by Heirloom  Doctools  [4mtroff[24m  (since
            Git  snapshot  151218)  and  [4mmandoc[24m  (since  1.14.5) but not by DWB,
            Plan 9, or Solaris [4mtroff[24ms.

     [1m.IP [22m[[4mmark[24m [[4mindentation[24m]]
            Set an indented paragraph with  an  optional  mark.   Arguments,  if
            present, are handled as with [1mTP[22m, except that the [4mmark[24m argument to [1mIP[0m
            cannot include a macro call, and the tag separation amount stored in
            the [1mTS [22mregister is not enforced.

   [1mSynopsis macros[0m
     Use  [1mSY  [22mand [1mYS [22mto summarize syntax using familiar Unix conventions.  Heir‐
     loom Doctools [4mtroff[24m (since Git snapshot 151218) and [4mmandoc[24m  (since  1.14.5)
     support these GNU extensions; DWB, Plan 9, and Solaris [4mtroff[24ms do not.

     [1m.SY [4m[22mkeyword[24m [[4msuffix[24m]
            Begin  synopsis.  Adjustment and automatic hyphenation are disabled.
            If [1mSY [22mhas already been called without a corresponding [1mYS[22m, a break is
            performed.  [4mkeyword[24m and any [4msuffix[24m are set in bold.  When [4msuffix[24m  is
            present, the package sets the next word after it without intervening
            space.   If  a  break  is required in subsequent text (up to a para‐
            graphing, sectioning, or [1mYS [22mmacro call), lines after the  first  are
            indented.  Unless the previous synopsis’s indentation is reused (see
            [1mYS  [22mbelow),  output lines after the first indent by the width of the
            pending output line up to the end of [4mkeyword[24m plus a space,  if  [4mkey‐[0m
            [4mword[24m is the only argument, and up to the end of [4msuffix[24m otherwise.

     [1m.YS [22m[[4mreuse‐indentation[24m]
            End  synopsis,  breaking the line and restoring indentation, adjust‐
            ment, and hyphenation to their previous states.  If an  argument  is
            given,  the  indentation  corresponding  to  the previous [1mSY [22mcall is
            reused by the next [1mSY [22mcall instead of being computed.

   [1mHyperlink macros[0m
     Man page cross references are best presented with [1mMR[22m.  Mark email addresses
     with [1mMT[22m/[1mME [22mand other sorts of URI with [1mUR[22m/[1mUE[22m.  To hyperlink text, terminals
     and pager programs  must  support  ECMA‐48  OSC  8  escape  sequences  (see
     ]8;;man:grotty(1)\[4mgrotty[24m(1)]8;;\).  When device support is unavailable or disabled with the [1mU [22mreg‐
     ister  (see  section “Options” below), [4mgroff[24m [4mman[24m renders these URIs between
     angle brackets ([1m⟨ ⟩[22m) after the linked text.

     [1mMT[22m, [1mME[22m, [1mUR[22m, and [1mUE [22mare GNU extensions supported by Heirloom Doctools  [4mtroff[0m
     (since  Git  snapshot  151218)  and [4mmandoc[24m ([1mUR[22m/[1mUE [22msince 1.12.3; [1mMT[22m/[1mME [22msince
     1.14.2) but not by DWB, Plan 9 (original), or Solaris [4mtroff[24ms.  Plan 9  from
     User Space’s [4mtroff[24m implements [1mMR[22m.

     Prepare arguments to [1mMR[22m, [1mMT[22m, and [1mUR [22mfor typesetting; they can appear in the
     output.   Use  special  character  escape sequences to encode Unicode basic
     Latin characters where necessary, particularly the hyphen‐minus.

     [1m.MR [4m[22mtopic[24m [[4mmanual‐section[24m [[4mtrailing‐text[24m]]
            [4m(since[24m groff [4m1.23)[24m Set a man page cross reference as  “[4mtopic[24m[1m([4m[22mmanual‐[0m
            [4msection[24m[1m)[22m”.   If [4mmanual‐section[24m is absent, the package omits the sur‐
            rounding parentheses.  If [4mtrailing‐text[24m (typically  punctuation)  is
            specified,  it  follows  the closing parenthesis without intervening
            space.  Hyphenation is disabled while the cross  reference  is  set.
            [4mtopic[24m is set in the font specified by the [1mMF [22mstring.  If [4mmanual‐sec‐[0m
            [4mtion[24m is present, the cross reference hyperlinks to a URI of the form
            “[1mman:[4m[22mtopic[24m([4mmanual‐section[24m)”.

     [1m.MT [4m[22maddress[0m
     [1m.ME [22m[[4mtrailing‐text[24m]
            Identify  [4maddress[24m  as an RFC 6068 [4maddr‐spec[24m for a “mailto:” URI with
            the text between the two macro calls as the link text.  An  argument
            to  [1mME [22mis placed after the link text without intervening space.  [4mad‐[0m
            [4mdress[24m may not be visible in the rendered document if hyperlinks  are
            enabled  and  supported  by the output driver.  If they are not, [4mad‐[0m
            [4mdress[24m is set in angle brackets after the link text and before [4mtrail‐[0m
            [4ming‐text.[24m  If hyperlinking is enabled but there is no link text, [4mad‐[0m
            [4mdress[24m is formatted and hyperlinked [4mwithout[24m  angle  brackets,  except
            when [4maddress[24m appears as a [1mTP [22mparagraph tag.

     [1m.UR [4m[22muri[0m
     [1m.UE [22m[[4mtrailing‐text[24m]
            Identify  [4muri[24m as an RFC 3986 URI hyperlink with the text between the
            two macro calls as the link text.  An argument to [1mUE [22mis placed after
            the link text without intervening space.  [4muri[24m may not be visible  in
            the rendered document if hyperlinks are enabled and supported by the
            output  driver.  If they are not, [4muri[24m is set in angle brackets after
            the link text and before [4mtrailing‐text.[24m  If hyperlinking is  enabled
            but  there is no link text, [4muri[24m is formatted and hyperlinked [4mwithout[0m
            angle brackets, except when [4muri[24m appears as a [1mTP [22mparagraph tag.

     If a [1mUR[22m/[1mUE [22mor [1mMT[22m/[1mME [22mpair occurs in a [1mTP [22mtag and  hyperlinking  is  unavail‐
     able, [4mgroff[24m [4mman[24m sets the link target at the beginning of the indented para‐
     graph, not as part of the tag, unless there is no link text.

   [1mFont style macros[0m
     The [4mman[24m macro package is limited in its font styling options, offering only
     [1mbold  [22m([1mB[22m),  [4mitalic[24m  ([1mI[22m),  and roman.  Italic text may instead render under‐
     scored on terminals.  [1mSM [22msets text at a smaller type  size,  which  differs
     visually  from  regular‐sized text only on typesetters.  The macros [1mBI[22m, [1mBR[22m,
     [1mIB[22m, [1mIR[22m, [1mRB[22m, and [1mRI [22mset their odd‐ and even‐numbered arguments  as  text  in
     the alternating styles their names indicate, with no space separating them.

     The  default type size and family for typesetters is 10‐point Times, except
     on the [1mX75-12 [22mand [1mX100-12 [22mdevices where the type size is  12  points.   The
     default style is roman.

     [1m.B [22m[[4mtext[24m]
            Set  [4mtext[24m  in  bold.   Given  no argument, [1mB [22mplants a one‐line input
            trap; text on the next line, which can be further formatted  with  a
            macro, is set in bold.

     [1m.I [22m[[4mtext[24m]
            Set  [4mtext[24m in an italic or oblique face.  Given no argument, [1mI [22mplants
            a one‐line input trap; text on the next line, which can  be  further
            formatted with a macro, is set in an italic or oblique face.

     [1m.SM [22m[[4mtext[24m]
            Set  [4mtext[24m  one  point smaller than the default type size on typeset‐
            ters.  Given no argument, [1mSM [22mplants a one‐line input trap;  text  on
            the  next  line, which can be further formatted with a macro, is set
            smaller.

     Unlike the above font style macros, the font style alternation macros below
     set no input traps; they must be given arguments to have effect.  They  ap‐
     ply italic corrections as appropriate.

     [1m.BI [4m[22mbold‐text[24m [4mitalic‐text[24m ...
            Set each argument in bold and italics, alternately.

     [1m.BR [4m[22mbold‐text[24m [4mroman‐text[24m ...
            Set each argument in bold and roman, alternately.

     [1m.IB [4m[22mitalic‐text[24m [4mbold‐text[24m ...
            Set each argument in italics and bold, alternately.

     [1m.IR [4m[22mitalic‐text[24m [4mroman‐text[24m ...
            Set each argument in italics and roman, alternately.

     [1m.RB [4m[22mroman‐text[24m [4mbold‐text[24m ...
            Set each argument in roman and bold, alternately.

     [1m.RI [4m[22mroman‐text[24m [4mitalic‐text[24m ...
            Set each argument in roman and italics, alternately.

   [1mHorizontal and vertical spacing[0m
     The  package sets all text inboard of the left edge of the output medium by
     the amount of the [4mpage[24m [4moffset;[24m see register [1mPO [22min section “Options”  below.
     Headers,  footers  (both set with [1mTH[22m), and section headings ([1mSH[22m) lie at the
     page offset.  [4mgroff[24m [4mman[24m indents subsection headings ([1mSS[22m) by the  amount  in
     the [1mSN [22mregister.

     Ordinary  paragraphs  not  within  an  [1mRS[22m/[1mRE  [22minset region are inset by the
     amount stored in the [1mBP [22mregister; see section “Options” below.  The [1mIN [22mreg‐
     ister configures the default indentation amount used by [1mRS [22m(as  the  [4minset‐[0m
     [4mamount[24m),  [1mIP[22m,  [1mTP[22m,  and  [1mHP[22m; an overriding argument is a number plus an op‐
     tional scaling unit.  If no scaling unit is given, the [4mman[24m package  assumes
     “n”.   An  indentation  specified in a call to [1mIP[22m, [1mTP[22m, or [1mHP [22mpersists until
     (1) another of these macros is called with an [4mindentation[24m argument, or  (2)
     [1mSH[22m,  [1mSS[22m,  or  [1mP  [22mor its synonyms is called; these clear the indentation en‐
     tirely.

     Several macros insert vertical space: [1mSH[22m, [1mSS[22m, [1mTP[22m, [1mP [22m(and its synonyms), [1mIP[22m,
     and [1mHP[22m.  They then enable [4mno‐space[24m [4mmode;[24m see ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\.  The default  inter‐
     section  and inter‐paragraph spacing is 1v for terminals and 0.4v for type‐
     setters.  (The deprecated macro [1mPD [22mcan change this vertical spacing, but we
     discourage its use.)  Between [1mEX [22mand [1mEE [22mcalls, the inter‐paragraph  spacing
     is 1v regardless of output device.

   [1mRegisters[0m
     Registers  are  described  in section “Options” below.  They can be set not
     only on the command line but in the site [4mman.local[24m file as well;  see  sec‐
     tion “Files” below.

   [1mStrings[0m
     The  following  strings are defined for use in man pages.  None of these is
     necessary in a contemporary man page; see  ]8;;man:groff_man_style(7)\[4mgroff_man_style[24m(7)]8;;\.   [4mgroff[24m  [4mman[0m
     supports others for configuration of rendering parameters; see section “Op‐
     tions” below.

     [1m\*R     [22minterpolates  a  special  character escape sequence for the “regis‐
             tered sign” glyph, [1m\(rg[22m, if available, and “(Reg.)” otherwise.

     [1m\*S     [22minterpolates an escape sequence setting the type size to the  docu‐
             ment default.

     [1m\*(lq[0m
     [1m\*(rq   [22minterpolate  special  character escape sequences for left and right
             double‐quotation marks, [1m\(lq [22mand [1m\(rq[22m, respectively.

     [1m\*(Tm   [22minterpolates a special character escape  sequence  for  the  “trade
             mark sign” glyph, [1m\(tm[22m, if available, and “(TM)” otherwise.

   [1mHooks[0m
     Two  macros,  both  GNU  extensions, are called internally by the [4mgroff[24m [4mman[0m
     package to format page headers and footers and can be redefined by the  ad‐
     ministrator  in  a  site’s [4mman.local[24m file (see section “Files” below).  The
     presentation of [1mTH [22mabove describes the default headers  and  footers.   Be‐
     cause  these  macros  are  hooks for [4mgroff[24m [4mman[24m internals, man pages have no
     reason to call them.  Such hook definitions typically consist of  “sp”  and
     “tl”  requests.   [1mPT  [22mfurthermore  has the responsibility of emitting a PDF
     bookmark after writing the first page header in a  document.   Consult  the
     existing implementations in [4man.tmac[24m when drafting replacements.

     [1m.BT    [22mSet the page footer text (“bottom trap”).

     [1m.PT    [22mSet the page header text (“page trap”).

     To remove a page header or footer entirely, define the appropriate macro as
     empty rather than deleting it.

   [1mDeprecated features[0m
     Use of the following in man pages for public distribution is discouraged.

     [1m.AT [22m[[4msystem[24m [[4mrelease[24m]]
            Alter  the footer for use with legacy AT&T man pages, overriding any
            definition of the [4mfooter‐inside[24m argument to [1mTH[22m.  This  macro  exists
            only to render man pages from historical systems.

            The inside footer is populated per the value of [4msystem.[0m

                   3      7th edition [4m(default)[0m

                   4      System III

                   5      System V

            The  optional  [4mrelease[24m  argument specifies the release number, as in
            “System V Release 3”.

     [1m.DT    [22mReset tab stops to the default (every 0.5i).

            Use of this presentation‐oriented macro is  deprecated.   It  trans‐
            lates poorly to HTML, under which exact space control and tabulation
            are  not  readily available.  Thus, information or distinctions that
            you use tab stops to express are likely to be  lost.   If  you  feel
            tempted  to  change the tab stops such that calling this macro later
            to restore them is  desirable,  consider  composing  a  table  using
            ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\ instead.

     [1m.OP [4m[22moption‐name[24m [[4moption‐argument[24m]
            Indicate  an optional command parameter called [4moption‐name[24m, which is
            set in bold.  If the option takes an argument, specify  [4moption‐argu‐[0m
            [4mment[24m  using  a  noun,  abbreviation,  or hyphenated noun phrase.  If
            present, [4moption‐argument[24m is preceded by a space and set in  italics.
            Square brackets in roman surround both arguments.

            Use of this quasi‐semantic macro, an extension whose name originated
            in DWB [4mtroff[24m, is deprecated; [4mgroff[24m’s interface differs.  Neither can
            easily  be  used to annotate options that take optional arguments or
            options whose arguments have internal structure (such as  a  mixture
            of  literal  and  variable components).  One could work around these
            limitations with font selection escape sequences, but font style al‐
            ternation macros are preferable; they are more flexible and  perform
            italic corrections on typesetters.

     [1m.PD [22m[[4mvertical‐space[24m]
            Configure  the  amount  of  vertical  space  between  paragraphs  or
            (sub)sections.  The optional argument [4mvertical‐space[24m  specifies  the
            amount;  the  default scaling unit is “v”.  Without an argument, in‐
            ter‐paragraph spacing resets to its default  value;  see  subsection
            “Horizontal and vertical spacing” above.

            Use  of  this  presentation‐oriented macro is deprecated.  It trans‐
            lates poorly to HTML, under which exact control  of  inter‐paragraph
            spacing is not readily available.  Thus, information or distinctions
            that you use [1mPD [22mto express are likely to be lost.

     [1m.SB [22m[[4mtext[24m]
            Set [4mtext[24m in bold and (on typesetters) one point smaller than the de‐
            fault  type  size.   Given  no  argument, [1mSB [22mplants a one‐line input
            trap; text on the next line, which can be further formatted  with  a
            macro,  is set smaller and in bold.  Use of this macro, an extension
            originating in SunOS 4.0 [4mtroff[24m, is deprecated.  [1mSM [22mwithout an  argu‐
            ment,  followed  immediately  by  “[1mB [4m[22mtext[24m”, produces the same output
            more portably.  The macros’ order is interchangeable; put [4mtext[24m  with
            the latter.

     [1m.UC [22m[[4mversion[24m]
            Alter  the  footer for use with legacy BSD man pages, overriding any
            definition of the [4mfooter‐inside[24m argument to [1mTH[22m.  This  macro  exists
            only to render man pages from historical systems.

            The inside footer is populated per the value of [4mversion.[0m

                   3      3rd Berkeley Distribution [4m(default)[0m

                   4      4th Berkeley Distribution

                   5      4.2 Berkeley Distribution

                   6      4.3 Berkeley Distribution

                   7      4.4 Berkeley Distribution

   [1mHistory[0m
     ]8;;mailto:m.douglas.mcilroy@dartmouth.edu\M.  Douglas  McIlroy]8;;\  designed,  implemented,  and  documented the AT&T [4mman[0m
     macros for Unix Version 7 (1979) and employed them to edit Volume 1 of  its
     [4mProgrammer’s[24m [4mManual[24m, a compilation of all man pages supplied by the system.
     The  package  supported the macros listed in this page not described as ex‐
     tensions, except [1mP [22mand the deprecated [1mAT [22mand [1mUC[22m.  It documented  no  regis‐
     ters and defined only [1mR [22mand [1mS [22mstrings.

     [1mUC  [22mappeared  in  3BSD (1980).  Unix System III (1980) introduced [1mP [22mand ex‐
     posed the registers [1mIN [22mand [1mLL[22m, which had been internal to  Seventh  Edition
     Unix  [4mman[24m.   PWB/Unix 2.0 (1980) added the [1mTm [22mstring.  4BSD (1980) added [1mlq[0m
     and [1mrq [22mstrings.  SunOS 2.0 (1985) recognized [1mC[22m,  [1mD[22m,  [1mP[22m,  and  [1mX  [22mregisters.
     4.3BSD  (1986) added [1mAT [22mand [1mP[22m.  Ninth Edition Unix (1986) introduced [1mEX [22mand
     [1mEE[22m.  SunOS 4.0 (1988) added [1mSB[22m.  Unix System V (1988) incorporated  the  [1mlq[0m
     and [1mrq [22mstrings.

     Except  for  [1mEX[22m/[1mEE[22m, James Clark implemented the foregoing features in early
     versions of [4mgroff.[24m  Later, [4mgroff[24m 1.20 (2009) resurrected [1mEX[22m/[1mEE  [22mand  origi‐
     nated  [1mSY[22m/[1mYS[22m,  [1mTQ[22m, [1mMT[22m/[1mME[22m, and [1mUR[22m/[1mUE[22m.  Plan 9 from User Space’s [4mtroff[24m intro‐
     duced [1mMR [22min 2020, and incorporated the [1mlq [22mand [1mrq [22mstrings in 2025.

[1mOptions[0m
     The following [4mgroff[24m options set registers (with [1m-r[22m) and strings  (with  [1m-d[22m)
     recognized  and used by the [4mman[24m macro package.  To ensure rendering consis‐
     tent with output device capabilities  and  reader  preferences,  man  pages
     should never manipulate them.

     [1m-dAD=[4m[22madjustment‐mode[0m
              Set line adjustment to [4madjustment‐mode,[24m which is typically “[1mb[22m” for
              adjustment  to  both margins (the default), or “[1ml[22m” for left align‐
              ment (ragged right margin).  Any valid argument  to  [4mgroff[24m’s  “ad”
              request may be used.  See ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\ for less‐common choices.

     [1m-rBP=[4m[22mbase‐paragraph‐inset[0m
              Set  the  inset amount for ordinary paragraphs not within an [1mRS[22m/[1mRE[0m
              inset.  The default is 5n.

     [1m-rcR=1   [22mEnable continuous rendering.  Output is  not  paginated;  instead,
              one (potentially very long) page is produced.  This is the default
              for terminal and HTML devices.  Use [1m-rcR=0 [22mto disable it on termi‐
              nals; on HTML devices, it cannot be disabled.

     [1m-rC1     [22mNumber  output  pages  consecutively,  in  strictly increasing se‐
              quence, rather than resetting the page number to 1 (or  the  value
              of register [1mP[22m) with each new [4mman[24m document.

     [1m-rCHECKSTYLE=[4m[22mn[0m
              Report  problems with usage of this macro package exhibited by the
              input at verbosity level [4mn[24m, where [4mn[24m is an  integer  in  the  range
              0–3,  inclusive; [1m0 [22mdisables the messages and is the default.  This
              feature is a development and debugging aid for man page  maintain‐
              ers;  the  problems  diagnosed, and range and meanings of the sup‐
              ported levels, are subject to change.

     [1m-rCS=1   [22mSet section headings (the argument(s) to  [1mSH[22m)  in  full  capitals.
              This  transformation is off by default because it discards letter‐
              case distinctions.

     [1m-rCT=1   [22mSet the man page identifier (the first argument  to  [1mTH[22m)  in  full
              capitals  in  headers  and footers.  This transformation is off by
              default because it discards lettercase distinctions.

     [1m-rD1     [22mEnable double‐sided layout, formatting footers for  even  and  odd
              pages  differently; see the description of [1mTH [22min subsection “Docu‐
              ment structure macros” above.

     [1m-rFT=[4m[22mfooter‐distance[0m
              Set distance of the footer relative to the bottom of the  page  to
              [4mfooter‐distance;[24m this amount is always negative.  At one half‐inch
              above  this  location,  the page text is broken before writing the
              footer.  Ignored if continuous rendering is enabled.  The  default
              is “-0.5i - 1v”.

     [1m-dHF=[4m[22mheading‐font[0m
              Select  the font used for section and subsection headings; the de‐
              fault is “[1mB[22m” (bold style of the default family).  Any valid  argu‐
              ment to [4mgroff[24m’s “ft” request may be used.  See ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\.

     [1m-rHY=0   [22mDisable  automatic hyphenation.  Normally, it is enabled (1).  The
              hyphenation mode is determined by the [4mgroff[24m  locale;  see  section
              “Localization“ of ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\.

     [1m-rIN=[4m[22mstandard‐indentation[0m
              Set the default indentation amount used by [1mIP[22m, [1mTP[22m, and [1mHP[22m, and the
              inset  amount used by [1mRS[22m.  The default is 7n on terminals and 7.2n
              on typesetters.  Use only integer multiples of unit “n” on  termi‐
              nals for consistent indentation.

     [1m-rLL=[4m[22mline‐length[0m
              Set line length; the default is 80n on terminals and 6.5i on type‐
              setters.

     [1m-rLT=[4m[22mtitle‐length[0m
              Set the line length for titles.  By default, it is set to the line
              length (see [1m-rLL [22mabove).

     [1m-dMF=[4m[22mman‐page‐topic‐font[0m
              Select the font used for man page identifiers in [1mTH [22mcalls and top‐
              ics named in [1mMR [22mcalls; the default is “[1mI[22m” (italic style of the de‐
              fault  family).  Any valid argument to [4mgroff[24m’s “ft” request may be
              used.  If the [1mMF [22mstring ends in “I”, the package assumes it to  be
              an oblique typeface, and applies italic corrections before and af‐
              ter man page topics and identifiers.

     [1m-rP[4m[22mn[24m     Start enumeration of pages at [4mn[24m.  The default is 1.

     [1m-rPO=[4m[22mpage‐offset[0m
              Set  page offset; the default is 0 on terminals and 1i on typeset‐
              ters.

     [1m-rS[4m[22mtype‐size[0m
              Use [4mtype‐size[24m for the document’s body text; acceptable values  are
              10,  11,  or  12 points.  See subsection “Font style macros” above
              for the default.

     [1m-rSN=[4m[22msubsection‐indentation[0m
              Set indentation of subsection headings to  [4msubsection‐indentation.[0m
              The default is 3n.

     [1m-rTS=[4m[22mseparation[0m
              Require  the given [4mseparation[24m between a [1mTP [22mparagraph’s tag and its
              body.  The default is 2n.

     [1m-rU0     [22mDisable generation of URI hyperlinks in output drivers capable  of
              them, making the arguments to [1mMT [22mand [1mUR [22mcalls visible as formatted
              text.   ]8;;man:grohtml(1)\[4mgrohtml[24m(1)]8;;\,  ]8;;man:gropdf(1)\[4mgropdf[24m(1)]8;;\, and ]8;;man:grotty(1)\[4mgrotty[24m(1)]8;;\ enable hyperlinks by
              default (the last only if not in its legacy output mode).

     [1m-rX[4m[22mp[24m     Number successors of page [4mp[24m as [4mp[24ma, [4mp[24mb, [4mp[24mc, and so forth.  The reg‐
              ister tracking the suffixed page letter uses format “a”  (see  the
              “af” request in ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\).

[1mFiles[0m
     [4m/usr/share/groff/1.24.1/tmac/an.tmac[0m
            Most  [4mman[24m macros are defined in this file.  It also loads extensions
            from [4man-ext.tmac[24m (see below).

     [4m/usr/share/groff/1.24.1/tmac/andoc.tmac[0m
            This brief [4mgroff[24m program detects whether the [4mman[24m or [4mmdoc[24m macro pack‐
            age is used by a document and loads the correct  macro  definitions,
            taking  advantage  of the fact that pages using them must call [1mTH [22mor
            [1mDd[22m, respectively, before any other macros.  A [4mman[24m program or a  user
            typing,  for  example,  “[1mgroff  -mandoc page.1[22m”, need not know which
            package the file [4mpage.1[24m uses.  Multiple man pages, in either format,
            can be handled; [4mandoc[24m  reloads  each  macro  package  as  necessary.
            Page‐local  redefinitions  of names used by the [4mman[24m or [4mmdoc[24m packages
            prior to [1mTH [22mor [1mDd [22mcalls are “clobbered” by  the  reloading  process.
            If  you want to provide your own definition of an extension macro to
            ensure its availability, the [4man-ext.tmac[24m entry below offers advice.

     [4m/usr/share/groff/1.24.1/tmac/an-ext.tmac[0m
            Definitions of macros described above as extensions (and not  depre‐
            cated)  are  contained in this file; in some cases, they are simpler
            versions of definitions appearing in [4man.tmac[24m, and are ignored if the
            formatter is GNU [4mtroff[24m.  They are written to be compatible with AT&T
            [4mtroff[24m and permissively licensed——not copylefted.  To reduce the risk
            of name space collisions, string and register names begin only  with
            “[1mm[22m”.   We  encourage man page authors who are concerned about porta‐
            bility to legacy Unix systems to copy these definitions  into  their
            pages,  and  maintainers of [4mtroff[24m implementations or work‐alike sys‐
            tems that format man pages to re‐use them.  To ensure reliable  ren‐
            dering,  define them after your page calls [1mTH[22m; see the discussion of
            [4mandoc.tmac[24m above.  Further, it is wise  to  define  such  page‐local
            macros  (if  at  all)  after the “Name” section to accommodate timid
            ]8;;man:makewhatis(8)\[4mmakewhatis[24m(8)]8;;\ or ]8;;man:mandb(8)\[4mmandb[24m(8)]8;;\ implementations that easily give up  scan‐
            ning for indexing material.

     [4m/usr/share/groff/1.24.1/tmac/man.tmac[0m
            is  a  wrapper enabling the package to be loaded with the option “[1m-m[0m
            [1mman[22m”.

     [4m/usr/share/groff/1.24.1/tmac/mandoc.tmac[0m
            is a wrapper enabling [4mandoc.tmac[24m to be loaded with  the  option  “[1m-m[0m
            [1mmandoc[22m”.

     [4m/usr/share/groff/site-tmac/man.local[0m
            Put site‐local changes and customizations into this file.

[1mAuthors[0m
     James  Clark wrote the initial GNU implementation of the [4mman[24m macro package.
     Later, ]8;;mailto:wl@gnu.org\Werner Lemberg]8;;\ supplied the [1mS[22m, [1mLT[22m, and  [1mcR  [22mregisters,  the  last  a
     4.3BSD‐Reno  [4mmdoc[24m(7) feature.  ]8;;mailto:kollar@alltel.net\Larry Kollar]8;;\ added the [1mFT[22m, [1mHY[22m, and [1mSN [22mregis‐
     ters; the [1mHF [22mstring; and the [1mPT [22mand [1mBT [22mmacros in [4mgroff[24m 1.19  (2003).   Lem‐
     berg  and ]8;;mailto:esr@thyrsus.com\Eric S. Raymond]8;;\ contributed [1mEX[22m/[1mEE[22m, [1mMT[22m/[1mME[22m, [1mUR[22m/[1mUE[22m, [1mTQ[22m, and an early
     version of the [1mSY[22m/[1mYS [22mmacros to [4mgroff[24m 1.20 (2009).  ]8;;mailto:g.branden.robinson@gmail.com\G. Branden Robinson]8;;\  im‐
     plemented  the [1mAD [22mand [1mMF [22mstrings; [1mCS[22m, [1mCT[22m, and [1mU [22mregisters; and the [1mMR [22mmacro
     for [4mgroff[24m 1.23 (2023), and the [1mBP[22m, [1mPO[22m, and [1mTS [22mregisters and a  revised  im‐
     plementation of the [1mSY[22m/[1mYS [22mmacros for [4mgroff[24m 1.24 (2026).

     ]8;;mailto:sgk@debian.org\Susan  G.  Kleinmann]8;;\ wrote the initial version of this document for the De‐
     bian GNU/Linux system.  Lemberg imported it to [4mgroff.[24m  He and Robinson  re‐
     vised  and  updated  it.   Raymond  and  Robinson  documented the extension
     macros.

[1mSee also[0m
     ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\, ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\, and ]8;;man:refer(1)\[4mrefer[24m(1)]8;;\ are preprocessors used with man pages.  ]8;;man:man(1)\[4mman[24m(1)]8;;\
     describes the man page librarian on your system.  ]8;;man:groff_mdoc(7)\[4mgroff_mdoc[24m(7)]8;;\ details the
     [4mgroff[24m version of BSD’s alternative macro package for man pages.

     ]8;;man:groff_man_style(7)\[4mgroff_man_style[24m(7)]8;;\, ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\, ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\

groff 1.24.1                       2026‐03‐20                       [4mgroff_man[24m(7)
────────────────────────────────────────────────────────────────────────────────
[4mgroff_man_style[24m(7)      Miscellaneous Information Manual      [4mgroff_man_style[24m(7)

[1mName[0m
     groff_man_style - GNU [4mroff[24m man page tutorial and style guide

[1mSynopsis[0m
     [1mgroff -man [22m[[4moption[24m ...] [[4mfile[24m ...]
     [1mgroff -m man [22m[[4moption[24m ...] [[4mfile[24m ...]

[1mDescription[0m
     The GNU implementation of the [4mman[24m macro package is part of the [4mgroff[24m  docu‐
     ment  formatting  system.  It is used to compose manual pages (“man pages”)
     like the one you are reading.  This document presents the  macros  themati‐
     cally;  for those needing only a quick reference, the following table lists
     them alphabetically, with references to appropriate subsections below.  Ex‐
     perienced [4mman[24m authors may prefer ]8;;man:groff_man(7)\[4mgroff_man[24m(7)]8;;\.

     Macro   Meaning                      Subsection
     ───────────────────────────────────────────────────────────────
     [1m.B      [22mBold                         Font style macros
     [1m.BI     [22mBold, italic alternating     Font style macros
     [1m.BR     [22mBold, roman alternating      Font style macros
     [1m.EE     [22mExample end                  Document structure macros
     [1m.EX     [22mExample begin                Document structure macros
     [1m.HP     [22mBegin hanging paragraph      Paragraphing macros
     [1m.I      [22mItalic                       Font style macros
     [1m.IB     [22mItalic, bold alternating     Font style macros
     [1m.IP     [22mIndented paragraph           Paragraphing macros
     [1m.IR     [22mItalic, roman alternating    Font style macros
     [1m.LP     [22mBegin paragraph              Paragraphing macros
     [1m.ME     [22mMail‐to end                  Hyperlink macros
     [1m.MR     [22mMan page cross reference     Hyperlink macros
     [1m.MT     [22mMail‐to start                Hyperlink macros
     [1m.P      [22mBegin paragraph              Paragraphing macros
     [1m.PP     [22mBegin paragraph              Paragraphing macros
     [1m.RB     [22mRoman, bold alternating      Font style macros
     [1m.RE     [22mRelative inset end           Document structure macros
     [1m.RI     [22mRoman, italic alternating    Font style macros
     [1m.RS     [22mRelative inset start         Document structure macros
     [1m.SH     [22mSection heading              Document structure macros
     [1m.SM     [22mSmall                        Font style macros
     [1m.SS     [22mSubsection heading           Document structure macros
     [1m.SY     [22mSynopsis start               Synopsis macros
     [1m.TH     [22mTitle heading                Document structure macros
     [1m.TP     [22mTagged paragraph             Paragraphing macros
     [1m.TQ     [22mSupplemental paragraph tag   Paragraphing macros
     [1m.UE     [22mURI end                      Hyperlink macros
     [1m.UR     [22mURI start                    Hyperlink macros
     [1m.YS     [22mSynopsis end                 Synopsis macros

     We discuss other macros ([1mAT[22m, [1mDT[22m, [1mOP[22m, [1mPD[22m, [1mSB[22m, and [1mUC[22m) in subsection  “Depre‐
     cated features” below.

     Throughout  Unix  documentation,  a manual entry is referred to simply as a
     “man page”, regardless of its length, without gendered implication, and ir‐
     respective of the macro package selected for its composition.

     A man page employs the Unix line‐ending convention (U+000A only).  Some ba‐
     sic Latin characters have special meaning to [4mroff;[24m see  subsection  “Porta‐
     bility” below.

   [1mFundamental concepts[0m
     [4mgroff[24m  is  a programming system for typesetting: we thus often use the verb
     “to set” in the sense “to typeset”.  The formatter ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ collects  words
     from  the  input and [4mfills[24m output lines with as many as can fit.  [4mWords[24m are
     separated by spaces and newlines.  A transition to a  new  output  line  is
     called  a  [4mbreak.[24m  Breaks can occur at explicit hyphens, at [1m\% [22mor [1m\: [22mescape
     sequences (see subsection “Portability” below), or at  predetermined  loca‐
     tions in a word if automatic hyphenation is enabled (see the [1m-rHY [22moption in
     section  “Options”  below).  An output line may be supplemented with [4minter‐[0m
     [4msentence[24m [4mspace,[24m then potentially [4madjusted[24m with more space to  a  consistent
     length  (see  the [1m-dAD [22moption).  ]8;;man:roff(7)\[4mroff[24m(7)]8;;\ details these processes.  The for‐
     matter prepares output for [4mterminals[24m or for more capable  [4mtypesetters[24m  that
     can change the type size and font family.

     A  [4mroff[24m  document  can contain [4mcontrol[24m [4mlines,[24m which start with a dot ([1m.[22m) or
     neutral apostrophe ([1m'[22m).  All other input lines are [4mtext[24m [4mlines[24m to be format‐
     ted.  A [4mmacro[24m collects control and/or text lines to ease document  composi‐
     tion.   [4mman[24m  is a [4mmacro[24m [4mpackage.[24m  To call a macro, put its name after a dot
     on a control line.  Some macros interpret [4marguments,[24m words that follow  its
     name.   A  newline,  unless  escaped  (see subsection “Portability” below),
     marks the end of the macro call.  A control line with no macro name  on  it
     is called an [4mempty[24m [4mrequest;[24m it does nothing.

     We  describe  below several [4mman[24m macros that plant one‐line [4minput[24m [4mtraps:[24m the
     next input line that directly produces formatted  output  is  treated  spe‐
     cially.   For [4mman[24m documents that follow the advice in section “Portability”
     below, this means that control lines using the  empty  request  and  uncom‐
     mented  input  lines ending with an escaped newline do not spring the trap;
     anything else does (but see the [1mTP [22mmacro description).

   [1mMacro reference preliminaries[0m
     A tagged paragraph describes each macro.   We  present  coupled  pairs  to‐
     gether,  as  with [1mEX [22mand [1mEE[22m.  Square brackets surround optional macro argu‐
     ments.  If a macro accepts multiple arguments, those containing space char‐
     acters must be double‐quoted to be interpreted correctly.  If  you  require
     an  empty  macro  argument,  specify  it as a pair of neutral double quotes
     ([1m""[22m).  See section “Notes” below for examples of cases where better  alter‐
     natives  to empty arguments in macro calls are available.  Most macro argu‐
     ments are formatted as text in the output; exceptions are noted.  We  iden‐
     tify some macros as [4mextensions[24m to the set originally implemented.  They are
     not supported everywhere; see subsection “Use of extensions” below.

   [1mDocument structure macros[0m
     Document structure macros organize a man page’s content.  All of them break
     the  output line.  [1mTH [22m(title heading) identifies the document as a man page
     and configures the page headers and footers.  Section headings ([1mSH[22m), one of
     which is mandatory and many of which are conventionally  expected,  facili‐
     tate location of material by the reader and aid the man page writer to dis‐
     cuss  all  essential  aspects of the topics presented.  Subsection headings
     ([1mSS[22m) are optional and permit sections that grow long to develop in  a  con‐
     trolled  way.   Many  technical  discussions benefit from examples; lengthy
     ones, especially those reflecting multiple lines of input to or output from
     the system, are usefully bracketed by [1mEX [22mand [1mEE[22m.  When none of the  forego‐
     ing  meets  a  structural  demand,  use  [1mRS[22m/[1mRE  [22mto  inset a region within a
     (sub)section.

     [1m.TH [4m[22midentifier[24m [4msection[24m [[4mfooter‐middle[24m [[4mfooter‐inside[24m [[4mheader‐middle[24m]]]
            Break the page, reset the page number to 1 (unless the  [1m-rC1  [22moption
            is  given),  and  use  the arguments to populate the page header and
            footer.  [4mroff[24m systems refer to these collectively as “titles”.   To‐
            gether, [4midentifier[24m and the [4msection[24m of the manual to which it belongs
            can  uniquely  identify  a  [4mman[24m document on the system.  This use of
            “section” has nothing to do with the section headings otherwise dis‐
            cussed in this page; it arises from  the  organizational  scheme  of
            printed and bound Unix manuals.  See ]8;;man:man(1)\[4mman[24m(1)]8;;\ or ]8;;man:intro(1)\[4mintro[24m(1)]8;;\ for the man‐
            ual  sectioning  applicable  to your system.  [4midentifier[24m and [4msection[0m
            are positioned at the left and right in the header;  the  latter  is
            set after the former, in parentheses and without space.  [4mfooter‐mid‐[0m
            [4mdle[24m  is  centered in the footer.  By default, [4mfooter‐inside[24m is posi‐
            tioned at the bottom left.  Use of the  double‐sided  layout  option
            [1m-rD1 [22mplaces [4mfooter‐inside[24m at the bottom left on recto (odd‐numbered)
            pages,  and the bottom right on verso (even‐numbered) pages.  By de‐
            fault, the outside footer is the page number.  Use of  the  continu‐
            ous‐rendering option [1m-rcR=1 [22mreplaces it with [4midentifier[24m and [4msection,[0m
            as in the header.  [4mheader‐middle[24m is centered in the header.  If [4msec‐[0m
            [4mtion[24m  is an integer between 1 and 9 (inclusive), there is no need to
            specify [4mheader‐middle;[24m [4man.tmac[24m supplies text for it.  If  [4midentifier[0m
            or  [4mfooter‐inside[24m  would  overrun  the space available in the header
            and/or footer, this package may abbreviate them with ellipses ([1m...[22m).
            [4mgroff[24m [4mman[24m suppresses headers and footers in HTML output.

            A valid [4mman[24m document calls [1mTH [22monly once, early in the file, prior to
            any other macro calls.  By convention, [4mfooter‐middle[24m is the date  of
            the  most  recent  modification  to the source document, in ISO 8601
            format ([4mYYYY[24m‐[4mMM[24m‐[4mDD[24m), and [4mfooter‐inside[24m is the name  and  version  or
            release of the project providing it.

     [1m.SH [22m[[4mheading‐text[24m]
            Set [4mheading‐text[24m as a section heading.  Given no argument, [1mSH [22mplants
            a  one‐line  input trap; text on the next line becomes [4mheading‐text.[0m
            The heading text is set in bold (or the font specified by the string
            [1mHF[22m), and, on typesetters, slightly larger than the base  type  size.
            If  the heading font [1m\*[HF] [22mis bold, use of an italic style in [4mhead‐[0m
            [4ming‐text[24m is mapped to the bold‐italic style if available in the font
            family.  The inset level is reset to 1; see  subsection  “Horizontal
            and  vertical  spacing” below.  Text lines after the call are set as
            an ordinary paragraph ([1mP[22m).

            The content of [4mheading‐text[24m and ordering of sections follows  a  set
            of  common  practices, as does much of the layout of material within
            sections.  For example, a section called “Name” or “NAME”  must  ex‐
            ist,  must  be the first section after the [1mTH [22mcall, and must contain
            only text of the form
                   [4mtopic[24m[[1m, [4m[22manother‐topic[24m]... \- [4msummary‐description[0m
            for tools like ]8;;man:makewhatis(8)\[4mmakewhatis[24m(8)]8;;\ or ]8;;man:mandb(8)\[4mmandb[24m(8)]8;;\ to index them.

     [1m.SS [22m[[4msubheading‐text[24m]
            Set [4msubheading‐text[24m as a subsection heading indented between a  sec‐
            tion  heading  and an ordinary paragraph ([1mP[22m).  Given no argument, [1mSS[0m
            plants a one‐line input trap; text on the next line becomes [4msubhead‐[0m
            [4ming‐text.[24m  The subheading text is set in bold (or the font specified
            by the string [1mHF[22m).  If the heading font [1m\*[HF] [22mis bold,  use  of  an
            italic  style  in [4msubheading‐text[24m is mapped to the bold‐italic style
            if available in the font family.  The inset level is reset to 1; see
            subsection “Horizontal and vertical spacing” below.  Text lines  af‐
            ter the call are set as an ordinary paragraph ([1mP[22m).

     [1m.EX[0m
     [1m.EE    [22mBegin and end example.  After [1mEX[22m, filling is disabled (and, on type‐
            setters,  a monospaced font family is selected).  Calling [1mEE [22menables
            filling (and restores the previous family).

            Example regions are useful for formatting code, shell sessions,  and
            text  file  contents.   An example region is not a “literal mode” of
            any sort: special character escape sequences must still be  used  to
            produce  correct  glyphs  for  [1m'[22m,  [1m-[22m, [1m\[22m, [1m^[22m, [1m`[22m, and [1m~ [22m(see subsection
            “Portability” below).  Sentence endings are still detected and  sup‐
            plemental inter‐sentence space applied.  If the amount of supplemen‐
            tal  inter‐sentence  spacing  is  altered, the rendering of, for in‐
            stance, regular expressions using [1m. [22mor [1m? [22mfollowed by multiple spaces
            can change.  Use the dummy character escape sequence [1m\&  [22mbefore  the
            spaces.

            Ninth  Edition  Unix  introduced  the  [1mEX  [22mand [1mEE [22mextensions.  Docu‐
            menter’s Workbench (DWB), Heirloom Doctools, and Plan 9 [4mtroff[24ms,  and
            [4mmandoc[24m (since 1.12.2) support them.  Solaris [4mtroff[24m does not.

     [1m.RS [22m[[4minset‐amount[24m]
            Start  new  relative  inset.  [4mman[24m saves any current inset amount and
            moves right by: [4minset‐amount,[24m if specified; the  [4mindentation[24m  amount
            of  the preceding [1mIP[22m, [1mTP[22m, or [1mHP [22mmacro call if no (sub‐)sectioning or
            ordinary paragraphing macro has intervened; or the amount of the  [1mIN[0m
            register.  [1mRS [22mcalls can nest; each increments by 1 the [4mlevel[24m used by
            [1mRE[22m.  The level prior to any [1mRS [22mcall is 1.

     [1m.RE [22m[[4minset‐level[24m]
            End a relative inset, reducing it to that of [4minset‐level[24m (or by 1 if
            not specified) and restoring the corresponding inset amount.

   [1mParagraphing macros[0m
     These  macros  break  the output line.  An [4mordinary[24m paragraph ([1mP[22m) like this
     one indents all output lines by the same amount.  A hanging paragraph  ([1mHP[22m)
     is  a  cosmetic  variant of [1mP [22mwith a hanging indent.  Definition lists fre‐
     quently occur in man pages; these can be set as  [4mtagged[24m  [4mparagraphs,[24m  which
     have one ([1mTP[22m) or more ([1mTQ[22m) leading tags followed by a paragraph that has an
     additional indentation.  The indented paragraph ([1mIP[22m) macro can continue the
     indented  content of a narrative started with [1mTP[22m, or present an itemized or
     ordered list.  If a paragraphing macro has been called since [1mSH [22mor [1mSS[22m,  all
     except  [1mTQ [22mfollow the break with vertical space (in an amount configured by
     the deprecated [1mPD [22mmacro); see subsection “Horizontal and vertical  spacing”
     below.   Except  for [1mTQ[22m, these macros reset the type size, hyphenation, and
     adjustment to (configured) defaults, and the font style to roman.

     [1m.P[0m
     [1m.LP[0m
     [1m.PP    [22mBegin a new paragraph; these macros are synonymous.  Any indentation
            from use of [1mIP[22m, [1mTP[22m, or [1mHP [22mis cleared.  The inset amount, as affected
            by [1mRS [22mand [1mRE[22m, is not.

     [1m.HP [22m[[4mindentation[24m]
            Set a paragraph with a hanging indentation.  Text  on  output  lines
            after the first is indented by [4mindentation,[24m if specified, and by the
            amount of the [1mIN [22mregister otherwise.

            [4mCaution:[24m  A  hanging  indentation  cannot  be expressed naturally in
            (pure) HTML, a hanging paragraph is not distinguishable from an  or‐
            dinary one if it formats on only one output line, and non‐[4mroff[24m‐based
            man  page interpreters may treat [1mHP [22mas an ordinary paragraph anyway.
            Thus, information or distinctions you mean to express with  indenta‐
            tion may be lost.

     [1m.TP [22m[[4mindentation[24m]
            Set  an indented paragraph with a leading unindented tag.  The macro
            plants a one‐line input trap that honors  the  [1m\c  [22mescape  sequence;
            text  on  the  next  line  becomes the tag, set without indentation.
            Text on subsequent lines is indented by [4mindentation,[24m  if  specified,
            and  by  the  amount of the [1mIN [22mregister otherwise.  If the tag, plus
            the “tag spacing” stored in the [1mTS [22mregister (see  section  “Options”
            below)  is  wider  than the indentation, the package breaks the line
            after the tag.

            The line containing the tag can include a macro call,  for  instance
            to set the tag in bold with [1mB[22m.  [1mTP [22mwas used to write the first para‐
            graph of this description of [1mTP[22m, and [1mIP [22mthe subsequent one.

     [1m.TQ    [22mSet  an  additional  tag  for a paragraph tagged with [1mTP[22m, planting a
            one‐line input trap as with [1mTP[22m.

            [1mTQ [22mis a GNU extension supported by Heirloom  Doctools  [4mtroff[24m  (since
            Git  snapshot  151218)  and  [4mmandoc[24m  (since  1.14.5) but not by DWB,
            Plan 9, or Solaris [4mtroff[24ms.

            The description of [1mP[22m, [1mLP[22m, and [1mPP [22mabove was written using [1mTP [22mand [1mTQ[22m.

     [1m.IP [22m[[4mmark[24m [[4mindentation[24m]]
            Set an indented paragraph with  an  optional  mark.   Arguments,  if
            present, are handled as with [1mTP[22m, except that the [4mmark[24m argument to [1mIP[0m
            cannot include a macro call, and the tag separation amount stored in
            the [1mTS [22mregister is not enforced.

            Two convenient uses for [1mIP [22mare

                (1)  to  start  a  new paragraph with the same indentation as an
                     immediately preceding [1mIP [22mor [1mTP [22mparagraph, if no [4mindentation[0m
                     argument is given; and

                (2)  to set a paragraph with a short [4mmark[24m that is  not  semanti‐
                     cally  important,  such  as a bullet (•)——obtained with the
                     [1m\[bu] [22mspecial character escape sequence——or  list  enumera‐
                     tor, as seen in this very paragraph.

   [1mSynopsis macros[0m
     Use  [1mSY  [22mand [1mYS [22mto summarize syntax using familiar Unix conventions.  Heir‐
     loom Doctools [4mtroff[24m (since Git snapshot 151218) and [4mmandoc[24m  (since  1.14.5)
     support these GNU extensions; DWB, Plan 9, and Solaris [4mtroff[24ms do not.

     [1m.SY [4m[22mkeyword[24m [[4msuffix[24m]
            Begin  synopsis.  Adjustment and automatic hyphenation are disabled.
            If [1mSY [22mhas already been called without a corresponding [1mYS[22m, a break is
            performed.  [4mkeyword[24m and any [4msuffix[24m are set in bold.  When [4msuffix[24m  is
            present, the package sets the next word after it without intervening
            space.   If  a  break  is required in subsequent text (up to a para‐
            graphing, sectioning, or [1mYS [22mmacro call), lines after the  first  are
            indented.  Unless the previous synopsis’s indentation is reused (see
            [1mYS  [22mbelow),  output lines after the first indent by the width of the
            pending output line up to the end of [4mkeyword[24m plus a space,  if  [4mkey‐[0m
            [4mword[24m is the only argument, and up to the end of [4msuffix[24m otherwise.

     [1m.YS [22m[[4mreuse‐indentation[24m]
            End  synopsis,  breaking the line and restoring indentation, adjust‐
            ment, and hyphenation to their previous states.  If an  argument  is
            given,  the  indentation  corresponding  to  the previous [1mSY [22mcall is
            reused by the next [1mSY [22mcall instead of being computed.

     Interleave multiple [1mSY[22m/[1mYS [22mblocks with paragraphing  macros  to  distinguish
     differing  modes  of  operation of a complex command like ]8;;man:tar(1)\[4mtar[24m(1)]8;;\.  Omit the
     paragraphing macro to indicate synonymous ways  of  invoking  a  particular
     mode  of  operation.   Paragraphing macros can similarly manage grouping of
     function synopses.

     [4mgroff[24m’s own command‐line interface illustrates most specimens  of  synopsis
     syntax one may encounter.

            .SY groff
            .RB [ \-abcCeEgGijklNpRsStUVXzZ ]
            .RB [ \-d\~\c
            .IR ctext ]
            .RB [ \-d\~\c
            .IB string =\c
            .IR text ]
            .RB [ \-D\~\c
            .IR fallback-encoding ]
            [4m(and[24m [4mso[24m [4mon[24m [4msimilarly)[0m
            .RI [ file\~ .\|.\|.]
            .YS
            .
            .
            .P
            .SY groff
            .B \-h
            .YS
            .
            .SY groff
            .B \-\-help
            .YS
            .
            .
            .P
            .SY groff
            .B \-v
            .RI [ option\~ .\|.\|.\&]
            .RI [ file\~ .\|.\|.]
            .YS
            .
            .SY groff
            .B \-\-version
            .RI [ option\~ .\|.\|.\&]
            .RI [ file\~ .\|.\|.]
            .YS

     Given the foregoing input, [4mgroff[24m [4mman[24m produces the following output.

            [1mgroff [22m[[1m-abcCeEgGijklNpRsStUVXzZ[22m] [[1m-d [4m[22mctext[24m] [[1m-d [4m[22mstring[24m[1m=[4m[22mtext[24m]
                  [[1m-D [4m[22mfallback‐encoding[24m] [[1m-f [4m[22mfont‐family[24m] [[1m-F [4m[22mfont‐directory[24m]
                  [[1m-I [4m[22minclusion‐directory[24m] [[1m-K [4m[22minput‐encoding[24m] [[1m-L [4m[22mspooler‐[0m
                  [4margument[24m] [[1m-m [4m[22mmacro‐package[24m] [[1m-M [4m[22mmacro‐directory[24m] [[1m-n [4m[22mpage‐[0m
                  [4mnumber[24m] [[1m-o [4m[22mpage‐list[24m] [[1m-P [4m[22mpostprocessor‐argument[24m]
                  [[1m-r [4m[22mcnumeric‐expression[24m] [[1m-r [4m[22mregister[24m[1m=[4m[22mnumeric‐expression[24m]
                  [[1m-T [4m[22moutput‐device[24m] [[1m-w [4m[22mwarning‐category[24m] [[1m-W [4m[22mwarning‐category[24m]
                  [[4mfile[24m ...]

            [1mgroff -h[0m
            [1mgroff --help[0m

            [1mgroff -v [22m[[4moption[24m ...] [[4mfile[24m ...]
            [1mgroff --version [22m[[4moption[24m ...] [[4mfile[24m ...]

     Several features of the above example are of note.

     •  The  empty  request (.), which does nothing, vertically spaces the input
        file for readability by the document maintainer; see subsection  “Porta‐
        bility” below regarding blank lines.

     •  Command and option names are presented in [1mbold [22mto cue the user that they
        should be input literally.

     •  Option  dashes are specified with the [1m\- [22mescape sequence; this is an im‐
        portant practice to make them clearly visible and  to  facilitate  copy‐
        and‐paste from the rendered man page to a shell prompt or text file.

     •  Option  arguments and command operands are presented in [4mitalics[24m (but see
        subsection “Font style macros” below regarding  terminals)  to  cue  the
        user that they must be replaced with appropriate input.

     •  Symbols  that  are  neither  to  be  typed literally nor replaced at the
        user’s discretion appear in the roman style; brackets surround  optional
        arguments, and an ellipsis indicates that the previous syntactic element
        may  be repeated arbitrarily.  Where whitespace separates optional argu‐
        ments, a space precedes the ellipsis.

     •  The non‐breaking adjustable space escape sequence [1m\~ [22mprevents the output
        line from breaking within the option brackets; see subsection “Portabil‐
        ity” below.

     •  The output line continuation escape sequence [1m\c [22mis used with font  style
        alternation  macros  to  allow  all  three font styles to be set without
        (breakable) space among them; see subsection “Portability” below.

     •  The dummy character escape sequence [1m\& [22mfollows the ellipsis when further
        text is to follow after space on the output line, keeping its  last  pe‐
        riod  from being interpreted as the end of a sentence because it is fol‐
        lowed by characters that are transparent to  end‐of‐sentence  detection,
        and/or  a  newline,  which would in turn normally cause the formatter to
        place  supplemental  inter‐sentence  space  after  it.   See  subsection
        “Portability” below.

     We might synopsize the standard C library function ]8;;man:bsearch(3)\[4mbsearch[24m(3)]8;;\ as follows.

            .P
            .B void *\c
            .SY bsearch (
            .BI const\~void\~* key ,
            .BI const\~void\~* base ,
            .BI size_t\~ nmemb ,
            .BI int\~(* compar )\c
            .B (const\~void\~*, const\~void\~*));
            .YS

     [4mgroff[24m [4mman[24m produces the following result.

            [1mvoid *bsearch(const void *[4m[22mkey[24m[1m, const void *[4m[22mbase[24m[1m, size_t [4m[22mnmemb[24m[1m,[0m
                          [1mint (*[4m[22mcompar[24m[1m)(const void *, const void *));[0m

   [1mHyperlink macros[0m
     Man  page  cross  references  like  ]8;;man:ls(1)\[4mls[24m(1)]8;;\ are best presented with [1mMR[22m.  Mark
     email addresses with [1mMT[22m/[1mME [22mand other sorts of URI with [1mUR[22m/[1mUE[22m.  To hyperlink
     text, terminals and pager programs must support ECMA‐48 OSC  8  escape  se‐
     quences  (see  ]8;;man:grotty(1)\[4mgrotty[24m(1)]8;;\).   When device support is unavailable or disabled
     with the [1mU [22mregister (see section “Options” below), [4mgroff[24m [4mman[24m renders  these
     URIs between angle brackets ([1m⟨ ⟩[22m) after the linked text.

     [1mMT[22m,  [1mME[22m, [1mUR[22m, and [1mUE [22mare GNU extensions supported by Heirloom Doctools [4mtroff[0m
     (since Git snapshot 151218) and [4mmandoc[24m ([1mUR[22m/[1mUE  [22msince  1.12.3;  [1mMT[22m/[1mME  [22msince
     1.14.2)  but not by DWB, Plan 9 (original), or Solaris [4mtroff[24ms.  Plan 9 from
     User Space’s [4mtroff[24m implements [1mMR[22m.

     Prepare arguments to [1mMR[22m, [1mMT[22m, and [1mUR [22mfor typesetting; they can appear in the
     output.  Use special character escape sequences  to  encode  Unicode  basic
     Latin characters where necessary, particularly the hyphen‐minus.  (See sub‐
     section  “Portability” below.)  URIs can be lengthy; rendering them can re‐
     sult in jarring adjustment or variations in line length, or [4mtroff[24m  warnings
     when  one  is  longer than an output line.  The application of non‐printing
     break point escape sequences [1m\: [22mafter each slash (or series  thereof),  and
     before each dot (or series thereof) is recommended as a rule of thumb.  The
     former  practice  avoids  forcing a trailing slash in a URI onto a separate
     output line, and the latter helps the reader to avoid mistakenly interpret‐
     ing a dot at the end of a line as a period (or multiple dots as  an  ellip‐
     sis).  Thus,
            .UR http://\:example\:.com/\:fb8afcfbaebc74e\:.cc
     has several potential break points in the URI shown.  Consider adding break
     points before or after at signs in email addresses, and question marks, am‐
     persands, and number signs in HTTP(S) URIs.

     [1m.MR [4m[22mtopic[24m [[4mmanual‐section[24m [[4mtrailing‐text[24m]]
            [4m(since[24m  groff [4m1.23)[24m Set a man page cross reference as “[4mtopic[24m[1m([4m[22mmanual‐[0m
            [4msection[24m[1m)[22m”.  If [4mmanual‐section[24m is absent, the package omits the  sur‐
            rounding  parentheses.   If [4mtrailing‐text[24m (typically punctuation) is
            specified, it follows the closing  parenthesis  without  intervening
            space.   Hyphenation  is  disabled while the cross reference is set.
            [4mtopic[24m is set in the font specified by the [1mMF [22mstring.  If [4mmanual‐sec‐[0m
            [4mtion[24m is present, the cross reference hyperlinks to a URI of the form
            “[1mman:[4m[22mtopic[24m([4mmanual‐section[24m)”.

                   The output driver
                   .MR grops 1
                   produces PostScript from
                   .I troff
                   output.
                   .
                   The Ghostscript program (\c
                   .MR gs 1 )
                   interprets PostScript and PDF.

     [1m.MT [4m[22maddress[0m
     [1m.ME [22m[[4mtrailing‐text[24m]
            Identify [4maddress[24m as an RFC 6068 [4maddr‐spec[24m for a “mailto:”  URI  with
            the  text between the two macro calls as the link text.  An argument
            to [1mME [22mis placed after the link text without intervening space.   [4mad‐[0m
            [4mdress[24m  may not be visible in the rendered document if hyperlinks are
            enabled and supported by the output driver.  If they  are  not,  [4mad‐[0m
            [4mdress[24m is set in angle brackets after the link text and before [4mtrail‐[0m
            [4ming‐text.[24m  If hyperlinking is enabled but there is no link text, [4mad‐[0m
            [4mdress[24m  is  formatted  and hyperlinked [4mwithout[24m angle brackets, except
            when [4maddress[24m appears as a [1mTP [22mparagraph tag.

            When rendered by [4mgroff[24m to a PostScript device,

                   Contact
                   .MT fred\:.foonly@\:fubar\:.net
                   Fred Foonly
                   .ME
                   for more information.

            formats as “Contact Fred Foonly ⟨fred.foonly@fubar.net⟩ for more in‐
            formation.”.

     [1m.UR [4m[22muri[0m
     [1m.UE [22m[[4mtrailing‐text[24m]
            Identify [4muri[24m as an RFC 3986 URI hyperlink with the text between  the
            two macro calls as the link text.  An argument to [1mUE [22mis placed after
            the  link text without intervening space.  [4muri[24m may not be visible in
            the rendered document if hyperlinks are enabled and supported by the
            output driver.  If they are not, [4muri[24m is set in angle brackets  after
            the  link text and before [4mtrailing‐text.[24m  If hyperlinking is enabled
            but there is no link text, [4muri[24m is formatted and hyperlinked  [4mwithout[0m
            angle brackets, except when [4muri[24m appears as a [1mTP [22mparagraph tag.

            When rendered by [4mgroff[24m to a PostScript device,

                   The GNU Project of the Free Software Foundation
                   hosts the
                   .UR https://\:www\:.gnu\:.org/\:software/\:groff/
                   .I groff
                   home page
                   .UE .

            formats  as  “The  GNU Project of the Free Software Foundation hosts
            the [4mgroff[24m home page ⟨https://www.gnu.org/software/groff/⟩.”.

     If a [1mUR[22m/[1mUE [22mor [1mMT[22m/[1mME [22mpair occurs in a [1mTP [22mtag and  hyperlinking  is  unavail‐
     able, [4mgroff[24m [4mman[24m sets the link target at the beginning of the indented para‐
     graph, not as part of the tag, unless there is no link text.

   [1mFont style macros[0m
     The [4mman[24m macro package is limited in its font styling options, offering only
     [1mbold  [22m([1mB[22m),  [4mitalic[24m  ([1mI[22m),  and roman.  Italic text may instead render under‐
     scored on terminals.  [1mSM [22msets text at a smaller type  size,  which  differs
     visually  from  regular‐sized text only on typesetters.  The macros [1mBI[22m, [1mBR[22m,
     [1mIB[22m, [1mIR[22m, [1mRB[22m, and [1mRI [22mset their odd‐ and even‐numbered arguments  as  text  in
     the alternating styles their names indicate, with no space separating them.

     Because  font  styles  are presentational rather than semantic, conflicting
     traditions have arisen regarding which font styles should be used  to  mark
     file or path names, environment variables, and inlined literals.

     The  default type size and family for typesetters is 10‐point Times, except
     on the [1mX75-12 [22mand [1mX100-12 [22mdevices where the type size is  12  points.   The
     default style is roman.

     [1m.B [22m[[4mtext[24m]
            Set  [4mtext[24m  in  bold.   Given  no argument, [1mB [22mplants a one‐line input
            trap; text on the next line, which can be further formatted  with  a
            macro, is set in bold.

            Use  bold  for literal portions of syntax synopses, for command‐line
            options in running text, and for literals that are major  topics  of
            the  subject  under discussion; for example, this page uses bold for
            macro, string, and register names.  In an [1mEX[22m/[1mEE [22mexample of  interac‐
            tive I/O (such as a shell session), set only user input in bold.

     [1m.I [22m[[4mtext[24m]
            Set  [4mtext[24m in an italic or oblique face.  Given no argument, [1mI [22mplants
            a one‐line input trap; text on the next line, which can  be  further
            formatted with a macro, is set in an italic or oblique face.

            Use  italics for file and path names, for environment variables, for
            C data types, for enumeration or preprocessor constants  in  C,  for
            variant  (user‐replaceable)  portions  of  syntax  synopses, for the
            first occurrence (only) of a technical concept being introduced, for
            names of journals and of literary works longer than an article,  and
            anywhere  a  parameter  requiring replacement by the user is encoun‐
            tered.  An exception involves variant  text  in  a  context  already
            typeset in italics, such as file or path names with replaceable com‐
            ponents; in such cases, follow the convention of mathematical typog‐
            raphy:  set  the file or path name in italics as usual but use roman
            for the variant part (see [1mIR [22mand [1mRI [22mbelow),  and  italics  again  in
            running roman text when referring to the variant material.

     [1m.SM [22m[[4mtext[24m]
            Set  [4mtext[24m  one  point smaller than the default type size on typeset‐
            ters.  Given no argument, [1mSM [22mplants a one‐line input trap;  text  on
            the  next  line, which can be further formatted with a macro, is set
            smaller.

            [4mNote:[24m terminals render [4mtext[24m at normal size  instead.   Do  not  rely
            upon  [1mSM [22mto communicate semantic information distinct from using ro‐
            man style at normal size; it is hidden from readers using  such  de‐
            vices.

     Observe  what  is [4mnot[24m prescribed for setting in bold or italics above: ele‐
     ments of “synopsis language” such as ellipses and brackets around  options;
     proper  names  and adjectives; titles of anything other than major works of
     literature; identifiers for standards documents or technical  reports  such
     as  CSTR  #54,  RFC 1918, Unicode 16, or POSIX.1‐2024; acronyms; and occur‐
     rences after the first of a technical term.

     Use italics for emphasis rarely, and bold almost never.  Brief specimens of
     literal text, such as article titles, inline examples, mentions of individ‐
     ual characters or short strings, and (sub)section headings  in  man  pages,
     are  suitable  for quotation; see the [1m\[lq][22m, [1m\[rq][22m, [1m\[oq][22m, and [1m\[cq] [22mescape
     sequences in subsection “Portability” below.

     Unlike the above font style macros, the font style alternation macros below
     set no input traps; they must be given arguments to have effect.  They  ap‐
     ply  italic  corrections  as appropriate.  If a space is required within an
     argument, first consider whether the same result could be achieved with  as
     much clarity by using single‐style macros on separate input lines.  When it
     cannot,  double‐quote  an  argument  containing  embedded space characters.
     Setting all three different styles within a word presents challenges; it is
     possible with the [1m\c [22mand/or [1m\f [22mescape sequences.  See subsection “Portabil‐
     ity” below for approaches.

     [1m.BI [4m[22mbold‐text[24m [4mitalic‐text[24m ...
            Set each argument in bold and italics, alternately.

                   .BI -r\~ register = numeric‐expression

     [1m.BR [4m[22mbold‐text[24m [4mroman‐text[24m ...
            Set each argument in bold and roman, alternately.

                   Set an ellipsis on the math axis with the GNU extension macro
                   .BR cdots .

     [1m.IB [4m[22mitalic‐text[24m [4mbold‐text[24m ...
            Set each argument in italics and bold, alternately.

                   In places where
                   .IB n th
                   is allowed,

     [1m.IR [4m[22mitalic‐text[24m [4mroman‐text[24m ...
            Set each argument in italics and roman, alternately.

                   Use GNU
                   .IR pic 's
                   .B figname
                   command to change the name of the vbox.

     [1m.RB [4m[22mroman‐text[24m [4mbold‐text[24m ...
            Set each argument in roman and bold, alternately.

                   .I file
                   is
                   .RB \[lq] \- \[rq],
                   .I groff
                   reads the standard input stream.

     [1m.RI [4m[22mroman‐text[24m [4mitalic‐text[24m ...
            Set each argument in roman and italics, alternately.

                   .RI ( tpic
                   was a fork of AT&T
                   .I pic
                   by Tim Morgan of the University of California at Irvine

   [1mHorizontal and vertical spacing[0m
     The package sets all text inboard of the left edge of the output medium  by
     the  amount of the [4mpage[24m [4moffset;[24m see register [1mPO [22min section “Options” below.
     Headers, footers (both set with [1mTH[22m), and section headings ([1mSH[22m) lie  at  the
     page  offset.   [4mgroff[24m [4mman[24m indents subsection headings ([1mSS[22m) by the amount in
     the [1mSN [22mregister.

     Ordinary paragraphs not within an [1mRS[22m/[1mRE  [22minset  region  are  inset  by  the
     amount stored in the [1mBP [22mregister; see section “Options” below.  The [1mIN [22mreg‐
     ister  configures  the default indentation amount used by [1mRS [22m(as the [4minset‐[0m
     [4mamount[24m), [1mIP[22m, [1mTP[22m, and [1mHP[22m; an overriding argument is a  number  plus  an  op‐
     tional  scaling unit.  If no scaling unit is given, the [4mman[24m package assumes
     “n”; that is, roughly the width of a letter “n” in the  font  current  when
     the  macro  is called——see section “Measurements” in ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\.  An indenta‐
     tion specified in a call to [1mIP[22m, [1mTP[22m, or [1mHP [22mpersists  until  (1)  another  of
     these macros is called with an [4mindentation[24m argument, or (2) [1mSH[22m, [1mSS[22m, or [1mP [22mor
     its synonyms is called; these clear the indentation entirely.

     The  inset  amount and indentation are related but distinct parameters with
     the same defaults.  The former is manipulated by [1mRS [22mand [1mRE [22m(and by  [1mSH  [22mand
     [1mSS[22m, which reset it to the default).  Indentation is controlled by the para‐
     graphing  macros  (though, again, [1mSH [22mand [1mSS [22mreset it); it is imposed by the
     [1mTP[22m, [1mIP[22m, and [1mHP [22mmacros, and cancelled by [1mP [22mand its synonyms.   An  extensive
     example follows.

     This  ordinary ([1mP[22m) paragraph is not in a relative inset nor does it possess
     an indentation.

            Now we have created a relative inset with [1mRS [22mand started another or‐
            dinary paragraph with [1mP[22m.  We observe that all of its lines are inset
            and indented the same; contrast with a first‐line indentation.

            [1mtag    [22mThis tagged paragraph, set with [1mTP[22m, is still  within  the  [1mRS[0m
                   region, but lines after the first have a supplementary inden‐
                   tation that the tag lacks.

                   A paragraph like this one, set with [1mIP[22m, appears to the reader
                   as also associated with the tag above, because [1mIP [22mre‐uses the
                   previous  paragraph’s indentation unless given an argument to
                   change it.  Both the inset amount ([1mRS[22m) and  indentation  ([1mIP[22m)
                   affect this paragraph.
                   ┌───────────────────────────────────┐
                   │ This table is affected both by    │
                   │ the inset amount and indentation. │
                   └───────────────────────────────────┘

            •      This  indented paragraph is marked with a bullet, contrasting
                   the inset amount and the indentation; only the former affects
                   the mark, but both affect the text of the paragraph.

            This ordinary ([1mP[22m) paragraph resets the indentation,  but  the  inset
            amount is unchanged.
            ┌─────────────────────────────┐
            │ This table is affected only │
            │ by the inset amount.        │
            └─────────────────────────────┘

     Finally,  we  have  ended the relative inset by using [1mRE[22m, which (because we
     used only one [1mRS[22m/[1mRE [22mpair) has restored the  inset  amount  to  its  initial
     value.  This is an ordinary [1mP [22mparagraph.

     Resist  the  temptation  to mock up tabular or multi‐column output with tab
     characters or the indentation arguments to [1mIP[22m, [1mTP[22m, [1mRS[22m, or  [1mHP[22m;  the  result
     may  not  be comprehensible on an output device you fail to check, or which
     is developed in the future.  Consider the  table  preprocessor  ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\  in‐
     stead.

     Several macros insert vertical space: [1mSH[22m, [1mSS[22m, [1mTP[22m, [1mP [22m(and its synonyms), [1mIP[22m,
     and  [1mHP[22m.  They then enable [4mno‐space[24m [4mmode;[24m see ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\.  The default inter‐
     section and inter‐paragraph spacing is 1v for terminals and 0.4v for  type‐
     setters.   “v” is a unit of vertical distance, where 1v is the distance be‐
     tween adjacent text baselines.  (The deprecated macro [1mPD  [22mcan  change  this
     vertical spacing, but we discourage its use.)  Between [1mEX [22mand [1mEE [22mcalls, the
     inter‐paragraph spacing is 1v regardless of output device.

   [1mRegisters[0m
     Registers  are  described  in section “Options” below.  They can be set not
     only on the command line but in the site [4mman.local[24m file as well;  see  sec‐
     tion “Files” below.

   [1mStrings[0m
     The following strings are defined for use in man pages.  [4mgroff[24m [4mman[24m supports
     others for configuration of rendering parameters; see section “Options” be‐
     low.

     [1m\*R     [22minterpolates  a  special  character escape sequence for the “regis‐
             tered sign” glyph, [1m\(rg[22m, if available, and “(Reg.)” otherwise.

     [1m\*S     [22minterpolates an escape sequence setting the type size to the  docu‐
             ment default.

     [1m\*(lq[0m
     [1m\*(rq   [22minterpolate  special  character escape sequences for left and right
             double‐quotation marks, [1m\(lq [22mand [1m\(rq[22m, respectively.

     [1m\*(Tm   [22minterpolates a special character escape  sequence  for  the  “trade
             mark sign” glyph, [1m\(tm[22m, if available, and “(TM)” otherwise.

     A  contemporary man page needs none of the above.  [1m\*S [22mis superfluous; type
     size changes are invisible on terminals, and macros that change it  restore
     its original value afterward.  Better alternatives exist for the rest; sim‐
     ply  use  the  [1m\[rg][22m,  [1m\[lq][22m, [1m\[rq][22m, and [1m\[tm] [22mspecial character escape se‐
     quences directly.  Unless you are aiming for a pathological level of porta‐
     bility——perhaps composing a man page for consumption on simulators of 1980s
     Unix systems (or Solaris [4mtroff[24m, though even it supports “[1m\(rg[22m”)——avoid  us‐
     ing the above strings.

   [1mUse of extensions[0m
     To ensure that your man page formats reliably on a wide variety of viewers,
     write it solely with the macros described in this page (except for the ones
     identified as deprecated, which you should avoid).  Macros described as ex‐
     tensions  might be unsupported by a formatter that is important to your au‐
     dience.  Nevertheless, [4mgroff[24m’s extensions are present because they  perform
     tasks  that are otherwise difficult or tedious to achieve portably.  If you
     require an extension but expect your man page to be rendered  on  a  system
     that  doesn’t  support it, write a configuration test to measure a property
     of the system, and use ]8;;man:m4(1)\[4mm4[24m(1)]8;;\, ]8;;man:sed(1)\[4msed[24m(1)]8;;\, or a similar tool to generate a  [4m.man[0m
     file  from a [4m.man.in[24m file, defining page‐local versions of extension macros
     only where necessary.  You can copy extension macro definitions from [4mgroff[24m;
     see [4man-ext.tmac[24m in section “Files” below.

     For example, we might put a line
            @DEFINE_MR@
     in our [4mman[24m document at the end of the “Name” section, test a system for the
     availability of the [4mgroff[24m [4mman[24m [1mMR [22mmacro, remove the line  if  the  macro  is
     present, and “inline” a definition otherwise, as follows.  (This version is
     slightly  simplified  and does not attempt to disable hyphenation when set‐
     ting arguments to [1mMR[22m.)
            have_MR=$(echo .pm | troff -man 2>&1 | grep 'MR[[:space:]]')
            if [ -n "$have_MR" ]
            then
              sed '/@DEFINE_MR@/d' myprog.man.in > myprog.man
            else
              sed 's/@DEFINE_MR@/.de MR\
            .  ie \\\\n(.$=1 .I \\\\$1\
            .  el .IR \\\\$1 (\\\\$2)\\\\$3\
            ../' myprog.man.in > myprog.man
            fi
     (The profusion of backslashes is due to its status as an  escape  character
     in both [4mroff[24m and [4msed[24m.)

     If  the  foregoing  method is too much trouble, you could apply the radical
     technique of reading your man page using every formatter of interest,  con‐
     firming  satisfactory  output  from each.  Test documentation for syntactic
     validity and semantic correctness, just as you would test code.

   [1mPortability[0m
     GNU [4mtroff[24m expects its input to contain Unicode basic Latin code points  ex‐
     clusively.   One  can  [4mmaintain[24m  it  in  a  more convenient encoding, using
     ]8;;man:preconv(1)\[4mpreconv[24m(1)]8;;\, as with ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\’s [1m-k [22moption, to generate a basic Latin version
     that employs special character escape sequences to access other glyphs.

     AT&T [4mtroff[24m’s [4mman[24m package and those of many of its  descendants  format  man
     pages using a line length of 65 ens (character cells) on terminals, whereas
     [4mgroff[24m [4mman[24m uses 80 ens (and ]8;;man:mandoc(1)\[4mmandoc[24m(1)]8;;\ 78).  Readers with low vision may also
     benefit  from the narrower line length.  Inspect your documents with “[1mnroff[0m
     [1m-t -r LL=65n -man[22m” to ensure that their output lines don’t overrun.

     In [4mroff[24m systems, elemental functions called [4mrequests[24m and  [4mescape[24m  [4msequences[0m
     control  formatting  operations.   A request appears on a control line.  An
     escape sequence starts with a backslash ([1m\[22m) and can appear almost anywhere.
     However, use of [4mroff[24m requests (apart from the empty request “[1m.[22m”) risks poor
     rendering when a page is processed by non‐[4mroff[24m formatters that  attempt  to
     interpret  page  sources.   (Historically,  this was commonly attempted for
     HTML conversion.)  Many of these programs don’t  interpret  the  full  [4mroff[0m
     language  (let alone extensions): they may be incapable of handling numeric
     expressions, control structures, or register,  string,  and  macro  defini‐
     tions,  causing  a  document’s contents to be presented incomprehensibly or
     omitted entirely.  If your document uses formatter requests, or escape  se‐
     quences  not shown below, it accepts responsibility for restoring formatter
     state to what the [4mman[24m macro package expects.

     Do not put blank (empty) lines in a man page  source  document.   They  can
     produce  excessive  space  in  the  output, or less than is attempted; some
     ]8;;man:man(1)\[4mman[24m(1)]8;;\ programs “squeeze” multiple blank output lines into one.

     The wise [4mman[24m author quotes multi‐word section and subsection headings;  the
     [1mSH  [22mand  [1mSS [22mmacros of ]8;;man:man(7)\[4mman[24m(7)]8;;\ implementations descended from Seventh Edition
     Unix supported six arguments at most.  This restriction also applied to the
     [1mB[22m, [1mI[22m, [1mSM[22m, and font style alternation macros.

     Exercise restraint with escape sequences as with requests.  Some escape se‐
     quences are however required for correct typesetting even in man pages  and
     usually  do not cause portability problems.  Several of these render glyphs
     corresponding to punctuation code points in the Unicode basic  Latin  range
     (U+0020–U+007F)  that  are  handled specially in [4mroff[24m input; the escape se‐
     quences below must be used to render them correctly and portably when docu‐
     menting material that uses them as literals——namely, any of the set [1m' - \ ^[0m
     [1m` ~ [22m(apostrophe, dash or  hyphen‐minus,  backslash,  caret,  grave  accent,
     tilde).

     [1m\"        [22mComment.  The formatter ignores everything after the double quote
               to  the  end  of  the input line.  Place whole‐line comments on a
               control line immediately after the empty request (“[1m.[22m”).

     [1m\[4m[22mnewline[24m  Join the next input line to the current one.  Except for the  up‐
               date  of the input line counter (used for diagnostic messages and
               related purposes), a series of lines ending in  backslash‐newline
               appears  to  [4mgroff[24m as a single input line.  Splitting excessively
               long input lines can ease document maintenance.

     [1m\%        [22mControl hyphenation.  The location of this escape sequence within
               a word marks a hyphenation point, supplementing [4mgroff[24m’s automatic
               hyphenation patterns.  At the beginning of a word, it  suppresses
               any hyphenation breaks within [4mexcept[24m those specified with [1m\%[22m.

     [1m\:        [22mInsert  a  non‐printing  break point.  A word can break at such a
               point, but a hyphen glyph is not written  to  the  output  if  it
               does.   The  remainder  of  the word is subject to hyphenation as
               normal.  You can use [1m\: [22mand [1m\% [22min combination to control breaking
               of a file name or URI or to permit hyphenation only after certain
               explicit  hyphens  within  a  word.   See  subsection  “Hyperlink
               macros” above for an example.

               [1m\:  [22mis  a GNU extension also supported by Heirloom Doctools [4mtroff[0m
               050915 (September 2005), [4mmandoc[24m 1.13.1 (2014‐08‐10), and [4mneatroff[0m
               (commit 399a4936, 2014‐02‐17), but not by DWB, Plan 9, or Solaris
               [4mtroff[24ms.

     [1m\~        [22mAdjustable non‐breaking space.  Use this escape sequence to  pre‐
               vent  a  break inside a short phrase or between a numerical quan‐
               tity and its corresponding unit(s).

                      Before starting the motor,
                      set the output speed to\~1.
                      There are 1,024\~bytes in 1\~KiB.
                      CSTR\~#8 documents the B\~language.

               [1m\~ [22mis a GNU extension also supported by Heirloom  Doctools  [4mtroff[0m
               050915  (September  2005),  [4mmandoc[24m  1.9.14 (2009‐11‐16), [4mneatroff[0m
               (commit 1c6ab0f6e, 2016‐09‐13), and Plan 9 from User Space  [4mtroff[0m
               (commit  93f8143600,  2022‐08‐12),  but  not  by  DWB  or Solaris
               [4mtroff[24ms.

     [1m\&        [22mDummy character.  Prefix an input line with it to prevent  a  dot
               or  apostrophe from being interpreted as beginning a [4mroff[24m control
               line.  Append [1m\& [22mto an end‐of‐sentence  punctuation  sequence  to
               keep it from being recognized as such.

     [1m\|        [22mThin  space  (one‐sixth  em  on typesetters, zero‐width on termi‐
               nals);  a  non‐breaking  space.   Used  primarily   in   ellipses
               (“.\|.\|.”) to space the dots more pleasantly on typesetters.

     [1m\c        [22mEnd  a  text  line without inserting space or attempting a break.
               Nothing on the input line after this escape sequence  is  format‐
               ted.   [1m\c [22mis useful when three font styles are needed in a single
               word, as in a command synopsis.

                      .RB [ \-\-stylesheet=\c
                      .IR name ]

               [1m\c [22malso helps when changing font styles in [1mEX[22m/[1mEE [22mexamples,  since
               they are not filled.

                      .EX
                      $ \c
                      .B groff \-T utf8 \-Z \c
                      .I file \c
                      .B | grotty \-i
                      .EE

               Normally,  if filling is enabled, the formatter treats the end of
               a text line like a space.  It checks for the end of  a  sentence,
               and  [4mmay[24m  break the output line (if not, it inserts an adjustable
               space).  If filling is disabled, the  formatter  [4mwill[24m  break  the
               output  line, as in [1mEX[22m/[1mEE [22mexamples.  The formatter interprets the
               next input line as usual, recognizing  control  lines,  including
               macro calls (contrast with [1m\[4m[22mnewline[24m).

               The  [1m\f  [22mfont  selection escape sequence is an alternative to [1m\c[22m;
               see below.  Using [1m\c [22mto continue a [1mTP [22mparagraph tag across multi‐
               ple input lines renders incorrectly  with  [4mgroff[24m  1.22.3,  [4mmandoc[0m
               1.14.1,  older  versions of these programs, and perhaps with some
               other formatters.

     [1m\e        [22mFormat the [4mroff[24m escape character on the output;  widely  used  in
               man pages to render a backslash glyph.  It works reliably as long
               as the “ec” request is not used, which should never happen in man
               pages,  and  it  is slightly more portable than the more explicit
               [1m\[rs] [22m(“reverse solidus”) special character escape sequence.

     [1m\fB[22m, [1m\fI[22m, [1m\fR[22m, [1m\fP[0m
               Switch to bold, italic, roman, or back to the previous style, re‐
               spectively.  Either [1m\f [22mor [1m\c [22mis needed when three different  font
               styles are required in a word.

                      .RB [ \-\-reference\-dictionary=\fI\,name\/\fP ]

                      .RB [ \-\-reference\-dictionary=\c
                      .IR name ]

               Style  escape  sequences  may be more portable than [1m\c[22m.  As shown
               above, it is up to you to account  for  italic  corrections  with
               “[1m\/[22m”  and  “[1m\,[22m”,  which are themselves GNU extensions, if desired
               and if supported by your implementation.

               [1m\fP [22mreliably returns to the style in  use  immediately  preceding
               the previous [1m\f [22mescape sequence only if no sectioning, paragraph,
               example, or style macro calls have intervened.

               As  long as at most two styles are needed in a word, style macros
               like [1mB [22mand [1mBI [22musually result in more readable [4mroff[24m source than [1m\f[0m
               escape sequences do.

     Several special characters are also widely portable.  Except for [1m\-[22m, [1m\[em][22m,
     and [1m\[ga][22m, AT&T [4mtroff[24m did not consistently define the characters listed be‐
     low, but its descendants, like DWB, Plan 9, or Solaris [4mtroff[24m, can  be  made
     to  support  them  by  defining them in font description files, making them
     aliases of existing glyphs if necessary; see  ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.   [4mgroff[24m’s  ex‐
     tended  notation  for  special  characters,  [1m\[[4m[22mxx[24m[1m][22m,  is  also  supported by
     ]8;;man:mandoc(1)\[4mmandoc[24m(1)]8;;\, Heirloom Doctools [4mtroff[24m, and [4mneatroff[24m, but not DWB, Plan  9,  or
     Solaris [4mtroff[24ms.

     [1m\-     [22mMinus sign.  [1m\- [22mproduces the basic Latin hyphen‐minus (U+002D) spec‐
            ifying  Unix command‐line options and frequently used in file names.
            “[1m-[22m” is a hyphen in [4mroff[24m; some output devices  format  it  as  U+2010
            (hyphen).

     [1m\[aq]  [22mBasic Latin neutral apostrophe.  Some output devices format “[1m'[22m” as a
            right single quotation mark.

     [1m\[oq][0m
     [1m\[cq]  [22mOpening  (left)  and  closing  (right)  single quotation marks.  Use
            these for paired directional single quotes, ‘like this’.

     [1m\[dq]  [22mBasic Latin quotation mark (double quote).  Employ it in macro calls
            to work around interpretation of ‘[1m"[22m’ as an argument delimiter.

                   .TP
                   .BI "split \[dq]" text \[dq]

     [1m\[lq][0m
     [1m\[rq]  [22mLeft and right double quotation marks.  Use these for paired  direc‐
            tional double quotes, “like this”.

     [1m\[em]  [22mEm dash.  Use for an interruption——such as this one——in a sentence.

     [1m\[en]  [22mEn  dash.   Use to separate the ends of a range, as between numbers;
            for example, “the digits 1–9”.

     [1m\[ga]  [22mBasic Latin grave accent.  Some output devices format “[1m`[22m” as a  left
            single quotation mark.

     [1m\[ha]  [22mBasic  Latin  circumflex accent (“hat”).  Some output devices format
            “[1m^[22m” as U+02C6 (modifier letter circumflex accent).

     [1m\[rs]  [22mReverse solidus (backslash).  The backslash is  the  default  escape
            character  in  the [4mroff[24m language, so it does not represent itself in
            output.  Also see [1m\e [22mabove.

     [1m\[ti]  [22mBasic Latin tilde.  Some output devices format “[1m~[22m” as U+02DC  (small
            tilde).

     For  maximum portability, avoid escape sequences (including special charac‐
     ters) not listed above.

   [1mHooks[0m
     Two macros, both GNU extensions, are called internally  by  the  [4mgroff[24m  [4mman[0m
     package  to format page headers and footers and can be redefined by the ad‐
     ministrator in a site’s [4mman.local[24m file (see section  “Files”  below).   The
     presentation  of  [1mTH  [22mabove describes the default headers and footers.  Be‐
     cause these macros are hooks for [4mgroff[24m [4mman[24m internals,  man  pages  have  no
     reason  to  call them.  Such hook definitions typically consist of “sp” and
     “tl” requests.  [1mPT [22mfurthermore has the responsibility  of  emitting  a  PDF
     bookmark  after  writing  the first page header in a document.  Consult the
     existing implementations in [4man.tmac[24m when drafting replacements.

     [1m.BT    [22mSet the page footer text (“bottom trap”).

     [1m.PT    [22mSet the page header text (“page trap”).

     To remove a page header or footer entirely, define the appropriate macro as
     empty rather than deleting it.

   [1mDeprecated features[0m
     Use of the following in man pages for public distribution is discouraged.

     [1m.AT [22m[[4msystem[24m [[4mrelease[24m]]
            Alter the footer for use with legacy AT&T man pages, overriding  any
            definition  of  the [4mfooter‐inside[24m argument to [1mTH[22m.  This macro exists
            only to render man pages from historical systems.

            The inside footer is populated per the value of [4msystem.[0m

                   3      7th edition [4m(default)[0m

                   4      System III

                   5      System V

            The optional [4mrelease[24m argument specifies the release  number,  as  in
            “System V Release 3”.

     [1m.DT    [22mReset tab stops to the default (every 0.5i [inches]).

            Use  of  this  presentation‐oriented macro is deprecated.  It trans‐
            lates poorly to HTML, under which exact space control and tabulation
            are not readily available.  Thus, information or  distinctions  that
            you  use  tab  stops  to express are likely to be lost.  If you feel
            tempted to change the tab stops such that calling this  macro  later
            to  restore  them  is  desirable,  consider  composing a table using
            ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\ instead.

     [1m.OP [4m[22moption‐name[24m [[4moption‐argument[24m]
            Indicate an optional command parameter called [4moption‐name[24m, which  is
            set  in bold.  If the option takes an argument, specify [4moption‐argu‐[0m
            [4mment[24m using a noun, abbreviation,  or  hyphenated  noun  phrase.   If
            present,  [4moption‐argument[24m is preceded by a space and set in italics.
            Square brackets in roman surround both arguments.

            Use of this quasi‐semantic macro, an extension whose name originated
            in DWB [4mtroff[24m, is deprecated; [4mgroff[24m’s interface differs.  Neither can
            easily be used to annotate options that take optional  arguments  or
            options  whose  arguments have internal structure (such as a mixture
            of literal and variable components).  One could  work  around  these
            limitations with font selection escape sequences, but font style al‐
            ternation  macros are preferable; they are more flexible and perform
            italic corrections on typesetters.

     [1m.PD [22m[[4mvertical‐space[24m]
            Configure  the  amount  of  vertical  space  between  paragraphs  or
            (sub)sections.   The  optional argument [4mvertical‐space[24m specifies the
            amount; the default scaling unit is “v”.  Without an  argument,  in‐
            ter‐paragraph  spacing  resets  to its default value; see subsection
            “Horizontal and vertical spacing” above.

            Use of this presentation‐oriented macro is  deprecated.   It  trans‐
            lates  poorly  to HTML, under which exact control of inter‐paragraph
            spacing is not readily available.  Thus, information or distinctions
            that you use [1mPD [22mto express are likely to be lost.

     [1m.SB [22m[[4mtext[24m]
            Set [4mtext[24m in bold and (on typesetters) one point smaller than the de‐
            fault type size.  Given no argument,  [1mSB  [22mplants  a  one‐line  input
            trap;  text  on the next line, which can be further formatted with a
            macro, is set smaller and in bold.  Use of this macro, an  extension
            originating  in SunOS 4.0 [4mtroff[24m, is deprecated.  [1mSM [22mwithout an argu‐
            ment, followed immediately by “[1mB [4m[22mtext[24m”,  produces  the  same  output
            more  portably.  The macros’ order is interchangeable; put [4mtext[24m with
            the latter.

            [4mNote:[24m terminals render [4mtext[24m in bold at the normal size instead.   Do
            not  rely  upon [1mSB [22mto communicate semantic information distinct from
            using bold style at normal size; it is  hidden  from  readers  using
            such devices.

     [1m.UC [22m[[4mversion[24m]
            Alter  the  footer for use with legacy BSD man pages, overriding any
            definition of the [4mfooter‐inside[24m argument to [1mTH[22m.  This  macro  exists
            only to render man pages from historical systems.

            The inside footer is populated per the value of [4mversion.[0m

                   3      3rd Berkeley Distribution [4m(default)[0m

                   4      4th Berkeley Distribution

                   5      4.2 Berkeley Distribution

                   6      4.3 Berkeley Distribution

                   7      4.4 Berkeley Distribution

   [1mHistory[0m
     ]8;;mailto:m.douglas.mcilroy@dartmouth.edu\M.  Douglas  McIlroy]8;;\  designed,  implemented,  and  documented the AT&T [4mman[0m
     macros for Unix Version 7 (1979) and employed them to edit Volume 1 of  its
     [4mProgrammer’s[24m [4mManual[24m, a compilation of all man pages supplied by the system.
     The  package  supported the macros listed in this page not described as ex‐
     tensions, except [1mP [22mand the deprecated [1mAT [22mand [1mUC[22m.  It documented  no  regis‐
     ters and defined only [1mR [22mand [1mS [22mstrings.

     [1mUC  [22mappeared  in  3BSD (1980).  Unix System III (1980) introduced [1mP [22mand ex‐
     posed the registers [1mIN [22mand [1mLL[22m, which had been internal to  Seventh  Edition
     Unix  [4mman[24m.   PWB/Unix 2.0 (1980) added the [1mTm [22mstring.  4BSD (1980) added [1mlq[0m
     and [1mrq [22mstrings.  SunOS 2.0 (1985) recognized [1mC[22m,  [1mD[22m,  [1mP[22m,  and  [1mX  [22mregisters.
     4.3BSD  (1986) added [1mAT [22mand [1mP[22m.  Ninth Edition Unix (1986) introduced [1mEX [22mand
     [1mEE[22m.  SunOS 4.0 (1988) added [1mSB[22m.  Unix System V (1988) incorporated  the  [1mlq[0m
     and [1mrq [22mstrings.

     Except  for  [1mEX[22m/[1mEE[22m, James Clark implemented the foregoing features in early
     versions of [4mgroff.[24m  Later, [4mgroff[24m 1.20 (2009) resurrected [1mEX[22m/[1mEE  [22mand  origi‐
     nated  [1mSY[22m/[1mYS[22m,  [1mTQ[22m, [1mMT[22m/[1mME[22m, and [1mUR[22m/[1mUE[22m.  Plan 9 from User Space’s [4mtroff[24m intro‐
     duced [1mMR [22min 2020, and incorporated the [1mlq [22mand [1mrq [22mstrings in 2025.

[1mOptions[0m
     The following [4mgroff[24m options set registers (with [1m-r[22m) and strings  (with  [1m-d[22m)
     recognized  and used by the [4mman[24m macro package.  To ensure rendering consis‐
     tent with output device capabilities  and  reader  preferences,  man  pages
     should never manipulate them.

     [1m-dAD=[4m[22madjustment‐mode[0m
              Set line adjustment to [4madjustment‐mode,[24m which is typically “[1mb[22m” for
              adjustment  to  both margins (the default), or “[1ml[22m” for left align‐
              ment (ragged right margin).  Any valid argument  to  [4mgroff[24m’s  “ad”
              request may be used.  See ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\ for less‐common choices.

     [1m-rBP=[4m[22mbase‐paragraph‐inset[0m
              Set  the  inset amount for ordinary paragraphs not within an [1mRS[22m/[1mRE[0m
              inset.  The default is 5n.

     [1m-rcR=1   [22mEnable continuous rendering.  Output is  not  paginated;  instead,
              one (potentially very long) page is produced.  This is the default
              for terminal and HTML devices.  Use [1m-rcR=0 [22mto disable it on termi‐
              nals; on HTML devices, it cannot be disabled.

     [1m-rC1     [22mNumber  output  pages  consecutively,  in  strictly increasing se‐
              quence, rather than resetting the page number to 1 (or  the  value
              of register [1mP[22m) with each new [4mman[24m document.

     [1m-rCHECKSTYLE=[4m[22mn[0m
              Report  problems with usage of this macro package exhibited by the
              input at verbosity level [4mn[24m, where [4mn[24m is an  integer  in  the  range
              0–3,  inclusive; [1m0 [22mdisables the messages and is the default.  This
              feature is a development and debugging aid for man page  maintain‐
              ers;  the  problems  diagnosed, and range and meanings of the sup‐
              ported levels, are subject to change.

     [1m-rCS=1   [22mSet section headings (the argument(s) to  [1mSH[22m)  in  full  capitals.
              This  transformation is off by default because it discards letter‐
              case distinctions.

     [1m-rCT=1   [22mSet the man page identifier (the first argument  to  [1mTH[22m)  in  full
              capitals  in  headers  and footers.  This transformation is off by
              default because it discards lettercase distinctions.

     [1m-rD1     [22mEnable double‐sided layout, formatting footers for  even  and  odd
              pages  differently; see the description of [1mTH [22min subsection “Docu‐
              ment structure macros” above.

     [1m-rFT=[4m[22mfooter‐distance[0m
              Set distance of the footer relative to the bottom of the  page  to
              [4mfooter‐distance;[24m this amount is always negative.  At one half‐inch
              above  this  location,  the page text is broken before writing the
              footer.  Ignored if continuous rendering is enabled.  The  default
              is “-0.5i - 1v”.

     [1m-dHF=[4m[22mheading‐font[0m
              Select  the font used for section and subsection headings; the de‐
              fault is “[1mB[22m” (bold style of the default family).  Any valid  argu‐
              ment to [4mgroff[24m’s “ft” request may be used.  See ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\.

     [1m-rHY=0   [22mDisable  automatic hyphenation.  Normally, it is enabled (1).  The
              hyphenation mode is determined by the [4mgroff[24m  locale;  see  section
              “Localization“ of ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\.

     [1m-rIN=[4m[22mstandard‐indentation[0m
              Set the default indentation amount used by [1mIP[22m, [1mTP[22m, and [1mHP[22m, and the
              inset  amount used by [1mRS[22m.  The default is 7n on terminals and 7.2n
              on typesetters.  Use only integer multiples of unit “n” on  termi‐
              nals for consistent indentation.

     [1m-rLL=[4m[22mline‐length[0m
              Set line length; the default is 80n on terminals and 6.5i on type‐
              setters.

     [1m-rLT=[4m[22mtitle‐length[0m
              Set  the  line  length for titles.  (“Titles” is the [4mroff[24m term for
              headers and footers.)  By default, it is set to  the  line  length
              (see [1m-rLL [22mabove).

     [1m-dMF=[4m[22mman‐page‐topic‐font[0m
              Select the font used for man page identifiers in [1mTH [22mcalls and top‐
              ics named in [1mMR [22mcalls; the default is “[1mI[22m” (italic style of the de‐
              fault  family).  Any valid argument to [4mgroff[24m’s “ft” request may be
              used.  If the [1mMF [22mstring ends in “I”, the package assumes it to  be
              an oblique typeface, and applies italic corrections before and af‐
              ter man page topics and identifiers.

     [1m-rP[4m[22mn[24m     Start enumeration of pages at [4mn[24m.  The default is 1.

     [1m-rPO=[4m[22mpage‐offset[0m
              Set  page offset; the default is 0 on terminals and 1i on typeset‐
              ters.

     [1m-rS[4m[22mtype‐size[0m
              Use [4mtype‐size[24m for the document’s body text; acceptable values  are
              10,  11,  or  12 points.  See subsection “Font style macros” above
              for the default.

     [1m-rSN=[4m[22msubsection‐indentation[0m
              Set indentation of subsection headings to  [4msubsection‐indentation.[0m
              The default is 3n.

     [1m-rTS=[4m[22mseparation[0m
              Require  the given [4mseparation[24m between a [1mTP [22mparagraph’s tag and its
              body.  The default is 2n.

     [1m-rU0     [22mDisable generation of URI hyperlinks in output drivers capable  of
              them, making the arguments to [1mMT [22mand [1mUR [22mcalls visible as formatted
              text.   ]8;;man:grohtml(1)\[4mgrohtml[24m(1)]8;;\,  ]8;;man:gropdf(1)\[4mgropdf[24m(1)]8;;\, and ]8;;man:grotty(1)\[4mgrotty[24m(1)]8;;\ enable hyperlinks by
              default (the last only if not in its legacy output mode).

     [1m-rX[4m[22mp[24m     Number successors of page [4mp[24m as [4mp[24ma, [4mp[24mb, [4mp[24mc, and so forth.  The reg‐
              ister tracking the suffixed page letter uses format “a”  (see  the
              “af”  request in ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\).  For example, the option [1m-rX2 [22mproduces
              the following page numbers: 1, 2, 2a, 2b, ..., 2aa,  2ab,  and  so
              on.

[1mFiles[0m
     [4m/usr/share/groff/1.24.1/tmac/an.tmac[0m
            Most  [4mman[24m macros are defined in this file.  It also loads extensions
            from [4man-ext.tmac[24m (see below).

     [4m/usr/share/groff/1.24.1/tmac/andoc.tmac[0m
            This brief [4mgroff[24m program detects whether the [4mman[24m or [4mmdoc[24m macro pack‐
            age is used by a document and loads the correct  macro  definitions,
            taking  advantage  of the fact that pages using them must call [1mTH [22mor
            [1mDd[22m, respectively, before any other macros.  A [4mman[24m program or a  user
            typing,  for  example,  “[1mgroff  -mandoc page.1[22m”, need not know which
            package the file [4mpage.1[24m uses.  Multiple man pages, in either format,
            can be handled; [4mandoc[24m  reloads  each  macro  package  as  necessary.
            Page‐local  redefinitions  of names used by the [4mman[24m or [4mmdoc[24m packages
            prior to [1mTH [22mor [1mDd [22mcalls are “clobbered” by  the  reloading  process.
            If  you want to provide your own definition of an extension macro to
            ensure its availability, the [4man-ext.tmac[24m entry below offers advice.

     [4m/usr/share/groff/1.24.1/tmac/an-ext.tmac[0m
            Definitions of macros described above as extensions (and not  depre‐
            cated)  are  contained in this file; in some cases, they are simpler
            versions of definitions appearing in [4man.tmac[24m, and are ignored if the
            formatter is GNU [4mtroff[24m.  They are written to be compatible with AT&T
            [4mtroff[24m and permissively licensed——not copylefted.  To reduce the risk
            of name space collisions, string and register names begin only  with
            “[1mm[22m”.   We  encourage man page authors who are concerned about porta‐
            bility to legacy Unix systems to copy these definitions  into  their
            pages,  and  maintainers of [4mtroff[24m implementations or work‐alike sys‐
            tems that format man pages to re‐use them.  To ensure reliable  ren‐
            dering,  define them after your page calls [1mTH[22m; see the discussion of
            [4mandoc.tmac[24m above.  Further, it is wise  to  define  such  page‐local
            macros  (if  at  all)  after the “Name” section to accommodate timid
            ]8;;man:makewhatis(8)\[4mmakewhatis[24m(8)]8;;\ or ]8;;man:mandb(8)\[4mmandb[24m(8)]8;;\ implementations that easily give up  scan‐
            ning for indexing material.

     [4m/usr/share/groff/1.24.1/tmac/man.tmac[0m
            is  a  wrapper enabling the package to be loaded with the option “[1m-m[0m
            [1mman[22m”.

     [4m/usr/share/groff/1.24.1/tmac/mandoc.tmac[0m
            is a wrapper enabling [4mandoc.tmac[24m to be loaded with  the  option  “[1m-m[0m
            [1mmandoc[22m”.

     [4m/usr/share/groff/site-tmac/man.local[0m
            Put site‐local changes and customizations into this file.

                   .\" Put only one space after the end of a sentence.
                   .ss 12 0 \" See groff(7).
                   .\" Keep pages narrow even on wide terminals.
                   .if n .if \n[LL]>80n .nr LL 80n

            On multi‐user systems, it is more considerate to users whose prefer‐
            ences may differ from the administrator’s to be less aggressive with
            such  settings,  or  to  permit  their override with a user‐specific
            [4mman.local[24m file.  Place the requests below at the end of the site‐lo‐
            cal file to manifest courtesy.
                   .soquiet \V[XDG_CONFIG_HOME]/man.local
                   .soquiet \V[HOME]/.man.local
            However, a security‐sandboxed ]8;;man:man(1)\[4mman[24m(1)]8;;\ program may lack permission  to
            open such files.

[1mNotes[0m
     Some tips on composing and troubleshooting your man pages follow.

     • What’s the difference between a man page topic and identifier?

       A  single man page may document several related but distinct topics.  For
       example, ]8;;man:printf(3)\[4mprintf[24m(3)]8;;\ and ]8;;man:fprintf(3)\[4mfprintf[24m(3)]8;;\ are often  presented  together.   More‐
       over,  multiple  programming languages have functions named “printf”, and
       may document these in a man page.  The identifier is  intended  to  (with
       the  section)  uniquely identify a page on the system; it may furthermore
       correspond closely to the file name of the document.

       The ]8;;man:man(1)\[4mman[24m(1)]8;;\ librarian makes access to man pages  convenient  by  resolving
       topics  to  man  page identifiers.  Thus, you can type “[1mman fprintf[22m”, and
       other pages can refer to it, without knowing whether the installed  docu‐
       ment uses “printf”, “fprintf”, or even “c_printf” as its identifier.

     • Some ASCII characters look funny or copy and paste wrong.

       On devices with large glyph repertoires, like UTF‐8‐capable terminals and
       PDF,  GNU  [4mtroff[24m, like AT&T [4mtroff[24m before it, maps several keycaps to code
       points outside the Unicode basic Latin range (historically  “ASCII”)  be‐
       cause  that  usually  results  in  better typography in the general case.
       When documenting GNU/Linux command or C language  syntax,  however,  this
       translation is sometimes not desirable.

       [1mTo get a “literal”...   ...should be input.[0m
       ────────────────────────────────────────────
                           '   \[aq]
                           -   \-
                           \   \[rs]
                           ^   \[ha]
                           `   \[ga]
                           ~   \[ti]
       ────────────────────────────────────────────

       If  a neutral double quote (") is needed in a macro argument, you can use
       [1m\[dq] [22mto get it.  Do [4mnot[24m use [1m\[aq] [22mfor  an  ordinary  apostrophe  (as  in
       “can’t”) or [1m\- [22mfor an ordinary hyphen (as in “word‐aligned”).

     • Do I ever need to use an empty macro argument ("")?

       Probably  not.  When this seems necessary, often a shorter or clearer al‐
       ternative is available.

              [1mInstead of...               ...should be considered.[0m
       ────────────────────────────────────────────────────────────────
       .TP ""                         .TP
       ────────────────────────────────────────────────────────────────
       .BI "" [4mitalic‐text[24m [4mbold‐text[24m   .IB [4mitalic‐text[24m [4mbold‐text[0m
       ────────────────────────────────────────────────────────────────
       .TH foo 1 "" "foo 1.2.3"       .TH foo 1 [4myyyy[24m‐[4mmm[24m‐[4mdd[24m "foo 1.2.3"
       ────────────────────────────────────────────────────────────────
       .IP "" 4n                      .IP
       ────────────────────────────────────────────────────────────────
       .IP "" 4n                      .RS 4n
       [4mparagraph[24m                      .P
       ...                            [4mparagraph[0m
       ...                            .RE
       ────────────────────────────────────────────────────────────────
       .B one two "" three            .B one two three

       In the title heading ([1mTH[22m), the date of the page’s last revision  is  more
       important than packaging information; it should not be omitted.  Ideally,
       a page maintainer keeps both up to date.

       [1mIP [22mis sometimes ill‐understood and misused, especially when no mark argu‐
       ment is supplied——an indentation argument is not required.  By setting an
       explicit  indentation,  you  may be overriding the reader’s preference as
       set with the [1m-rIN [22moption.  If your page renders adequately  without  one,
       use  the  simpler  form.  If you need to indent multiple (unmarked) para‐
       graphs, consider setting an inset region with [1mRS [22mand [1mRE [22minstead.

       In the last example, the empty argument does have a subtly different  ef‐
       fect  than  its suggested replacement: the empty argument causes an addi‐
       tional space character to be interpolated between the arguments “two” and
       “three”——but it is a regular breaking space, so it can  be  discarded  at
       the  end  of an output line.  It is better not to be subtle, particularly
       with space, which can be overlooked in source and rendered forms.

     • [1mRS [22mdoesn’t indent relative to my indented paragraph.

       The [1mRS [22mmacro determines the [4minset[24m [4mamount,[24m the position at which an  [4mordi‐[0m
       [4mnary[24m  paragraph ([1mP [22mand its synonyms) is set; the value of the [1mIN [22mregister
       determines its default amount.  This register also determines the default
       indentation used by [1mIP[22m, [1mTP[22m, and [1mHP[22m.  To create an inset  relative  to  an
       indented paragraph, call [1mRS [22mrepeatedly until an acceptable indentation is
       achieved,  or give [1mRS [22man indentation argument that is at least as much as
       the paragraph’s indentation amount relative to an adjacent  ordinary  ([1mP[22m)
       paragraph.

       Another approach to tagged paragraphs places an [1mRS [22mcall immediately after
       the  tag;  this  also forces a break regardless of the tag’s width, which
       some authors prefer.  Follow‐up paragraphs under the tag can then be  set
       with  [1mP [22minstead of [1mIP[22m.  Remember to use [1mRE [22mto end the indented region be‐
       fore starting the next  tagged  paragraph  (at  the  appropriate  nesting
       level).

     • [1mRE [22mdoesn’t move the inset back to the expected level.

       [1mRE  [22mtakes  an  inset  [4mlevel[24m  as  an  argument,  unlike [1mRS[22m’s inset [4mamount.[0m
       “[1m.RE 1[22m” goes to the level before any [1mRS [22mmacros were called, [1mRE 2 [22mgoes  to
       the  level  of  the  first [1mRS [22mcall you made, and so forth.  If you desire
       symmetry in your macro calls, simply issue one [1mRE [22mwithout an argument for
       each [1mRS [22mthat precedes it.

       The [1mSH [22mand [1mSS [22msectioning macros clear relative insets; [1mRE [22mcalls  have  no
       effect until [1mRS [22mis used again.

     • Do I need to keep typing the indentation in a series of [1mIP [22mcalls?

       Not  if  you  don’t want to change it.  Review subsection “Horizontal and
       vertical spacing” above.

         [1mInstead of...     ...should be considered.[0m
       ─────────────────────────────────────────────
       .IP \[bu] 4n        .IP \[bu] 4n
       [4mparagraph[24m           [4mparagraph[0m
       .IP \[bu] 4n        .IP \[bu]
       [4manother‐paragraph[24m   [4manother‐paragraph[0m
       ─────────────────────────────────────────────

     • Why doesn’t the package provide a string to insert an ellipsis?

       Examples of ellipsis usage  are  shown  above,  in  subsection  “Synopsis
       macros”.   The  idiomatic [4mroff[24m ellipsis is three dots (periods) with thin
       space escape sequences [1m\| [22minternally separating them.   Since  dots  both
       begin  control  lines  and are candidate end‐of‐sentence characters, how‐
       ever, it is sometimes necessary to prefix and/or suffix an ellipsis  with
       the  dummy  character  escape  sequence  [1m\&[22m.   That fact stands even if a
       string is defined to contain the sequence; further, if  the  string  ends
       with [1m\&[22m, end‐of‐sentence detection is defeated when you use the string at
       the  end  of  an actual sentence.  (Ending a sentence with an ellipsis is
       often poor style, but not always.)  A hypothetical string  [1mEL  [22mthat  con‐
       tained  an  ellipsis, but not the trailing dummy character [1m\&[22m, would then
       need to be suffixed with the latter when not ending a sentence.

           [1mInstead of...              ...do this.[0m
       ──────────────────────────────────────────────────
       .ds EL \&.\|.\|.         Arguments are
       Arguments are            .IR src‐file\~ .\|.\|.\&
       .IR src‐file\~ \*(EL\&   .IR dest‐dir .
       .IR dest‐dir .
       ──────────────────────────────────────────────────

       The first column practices a false economy; the savings in typing is off‐
       set by the cost of obscuring even the suggestion of an ellipsis to a  ca‐
       sual  reader  of the source document, and reduced portability to non‐[4mroff[0m
       man page formatters that cannot handle string definitions.

       Unicode defines an ellipsis code point, and some fonts have  an  ellipsis
       glyph,  which some man pages have accessed non‐portably with the font‐de‐
       pendent [1m\N [22mescape sequence.  We discourage their use; on terminals,  they
       may crowd the dots into a half‐width character cell, and do not render at
       all  if the output device lacks the glyph.  In synopses, missing ellipses
       can mislead the reader.  Dots and space are universally supported.

     • When and how should I use quotation marks?

       As noted above in subsection “Font style macros”, apply  quotation  marks
       to “brief specimens of literal text, such as article titles, inline exam‐
       ples,  mentions  of individual characters or short strings, and (sub)sec‐
       tion headings in man pages”.  Multi‐word literals, such as Unix  commands
       with  arguments,  when set inline (as opposed to displayed between [1mEX [22mand
       [1mEE[22m), should be quoted to ensure that the boundaries of  the  literal  are
       clear even when the material is stripped of font styling by, for example,
       copy‐and‐paste operations.  [4mgroff[24m, Heirloom Doctools [4mtroff[24m, [4mneatroff[24m, and
       [4mmandoc[24m  support all of the special characters [1m\[oq][22m, [1m\[cq][22m, [1m\[lq][22m, [1m\[rq][22m,
       [1m\[aq][22m, and [1m\[dq]  [22mdescribed  in  subsection  “Portability”  above.   DWB,
       Plan  9,  and Solaris [4mtroff[24ms do not.  Interpolating the strings [1m\*(lq [22mand
       [1m\*(rq [22mportably yields directional double quotation marks,  if  available,
       in  all  these  formatters  (though  [4mneatroff[24m does not supply a [4mman[24m macro
       package), but they cannot reliably be used in macro arguments.

       Obtaining directional single quotation marks  is  more  of  a  challenge.
       Historically, man pages used [1m` [22mand [1m', [22mwhich [4mtroff[24m rendered on typesetters
       as  ‘  and  ’, exclusively for them.  However, in recent years, some dis‐
       tributors of [4mgroff[24m have chosen to override the meanings of these  charac‐
       ters  in  man  pages,  remapping  them  to their Unicode Basic Latin code
       points.  Unfortunately, [1m` [22mand [1m' [22mare the [4monly[24m reliable means of  obtaining
       directional single quotation marks in AT&T [4mtroff[24m; in that implementation,
       often  no  special character escape sequences exist to obtain them.  Fur‐
       ther, AT&T [4mtroff[24m’s special character identifiers, like  its  font  names,
       were  device‐specific.   To  achieve quotation portably in man pages ren‐
       dered both by AT&T and more modern [4mtroff[24ms, consider adding a preamble  to
       your page after the [1mTH [22mcall as follows.

              .ie \n(.g \{\
              .  ds oq \[oq]\"
              .  ds cq \[cq]\"
              .\}
              .el \{\
              .  ds oq `\"
              .  ds cq '\"
              .\}

       You  must  then  use  the [1m\* [22mescape sequence to interpolate the quotation
       mark strings.

              The command
              .RB \*(oq "while !\& git pull; do sleep 10; done" \*(cq
              retries an update from the repository until it succeeds.

       If this procedure seems complex,  petition  your  distributor  to  revert
       their remapping of the ` and ' characters.

     • Escape sequences of the form [1m\[[4m[22mxx[24m[1m] [22mdon’t format correctly.

       The [1m\[[4m[22mxx[24m[1m] [22mspecial character escape sequence is a GNU [4mtroff[24m extension also
       supported by [4mmandoc,[24m Heirloom Doctools [4mtroff,[24m and [4mneatroff.[24m  DWB, Plan 9,
       and  Solaris [4mtroff[24ms don’t implement it.  If your man page requires porta‐
       bility to these formatters, spell such escape  sequences  as  “[1m\([4m[22mxx[24m”;  no
       closing  parenthesis  is  used.   [4mxx[24m  must  be  exactly  two  characters;
       ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\ lists portable special character identifiers.

[1mAuthors[0m
     James Clark wrote the initial GNU implementation of the [4mman[24m macro  package.
     Later,  ]8;;mailto:wl@gnu.org\Werner  Lemberg]8;;\  supplied  the  [1mS[22m, [1mLT[22m, and [1mcR [22mregisters, the last a
     4.3BSD‐Reno [4mmdoc[24m(7) feature.  ]8;;mailto:kollar@alltel.net\Larry Kollar]8;;\ added the [1mFT[22m, [1mHY[22m, and [1mSN  [22mregis‐
     ters;  the  [1mHF [22mstring; and the [1mPT [22mand [1mBT [22mmacros in [4mgroff[24m 1.19 (2003).  Lem‐
     berg and ]8;;mailto:esr@thyrsus.com\Eric S. Raymond]8;;\ contributed [1mEX[22m/[1mEE[22m, [1mMT[22m/[1mME[22m, [1mUR[22m/[1mUE[22m, [1mTQ[22m, and an  early
     version  of the [1mSY[22m/[1mYS [22mmacros to [4mgroff[24m 1.20 (2009).  ]8;;mailto:g.branden.robinson@gmail.com\G. Branden Robinson]8;;\ im‐
     plemented the [1mAD [22mand [1mMF [22mstrings; [1mCS[22m, [1mCT[22m, and [1mU [22mregisters; and the [1mMR  [22mmacro
     for  [4mgroff[24m  1.23 (2023), and the [1mBP[22m, [1mPO[22m, and [1mTS [22mregisters and a revised im‐
     plementation of the [1mSY[22m/[1mYS [22mmacros for [4mgroff[24m 1.24 (2026).

     ]8;;mailto:sgk@debian.org\Susan G. Kleinmann]8;;\ wrote the initial version of this document for  the  De‐
     bian  GNU/Linux system.  Lemberg imported it to [4mgroff.[24m  He and Robinson re‐
     vised and updated  it.   Raymond  and  Robinson  documented  the  extension
     macros.   Raymond  also  originated  the portability section, to which ]8;;mailto:schwarze@usta.de\Ingo
     Schwarze]8;;\ contributed most of the material on escape sequences.

[1mSee also[0m
     ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\, ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\, and ]8;;man:refer(1)\[4mrefer[24m(1)]8;;\ are preprocessors used with man pages.  ]8;;man:man(1)\[4mman[24m(1)]8;;\
     describes the man page librarian on your system.  ]8;;man:groff_mdoc(7)\[4mgroff_mdoc[24m(7)]8;;\ details the
     [4mgroff[24m version of BSD’s alternative macro package for man pages.

     ]8;;man:groff_man(7)\[4mgroff_man[24m(7)]8;;\, ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\, ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\

groff 1.24.1                       2026‐03‐20                 [4mgroff_man_style[24m(7)
────────────────────────────────────────────────────────────────────────────────
[4mgroff_mdoc[24m(7)            Miscellaneous Information Manual          [4mgroff_mdoc[24m(7)

[1mName[0m
     [1mgroff_mdoc [22m—— compose BSD‐style manual (man) pages with GNU [4mroff[0m

[1mSynopsis[0m
     [1mgroff -mdoc [4m[22mfile[24m ...

[1mDescription[0m
     The GNU implementation of the [4mmdoc[24m macro package is part  of  the  ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\
     document  formatting system.  [4mmdoc[24m is a structurally‐ and semantically‐ori‐
     ented package for writing Unix manual pages with ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\.   Its  predeces‐
     sor, the ]8;;man:man(7)\[4mman[24m(7)]8;;\ package, primarily addressed page layout and presentational
     concerns,  leaving  the selection of fonts and other typesetting details to
     the individual author.  This discretion has led to divergent styling  prac‐
     tices among authors using it.

     [4mmdoc[24m organizes its macros into [4mdomains[24m.  The [4mpage[24m [4mstructure[24m [4mdomain[24m lays out
     the  page and comprises titles, section headings, displays, and lists.  The
     [4mgeneral[24m [4mtext[24m [4mdomain[24m supplies macros to quote or style text, or to  interpo‐
     late  common noun phrases.  The [4mmanual[24m [4mdomain[24m offers semantic macros corre‐
     sponding to the terminology used by practitioners  in  discussion  of  Unix
     commands,  routines,  and files.  Manual domain macros distinguish command‐
     line arguments and options, function names, function parameters, pathnames,
     variables, cross references to other manual pages, and so on.  These  terms
     are  meaningful both to the author and the readers of a manual page.  It is
     hoped that the resulting increased consistency of the man page corpus  will
     enable easier translation to future documentation tools.

     Throughout  Unix  documentation,  a manual entry is referred to simply as a
     “man page”, regardless of its length, without gendered implication, and ir‐
     respective of the macro package selected for its composition.

[1mGetting started[0m
     The [4mmdoc[24m package attempts to simplify man page authorship  and  maintenance
     without  requiring  mastery  of  the [4mroff[24m language.  This document presents
     only essential facts about [4mroff.[24m For further background, including  a  dis‐
     cussion  of  basic  typographical  concepts like “breaking”, “filling”, and
     “adjustment”, see ]8;;man:roff(7)\[4mroff[24m(7)]8;;\.  Specialized units of  measurement  also  arise,
     namely  ens,  vees, inches, and points, abbreviated “n”, “v”, “i”, and “p”,
     respectively; see section “Measurements” of ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\.

     For brief examples, we employ an arrow notation illustrating a  transforma‐
     tion  of  input  on the left to rendered output on the right.  Consider the
     .[1mDq [22mmacro, which double‐quotes its arguments.
           [1m.Dq man page  [22m→ “man page”

   [1mUsage[0m
     An [4mmdoc[24m [4mmacro[24m is [4mcalled[24m by placing the [4mroff[24m control character, ‘.’ (dot) at
     the beginning of a line followed by its name.  In this document,  we  often
     discuss  a macro name with this leading dot to identify it clearly, but the
     dot is [4mnot[24m part of its name.  Space or tab characters can separate the  dot
     from  the  macro name.  Arguments may follow, separated from the macro name
     and each other by spaces, but [4mnot[24m tabs.  The dot at the  beginning  of  the
     line prepares the formatter to expect a macro name.  A dot followed immedi‐
     ately  by a newline is ignored; this is called the [4mempty[24m [4mrequest[24m.  To begin
     an input line with a dot (or a neutral  apostrophe  ‘'’)  in  some  context
     other  than a macro call, precede it with the ‘\&’ escape sequence; this is
     a dummy character, not formatted for output.  The backslash is the [4mroff[24m es‐
     cape character; it can appear anywhere and it always followed by  at  least
     one  more  character.   If followed by a newline, the backslash escapes the
     input line break; you can thus keep input  lines  to  a  reasonable  length
     without affecting their interpretation.

     Macros  in  GNU [4mtroff[24m accept an unlimited number of arguments; other [4mtroff[24ms
     often can’t handle more than nine.  In some cases, arguments  may  continue
     or  extend onto the next input line without resort to the ‘\[4mnewline[24m’ escape
     sequence; see subsection “Extended arguments” below.  Neutral double quotes
     [1m" [22mcan be used to group multiple words  into  an  argument;  see  subsection
     “Passing space characters in an argument” below.

     Most  of  [4mmdoc[24m’s general text and manual domain macros [4mparse[24m their argument
     lists for [4mcallable[24m macro names.  This means that an argument  in  the  list
     matching  a  general  text  or  manual domain macro name (and defined to be
     callable) will be called with the remaining arguments when  it  is  encoun‐
     tered.   In  such cases, the argument, although the name of a macro, is not
     preceded by a dot.  Macro calls can thus be nested.  This approach to macro
     argument processing is a unique characteristic of the [4mmdoc[24m package,  not  a
     general feature of [4mroff[24m syntax.

     For  example, the option macro, .[1mOp[22m, may call the flag and argument macros,
     .[1mFl [22mand .[1mAr[22m, to specify an optional flag with an argument.
           [1m.Op Fl s Ar bytes      [22m→ [[1m-s [4m[22mbytes[24m]
     To prevent a word from being interpreted as a macro name, precede  it  with
     the dummy character.
           [1m.Op \&Fl s \&Ar bytes  [22m→ [Fl s Ar bytes]

     In  this  document,  a  macro that parses its argument list for other macro
     names is termed [4mparsed[24m; macros that permit other macros to call  them  thus
     are  described  as [4mcallable[24m.  This usage is a technical [4mfaux[24m [4mpas[24m, since all
     [4mmdoc[24m macros are in fact interpreted (unless prevented with ‘\&’), but as it
     is cumbersome to constantly refer to macros as “being able  to  call  other
     macros”,  we  employ  the  term  “parsed” instead.  Except where explicitly
     stated, all [4mmdoc[24m macros are parsed and callable.

     In the following, we term an [4mmdoc[24m macro that starts a line (with a  leading
     dot)  a [4mcommand[24m if a distinction from those appearing as arguments of other
     macros is necessary.

   [1mPassing space characters in an argument[0m
     Sometimes it is desirable to give a macro an  argument  containing  one  or
     more  space characters, for instance to specify a particular arrangement of
     arguments demanded by the macro.  Additionally,  quoting  multi‐word  argu‐
     ments  that  are to be treated the same makes [4mmdoc[24m work faster; macros that
     parse arguments do so once (at most) for each.  For example,  the  function
     command .[1mFn [22mexpects its first argument to be the name of a function and any
     remaining  arguments  to  be function parameters.  Because C language stan‐
     dards mandate the inclusion of types [4mand[24m identifiers in the parameter lists
     of function definitions, each ‘Fn’ parameter after the  first  will  be  at
     least two words in length, as in “[4mint[24m [4mfoo[24m”.

     There  are  a few ways to embed a space in a macro argument.  One is to use
     the unadjustable space escape sequence [1m\[4m[22mspace[24m.  The formatter  treats  this
     escape  sequence  as if it were any other printable character, and will not
     break a line there as it would a word space when the output line  is  full.
     This method is useful for macro arguments that are not expected to straddle
     an  output line boundary, but has a drawback: this space does not adjust as
     others do when the output line is formatted.  An alternative is to use  the
     unbreakable  space  escape  sequence, ‘\~’, which cannot break but does ad‐
     just.  This [4mgroff[24m extension is widely but not perfectly portable.   Another
     method is to enclose the string in double quotes.
           [1m.Fn fetch char\ *str   [22m→ [1mfetch[22m([4mchar[24m [4m*str[24m)
           [1m.Fn fetch char\~*str   [22m→ [1mfetch[22m([4mchar[24m [4m*str[24m)
           [1m.Fn fetch "char *str"  [22m→ [1mfetch[22m([4mchar[24m [4m*str[24m)
     If  the  ‘\’  before the space in the first example or the double quotes in
     the third example were omitted, ‘.Fn’ would see three  arguments,  and  the
     result would contain an undesired comma.
           [1m.Fn fetch char *str    [22m→ [1mfetch[22m([4mchar[24m, [4m*str[24m)

   [1mTrailing space characters[0m
     It  is wise to remove trailing spaces from the ends of input lines.  Should
     the need arise to put a formattable space at the end of a line, do so  with
     the unadjustable or unbreakable space escape sequences.

   [1mFormatting the backslash and other glyphs[0m
     When  you  need  the [4mroff[24m escape character ‘\’ to appear in the output, use
     ‘\e’ or ‘\[rs]’ instead.  Strictly, ‘\e’ formats the current escape charac‐
     ter; it works reliably as long as no [4mroff[24m request is  used  to  change  it,
     which should never happen in man pages.  ‘\[rs]’ is a [4mgroff[24m [4mspecial[24m [4mcharac‐[0m
     [4mter[24m  escape  sequence  that explicitly formats the “reverse solidus” (back‐
     slash) glyph.  In general, use special character escape sequences to format
     characters outside the ISO 646 (“ASCII”) or Unicode Basic Latin range,  and
     to  format  correct  glyphs for the characters ‘"’, “'”, ‘-’, ‘^’, ‘`’, and
     ‘~’.  ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\ presents the formatter’s special character identifiers,
     annotating those that are portable to legacy systems.  Section  “Predefined
     strings” below lists characters commonly used by [4mmdoc[24m documents.

   [1mOther possible pitfalls[0m
     [4mgroff[24m  [4mmdoc[24m warns when an empty input line is found outside of a [4mdisplay[24m, a
     topic presented in subsection “Examples and displays” below.  Use empty re‐
     quests to space the source document for maintenance.

     Leading spaces cause a break and are formatted.  Avoid  this  behaviour  if
     possible.   Similarly,  do  not put more than one space between words in an
     ordinary text line; they are not “normalized” to a single  space  as  other
     text formatters might do.

     Don’t try to use the neutral double quote character ‘"’ to represent itself
     in  an argument.  Use the special character escape sequence ‘\[dq]’ to for‐
     mat it.  Avoid using ‘\[dq]’ for  conventional  quotation;  see  subsection
     “Enclosure and quoting macros” below.

     If  your  document  must be portable to legacy systems like 4.4BSD, special
     character escape sequences shown here in the form  [1m\[[4m[22mxx[24m]  must  be  spelled
     [1m\([4m[22mxx[24m instead.  No version of [4mgroff[24m or [4mmandoc[24m requires the latter form.

     As  a  typesetting  system,  [4mroff[24m  distinguishes  hyphens, minus signs, and
     dashes of various widths.  When inputting a hyphen or dash (“hyphen‐minus”)
     (Unicode U+002D) that should be usable in URLs or copy‐and‐paste operations
     to shell prompts or program code, prefix  it  with  the  escape  character:
     ‘\-’.

     The  formatter attempts to detect the ends of sentences and by default puts
     the equivalent of two spaces between sentences on the same output line; see
     ]8;;man:roff(7)\[4mroff[24m(7)]8;;\.  To defeat this detection in a parsed list of macro arguments, put
     ‘\&’ before the punctuation mark.  Thus,
           The
           .Ql .
           character.
           .Pp
           The
           .Ql \&.
           character.
           .Pp
           .No test .
           test
           .Pp
           .No test.
           test
     gives
           The ‘’.  character

           The ‘.’ character.

           test.  test

           test. test
     as output.  As can be seen in the first and third output lines,  [4mmdoc[24m  han‐
     dles punctuation characters specially in macro arguments.  This will be ex‐
     plained in section “General syntax” below.

     A  comment  in  the  source  file of a man page can begin with ‘.\"’ at the
     start of an input line, ‘\"’ after other input, or ‘\#’ anywhere (the  last
     is a [4mgroff[24m extension); the remainder of any such line is ignored.

[1mA man page template[0m
     Use [4mmdoc[24m to construct a man page from the following template.

           .\" The following three macro calls are required.
           .Dd date
           .Dt identifier [section‐id [section‐keyword‐or‐title]]
           .Os [package‐or‐operating system [version‐or‐release]]
           .Sh Name
           .Nm topic
           .Nd summary‐description
           .\" The next heading is used in sections 2 and 3.
           .\" .Sh Library
           .\" The next heading is used in sections 1‐4, 6, 8, and 9.
           .Sh Synopsis
           .Sh Description
           .\" Uncomment and populate the following sections as needed.
           .\" .Sh "Implementation notes"
           .\" The next heading is used in sections 2, 3, and 9.
           .\" .Sh "Return values"
           .\" The next heading is used in sections 1, 3, 6, and 8.
           .\" .Sh Environment
           .\" .Sh Files
           .\" The next heading is used in sections 1, 6, and 8.
           .\" .Sh "Exit status"
           .\" .Sh Examples
           .\" The next heading is used in sections 1, 4, 6, 8, and 9.
           .\" .Sh Diagnostics
           .\" .Sh Compatibility
           .\" The next heading is used in sections 2, 3, 4, and 9.
           .\" .Sh Errors
           .\" .Sh "See also"
           .\" .Sh Standards
           .\" .Sh History
           .\" .Sh Authors
           .\" .Sh Caveats
           .\" .Sh Bugs

     The  first  items in the template are the commands .[1mDd[22m, .[1mDt[22m, and .[1mOs[22m.  They
     identify the page and are discussed below in section “Title macros”.

     The remaining items in the template are section headings  (.[1mSh[22m);  of  which
     “Name”  and  “Description”  are mandatory.  These headings are discussed in
     section “Page structure domain”, which  follows  section  “Manual  domain”.
     Familiarize yourself with manual domain macros first; we use them to illus‐
     trate the use of page structure domain macros.

[1mConventions[0m
     In  the descriptions of macros below, square brackets surround optional ar‐
     guments.  An ellipsis (‘...’) represents repetition of the preceding  argu‐
     ment  zero  or more times.  Alternative values of a parameter are separated
     with ‘|’.  If a mandatory parameter can take  one  of  several  alternative
     values,  use  braces to enclose the set, with spaces and ‘|’ separating the
     items.
           [1mztar [22m{[1mc [22m| [1mx[22m} [[1m-w [22m[[1m-y [22m| [1m-z[22m]] [[1m-f [4m[22marchive[24m] [4mmember[24m ...
     An alternative to using braces is to separately synopsize  distinct  opera‐
     tion  modes, particularly if the list of valid optional arguments is depen‐
     dent on the user’s choice of a mandatory parameter.
           [1mztar c [22m[[1m-w [22m[[1m-y [22m| [1m-z[22m]] [[1m-f [4m[22marchive[24m] [4mmember[24m ...
           [1mztar x [22m[[1m-w [22m[[1m-y [22m| [1m-z[22m]] [[1m-f [4m[22marchive[24m] [4mmember[24m ...

     Most macros affect subsequent arguments until another macro or a newline is
     encountered.  For example, ‘[1m.Li ls Bq Ar file[22m’ doesn’t produce ‘[1mls [file][22m’,
     but ‘[1mls [22m[[4mfile[24m]’.  Consequently, a warning message is emitted for many  com‐
     mands  if the first argument is itself a macro, since it cancels the effect
     of the preceding one.  On rare occasions, you might want to format  a  word
     along with surrounding brackets as a literal.
           [1m.Li "ls [file]"  [22m→ [1mls [file] [4m[22m#[24m [4mlist[24m [4many[24m [4mfiles[24m [4mnamed[24m [4me,[24m [4mf,[24m [4mi,[24m [4mor[24m [4ml[0m

     Many  macros  possess  an  implicit  width, used when they are contained in
     lists and displays.  If you avoid relying on  these  default  measurements,
     you  escape  potential  conflicts with site‐local modifications of the [4mmdoc[0m
     package.  Explicit [1m-width [22mand [1m-offset [22marguments to the .[1mBl [22mand  .[1mBd  [22mmacros
     are preferable.

[1mTitle macros[0m
     We  present  the  [1mmandatory [22mtitle macros first due to their importance even
     though they formally belong to the page structure domain macros.  They des‐
     ignate the page identifier and section of the manual, date  of  last  revi‐
     sion,  and  the  operating  system  or software project associated with the
     page.  Call each once at the beginning of the document.  They populate  the
     page headers and footers, “titles” in [4mroff[24m parlance.

     [1m.Dd [4m[22mdate[0m
             This  first  macro of any [4mmdoc[24m manual records the last modification
             date of the document source.  Arguments are catenated and separated
             with space characters.

             Historically, [4mdate[24m was written in U.S. traditional  format,  “[4mMonth[0m
             [4mday[24m  ,  [4myear[24m” where [4mMonth[24m is the full month name in English, [4mday[24m an
             integer without a leading zero, and [4myear[24m the four‐digit year.  This
             localism is not enforced, however.  [4mgroff[24m recommends ISO 8601  for‐
             mat,  [4mYYYY‐MM‐DD.[24m  A [4mdate[24m of the form ‘[1m$Mdocdate: [4m[22mMonth[24m [4mday[24m [4myear[24m [1m$[22m’
             is also recognized.  It is used in OpenBSD manuals to automatically
             insert the current date when committing.

             This macro is neither callable nor parsed.

     [1m.Dt [4m[22midentifier[24m [[4msection‐id[24m [[4msection‐keyword‐or‐title[24m]]
             [4midentifier[24m and [4msection‐id[24m together should uniquely indicate the man
             page on the system.  A [4msection‐id[24m that begins with  an  integer  in
             the  range  1–9 or is one of the words ‘unass’, ‘draft’, or ‘paper’
             selects a predefined section title.   This  use  of  “section”  has
             nothing to do with the section headings otherwise discussed in this
             page; it arises from the organizational scheme of printed and bound
             Unix manuals.

             In  this implementation, the following titles are defined for inte‐
             gral section numbers.

                   1   General Commands Manual
                   2   System Calls Manual
                   3   Library Functions Manual
                   4   Kernel Interfaces Manual
                   5   File Formats Manual
                   6   Games Manual
                   7   Miscellaneous Information Manual
                   8   System Manager’s Manual
                   9   Kernel Developer’s Manual

             A section title may be arbitrary or one of the following  abbrevia‐
             tions.

                   USD     User’s Supplementary Documents
                   PS1     Programmer’s Supplementary Documents
                   AMD     Ancestral Manual Documents
                   SMM     System Manager’s Manual
                   URM     User’s Reference Manual
                   PRM     Programmer’s Manual
                   KM      Kernel Manual
                   IND     Manual Master Index
                   LOCAL   Local Manual
                   CON     Contributed Software Manual

             For  compatibility,  ‘MMI’  can  be  used  for ‘IND’, and ‘LOC’ for
             ‘LOCAL’.  Values from the previous table will specify a new section
             title.  If [4msection‐keyword‐or‐title[24m designates a computer architec‐
             ture recognized by [4mgroff[24m [4mmdoc[24m, its value is prepended  to  the  de‐
             fault  section  title as specified by the second parameter.  By de‐
             fault, the following architecture keywords are defined.

                 acorn26, acorn32, algor, alpha, amd64, amiga, amigappc, arc,
                 arm, arm26, arm32, armish, atari, aviion, beagle, bebox, cats,
                 cesfic, cobalt, dreamcast, emips, evbarm, evbmips, evbppc,
                 evbsh3, ews4800mips, hp300, hp700, hpcarm, hpcmips, hpcsh,
                 hppa, hppa64, i386, ia64, ibmnws, iyonix, landisk, loongson,
                 luna68k, luna88k, m68k, mac68k, macppc, mips, mips64, mipsco,
                 mmeye, mvme68k, mvme88k, mvmeppc, netwinder, news68k, newsmips,
                 next68k, ofppc, palm, pc532, playstation2, pmax, pmppc,
                 powerpc, prep, rs6000, sandpoint, sbmips, sgi, sgimips, sh3,
                 shark, socppc, solbourne, sparc, sparc64, sun2, sun3, tahoe,
                 vax, x68k, x86_64, xen, zaurus

             If a section title is not determined after the above  matches  have
             been attempted, [4msection‐keyword‐or‐title[24m is used.

             The  effects  of varying ‘.Dt’ arguments on the page header content
             are shown below.  Observe how ‘\&’ prevents the numeral 2 from  be‐
             ing used to look up a predefined section title.

               .Dt foo 2       →  foo(2)     System Calls Manual      foo(2)
               .Dt foo 2 m68k  →  foo(2)   m68k System Calls Manual   foo(2)
               .Dt foo 2 baz   →  foo(2)     System Calls Manual      foo(2)
               .Dt foo \&2 baz →  foo(2)             baz              foo(2)
               .Dt foo "" baz  →  foo                baz                 foo
               .Dt foo M Z80   →  foo(M)             Z80              foo(M)

             [4mroff[24m  strings  define  section titles and architecture identifiers.
             Site‐specific additions might be found in the file [4mmdoc.local[24m;  see
             section “Files” below.

             This macro is neither callable nor parsed.

     [1m.Os [22m[[4moperating‐system‐or‐package‐name[24m [[4mversion‐or‐release[24m]]
             This  macro  associates  the document with a software distribution.
             When composing a man page to be included in the  base  installation
             of  an operating system, do not provide an argument; [4mmdoc[24m will sup‐
             ply it.  In this implementation, that default is “GNU”.  It may  be
             overridden  in the site configuration file, [4mmdoc.local[24m; see section
             “Files” below.  A portable software package maintaining its own man
             pages can supply its name and version number or release  identifier
             as  optional  arguments.   A [4mversion‐or‐release[24m argument should use
             the standard nomenclature for the software specified.  In the  fol‐
             lowing table, recognized [4mversion‐or‐release[24m arguments for some pre‐
             defined  operating systems are listed.  As with .[1mDt[22m, site additions
             might be defined in [4mmdoc.local[24m.

                   ATT        7th, 7, III, 3, V, V.2, V.3, V.4

                   BSD        3, 4, 4.1, 4.2, 4.3, 4.3t, 4.3T, 4.3r, 4.3R, 4.4

                   NetBSD     0.8, 0.8a, 0.9, 0.9a, 1.0, 1.0a, 1.1, 1.2, 1.2a,
                              1.2b, 1.2c, 1.2d, 1.2e, 1.3, 1.3a, 1.4, 1.4.1,
                              1.4.2, 1.4.3, 1.5, 1.5.1, 1.5.2, 1.5.3, 1.6,
                              1.6.1, 1.6.2, 1.6.3, 2.0, 2.0.1, 2.0.2, 2.0.3,
                              2.1, 3.0, 3.0.1, 3.0.2, 3.0.3, 3.1, 3.1.1, 4.0,
                              4.0.1, 5.0, 5.0.1, 5.0.2, 5.1, 5.1.2, 5.1.3,
                              5.1.4, 5.2, 5.2.1, 5.2.2, 6.0, 6.0.1, 6.0.2,
                              6.0.3, 6.0.4, 6.0.5, 6.0.6, 6.1, 6.1.1, 6.1.2,
                              6.1.3, 6.1.4, 6.1.5, 7.0, 7.0.1, 7.0.2, 7.1,
                              7.1.1, 7.1.2, 7.2, 8.0, 8.1

                   FreeBSD    1.0, 1.1, 1.1.5, 1.1.5.1, 2.0, 2.0.5, 2.1, 2.1.5,
                              2.1.6, 2.1.7, 2.2, 2.2.1, 2.2.2, 2.2.5, 2.2.6,
                              2.2.7, 2.2.8, 2.2.9, 3.0, 3.1, 3.2, 3.3, 3.4, 3.5,
                              4.0, 4.1, 4.1.1, 4.2, 4.3, 4.4, 4.5, 4.6, 4.6.2,
                              4.7, 4.8, 4.9, 4.10, 4.11, 5.0, 5.1, 5.2, 5.2.1,
                              5.3, 5.4, 5.5, 6.0, 6.1, 6.2, 6.3, 6.4, 7.0, 7.1,
                              7.2, 7.3, 7.4, 8.0, 8.1, 8.2, 8.3, 8.4, 9.0, 9.1,
                              9.2, 9.3, 10.0, 10.1, 10.2, 10.3, 10.4, 11.0,
                              11.1, 11.2, 11.3, 12.0, 12.1

                   OpenBSD    2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 2.9,
                              3.0, 3.1, 3.2, 3.3, 3.4, 3.5, 3.6, 3.7, 3.8, 3.9,
                              4.0, 4.1, 4.2, 4.3, 4.4, 4.5, 4.6, 4.7, 4.8, 4.9,
                              5.0, 5.1, 5.2, 5.3, 5.4, 5.5, 5.6, 5.7, 5.8, 5.9,
                              6.0, 6.1, 6.2, 6.3, 6.4, 6.5, 6.6

                   DragonFly  1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8,
                              1.8.1, 1.9, 1.10, 1.11, 1.12, 1.12.2, 1.13, 2.0,
                              2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 2.9,
                              2.9.1, 2.10, 2.10.1, 2.11, 2.12, 2.13, 3.0, 3.0.1,
                              3.0.2, 3.1, 3.2, 3.2.1, 3.2.2, 3.3, 3.4, 3.4.1,
                              3.4.2, 3.4.3, 3.5, 3.6, 3.6.1, 3.6.2, 3.7, 3.8,
                              3.8.1, 3.8.2, 4.0, 4.0.1, 4.0.2, 4.0.3, 4.0.4,
                              4.0.5, 4.0.6, 4.1, 4.2, 4.2.1, 4.2.2, 4.2.3,
                              4.2.4, 4.3, 4.4, 4.4.1, 4.4.2, 4.4.3, 4.5, 4.6,
                              4.6.1, 4.6.2, 4.7, 4.8, 4.8.1, 4.9, 5.0, 5.0.1,
                              5.0.2, 5.1, 5.2, 5.2.1, 5.2.2, 5.3, 5.4, 5.4.1,
                              5.4.2, 5.4.3, 5.5, 5.6, 5.6.1, 5.6.2

                   Darwin     8.0.0, 8.1.0, 8.2.0, 8.3.0, 8.4.0, 8.5.0, 8.6.0,
                              8.7.0, 8.8.0, 8.9.0, 8.10.0, 8.11.0, 9.0.0, 9.1.0,
                              9.2.0, 9.3.0, 9.4.0, 9.5.0, 9.6.0, 9.7.0, 9.8.0,
                              10.0.0, 10.1.0, 10.2.0, 10.3.0, 10.4.0, 10.5.0,
                              10.6.0, 10.7.0, 10.8.0, 11.0.0, 11.1.0, 11.2.0,
                              11.3.0, 11.4.0, 11.5.0, 12.0.0, 12.1.0, 12.2.0,
                              13.0.0, 13.1.0, 13.2.0, 13.3.0, 13.4.0, 14.0.0,
                              14.1.0, 14.2.0, 14.3.0, 14.4.0, 14.5.0, 15.0.0,
                              15.1.0, 15.2.0, 15.3.0, 15.4.0, 15.5.0, 15.6.0,
                              16.0.0, 16.1.0, 16.2.0, 16.3.0, 16.4.0, 16.5.0,
                              16.6.0, 17.0.0, 17.1.0, 17.2.0, 17.3.0, 17.4.0,
                              17.5.0, 17.6.0, 17.7.0, 18.0.0, 18.1.0, 18.2.0,
                              18.3.0, 18.4.0, 18.5.0, 18.6.0, 18.7.0, 19.0.0,
                              19.1.0, 19.2.0

             Historically, the first argument used with .[1mDt [22mwas [1mBSD [22mor [1mATT[22m.   An
             unrecognized  version  argument  after [1mATT [22mis replaced with “Unix”;
             for other predefined abbreviations, it is ignored and a warning di‐
             agnostic emitted.  Otherwise, unrecognized arguments are  displayed
             verbatim  in  the  page  footer.  For instance, this page uses “[1m.Os[0m
             [1mgroff 1.24.1[22m” whereas a locally produced  page  might  employ  “[1m.Os[0m
             [1m"UXYZ CS Department"[22m”, omitting versioning.

             This macro is neither callable nor parsed.

[1mIntroduction to manual and general text domains[0m
   [1mWhat’s in a Name[22m...
     The manual domain macro names are derived from the day to day informal lan‐
     guage  used  to describe commands, subroutines and related files.  Slightly
     different variations of this language are used to describe the  three  dif‐
     ferent  aspects  of writing a man page.  First, there is the description of
     [4mmdoc[24m macro command usage.  Second is the description of a Unix command [4mwith[0m
     [4mmdoc[24m macros, and third, the description of a command to a user in the  ver‐
     bal sense; that is, discussion of a command in the text of a man page.

     In  the first case, [4mtroff[24m macros are themselves a type of command; the gen‐
     eral syntax for a [4mtroff[24m command is:

           [1m.Xx argument1 argument2 [22m...

     ‘.Xx’ is a macro command, and anything following it  are  arguments  to  be
     processed.  In the second case, the description of a Unix command using the
     manual  domain  macros is a bit more involved; a typical “Synopsis” command
     line might be displayed as:

           [1mfilter [22m[[1m-flag[22m] ⟨[4minfile[24m⟩ ⟨[4moutfile[24m⟩

     Here, [1mfilter [22mis the command name and the bracketed string [1m-flag [22mis  a  [4mflag[0m
     argument  designated  as  optional  by the option brackets.  In [4mmdoc[24m terms,
     ⟨[4minfile[24m⟩ and ⟨[4moutfile[24m⟩ are called [4mmeta[24m [4marguments[24m; in this example, the user
     has to replace the meta expressions given in angle brackets with real  file
     names.  Note that in this document meta arguments are used to describe [4mmdoc[0m
     commands;  in  most  man pages, meta variables are not specifically written
     with angle brackets.  The macros that formatted the above example:

           .Nm filter
           .Op Fl flag
           .Ao Ar infile Ac Ao Ar outfile Ac

     In the third case, discussion of commands and command syntax includes  both
     examples  above,  but  may  add  more  detail.   The arguments ⟨[4minfile[24m⟩ and
     ⟨[4moutfile[24m⟩ from the example above might be referred to as [4moperands[24m  or  [4mfile[0m
     [4marguments[24m.  Some command‐line argument lists are quite long:

           [1mmake  [22m[[1m-eiknqrstv[22m] [[1m-D [4m[22mvariable[24m] [[1m-d [4m[22mflags[24m] [[1m-f [4m[22mmakefile[24m] [[1m-I[0m
                 [4mdirectory[24m] [[1m-j [4m[22mmax_jobs[24m] [[4mvariable[24m=[4mvalue[24m] [[4mtarget[24m ...]

     Here  one  might  talk  about  the  command  [4mmake[24m and qualify the argument,
     [4mmakefile[24m, as an argument to the flag, [1m-f[22m,  or  discuss  the  optional  file
     operand  [4mtarget[24m.  In the verbal context, such detail can prevent confusion,
     however the [4mmdoc[24m package does not have a macro for an argument [4mto[24m  a  flag.
     Instead  the  ‘Ar’  argument  macro is used for an operand or file argument
     like [4mtarget[24m as well as an argument to a flag like [4mvariable[24m.  The make  com‐
     mand line was produced from:

           .Nm make
           .Op Fl eiknqrstv
           .Op Fl D Ar variable
           .Op Fl d Ar flags
           .Op Fl f Ar makefile
           .Op Fl I Ar directory
           .Op Fl j Ar max_jobs
           .Op Ar variable Ns = Ns Ar value
           .Bk
           .Op Ar target ...
           .Ek

     The ‘.Bk’ and ‘.Ek’ macros are explained in “Keeps”.

   [1mGeneral Syntax[0m
     The  manual  domain  and  general text domain macros share a similar syntax
     with a few minor deviations; most notably, ‘.Ar’, ‘.Fl’, ‘.Nm’,  and  ‘.Pa’
     differ  only  when  called without arguments; and ‘.Fn’ and ‘.Xr’ impose an
     order on their argument lists.  All manual domain  macros  are  capable  of
     recognizing  and  properly  handling punctuation, provided each punctuation
     character is separated by a leading space.  If a command is given:

           [1m.Ar sptr, ptr),[0m

     The result is:

           [4msptr,[24m [4mptr),[0m

     The punctuation is not recognized and all is output in  the  font  used  by
     ‘.Ar’.  If the punctuation is separated by a leading whitespace:

           [1m.Ar sptr , ptr ) ,[0m

     The result is:

           [4msptr[24m, [4mptr[24m),

     The  punctuation  is  now recognized and output in the default font distin‐
     guishing it from the argument strings.  To remove the special meaning  from
     a punctuation character, escape it with ‘\&’.

     The following punctuation characters are recognized by [4mmdoc[24m:

               [1m.         ,         :         ;         ([0m
               [1m)         [         ]         ?         ![0m

     [4mtroff[24m  is  limited  as  a macro language, and has difficulty when presented
     with a string containing certain mathematical, logical, or quotation  char‐
     acter sequences:

                 {+,-,/,*,%,<,>,<=,>=,=,==,&,`,',"}

     The problem is that [4mtroff[24m may assume it is supposed to actually perform the
     operation  or evaluation suggested by the characters.  To prevent the acci‐
     dental evaluation of these characters, escape them with ‘\&’.  Typical syn‐
     tax is shown in the first manual domain macro displayed below, ‘.Ad’.

[1mManual domain[0m
   [1mAddresses[0m
     The address macro identifies an address construct.

           [1mUsage: .Ad [22m⟨address⟩ ...

                    [1m.Ad addr1           [4m[22maddr1[0m
                    [1m.Ad addr1 .         [4m[22maddr1[24m.
                    [1m.Ad addr1 , file2   [4m[22maddr1[24m, [4mfile2[0m
                    [1m.Ad f1 , f2 , f3 :  [4m[22mf1[24m, [4mf2[24m, [4mf3[24m:
                    [1m.Ad addr ) ) ,      [4m[22maddr[24m)),

     The default width is 12n.

   [1mAuthor Name[0m
     The ‘.An’ macro is used to specify the name of the author of the item being
     documented, or the name of the author of the actual manual page.

           [1mUsage: .An [22m⟨author name⟩ ...

                    [1m.An "Joe Author"        [22mJoe Author

                    [1m.An "Joe Author" ,      [22mJoe Author,

                    [1m.An "Joe Author" Aq nobody@FreeBSD.org[0m
                                            Joe Author <nobody@FreeBSD.org>

                    [1m.An "Joe Author" ) ) ,  [22mJoe Author)),

     The default width is 12n.

     In a section titled “Authors”, ‘An’ causes a break, allowing each new  name
     to appear on its own line.  If this is not desirable,

           .An -nosplit

     call will turn this off.  To turn splitting back on, write

           .An -split

   [1mArguments[0m
     The  [1m.Ar [22margument macro may be used whenever an argument is referenced.  If
     called without arguments, ‘[4mfile[24m ...’ is output.

           [1mUsage: .Ar [22m[⟨argument⟩] ...

                    [1m.Ar                    [4m[22mfile[24m ...
                    [1m.Ar file1              [4m[22mfile1[0m
                    [1m.Ar file1 .            [4m[22mfile1[24m.
                    [1m.Ar file1 file2        [4m[22mfile1[24m [4mfile2[0m
                    [1m.Ar file ... dest‐dir  [4m[22mfile[24m ... [4mdest‐dir[0m
                    [1m.Ar f1 f2 f3 :         [4m[22mf1[24m [4mf2[24m [4mf3[24m:
                    [1m.Ar file ) ) ,         [4m[22mfile[24m)),

     The default width is 12n.

   [1mConfiguration Declaration (Section Four Only)[0m
     The ‘.Cd’ macro is used to demonstrate a ]8;;man:config(8)\[4mconfig[24m(8)]8;;\ declaration for a device
     interface in a section four manual.

           [1mUsage: .Cd [22m⟨argument⟩ ...

                    [1m.Cd "device le0 at scode?"  device le0 at scode?[0m

     In a section titled “Synopsis”, ‘Cd’ causes a break before  and  after  its
     arguments.

     The default width is 12n.

   [1mCommand Modifiers[0m
     The  command modifier is identical to the ‘.Fl’ (flag) command with the ex‐
     ception that the ‘.Cm’ macro does not assert a dash in front of every argu‐
     ment.  Traditionally flags are marked by the preceding dash, however,  some
     commands  or  subsets  of  commands do not use them.  Command modifiers may
     also be specified in conjunction with interactive commands such  as  editor
     commands.  See “Flags”.

     The default width is 10n.

   [1mDefined Variables[0m
     A variable (or constant) that is defined in an include file is specified by
     the macro ‘.Dv’.

           [1mUsage: .Dv [22m⟨defined‐variable⟩ ...

                    [1m.Dv MAXHOSTNAMELEN  [22mMAXHOSTNAMELEN
                    [1m.Dv TIOCGPGRP )     [22mTIOCGPGRP)

     The default width is 12n.

   [1mErrnos[0m
     The  ‘.Er’  errno  macro specifies the error return value for section 2, 3,
     and 9 library routines.  The second example below shows ‘.Er’ used with the
     ‘.Bq’ general text domain macro, as it would be used in a section two  man‐
     ual page.

           [1mUsage: .Er [22m⟨errno type⟩ ...

                    [1m.Er ENOENT      [22mENOENT
                    [1m.Er ENOENT ) ;  [22mENOENT);
                    [1m.Bq Er ENOTDIR  [22m[ENOTDIR]

     The default width is 17n.

   [1mEnvironment Variables[0m
     The ‘.Ev’ macro specifies an environment variable.

           [1mUsage: .Ev [22m⟨argument⟩ ...

                    [1m.Ev DISPLAY        [4m[22mDISPLAY[0m
                    [1m.Ev PATH .         [4m[22mPATH[24m.
                    [1m.Ev PRINTER ) ) ,  [4m[22mPRINTER[24m)),

     The default width is 15n.

   [1mFlags[0m
     The  ‘.Fl’  macro  handles command‐line flags.  It prepends a dash, ‘-’, to
     the flag.  For interactive command flags that  are  not  prepended  with  a
     dash,  the  ‘.Cm’  (command  modifier)  macro is identical, but without the
     dash.

           [1mUsage: .Fl [22m⟨argument⟩ ...

                    [1m.Fl          -[0m
                    [1m.Fl cfv      -cfv[0m
                    [1m.Fl cfv .    -cfv[22m.
                    [1m.Cm cfv .    cfv[22m.
                    [1m.Fl s v t    -s -v -t[0m
                    [1m.Fl - ,      --[22m,
                    [1m.Fl xyz ) ,  -xyz[22m),
                    [1m.Fl |        - [22m|

     The ‘.Fl’ macro without  any  arguments  results  in  a  dash  representing
     stdin/stdout.   Note  that  giving  ‘.Fl’  a single dash will result in two
     dashes.

     The default width is 12n.

   [1mFunction Declarations[0m
     The ‘.Fd’ macro is used in the “Synopsis” section with section two or three
     functions.  It is neither callable nor parsed.

           [1mUsage: .Fd [22m⟨argument⟩ ...

                    [1m.Fd "#include <sys/types.h>"  #include <sys/types.h>[0m

     In a section titled “Synopsis”, ‘Fd’ causes a break if a function  has  al‐
     ready  been  presented and a break has not occurred, leaving vertical space
     between one function declaration and the next.

     In a section titled “Synopsis”, the  ‘In’  macro  represents  the  [1m#include[0m
     statement,  and  is  the short form of the above example.  It specifies the
     C header file as being included in a C program.  It also causes a break.

     While not in the “Synopsis” section, it represents the header file enclosed
     in angle brackets.

           [1mUsage: .In [22m⟨header file⟩

                    [1m.In stdio.h  [22m<[4mstdio.h[24m>
                    [1m.In stdio.h  [22m<[4mstdio.h[24m>

   [1mFunction Types[0m
     This macro is intended for the “Synopsis” section.  It may be used anywhere
     else in the man page without problems, but its main purpose is  to  present
     the  function  type  (in BSD kernel normal form) for the “Synopsis” of sec‐
     tions two and three.  (It causes a break, allowing the function name to ap‐
     pear on the next line.)

           [1mUsage: .Ft [22m⟨type⟩ ...

                    [1m.Ft struct stat  [4m[22mstruct[24m [4mstat[0m

   [1mFunctions (Library Routines)[0m
     The ‘.Fn’ macro is modeled on ANSI C conventions.

           [1mUsage: .Fn [22m⟨function⟩ [⟨parameter⟩] ...

                    [1m.Fn getchar              getchar[22m()
                    [1m.Fn strlen ) ,           strlen[22m()),
                    [1m.Fn align "char *ptr" ,  align[22m([4mchar[24m [4m*ptr[24m),

     Note that any call to another macro signals the end of the ‘.Fn’  call  (it
     will insert a closing parenthesis at that point).

     For functions with many parameters (which is rare), the macros ‘.Fo’ (func‐
     tion  open) and ‘.Fc’ (function close) may be used with ‘.Fa’ (function ar‐
     gument).

     Example:

           .Ft int
           .Fo res_mkquery
           .Fa "int op"
           .Fa "char *dname"
           .Fa "int class"
           .Fa "int type"
           .Fa "char *data"
           .Fa "int datalen"
           .Fa "struct rrec *newrr"
           .Fa "char *buf"
           .Fa "int buflen"
           .Fc

     Produces:

           [4mint[24m [1mres_mkquery[22m([4mint[24m [4mop[24m, [4mchar[24m [4m*dname[24m, [4mint[24m [4mclass[24m, [4mint[24m [4mtype[24m, [4mchar[24m [4m*data[24m,
           [4mint[24m [4mdatalen[24m, [4mstruct[24m [4mrrec[24m [4m*newrr[24m, [4mchar[24m [4m*buf[24m, [4mint[24m [4mbuflen[24m)

     Typically, in a “Synopsis” section, the function declaration will begin the
     line.  If more than one function is presented in the “Synopsis” section and
     a function type has not been given, a break will  occur,  leaving  vertical
     space between the current and prior function names.

     The default width values of ‘.Fn’ and ‘.Fo’ are 12n and 16n, respectively.

   [1mFunction Arguments[0m
     The ‘.Fa’ macro is used to refer to function arguments (parameters) outside
     of the “Synopsis” section of the manual or inside the “Synopsis” section if
     the  enclosure macros ‘.Fo’ and ‘.Fc’ instead of ‘.Fn’ are used.  ‘.Fa’ may
     also be used to refer to structure members.

           [1mUsage: .Fa [22m⟨function argument⟩ ...

                    [1m.Fa d_namlen ) ) ,  [4m[22md_namlen[24m)),
                    [1m.Fa iov_len         [4m[22miov_len[0m

     The default width is 12n.

   [1mReturn Values[0m
     The ‘.Rv’ macro generates text for use in the “Return values” section.

           [1mUsage: .Rv [22m[-std] [⟨function⟩ ...]

     For example, ‘.Rv -std atexit’ produces:

           The [1matexit[22m() function returns the value 0 if successful; otherwise
           the value -1 is returned and the global variable [4merrno[24m is set to in‐
           dicate the error.

     The [1m-std [22moption is valid only for manual page sections 2 and 3.  Currently,
     this macro does nothing if used without the [1m-std [22mflag.

   [1mExit Status[0m
     The ‘.Ex’ macro generates text for use in the “Diagnostics” section.

           [1mUsage: .Ex [22m[-std] [⟨utility⟩ ...]

     For example, ‘.Ex -std cat’ produces:

           The [1mcat [22mutility exits 0 on success, and >0 if an error occurs.

     The [1m-std [22moption is valid only for manual page sections 1, 6  and  8.   Cur‐
     rently, this macro does nothing if used without the [1m-std [22mflag.

   [1mInteractive Commands[0m
     The ‘.Ic’ macro designates an interactive or internal command.

           [1mUsage: .Ic [22m⟨argument⟩ ...

                    [1m.Ic :wq                :wq[0m
                    [1m.Ic "do while {...}"   do while {...}[0m
                    [1m.Ic setenv , unsetenv  setenv[22m, [1munsetenv[0m

     The default width is 12n.

   [1mLibrary Names[0m
     The  ‘.Lb’ macro is used to specify the library where a particular function
     is compiled in.

           [1mUsage: .Lb [22m⟨argument⟩ ...

     Available arguments to ‘.Lb’ and their results are:

           [1mlibarchive     [22mReading  and  Writing   Streaming   Archives   Library
                          (libarchive, -larchive)
           [1mlibarm         [22mARM Architecture Library (libarm, -larm)
           [1mlibarm32       [22mARM32 Architecture Library (libarm32, -larm32)
           [1mlibbluetooth   [22mBluetooth Library (libbluetooth, -lbluetooth)
           [1mlibbsm         [22mBasic Security Module Library (libbsm, -lbsm)
           [1mlibc           [22mStandard C Library (libc, -lc)
           [1mlibc_r         [22mReentrant C Library (libc_r, -lc_r)
           [1mlibcalendar    [22mCalendar Arithmetic Library (libcalendar, -lcalendar)
           [1mlibcam         [22mCommon Access Method User Library (libcam, -lcam)
           [1mlibcdk         [22mCurses Development Kit Library (libcdk, -lcdk)
           [1mlibcipher      [22mFreeSec Crypt Library (libcipher, -lcipher)
           [1mlibcompat      [22mCompatibility Library (libcompat, -lcompat)
           [1mlibcrypt       [22mCrypt Library (libcrypt, -lcrypt)
           [1mlibcurses      [22mCurses Library (libcurses, -lcurses)
           [1mlibdevinfo     [22mDevice   and   Resource  Information  Utility  Library
                          (libdevinfo, -ldevinfo)
           [1mlibdevstat     [22mDevice Statistics Library (libdevstat, -ldevstat)
           [1mlibdisk        [22mInterface  to  Slice  and  Partition  Labels   Library
                          (libdisk, -ldisk)
           [1mlibdwarf       [22mDWARF Access Library (libdwarf, -ldwarf)
           [1mlibedit        [22mCommand Line Editor Library (libedit, -ledit)
           [1mlibelf         [22mELF Access Library (libelf, -lelf)
           [1mlibevent       [22mEvent Notification Library (libevent, -levent)
           [1mlibfetch       [22mFile Transfer Library for URLs (libfetch, -lfetch)
           [1mlibform        [22mCurses Form Library (libform, -lform)
           [1mlibgeom        [22mUserland   API   Library  for  kernel  GEOM  subsystem
                          (libgeom, -lgeom)
           [1mlibgpib        [22mGeneral‐Purpose   Instrument   Bus   (GPIB)    library
                          (libgpib, -lgpib)
           [1mlibi386        [22mi386 Architecture Library (libi386, -li386)
           [1mlibintl        [22mInternationalized  Message  Handling Library (libintl,
                          -lintl)
           [1mlibipsec       [22mIPsec Policy Control Library (libipsec, -lipsec)
           [1mlibipx         [22mIPX Address Conversion Support Library (libipx, -lipx)
           [1mlibiscsi       [22miSCSI protocol library (libiscsi, -liscsi)
           [1mlibjail        [22mJail Library (libjail, -ljail)
           [1mlibkiconv      [22mKernel side iconv library (libkiconv, -lkiconv)
           [1mlibkse         [22mN:M Threading Library (libkse, -lkse)
           [1mlibkvm         [22mKernel Data Access Library (libkvm, -lkvm)
           [1mlibm           [22mMath Library (libm, -lm)
           [1mlibm68k        [22mm68k Architecture Library (libm68k, -lm68k)
           [1mlibmagic       [22mMagic Number Recognition Library (libmagic, -lmagic)
           [1mlibmd          [22mMessage  Digest  (MD4,  MD5,  etc.)  Support   Library
                          (libmd, -lmd)
           [1mlibmemstat     [22mKernel    Memory    Allocator    Statistics    Library
                          (libmemstat, -lmemstat)
           [1mlibmenu        [22mCurses Menu Library (libmenu, -lmenu)
           [1mlibnetgraph    [22mNetgraph User Library (libnetgraph, -lnetgraph)
           [1mlibnetpgp      [22mNetpgp signing, verification, encryption  and  decryp‐
                          tion (libnetpgp, -lnetpgp)
           [1mlibossaudio    [22mOSS Audio Emulation Library (libossaudio, -lossaudio)
           [1mlibpam         [22mPluggable   Authentication   Module  Library  (libpam,
                          -lpam)
           [1mlibpcap        [22mPacket Capture Library (libpcap, -lpcap)
           [1mlibpci         [22mPCI Bus Access Library (libpci, -lpci)
           [1mlibpmc         [22mPerformance Counters Library (libpmc, -lpmc)
           [1mlibposix       [22mPOSIX Compatibility Library (libposix, -lposix)
           [1mlibprop        [22mProperty Container Object Library (libprop, -lprop)
           [1mlibpthread     [22mPOSIX Threads Library (libpthread, -lpthread)
           [1mlibpuffs       [22mpuffs Convenience Library (libpuffs, -lpuffs)
           [1mlibrefuse      [22mFile   System   in   Userspace   Convenience   Library
                          (librefuse, -lrefuse)
           [1mlibresolv      [22mDNS Resolver Library (libresolv, -lresolv)
           [1mlibrpcsec_gss  [22mRPC  GSS‐API  Authentication  Library  (librpcsec_gss,
                          -lrpcsec_gss)
           [1mlibrpcsvc      [22mRPC Service Library (librpcsvc, -lrpcsvc)
           [1mlibrt          [22mPOSIX Real‐time Library (librt, -lrt)
           [1mlibsdp         [22mBluetooth  Service  Discovery  Protocol  User  Library
                          (libsdp, -lsdp)
           [1mlibssp         [22mBuffer Overflow Protection Library (libssp, -lssp)
           [1mlibSystem      [22mSystem Library (libSystem, -lSystem)
           [1mlibtermcap     [22mTermcap Access Library (libtermcap, -ltermcap)
           [1mlibterminfo    [22mTerminal Information Library (libterminfo, -lterminfo)
           [1mlibthr         [22m1:1 Threading Library (libthr, -lthr)
           [1mlibufs         [22mUFS File System Access Library (libufs, -lufs)
           [1mlibugidfw      [22mFile  System  Firewall  Interface  Library (libugidfw,
                          -lugidfw)
           [1mlibulog        [22mUser Login Record Library (libulog, -lulog)
           [1mlibusbhid      [22mUSB  Human  Interface  Devices   Library   (libusbhid,
                          -lusbhid)
           [1mlibutil        [22mSystem Utilities Library (libutil, -lutil)
           [1mlibvgl         [22mVideo Graphics Library (libvgl, -lvgl)
           [1mlibx86_64      [22mx86_64 Architecture Library (libx86_64, -lx86_64)
           [1mlibz           [22mCompression Library (libz, -lz)

     Site‐specific  additions might be found in the file [4mmdoc.local[24m; see section
     “Files” below.

     In a section titled “Library”, ‘Lb’ causes a break before and after its ar‐
     guments.

   [1mLiterals[0m
     The ‘Li’ literal macro may be used for special  characters,  symbolic  con‐
     stants,  and  other  syntactical items that should be typed exactly as dis‐
     played.

           [1mUsage: .Li [22m⟨argument⟩ ...

                    [1m.Li \en          \n[0m
                    [1m.Li M1 M2 M3 ;   M1 M2 M3[22m;
                    [1m.Li cntrl-D ) ,  cntrl‐D[22m),
                    [1m.Li 1024 ...     1024 [22m...

     The default width is 16n.

   [1mNames[0m
     The ‘Nm’ macro identifies the document’s central  topic.   Upon  its  first
     call,  it  has  the  peculiarity  of remembering its argument.  When subse‐
     quently called without arguments, ‘Nm’ regurgitates this initial  name  for
     the  sole  purpose  of  making less work for the document’s author.  Use of
     ‘Nm’ is also appropriate when presenting a command synopsis for  the  topic
     of  a  man page in section 1, 6, or 8.  Its behavior changes when presented
     with arguments of various forms.

                    [1m.Nm groff_mdoc  groff_mdoc[0m
                    [1m.Nm             groff_mdoc[0m
                    [1m.Nm \-mdoc      -mdoc[0m
                    [1m.Nm foo ) ) ,   foo[22m)),
                    [1m.Nm :           groff_mdoc[22m:

     By default, the topic is set in boldface to reflect its prime importance in
     the discussion.  Cross references to other man page topics should use ‘Xr’;
     including a second argument for the section number enables them to  be  hy‐
     perlinked.  By default, cross‐referenced topics are set in italics to avoid
     cluttering the page with boldface.

     The default width is 10n.

   [1mOptions[0m
     The  ‘.Op’  macro  places option brackets around any remaining arguments on
     the command line, and places any trailing punctuation outside the brackets.
     The macros ‘.Oo’ and ‘.Oc’ (which produce an opening and a  closing  option
     bracket,  respectively)  may be used across one or more lines or to specify
     the exact position of the closing parenthesis.

           [1mUsage: .Op [22m[⟨option⟩] ...

                    [1m.Op                                [22m[]
                    [1m.Op Fl k                           [22m[[1m-k[22m]
                    [1m.Op Fl k ) .                       [22m[[1m-k[22m]).
                    [1m.Op Fl k Ar kookfile               [22m[[1m-k [4m[22mkookfile[24m]
                    [1m.Op Fl k Ar kookfile ,             [22m[[1m-k [4m[22mkookfile[24m],
                    [1m.Op Ar objfil Op Ar corfil         [22m[[4mobjfil[24m [[4mcorfil[24m]]
                    [1m.Op Fl c Ar objfil Op Ar corfil ,  [22m[[1m-c [4m[22mobjfil[24m [[4mcorfil[24m]],
                    [1m.Op word1 word2                    [22m[word1 word2]
                    [1m.Li .Op Oo Ao option Ac Oc ...     .Op [22m[⟨option⟩] ...

     Here a typical example of the ‘.Oo’ and ‘.Oc’ macros:

           .Oo
           .Op Fl k Ar kilobytes
           .Op Fl i Ar interval
           .Op Fl c Ar count
           .Oc

     Produces:

           [[[1m-k [4m[22mkilobytes[24m] [[1m-i [4m[22minterval[24m] [[1m-c [4m[22mcount[24m]]

     The default width values of ‘.Op’ and ‘.Oo’ are 14n and 10n, respectively.

   [1mPathnames[0m
     The ‘.Pa’ macro formats file specifications.  If called without  arguments,
     ‘[4m~[24m’ (recognized by many shells) is output, representing the user’s home di‐
     rectory.

           [1mUsage: .Pa [22m[⟨pathname⟩] ...

                    [1m.Pa                    [4m[22m~[0m
                    [1m.Pa /usr/share         [4m[22m/usr/share[0m
                    [1m.Pa /tmp/fooXXXXX ) .  [4m[22m/tmp/fooXXXXX[24m).

     The default width is 32n.

   [1mStandards[0m
     The ‘.St’ macro replaces standard abbreviations with their formal names.

           [1mUsage: .St [22m⟨abbreviation⟩ ...

     Available pairs for “Abbreviation/Formal Name” are:

     ANSI/ISO C

           [1m-ansiC          [22mANSI X3.159‐1989 (“ANSI C89”)
           [1m-ansiC-89       [22mANSI X3.159‐1989 (“ANSI C89”)
           [1m-isoC           [22mISO/IEC 9899:1990 (“ISO C90”)
           [1m-isoC-90        [22mISO/IEC 9899:1990 (“ISO C90”)
           [1m-isoC-99        [22mISO/IEC 9899:1999 (“ISO C99”)
           [1m-isoC-2011      [22mISO/IEC 9899:2011 (“ISO C11”)
           [1m-isoC-2023      [22mISO/IEC 9899:2024 (“ISO C23”)

     POSIX Part 1: System API

           [1m-iso9945-1-90   [22mISO/IEC 9945‐1:1990 (“POSIX.1”)
           [1m-iso9945-1-96   [22mISO/IEC 9945‐1:1996 (“POSIX.1”)
           [1m-p1003.1        [22mIEEE Std 1003.1 (“POSIX.1”)
           [1m-p1003.1-88     [22mIEEE Std 1003.1‐1988 (“POSIX.1”)
           [1m-p1003.1-90     [22mISO/IEC 9945‐1:1990 (“POSIX.1”)
           [1m-p1003.1-96     [22mISO/IEC 9945‐1:1996 (“POSIX.1”)
           [1m-p1003.1b-93    [22mIEEE Std 1003.1b‐1993 (“POSIX.1”)
           [1m-p1003.1c-95    [22mIEEE Std 1003.1c‐1995 (“POSIX.1”)
           [1m-p1003.1g-2000  [22mIEEE Std 1003.1g‐2000 (“POSIX.1”)
           [1m-p1003.1i-95    [22mIEEE Std 1003.1i‐1995 (“POSIX.1”)
           [1m-p1003.1-2001   [22mIEEE Std 1003.1‐2001 (“POSIX.1”)
           [1m-p1003.1-2004   [22mIEEE Std 1003.1‐2004 (“POSIX.1”)
           [1m-p1003.1-2008   [22mIEEE Std 1003.1‐2008 (“POSIX.1”)
           [1m-p1003.1-2024   [22mIEEE Std 1003.1‐2024 (“POSIX.1”)

     POSIX Part 2: Shell and Utilities

           [1m-iso9945-2-93   [22mISO/IEC 9945‐2:1993 (“POSIX.2”)
           [1m-p1003.2        [22mIEEE Std 1003.2 (“POSIX.2”)
           [1m-p1003.2-92     [22mIEEE Std 1003.2‐1992 (“POSIX.2”)
           [1m-p1003.2a-92    [22mIEEE Std 1003.2a‐1992 (“POSIX.2”)

     X/Open

           [1m-susv1          [22mVersion 1 of the Single UNIX Specification (“SUSv1”)
           [1m-susv2          [22mVersion 2 of the Single UNIX Specification (“SUSv2”)
           [1m-susv3          [22mVersion 3 of the Single UNIX Specification (“SUSv3”)
           [1m-susv4          [22mVersion 4 of the Single UNIX Specification (“SUSv4”)
           [1m-svid4          [22mSystem   V   Interface   Definition,  Fourth  Edition
                           (“SVID4”)
           [1m-xbd5           [22mX/Open Base Definitions Issue 5 (“XBD5”)
           [1m-xcu5           [22mX/Open Commands and Utilities Issue 5 (“XCU5”)
           [1m-xcurses4.2     [22mX/Open Curses Issue 4, Version 2 (“XCURSES4.2”)
           [1m-xns5           [22mX/Open Networking Services Issue 5 (“XNS5”)
           [1m-xns5.2         [22mX/Open Networking Services Issue 5.2 (“XNS5.2”)
           [1m-xpg3           [22mX/Open Portability Guide Issue 3 (“XPG3”)
           [1m-xpg4           [22mX/Open Portability Guide Issue 4 (“XPG4”)
           [1m-xpg4.2         [22mX/Open  Portability  Guide   Issue   4,   Version   2
                           (“XPG4.2”)
           [1m-xsh5           [22mX/Open System Interfaces and Headers Issue 5 (“XSH5”)

     Miscellaneous

           [1m-ieee754        [22mIEEE Std 754‐1985
           [1m-iso8601        [22mISO 8601
           [1m-iso8802-3      [22mISO/IEC 8802‐3:1989

   [1mVariable Types[0m
     The  ‘.Vt’  macro  may be used whenever a type is referenced.  In a section
     titled “Synopsis”, ‘Vt’ causes a break (useful for old‐style C variable de‐
     clarations).

           [1mUsage: .Vt [22m⟨type⟩ ...

                    [1m.Vt extern char *optarg ;  [4m[22mextern[24m [4mchar[24m [4m*optarg[24m;
                    [1m.Vt FILE *                 [4m[22mFILE[24m [4m*[0m

   [1mVariables[0m
     Generic variable reference.

           [1mUsage: .Va [22m⟨variable⟩ ...

                    [1m.Va count             [4m[22mcount[0m
                    [1m.Va settimer ,        [4m[22msettimer[24m,
                    [1m.Va "int *prt" ) :    [4m[22mint[24m [4m*prt[24m):
                    [1m.Va "char s" ] ) ) ,  [4m[22mchar[24m [4ms[24m])),

     The default width is 12n.

   [1mManual Page Cross References[0m
     The ‘.Xr’ macro expects the first argument to be a manual page  name.   The
     optional second argument, if a string (defining the manual section), is put
     into parentheses.

           [1mUsage: .Xr [22m⟨man page name⟩ [⟨section⟩] ...

                    [1m.Xr mdoc        [4m[22mmdoc[0m
                    [1m.Xr mdoc ,      [4m[22mmdoc[24m,
                    [1m.Xr mdoc 7      [22m]8;;man:mdoc(7)\[4mmdoc[24m(7)]8;;\
                    [1m.Xr xinit 1x ;  [22m]8;;man:xinit(1x)\[4mxinit[24m(1x)]8;;\;

     The default width is 10n.

[1mGeneral text domain[0m
   [1mAT&T Macro[0m
           [1mUsage: .At [22m[⟨version⟩] ...

                    [1m.At       [22mAT&T UNIX
                    [1m.At v6 .  [22mVersion 6 AT&T UNIX.

     The following values for ⟨version⟩ are possible:

           [1m32v, v1, v2, v3, v4, v5, v6, v7, III, V, V.1, V.2, V.3, V.4[0m

   [1mBSD Macro[0m
           [1mUsage: .Bx [22m{-alpha | -beta | -devel} ...
                  [1m.Bx [22m[⟨version⟩ [⟨release⟩]] ...

                    [1m.Bx         [22mBSD
                    [1m.Bx 4.3 .   [22m4.3BSD.
                    [1m.Bx -devel  [22mBSD (currently under development)

     ⟨version⟩  will be prepended to the string ‘BSD’.  The following values for
     ⟨release⟩ are possible:

           [1mReno, reno, Tahoe, tahoe, Lite, lite, Lite2, lite2[0m

   [1mNetBSD Macro[0m
           [1mUsage: .Nx [22m[⟨version⟩] ...

                    [1m.Nx        [22mNetBSD
                    [1m.Nx 1.4 .  [22mNetBSD 1.4.

     For possible values of ⟨version⟩ see the description of the  ‘.Os’  command
     above in section “Title macros”.

   [1mFreeBSD Macro[0m
           [1mUsage: .Fx [22m[⟨version⟩] ...

                    [1m.Fx        [22mFreeBSD
                    [1m.Fx 2.2 .  [22mFreeBSD 2.2.

     For  possible  values of ⟨version⟩ see the description of the ‘.Os’ command
     above in section “Title macros”.

   [1mDragonFly Macro[0m
           [1mUsage: .Dx [22m[⟨version⟩] ...

                    [1m.Dx        [22mDragonFly
                    [1m.Dx 1.4 .  [22mDragonFly 1.4.

     For possible values of ⟨version⟩ see the description of the  ‘.Os’  command
     above in section “Title macros”.

   [1mOpenBSD Macro[0m
           [1mUsage: .Ox [22m[⟨version⟩] ...

                    [1m.Ox 1.0  [22mOpenBSD 1.0

   [1mBSD/OS Macro[0m
           [1mUsage: .Bsx [22m[⟨version⟩] ...

                    [1m.Bsx 1.0  [22mBSD/OS 1.0

   [1mUnix Macro[0m
           [1mUsage: .Ux [22m...

                    [1m.Ux  [22mUnix

   [1mEmphasis Macro[0m
     Text  may  be  stressed or emphasized with the ‘.Em’ macro.  The usual font
     for emphasis is italic.

           [1mUsage: .Em [22m⟨argument⟩ ...

                    [1m.Em does not          [4m[22mdoes[24m [4mnot[0m
                    [1m.Em exceed 1024 .     [4m[22mexceed[24m [4m1024[24m.
                    [1m.Em vide infra ) ) ,  [4m[22mvide[24m [4minfra[24m)),

     The default width is 10n.

   [1mFont Mode[0m
     The ‘.Bf’ font mode must be ended with the ‘.Ef’ macro (the latter takes no
     arguments).  Font modes may be nested within other font modes.

     ‘.Bf’ has the following syntax:

           [1m.Bf [22m⟨font mode⟩

     ⟨font mode⟩ must be one of the following three types:

           [1mEm [22m| [1m-emphasis  [22mSame as if the ‘.Em’ macro was used  for  the  entire
                           block of text.
           [1mLi [22m| [1m-literal   [22mSame  as  if  the ‘.Li’ macro was used for the entire
                           block of text.
           [1mSy [22m| [1m-symbolic  [22mSame as if the ‘.Sy’ macro was used  for  the  entire
                           block of text.

     Both macros are neither callable nor parsed.

   [1mEnclosure and Quoting Macros[0m
     The  concept  of  enclosure is similar to quoting.  The object being to en‐
     close one or more strings between a  pair  of  characters  like  quotes  or
     parentheses.   The  terms  quoting  and  enclosure are used interchangeably
     throughout this document.  Most of the one‐line  enclosure  macros  end  in
     small letter ‘q’ to give a hint of quoting, but there are a few irregulari‐
     ties.   For  each  enclosure  macro, there is a pair of opening and closing
     macros that end with the lowercase letters ‘o’ and ‘c’ respectively.

     [1mQuote   Open   Close   Function                  Result[0m
     .Aq     .Ao    .Ac     Angle Bracket Enclosure   <string>
     .Bq     .Bo    .Bc     Bracket Enclosure         [string]
     .Brq    .Bro   .Brc    Brace Enclosure           {string}
     .Dq     .Do    .Dc     Double Quote              “string”
     .Eq     .Eo    .Ec     Enclose String (in XY)    XstringY
     .Pq     .Po    .Pc     Parenthesis Enclosure     (string)
     .Ql                    Quoted or Literal         “string” or string
     .Qq     .Qo    .Qc     Straight Double Quote     "string"
     .Sq     .So    .Sc     Single Quote              ‘string’

     All macros ending with ‘q’ and ‘o’ have a default width value of 12n.

     [1m.Eo[22m, [1m.Ec  [22mThese macros expect the first argument  to  be  the  opening  and
               closing strings, respectively.

     [1m.Es[22m, [1m.En  [22mTo work around the nine‐argument limit in the original [4mtroff[24m pro‐
               gram,  [4mmdoc[24m  supports  two  other  macros  that are now obsolete.
               ‘.Es’ uses its first and second parameters as opening and closing
               marks which are then used to enclose the arguments of ‘.En’.  The
               default width value is 12n for both macros.

     [1m.Eq       [22mThe first and second arguments of this macro are the opening  and
               closing strings respectively, followed by the arguments to be en‐
               closed.

     [1m.Ql       [22mThe  quoted‐or‐literal  macro  behaves  differently  in [4mtroff[24m and
               [4mnroff[24m modes.  When formatting with ]8;;man:nroff(1)\[4mnroff[24m(1)]8;;\, [4mmdoc[24m quotes the  ar‐
               guments.  With [4mtroff[24m, [4mmdoc[24m sets them in a constant‐width font.

               The default width is 16n.

     [1m.Pf       [22mThe  prefix macro suppresses the whitespace between its first and
               second argument:

                     [1m.Pf ( Fa name2  [22m([4mname2[0m

               The default width is 12n.

               The ‘.Ns’ macro (see below) performs the analogous  suffix  func‐
               tion.

     [1m.Ap       [22mThe  ‘.Ap’ macro inserts an apostrophe and exits any special text
               modes, continuing in ‘.No’ mode.

     Examples of quoting:

           [1m.Aq                      [22m⟨⟩
           [1m.Aq Pa ctype.h ) ,       [22m⟨[4mctype.h[24m⟩),
           [1m.Bq                      [22m[]
           [1m.Bq Em Greek , French .  [22m[[4mGreek[24m, [4mFrench[24m].
           [1m.Dq                      [22m“”
           [1m.Dq string abc .         [22m“string abc”.
           [1m.Dq '\[ha][A-Z]'         [22m“’^[A‐Z]’”
           [1m.Ql man mdoc             [22m‘man mdoc’
           [1m.Qq                      [22m""
           [1m.Qq string ) ,           [22m"string"),
           [1m.Qq string Ns ),         [22m"string),"
           [1m.Sq                      [22m‘’
           [1m.Sq string               [22m‘string’
           [1m.Em or Ap ing            [4m[22mor[24m’ing

     For a good example of nested enclosure macros, see the ‘.Op’ option  macro.
     It was created from the same underlying enclosure macros as those presented
     in  the  list above.  The ‘.Xo’ and ‘.Xc’ extended argument list macros are
     discussed below.

   [1mNormal text macro[0m
     ‘No’ formats subsequent argument(s) normally, ending the effect of ‘Em’ and
     similar.  Parsing is [4mnot[24m suppressed, so you must  prefix  words  like  ‘No’
     with ‘\&’ to avoid their interpretation as [4mmdoc[24m macros.

           [1mUsage: .No [4m[22margument[24m ...

                    [1m.Em Use caution No here .  [22m→ [4mUse[24m [4mcaution[24m here.
                    [1m.Em No dogs allowed .      [22m→ [4mNo[24m dogs allowed.
                    [1m.Em \&No dogs allowed .    [22m→ [4mNo[24m [4mdogs[24m [4mallowed[24m.

     The default width is 12n.

   [1mNo‐Space Macro[0m
     The  ‘.Ns’  macro suppresses insertion of a space between the current posi‐
     tion and its first parameter.  For example, it is useful for old style  ar‐
     gument lists where there is no space between the flag and argument:

           [1mUsage: [22m... ⟨argument⟩ Ns [⟨argument⟩] ...
                  [1m.Ns [22m⟨argument⟩ ...

                    [1m.Op Fl I Ns Ar directory  [22m[[1m-I[4m[22mdirectory[24m]

     Note:  The ‘.Ns’ macro always invokes the ‘.No’ macro after eliminating the
     space unless another macro name follows it.  If used as  a  command  (i.e.,
     the second form above in the ‘Usage’ line), ‘.Ns’ is identical to ‘.No’.

   [1m(Sub)section cross references[0m
     Use  the  ‘.Sx’ macro to cite a (sub)section heading within the given docu‐
     ment.

           [1mUsage: .Sx [22m⟨section‐reference⟩ ...

                    [1m.Sx Files  [22m→ “Files”

     The default width is 16n.

   [1mSymbolics[0m
     The symbolic emphasis macro is generally a boldface  macro  in  either  the
     symbolic sense or the traditional English usage.

           [1mUsage: .Sy [22m⟨symbol⟩ ...

                    [1m.Sy Important Notice  [22m→ [1mImportant Notice[0m

     The default width is 6n.

   [1mMathematical Symbols[0m
     Use this macro for mathematical symbols and similar things.

           [1mUsage: .Ms [22m⟨math symbol⟩ ...

                    [1m.Ms sigma  [22m→ [1msigma[0m

     The default width is 6n.

   [1mReferences and Citations[0m
     The  following macros make a modest attempt to handle references.  At best,
     the macros make it convenient to manually drop  in  a  subset  of  ]8;;man:refer(1)\[4mrefer[24m(1)]8;;\
     style references.

           [1m.Rs     [22mReference  start (does not take arguments).  In a section ti‐
                   tled “See also”, it causes a break and begins  collection  of
                   reference information until the reference end macro is read.
           [1m.Re     [22mReference  end  (does  not take arguments).  The reference is
                   printed.
           [1m.%A     [22mReference author name; one name per invocation.
           [1m.%B     [22mBook title.
           [1m.%C     [22mCity/place.
           [1m.%D     [22mDate.
           [1m.%I     [22mIssuer/publisher name.
           [1m.%J     [22mJournal name.
           [1m.%N     [22mIssue number.
           [1m.%O     [22mOptional information.
           [1m.%P     [22mPage number.
           [1m.%Q     [22mCorporate or foreign author.
           [1m.%R     [22mReport name.
           [1m.%T     [22mTitle of article.
           [1m.%U     [22mOptional hypertext reference.
           [1m.%V     [22mVolume.

     Macros beginning with ‘%’ are not callable but accept multiple arguments in
     the usual way.  Only the ‘.Tn’ macro is handled properly  as  a  parameter;
     other  macros  will cause strange output.  ‘.%B’ and ‘.%T’ can be used out‐
     side of the ‘.Rs/.Re’ environment.

     Example:

           .Rs
           .%A "Matthew Bar"
           .%A "John Foo"
           .%T "Implementation Notes on foobar(1)"
           .%R "Technical Report ABC-DE-12-345"
           .%Q "Drofnats College"
           .%C "Nowhere"
           .%D "April 1991"
           .Re

     produces

           Matthew Bar and John Foo, [4mImplementation[24m [4mNotes[24m [4mon[24m [4mfoobar(1)[24m, Techni‐
           cal Report ABC‐DE‐12‐345, Drofnats College, Nowhere, April 1991.

   [1mTrade Names or Acronyms[0m
     The trade name macro prints its arguments at a smaller type  size.   It  is
     intended to imitate a small caps fonts for fully capitalized acronyms.

           [1mUsage: .Tn [22m⟨symbol⟩ ...

                    [1m.Tn DEC    [22mDEC
                    [1m.Tn ASCII  [22mASCII

     The default width is 10n.

   [1mExtended Arguments[0m
     The  [1m.Xo  [22mand  [1m.Xc  [22mmacros  allow one to extend an argument list on a macro
     boundary for the ‘.It’ macro (see below).  Note that [1m.Xo [22mand [1m.Xc [22mare imple‐
     mented similarly to all other  macros  opening  and  closing  an  enclosure
     (without  inserting  characters, of course).  This means that the following
     is true for those macros also.

     Here is an example of ‘.Xo’ using the space mode macro to turn spacing off:

           .Bd -literal -offset indent
           .Sm off
           .It Xo Sy I Ar operation
           .No \en Ar count No \en
           .Xc
           .Sm on
           .Ed

     produces

           [1mI[4m[22moperation[24m\n[4mcount[24m\n

     Another one:

           .Bd -literal -offset indent
           .Sm off
           .It Cm S No / Ar old_pattern Xo
           .No / Ar new_pattern
           .No / Op Cm g
           .Xc
           .Sm on
           .Ed

     produces

           [1mS[22m/[4mold_pattern[24m/[4mnew_pattern[24m/[[1mg[22m]

     Another example of ‘.Xo’ and enclosure macros: Test the value  of  a  vari‐
     able.

           .Bd -literal -offset indent
           .It Xo
           .Ic .ifndef
           .Oo \&! Oc Ns Ar variable Oo
           .Ar operator variable No ...
           .Oc Xc
           .Ed

     produces

           [1m.ifndef [22m[!][4mvariable[24m [[4moperator[24m [4mvariable[24m ...]

[1mPage structure domain[0m
   [1mSection headings[0m
     The  following ‘.Sh’ section heading macros are required in every man page.
     The remaining section headings are recommended at the discretion of the au‐
     thor writing the manual page.  The ‘.Sh’ macro is parsed but not  generally
     callable.   It  can be used as an argument in a call to ‘.Sh’ only; it then
     reactivates the default font for ‘.Sh’.

     The default width is 8n.

     [1m.Sh Name           [22mThe ‘.Sh Name’ macro is mandatory.   If  not  specified,
                        headers,  footers,  and page layout defaults will not be
                        set and things will be rather unpleasant.  The [4mName[24m sec‐
                        tion consists of at least three items.  The first is the
                        ‘.Nm’ name macro naming the subject  of  the  man  page.
                        The  second  is the name description macro, ‘.Nd’, which
                        separates the subject name from the third item, which is
                        the description.  The description  should  be  the  most
                        terse  and  lucid  possible,  as  the space available is
                        small.

                        ‘.Nd’ first prints ‘-’, then all its arguments.

     [1m.Sh Library        [22mThis section is  for  section  two  and  three  function
                        calls.   It should consist of a single ‘.Lb’ macro call;
                        see “Library Names”.

     [1m.Sh Synopsis       [22mThe “Synopsis” section describes the  typical  usage  of
                        the  subject of a man page.  The macros required are ei‐
                        ther ‘.Nm’, ‘.Cd’, or ‘.Fn’ (and possibly ‘.Fo’,  ‘.Fc’,
                        ‘.Fd’, and ‘.Ft’).  The function name macro ‘.Fn’ is re‐
                        quired for manual page sections 2 and 3; the command and
                        general  name macro ‘.Nm’ is required for sections 1, 5,
                        6, 7, and 8.  Section 4 manuals require a  ‘.Nm’,  ‘.Fd’
                        or  a  ‘.Cd’  configuration device usage macro.  Several
                        other macros may be necessary to  produce  the  synopsis
                        line as shown below:

                              [1mcat [22m[[1m-benstuv[22m] [[1m-[22m] [4mfile[24m ...

                        The following macros were used:

                              [1m.Nm cat[0m
                              [1m.Op Fl benstuv[0m
                              [1m.Op Fl[0m
                              [1m.Ar file No ...[0m

     [1m.Sh Description    [22mIn  most  cases the first text in the “Description” sec‐
                        tion is a brief paragraph on the  command,  function  or
                        file,  followed by a lexical list of options and respec‐
                        tive explanations.  To create such  a  list,  the  ‘.Bl’
                        (begin  list),  ‘.It’  (list  item) and ‘.El’ (end list)
                        macros are used (see “Lists and Columns” below).

     [1m.Sh Implementation notes[0m
                        Implementation specific  information  should  be  placed
                        here.

     [1m.Sh Return values  [22mSections  2,  3  and  9 function return values should go
                        here.  The ‘.Rv’ macro may be used to generate text  for
                        use  in  the  “Return values” section for most section 2
                        and 3 library functions; see “Return Values”.

     The following ‘.Sh’ section headings are part of the preferred manual  page
     layout  and  must  be used appropriately to maintain consistency.  They are
     listed in the order in which they would be used.

     [1m.Sh Environment    [22mThe [4mEnvironment[24m section should reveal any related  envi‐
                        ronment variables and clues to their behavior and/or us‐
                        age.

     [1m.Sh Files          [22mFiles  which are used or created by the man page subject
                        should be listed via the ‘.Pa’ macro in the “Files” sec‐
                        tion.

     [1m.Sh Examples       [22mThere are several ways to create examples.  See  subsec‐
                        tion “Examples and Displays” below for details.

     [1m.Sh Diagnostics    [22mDiagnostic  messages  from a command should be placed in
                        this section.  The ‘.Ex’ macro may be used  to  generate
                        text  for use in the “Diagnostics” section for most sec‐
                        tion 1, 6 and 8 commands; see “Exit Status”.

     [1m.Sh Compatibility  [22mKnown compatibility issues (e.g. deprecated  options  or
                        parameters) should be listed here.

     [1m.Sh Errors         [22mSpecific  error  handling, especially from library func‐
                        tions (man page sections 2, 3, and 9)  should  go  here.
                        The ‘.Er’ macro is used to specify an error (errno).

     [1m.Sh See also       [22mReferences  to  other material on the man page topic and
                        cross references to other relevant man pages  should  be
                        placed  in the “See also” section.  Cross references are
                        specified using the  ‘.Xr’  macro.   Currently  ]8;;man:refer(1)\[4mrefer[24m(1)]8;;\
                        style references are not accommodated.

                        It is recommended that the cross references be sorted by
                        section  number, then alphabetically by name within each
                        section, then separated by commas.  Example:

                        ]8;;man:ls(1)\[4mls[24m(1)]8;;\, ]8;;man:ps(1)\[4mps[24m(1)]8;;\, ]8;;man:group(5)\[4mgroup[24m(5)]8;;\, ]8;;man:passwd(5)\[4mpasswd[24m(5)]8;;\

     [1m.Sh Standards      [22mIf the command, library function, or file adheres  to  a
                        specific   implementation   such   as  IEEE  Std  1003.2
                        (“POSIX.2”) or ANSI X3.159‐1989 (“ANSI C89”) this should
                        be noted here.  If the command does not  adhere  to  any
                        standard,  its  history  should  be noted in the [4mHistory[0m
                        section.

     [1m.Sh History        [22mAny command which does not adhere to any specific  stan‐
                        dards should be outlined historically in this section.

     [1m.Sh Authors        [22mCredits  should be placed here.  Use the ‘.An’ macro for
                        names and the ‘.Aq’ macro for email addresses within op‐
                        tional contact information.  Explicitly indicate whether
                        the person authored the initial manual page or the soft‐
                        ware or whatever the person is being credited for.

     [1m.Sh Bugs           [22mBlatant problems with the topic go here.

     User‐specified ‘.Sh’ sections may be added; for example, this  section  was
     set with:

                    .Sh "Page structure domain"

   [1mSubsection headings[0m
     Subsection headings have exactly the same syntax as section headings: ‘.Ss’
     is  parsed  but not generally callable.  It can be used as an argument in a
     call to ‘.Ss’ only; it then reactivates the default font for ‘.Ss’.

     The default width is 8n.

   [1mParagraphs and Line Spacing[0m
     [1m.Pp  [22mThe ‘.Pp’ paragraph command may be used to specify a line space  where
          necessary.  The macro is not necessary after a ‘.Sh’ or ‘.Ss’ macro or
          before  a  ‘.Bl’ or ‘.Bd’ macro (which both assert a vertical distance
          unless the [1m-compact [22mflag is given).

          The macro is neither callable nor parsed and takes  no  arguments;  an
          alternative name is ‘.Lp’.

   [1mKeeps[0m
     The  only  keep  that is implemented at this time is for words.  The macros
     are ‘.Bk’ (begin keep) and ‘.Ek’ (end keep).  The only  option  that  ‘.Bk’
     currently accepts is [1m-words [22m(also the default); this prevents breaks in the
     middle  of  options.   In  the example for [1mmake [22mcommand‐line arguments (see
     “What’s in a Name”), the keep prevents [4mnroff[24m from placing the flag and  the
     argument on separate lines.

     Neither macro is callable or parsed.

     More work needs to be done on the keep macros; specifically, a [1m-line [22moption
     should be added.

   [1mExamples and Displays[0m
     There are seven types of displays.

     [1m.D1  [22m(This  is  D‐one.)   Display one line of indented text.  This macro is
          parsed but not callable.

                [1m-ldghfstru[0m

          The above was produced by: [1m.D1 Fl ldghfstru[22m.

     [1m.Dl  [22m(This is D‐ell.)  Display one line  of  indented  [4mliteral[24m  text.   The
          ‘.Dl’ example macro has been used throughout this file.  It allows the
          indentation (display) of one line of text.  Its default font is set to
          constant width (literal).  ‘.Dl’ is parsed but not callable.

                [1m% ls -ldg /usr/local/bin[0m

          The above was produced by: [1m.Dl % ls \-ldg /usr/local/bin[22m.

     [1m.Bd  [22mBegin  display.  The ‘.Bd’ display must be ended with the ‘.Ed’ macro.
          It has the following syntax:

                [1m.Bd [22m{-literal | -filled | -unfilled | -ragged | -centered}
                     [-offset ⟨string⟩] [-file ⟨file name⟩] [-compact]

          [1m-ragged            [22mFill, but do not adjust  (leave  the  right  margin
                             ragged).
          [1m-centered          [22mCenter  lines  between  the  current left and right
                             margin.  Note that each single line is centered.
          [1m-unfilled          [22mDo not fill; break lines where  their  input  lines
                             are  broken.  This can produce overlong lines with‐
                             out warning messages.
          [1m-filled            [22mDisplay a filled block.  Text  is  filled  and  ad‐
                             justed; the left and right margins are straight.
          [1m-literal           [22mDisplay  block  with  literal  font (usually fixed‐
                             width).  Useful for source code or simple tabbed or
                             spaced text.
          [1m-file [22m⟨[4mfile[24m [4mname[24m⟩  The file whose name follows the [1m-file [22mflag is  read
                             and  displayed  before any data enclosed with ‘.Bd’
                             and ‘.Ed’, using the selected  display  type.   Any
                             [4mtroff/mdoc[24m commands in the file will be processed.
          [1m-offset [22m⟨[4mstring[24m⟩   If  [1m-offset  [22mis specified with one of the following
                             strings, the string is interpreted to indicate  the
                             level  of  indentation for the forthcoming block of
                             text:

                             [4mleft[24m        Align block on the current left margin;
                                         this is the default mode of ‘.Bd’.
                             [4mcenter[24m      Supposedly center the block.   At  this
                                         time  unfortunately,  the  block merely
                                         gets left aligned  about  an  imaginary
                                         center margin.
                             [4mindent[24m      Indent  by  one default indent value or
                                         tab.  The default indent value is  also
                                         used for the ‘.D1’ and ‘.Dl’ macros, so
                                         one is guaranteed the two types of dis‐
                                         plays  will  line  up.  The indentation
                                         value is normally set to  6n  or  about
                                         two  thirds  of  an  inch (six constant
                                         width characters).
                             [4mindent-two[24m  Indent two  times  the  default  indent
                                         value.
                             [4mright[24m       This  [4mleft[24m  aligns  the block about two
                                         inches from the right side of the page.
                                         This macro needs work and  perhaps  may
                                         never do the right thing within [4mtroff[24m.

                             If  ⟨string⟩  is a valid numeric expression instead
                             ([4mwith[24m [4ma[24m [4mscaling[24m [4mindicator[24m [4mother[24m [4mthan[24m ‘[4mu[24m’), use that
                             value for indentation.  The most useful scaling in‐
                             dicators are ‘m’ and ‘n’, specifying the  so‐called
                             [4mEm[24m  and [4mEn[24m [4msquare[24m.  This is approximately the width
                             of the letters ‘m’ and ‘n’ respectively of the cur‐
                             rent font (for [4mnroff[24m output, both  scaling  indica‐
                             tors  give  the  same values).  If ⟨string⟩ isn’t a
                             numeric expression, it is tested whether it  is  an
                             [4mmdoc[24m macro name, and the default offset value asso‐
                             ciated  with  this  macro is used.  Finally, if all
                             tests fail, the width of ⟨string⟩ (typeset  with  a
                             fixed‐width font) is taken as the offset.
          [1m-compact           [22mSuppress  insertion  of vertical space before begin
                             of display.

     [1m.Ed  [22mEnd display (takes no arguments).

   [1mLists and Columns[0m
     There are several types of lists which may be initiated with the ‘.Bl’  be‐
     gin‐list  macro.   Items  within the list are specified with the ‘.It’ item
     macro, and each list must end with the ‘.El’ macro.  Lists  may  be  nested
     within  themselves and within displays.  The use of columns inside of lists
     or lists inside of columns is untested.

     In addition, several list attributes may be specified such as the width  of
     a  tag, the list offset, and compactness (blank lines between items allowed
     or disallowed).  Most of this document has been formatted with a tag  style
     list ([1m-tag[22m).

     It has the following syntax forms:

           [1m.Bl [22m{-hang | -ohang | -tag | -diag | -inset} [-width ⟨string⟩]
                [-offset ⟨string⟩] [-compact]
           [1m.Bl [22m-column [-offset ⟨string⟩] ⟨string1⟩ ⟨string2⟩ ...
           [1m.Bl [22m{-item | -enum [-nested] | -bullet | -hyphen | -dash} [-offset
                ⟨string⟩] [-compact]

     And now a detailed description of the list types.

     [1m-bullet  [22mA bullet list.

                    .Bl -bullet -offset indent -compact
                    .It
                    Bullet one goes here.
                    .It
                    Bullet two here.
                    .El

              Produces:

                    [1m•   [22mBullet one goes here.
                    [1m•   [22mBullet two here.

     [1m-dash [22m(or [1m-hyphen[22m)
              A dash list.

                    .Bl -dash -offset indent -compact
                    .It
                    Dash one goes here.
                    .It
                    Dash two here.
                    .El

              Produces:

                    [1m-   [22mDash one goes here.
                    [1m-   [22mDash two here.

     [1m-enum    [22mAn enumerated list.

                    .Bl -enum -offset indent -compact
                    .It
                    Item one goes here.
                    .It
                    And item two here.
                    .El

              The result:

                    1.   Item one goes here.
                    2.   And item two here.

              If you want to nest enumerated lists, use the [1m-nested [22mflag (start‐
              ing with the second‐level list):

                    .Bl -enum -offset indent -compact
                    .It
                    Item one goes here
                    .Bl -enum -nested -compact
                    .It
                    Item two goes here.
                    .It
                    And item three here.
                    .El
                    .It
                    And item four here.
                    .El

              Result:

                    1.   Item one goes here.
                         1.1.   Item two goes here.
                         1.2.   And item three here.
                    2.   And item four here.

     [1m-item    [22mA list of type [1m-item [22mwithout list markers.

                    .Bl -item -offset indent
                    .It
                    Item one goes here.
                    Item one goes here.
                    Item one goes here.
                    .It
                    Item two here.
                    Item two here.
                    Item two here.
                    .El

              Produces:

                    Item  one  goes  here.   Item  one goes here.  Item one goes
                    here.

                    Item two here.  Item two here.  Item two here.

     [1m-tag     [22mA list with tags.  Use [1m-width [22mto specify the tag width.

                    SL    sleep time of the process (seconds blocked)
                    PAGEIN
                          number of disk I/O operations  resulting  from  refer‐
                          ences by the process to pages not loaded in core.
                    UID   numerical user‐id of process owner
                    PPID  numerical  id of parent of process priority (non‐posi‐
                          tive when in non‐interruptible wait)

              The raw text:

                    .Bl -tag -width "PPID" -compact -offset indent
                    .It SL
                    sleep time of the process (seconds blocked)
                    .It PAGEIN
                    number of disk I/O operations resulting from references
                    by the process to pages not loaded in core.
                    .It UID
                    numerical user-id of process owner
                    .It PPID
                    numerical id of parent of process priority
                    (non-positive when in non-interruptible wait)
                    .El

     [1m-diag    [22mDiag lists create section four diagnostic lists and are similar to
              inset lists except callable macros are ignored.  The  [1m-width  [22mflag
              is not meaningful in this context.

              Example:

                    .Bl -diag
                    .It You can’t use Sy here.
                    The message says all.
                    .El

              produces

              [1mYou can’t use Sy here.  [22mThe message says all.

     [1m-hang    [22mA list with hanging tags.

                    [4mHanged[24m  labels appear similar to tagged lists when the label
                            is smaller than the label width.

                    [4mLonger[24m  [4mhanged[24m  [4mlist[24m  [4mlabels[24m blend into the paragraph unlike
                            tagged paragraph labels.

              And the unformatted text which created it:

                    .Bl -hang -offset indent
                    .It Em Hanged
                    labels appear similar to tagged lists when the
                    label is smaller than the label width.
                    .It Em Longer hanged list labels
                    blend into the paragraph unlike
                    tagged paragraph labels.
                    .El

     [1m-ohang   [22mLists with overhanging tags do not use indentation for the  items;
              tags are written to a separate line.

                    [1mSL[0m
                    sleep time of the process (seconds blocked)

                    [1mPAGEIN[0m
                    number  of  disk I/O operations resulting from references by
                    the process to pages not loaded in core.

                    [1mUID[0m
                    numerical user‐id of process owner

                    [1mPPID[0m
                    numerical id of parent  of  process  priority  (non‐positive
                    when in non‐interruptible wait)

              The raw text:

                    .Bl -ohang -offset indent
                    .It Sy SL
                    sleep time of the process (seconds blocked)
                    .It Sy PAGEIN
                    number of disk I/O operations resulting from references
                    by the process to pages not loaded in core.
                    .It Sy UID
                    numerical user-id of process owner
                    .It Sy PPID
                    numerical id of parent of process priority
                    (non-positive when in non-interruptible wait)
                    .El

     [1m-inset   [22mHere is an example of inset labels:

                    [4mTag[24m  The tagged list (also called a tagged paragraph) is the
                    most common type of list used in the Berkeley manuals.   Use
                    a [1m-width [22mattribute as described below.

                    [4mDiag[24m Diag lists create section four diagnostic lists and are
                    similar to inset lists except callable macros are ignored.

                    [4mHang[24m Hanged labels are a matter of taste.

                    [4mOhang[24m Overhanging labels are nice when space is constrained.

                    [4mInset[24m  Inset  labels  are  useful  for controlling blocks of
                    paragraphs and are valuable for converting [4mmdoc[24m  manuals  to
                    other formats.

              Here is the source text which produced the above example:

                    .Bl -inset -offset indent
                    .It Em Tag
                    The tagged list (also called a tagged paragraph)
                    is the most common type of list used in the
                    Berkeley manuals.
                    .It Em Diag
                    Diag lists create section four diagnostic lists
                    and are similar to inset lists except callable
                    macros are ignored.
                    .It Em Hang
                    Hanged labels are a matter of taste.
                    .It Em Ohang
                    Overhanging labels are nice when space is constrained.
                    .It Em Inset
                    Inset labels are useful for controlling blocks of
                    paragraphs and are valuable for converting
                    .Xr mdoc
                    manuals to other formats.
                    .El

     [1m-column  [22mThis  list type generates multiple columns.  The number of columns
              and the width of each column is determined by the arguments to the
              [1m-column [22mlist, ⟨[4mstring1[24m⟩, ⟨[4mstring2[24m⟩, etc.  If ⟨[4mstringN[24m⟩ starts with
              a ‘.’ (dot) immediately followed by a valid [4mmdoc[24m macro  name,  in‐
              terpret ⟨[4mstringN[24m⟩ and use the width of the result.  Otherwise, the
              width  of  ⟨[4mstringN[24m⟩ (typeset with a fixed‐width font) is taken as
              the [4mN[24mth column width.

              Each ‘.It’ argument is parsed to make a row,  each  column  within
              the  row  is  a  separate argument separated by a tab or the ‘.Ta’
              macro.

              The table:

                    [1mString    Nroff    Troff[0m
                    [1m<=        [22m<=       ≤
                    [1m>=        [22m>=       ≥

              was produced by:

              .Bl -column -offset indent ".Sy String" ".Sy Nroff" ".Sy Troff"
              .It Sy String Ta Sy Nroff Ta Sy Troff
              .It Li <= Ta <= Ta \*(<=
              .It Li >= Ta >= Ta \*(>=
              .El

              Don’t abuse this list type!  For more complicated cases  it  might
              be far better and easier to use ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\, the table preprocessor.

     Other keywords:

     [1m-width [22m⟨[4mstring[24m⟩   If  ⟨[4mstring[24m⟩ starts with a ‘.’ (dot) immediately followed
                       by a valid [4mmdoc[24m macro name, interpret  ⟨[4mstring[24m⟩  and  use
                       the  width of the result.  Almost all lists in this docu‐
                       ment use this option.

                       Example:

                             .Bl -tag -width ".Fl test Ao Ar string Ac"
                             .It Fl test Ao Ar string Ac
                             This is a longer sentence to show how the
                             .Fl width
                             flag works in combination with a tag list.
                             .El

                       gives:

                       [1m-test [22m⟨[4mstring[24m⟩  This is a longer sentence to show how the
                                       [1m-width [22mflag works in combination  with  a
                                       tag list.

                       (Note  that  the  current  state  of [4mmdoc[24m is saved before
                       ⟨[4mstring[24m⟩ is interpreted; afterward, all variables are re‐
                       stored again.  However, boxes (used for enclosures) can’t
                       be saved in GNU ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\;  as  a  consequence,  arguments
                       must always be [4mbalanced[24m to avoid nasty errors.  For exam‐
                       ple,  do not write ‘.Ao Ar string’ but ‘.Ao Ar string Xc’
                       instead  if  you  really  need  only  an  opening   angle
                       bracket.)

                       Otherwise,  if  ⟨[4mstring[24m⟩  is  a  valid numeric expression
                       ([4mwith[24m [4ma[24m [4mscaling[24m [4mindicator[24m [4mother[24m [4mthan[24m ‘[4mu[24m’), use that value
                       for indentation.  The most useful scaling indicators  are
                       ‘m’  and  ‘n’, specifying the so‐called [4mEm[24m and [4mEn[24m [4msquare[24m.
                       This is approximately the width of the  letters  ‘m’  and
                       ‘n’  respectively  of the current font (for [4mnroff[24m output,
                       both  scaling  indicators  give  the  same  values).   If
                       ⟨[4mstring[24m⟩ isn’t a numeric expression, it is tested whether
                       it is an [4mmdoc[24m macro name, and the default width value as‐
                       sociated  with this macro is used.  Finally, if all tests
                       fail, the width of ⟨[4mstring[24m⟩ (typeset with  a  fixed‐width
                       font) is taken as the width.

                       If  a  width is not specified for the tag list type, ‘6n’
                       is used.

     [1m-offset [22m⟨[4mstring[24m⟩  If ⟨[4mstring[24m⟩ is [4mindent[24m, a default indent  value  (normally
                       set  to  6n, similar to the value used in ‘.Dl’ or ‘.Bd’)
                       is used.  If ⟨[4mstring[24m⟩ is a valid numeric  expression  in‐
                       stead ([4mwith[24m [4ma[24m [4mscaling[24m [4mindicator[24m [4mother[24m [4mthan[24m ‘[4mu[24m’), use that
                       value  for  indentation.  The most useful scaling indica‐
                       tors are ‘m’ and ‘n’, specifying the so‐called [4mEm[24m and  [4mEn[0m
                       [4msquare[24m.   This  is approximately the width of the letters
                       ‘m’ and ‘n’ respectively of the current font  (for  [4mnroff[0m
                       output,  both  scaling  indicators give the same values).
                       If ⟨[4mstring[24m⟩ isn’t a  numeric  expression,  it  is  tested
                       whether  it is an [4mmdoc[24m macro name, and the default offset
                       value associated with this macro is  used.   Finally,  if
                       all  tests  fail,  the  width of ⟨[4mstring[24m⟩ (typeset with a
                       fixed‐width font) is taken as the offset.

     [1m-compact          [22mSuppress insertion of vertical space before the list  and
                       between list items.

[1mMiscellaneous macros[0m
     A  double  handful  of  macros fit only uncomfortably into one of the above
     sections.  Of these, we couldn’t find attested examples for ‘Me’  or  ‘Ot’.
     They  are documented here for completeness——if you know their proper usage,
     please send a mail to ]8;;mailto:groff@gnu.org\groff@gnu.org]8;;\ and include a specimen with its  prove‐
     nance.

     [1m.Bt  [22mformats boilerplate text.

                [1m.Bt  [22m→ is currently in beta test.

          It is neither callable nor parsed and takes no arguments.  Its default
          width is 6n.

     [1m.Fr  [22mis an obsolete means of specifying a function return value.

                Usage: .[1mFr [4m[22mreturn‐value[24m ...

          ‘Fr’  allows  a  break right before the return value (usually a single
          digit) which is bad typographical behaviour.  Instead, set the  return
          value with the rest of the code, using ‘\~’ to tie the return value to
          the previous word.

          Its default width is 12n.

     [1m.Hf  [22mInlines the contents of a (header) file into the document.

                Usage: .[1mHf [4m[22mfile[0m

          It  first  prints ‘File:’ followed by the file name, then the contents
          of [4mfile[24m.  It is neither callable nor parsed.

     [1m.Lk  [22mEmbed hyperlink.  This is a GNU extension  introduced  in  [4mgroff[24m  1.17
          (April 2001).

                Usage: .[1mLk [4m[22muri[24m [[4mlink‐text[24m]

          Its default width is 6n.

     [1m.Me  [22mUsage  unknown.  The [4mmdoc[24m sources describe it as a macro for “menu en‐
          tries”.

          Its default width is 6n.

     [1m.Mt  [22mEmbed email address.  This is a GNU extension introduced in [4mgroff[24m 1.17
          (April 2001).

                Usage: .[1mMt [4m[22memail‐address[0m

          Its default width is 6n.

     [1m.Ot  [22mUsage unknown.  The [4mmdoc[24m sources describe it  as  “old  function  type
          (fortran)”.

     [1m.Sm  [22mManipulate or toggle argument‐spacing mode.

                Usage: .[1mSm [22m[[1mon [22m| [1moff[22m] ...

          If argument‐spacing mode is off, no spaces between macro arguments are
          inserted.   If called without a parameter (or if the next parameter is
          neither ‘on’ nor ‘off’), ‘Sm’ toggles argument‐spacing mode.

          Its default width is 8n.

     [1m.Ud  [22mformats boilerplate text.

                [1m.Ud  [22m→ currently under development.

          It is neither callable nor parsed and takes no arguments.  Its default
          width is 8n.

[1mPredefined strings[0m
     The following strings are predefined for  compatibility  with  legacy  [4mmdoc[0m
     documents.   Contemporary  ones  should  use  the alternatives shown in the
     “Prefer” column below.  See ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\ for a full  discussion  of  these
     special character escape sequences.

     [1mString   7‐bit     8‐bit     UCS   Prefer    Meaning[0m
     \*(<=    <=        <=        ≤     \[<=]     less than or equal to
     \*(>=    >=        >=        ≥     \[>=]     greater than or equal to
     \*(Rq    "         "         ”     \[rq]     right double quote
     \*(Lq    "         "         “     \[lq]     left double quote
     \*(ua    ^         ^         ↑     \[ua]     vertical arrow up
     \*(aa    '         ´         ´     \[aa]     acute accent
     \*(ga    `         `         `     \[ga]     grave accent
     \*(q     "         "         "     \[dq]     neutral double quote
     \*(Pi    pi        pi        π     \[*p]     lowercase pi
     \*(Ne    !=        !=        ≠     \[!=]     not equals
     \*(Le    <=        <=        ≤     \[<=]     less than or equal to
     \*(Ge    >=        >=        ≥     \[>=]     greater than or equal to
     \*(Lt    <         <         <     <         less than
     \*(Gt    >         >         >     >         greater than
     \*(Pm    +-        ±         ±     \[+-]     plus or minus
     \*(If    infinity  infinity  ∞     \[if]     infinity
     \*(Am    &         &         &     &         ampersand
     \*(Na    [4mNaN[24m       [4mNaN[24m       [4mNaN[24m   .Em NaN   not a number (slanted)
     \*(Ba    |         |         |     |         bar (upright)

     Some  column  headings  are shorthand for standardized character encodings;
     “7‐bit” for ISO 646:1991 IRV (US‐ASCII), “8‐bit” for ISO Latin‐1  (8859‐1),
     and  “UCS”  for ISO 10646 (Unicode character set).  Historically, [4mmdoc[24m con‐
     figured the string definitions to fit the capabilities expected of the out‐
     put device.  Old typesetters lacked directional  double  quotes,  producing
     repeated directional single quotes ‘‘like this’’; early versions of [4mmdoc[24m in
     fact  defined the ‘Lq’ and ‘Rq’ strings this way.  Nowadays, output drivers
     take on the responsibility of glyph substitution, as they possess  relevant
     knowledge  of their available repertoires.  The ‘Ba’ and ‘Na’ strings imply
     a mandatory typeface: upright (roman) in the former, and slanted  (italics)
     with the latter.

[1mDiagnostics[0m
     The  debugging macro ‘.Db’ offered by previous versions of [4mmdoc[24m is unavail‐
     able in GNU ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ since the latter provides better facilities  to  check
     parameters; additionally, [4mgroff[24m [4mmdoc[24m implements many error and warning mes‐
     sages, making the package more robust and more verbose.

     The  remaining  debugging  macro is ‘.Rd’, which dumps the package’s global
     register and string contents to the standard error stream.  A  normal  user
     will never need it.

[1mOptions[0m
     The  following  [4mgroff[24m options set registers (with [1m-r[22m) and strings (with [1m-d[22m)
     recognized and used by the [4mmdoc[24m macro package.  To ensure rendering consis‐
     tent with output device capabilities  and  reader  preferences,  man  pages
     should never manipulate them.

     Setting string ‘AD’ configures the adjustment mode for most formatted text.
     Typical values are ‘b’ for adjustment to both margins (the default), or ‘l’
     for  left  alignment  (ragged right margin).  Any valid argument to [4mgroff[24m’s
     ‘ad’ request may be used.  See ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\ for less‐common choices.
           [1mgroff -Tutf8 -dAD=l -mdoc groff_mdoc.7 [22m| [1mless -R[0m

     Setting register ‘C’ to 1 numbers output pages consecutively,  rather  than
     resetting the page number to 1 (or the value of register ‘P’) with each new
     [4mmdoc[24m document.

     By  default,  the package inhibits page breaks, headers, and footers in the
     midst of the document text if it is being displayed with a terminal  device
     such  as  ‘latin1’ or ‘utf8’, to enable more efficient viewing of the page.
     This behavior can be changed to format the page as if for 66‐line  Teletype
     output  by  setting  the  continuous  rendering register ‘cR’ to zero while
     calling ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\.
           [1mgroff -Tlatin1 -rcR=0 -mdoc foo.man > foo.txt[0m
     On HTML devices, it cannot be disabled.

     Section headings (defined with ‘.Sh’) and page titles in  headers  (defined
     with ‘.Dt’) can be presented in full capitals by setting the registers ‘CS’
     and ‘CT’, respectively, to 1.  These transformations are off by default be‐
     cause they discard case distinction information.

     Setting  register  ‘D’ to 1 enables double‐sided page layout, which is only
     distinct when not continuously rendering.  It places the page number at the
     bottom right on odd‐numbered (recto) pages, and at the bottom left on even‐
     numbered (verso) pages, swapping places with the arguments to ‘.Os’.
           [1mgroff -Tps -rD1 -mdoc foo.man > foo.ps[0m

     The value of the ‘FT’ register determines the footer’s  distance  from  the
     page  bottom;  this  amount is always negative and should specify a scaling
     unit.  At one half‐inch above this location, the page text is broken before
     writing the footer.  It is ignored if continuous rendering is enabled.  The
     default is “-0.5i - 1v”.

     The ‘HF’ string sets the font used for section and subsection headings; the
     default is ‘B’ (bold style of the default family).  Any valid  argument  to
     [4mgroff[24m’s ‘ft’ request may be used.

     Normally,  automatic hyphenation is enabled using a mode appropriate to the
     [4mgroff[24m locale; see section “Localization“ of ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\.  It can  be  disabled
     by setting the ‘HY’ register to zero.
           [1mgroff -Tutf8 -rHY=0 -mdoc foo.man [22m| [1mless -R[0m

     The  paragraph and subsection heading indentation amounts can be changed by
     setting the registers ‘BP’ and ‘SN’.
           [1mgroff -Tutf8 -rBP=4n -rSN=2n -mdoc foo.man [22m| [1mless -R[0m
     The default paragraph and subsection heading indentation amounts are 5n and
     3n, respectively.  Section headings are set with an indentation of zero.

     The line and title lengths can be changed by setting the registers ‘LL’ and
     ‘LT’, respectively:
           [1mgroff -Tutf8 -rLL=100n -rLT=100n -mdoc foo.man [22m| [1mless -R[0m
     If not set, both registers default to 80n for  terminal  devices  and  6.5i
     otherwise.

     The  ‘MF’  string  sets  the font used for man page identifiers in document
     headers and footers and in the formatted output of the ‘Xr’ macro.  The de‐
     fault is ‘I’ (italic style of the default family).  Any valid  argument  to
     [4mgroff[24m’s ‘ft’ request may be used.

     Setting the ‘P’ register starts enumeration of pages at its value.  The de‐
     fault is 1.

     The ‘PO’ register configures the page offset.  The default is device‐depen‐
     dent; typically 0 for terminal devices and 1i otherwise.

     To  change  the  document font size to 11p or 12p, set register ‘S’ accord‐
     ingly:
           [1mgroff -Tdvi -rS11 -mdoc foo.man > foo.dvi[0m
     Register ‘S’ is ignored when formatting for terminal devices.

     By default, [4mgroff[24m hyperlinks the formatted text of  ‘Lk’,  ‘Mt’,  and  ‘Xr’
     calls  on output devices that support hyperlinking (“html”, “pdf”, and ter‐
     minal devices).  Set the ‘U’ register to 0 to disable this feature.

     Setting the ‘X’ register to a page number [4mp[24m numbers its successors  as  [4mp[24m[1ma[22m,
     [4mp[24m[1mb[22m,  [4mp[24m[1mc[22m, and so forth.  The register tracking the suffixed page letter uses
     format ‘a’ (see the ‘af’ request in ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\).

[1mFiles[0m
     [4m/usr/share/groff/1.24.1/tmac/andoc.tmac[0m
             This brief [4mgroff[24m program detects whether  the  [4mman[24m  or  [4mmdoc[24m  macro
             package is being used by a document and loads the correct macro de‐
             finitions,  taking advantage of the fact that pages using them must
             call [1mTH [22mor [1mDd[22m, respectively, before any other macros.  A user  typ‐
             ing, for example,
                   [1mgroff -mandoc page.1[0m
             need  not  know  which  package the file [4mpage.1[24m uses.  Multiple man
             pages, in either format, can be handled;  [4mandoc.tmac[24m  reloads  each
             macro package as necessary.

     [4m/usr/share/groff/1.24.1/tmac/doc.tmac[0m
             implements  the  bulk  of  the [4mgroff[24m [4mmdoc[24m package and loads further
             components as needed from the [4mmdoc[24m subdirectory.

     [4m/usr/share/groff/1.24.1/tmac/doc-old.tmac[0m
             implements a legacy version of the [4mmdoc[24m package; it was  superseded
             in  4.4BSD  (1994)  and  is needed only to render certain man pages
             from 4.3BSD‐Reno.

     [4m/usr/share/groff/1.24.1/tmac/mdoc.tmac[0m
             is a wrapper enabling the package to be loaded with the option  “[1m-m[0m
             [1mmdoc[22m”.

     [4m/usr/share/groff/1.24.1/tmac/mdoc/doc-common[0m
             defines  macros,  registers, and strings concerned with the produc‐
             tion  of  formatted  output.   It  includes  strings  of  the  form
             ‘doc-volume-ds-[4mX[24m’  and  ‘doc-volume-as-[4mX[24m’ for manual section titles
             and architecture identifiers, respectively, where [4mX[24m is an  argument
             recognized by .[1mDt[22m.

     [4m/usr/share/groff/1.24.1/tmac/mdoc/doc-nroff[0m
             defines parameters appropriate for rendering to terminal devices.

     [4m/usr/share/groff/1.24.1/tmac/mdoc/doc-ditroff[0m
             defines parameters appropriate for rendering to typesetter devices.

     [4m/usr/share/groff/1.24.1/tmac/mdoc/doc-syms[0m
             defines  many  strings  and macros that interpolate formatted text,
             such as names of operating system  releases,  *BSD  libraries,  and
             standards   documents.    The   string   names   are  of  the  form
             ‘doc-str-[4mO[24m[1m-[4m[22mV[24m’, ‘doc-str-St[1m--[4m[22mS[24m[1m-[4m[22mI[24m’ (observe the  double  dashes),  or
             ‘doc-str-Lb-[4mL[24m’,  where [4mO[24m is one of the operating system macros from
             section “General text domain” above, [4mV[24m is an encoding of an operat‐
             ing system release (sometimes omitted along with the ‘-’  preceding
             it),  [4mS[24m  an identifier for a standards body or committee, [4mI[24m one for
             an issue of a standard promulgated by [4mS[24m, and [4mL[24m a keyword  identify‐
             ing a *BSD library.

     [4m/usr/share/groff/site-tmac/mdoc.local[0m
             This file houses local additions and customizations to the package.
             It can be empty.

[1mSee also[0m
     The ]8;;https://mandoc.bsd.lv/\mandoc]8;;\ project maintains an independent implementation of the [4mmdoc[24m lan‐
     guage  and  a  renderer  that directly parses its markup as well as that of
     [4mman[24m.

     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, ]8;;man:man(1)\[4mman[24m(1)]8;;\, ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\, ]8;;man:groff_man(7)\[4mgroff_man[24m(7)]8;;\, ]8;;man:mdoc(7)\[4mmdoc[24m(7)]8;;\

[1mBugs[0m
     Section 3f has not been added to the header routines.

     ‘.Fn’ needs to have a check to prevent splitting up the line if its  length
     is  too  short.   Occasionally it separates the last parenthesis, and some‐
     times looks ridiculous if output lines are being filled.

     The list and display macros do not do any keeps  and  certainly  should  be
     able to.

     As  of [4mgroff[24m 1.23, ‘Tn’ no longer changes the type size; this functionality
     may return in a future release.

groff 1.24.1                       2026‐03‐20                      [4mgroff_mdoc[24m(7)
────────────────────────────────────────────────────────────────────────────────
[4mgroff_me[24m(7)             Miscellaneous Information Manual             [4mgroff_me[24m(7)

[1mName[0m
     groff_me - “me” macro package for formatting [4mroff[24m documents

[1mSynopsis[0m
     [1mgroff -me [22m[[4moption[24m ...] [[4mfile[24m ...]
     [1mgroff -m me [22m[[4moption[24m ...] [[4mfile[24m ...]

[1mDescription[0m
     The GNU implementation of the [4mme[24m macro package is part of the  [4mgroff[24m  docu‐
     ment  formatting  system.  The [4mme[24m package of macro definitions for the [4mroff[0m
     language provides a convenient facility for preparing technical  papers  in
     various  formats.   This version is based on the [4mme[24m distributed with 4.4BSD
     and can be used with the GNU [4mtroff[24m formatter as  well  as  those  descended
     from AT&T [4mtroff[24m.

     Some  formatter requests affect page layout unpredictably when used in con‐
     junction with this package; however, the following may  be  used  with  im‐
     punity  after  the  first call to a paragraphing macro like [1mlp [22mor [1mpp[22m.  Some
     arguments are optional; see ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\ for details, particularly of  requests
     whose  argument  list  is designated with an ellipsis.  An asterisk [1m* [22mmarks
     [4mgroff[24m extensions.

     [1mad [4m[22mc[24m       set text adjustment mode to [4mc[0m
     [1maf [4m[22mr[24m [4mf[24m     assign format [4mf[24m to register [4mr[0m
     [1mam [4m[22mm[24m [4me[24m     append to macro [4mm[24m until [4me[24m called
     [1mas [4m[22ms[24m [4mt[24m     append rest of line [4mt[24m to string [4ms[0m
     [1mbp [4m[22mn[24m       begin new page numbered [4mn[0m
     [1mbr         [22mbreak output line
     [1mce [4m[22mn[24m       center next [4mn[24m productive input lines
     [1mcp [4m[22mn[24m       en‐/disable AT&T [4mtroff[24m compatibility mode[1m*[0m
     [1mde [4m[22mm[24m [4me[24m     define macro [4mm[24m until [4me[24m called
     [1mdo [4m[22mt[24m       interpret input [4mt[24m with compatibility mode off[1m*[0m
     [1mds [4m[22ms[24m [4mt[24m     define rest of line [4mt[24m as string [4ms[0m
     [1mel [4m[22mt[24m       interpret [4mt[24m if corresponding [1mie[22m’s [4mp[24m false
     [1mfc [4m[22mc[24m [4md[24m     set field delimiter [4mc[24m and padding glyph [4md[0m
     [1mfi         [22menable filling
     [1mhc [4m[22mc[24m       set hyphenation character to [4mc[0m
     [1mhy [4m[22mm[24m       set automatic hyphenation mode to [4mm[0m
     [1mie [4m[22mp[24m [4mt[24m     as [1mif[22m, but enable interpretation of later [1mel[0m
     [1mif [4m[22mp[24m [4mt[24m     if condition [4mp[24m, interpret rest of line [4mt[0m
     [1min [4m[22mh[24m       set indentation to distance [4mh[0m
     [1mlc [4m[22mc[24m       set leader repetition glyph to [4mc[0m
     [1mls [4m[22mn[24m       set line spacing to [4mn[0m
     [1mmc [4m[22mc[24m [4mh[24m     set (right) margin glyph to [4mc[24m at distance [4mh[0m
     [1mmk [4m[22mr[24m       mark vertical position in register [4mr[0m
     [1mna         [22mdisable adjustment of text
     [1mne [4m[22mv[24m       need vertical space of distance [4mv[0m
     [1mnf         [22mdisable filling
     [1mnh         [22mdisable automatic hyphenation
     [1mnr [4m[22mr[24m [4mn[24m [4mi[24m   assign register [4mr[24m value [4mn[24m with auto‐increment [4mi[0m
     [1mns         [22mbegin no‐space mode
     [1mpl [4m[22mv[24m       set page length to [4mv[0m
     [1mpn [4m[22mn[24m       set next page number to [4mn[0m
     [1mpo [4m[22mh[24m       set page offset to [4mh[0m
     [1mrj [4m[22mn[24m       right‐align next [4mn[24m productive input lines[1m*[0m
     [1mrm [4m[22mm[24m       remove macro, string, or request [4mm[0m
     [1mrn [4m[22mm[24m [4mn[24m     rename macro, string, or request [4mm[24m to [4mn[0m
     [1mrr [4m[22mr[24m       remove register [4mr[0m
     [1mrs         [22mresume spacing (end no‐space mode)
     [1mrt [4m[22mv[24m       return to vertical position set by [1mmk[22m, or [4mv[0m
     [1mso [4m[22mf[24m       source (interpolate) input file [4mf[0m
     [1msp [4m[22mn[24m       insert [4mn[24m lines of vertical space
     [1mta [22m...     set tab stops
     [1mtc [4m[22mc[24m       set tab repetition glyph to [4mc[0m
     [1mti [4m[22mh[24m       set temporary indentation (next line only) to [4mh[0m
     [1mtl [22m...     output three‐part title
     [1mtr [22m...     translate characters
     [1mul [4m[22mn[24m       underline next [4mn[24m productive input lines

     Except on title pages (produced by calling [1mtp[22m), [4mme[24m suppresses the output of
     vertical space at the tops of pages (after the output of any page  header);
     the  [1msp  [22mrequest  thus does not work there.  You can instead call [1mbl [22mor en‐
     close the desired spacing request in a diversion, for instance  by  calling
     [1m(b  [22mand  [1m)b[22m.  [4mme[24m also intercepts the [1mll [22mrequest; see the “[4mme[24m Reference Man‐
     ual” for details.

   [1mName space[0m
     Objects in [4mme[24m follow a rigid naming convention.   To  avoid  conflict,  any
     user‐defined  register, string, or macro names should be single numerals or
     uppercase letters, or any longer sequence of letters and numerals  with  at
     least  one  uppercase  letter.   (For portability between BSD and [4mgroff[24m [4mme[24m,
     limit names to two characters, and avoid the name [1m[ [22m(left square bracket).)
     The names employed by any preprocessors in use should also  not  be  repur‐
     posed.

   [1mMacros[0m
     [1m$0   [22mpost‐section heading hook
     [1m$1   [22mpre‐section depth 1 hook
     [1m$2   [22mpre‐section depth 2 hook
     [1m$3   [22mpre‐section depth 3 hook
     [1m$4   [22mpre‐section depth 4 hook
     [1m$5   [22mpre‐section depth 5 hook
     [1m$6   [22mpre‐section depth 6 hook
     [1m$C   [22mpost‐chapter title hook
     [1m$H   [22mpage/column heading hook
     [1m$c   [22moutput chapter number and title
     [1m$f   [22moutput footer
     [1m$h   [22moutput header
     [1m$p   [22moutput section heading
     [1m$s   [22moutput footnote area separator
     [1m(b   [22mbegin block
     [1m(c   [22mbegin centered block
     [1m(d   [22mbegin delayed text
     [1m(f   [22mbegin footnote
     [1m(l   [22mbegin list
     [1m(q   [22mbegin long quotation
     [1m(x   [22mbegin index entry
     [1m(z   [22mbegin floating keep
     [1m)b   [22mend block
     [1m)c   [22mend centered block
     [1m)d   [22mend delayed text
     [1m)f   [22mend footnote
     [1m)l   [22mend list
     [1m)q   [22mend long quotation
     [1m)x   [22mend index entry
     [1m)z   [22mend floating keep
     [1m++   [22mset document segment type
     [1m+c   [22mbegin chapter
     [1m1c   [22mend multi‐column layout
     [1m2c   [22mbegin multi‐column layout
     [1mEN   [22mend [4meqn[24m equation
     [1mEQ   [22mbegin [4meqn[24m equation
     [1mGE   [22mend [4mgrn[24m picture with drawing position at bottom
     [1mGF   [22mend [4mgrn[24m picture with drawing position at top
     [1mGS   [22mstart [4mgrn[24m picture
     [1mIE   [22mend [4mideal[24m picture with drawing position at bottom
     [1mIF   [22mend [4mideal[24m picture with drawing position at top
     [1mIS   [22mstart [4mideal[24m picture
     [1mPE   [22mend [4mpic[24m picture with drawing position at bottom
     [1mPF   [22mend [4mpic[24m picture with drawing position at top
     [1mPS   [22mstart [4mpic[24m picture
     [1mTE   [22mend [4mtbl[24m table
     [1mTH   [22mend heading for multi‐page [4mtbl[24m table
     [1mTS   [22mstart [4mtbl[24m table
     [1mb    [22membolden argument
     [1mba   [22mset base indentation
     [1mbc   [22mbegin new column
     [1mbi   [22membolden and italicize argument
     [1mbx   [22mbox argument
     [1mef   [22mset even‐numbered page footer
     [1meh   [22mset even‐numbered page header
     [1mep   [22mend page
     [1mfo   [22mset footer
     [1mhe   [22mset header
     [1mhl   [22mdraw horizontal line
     [1mhx   [22msuppress next page’s headers/footers
     [1mi    [22mitalicize argument
     [1mip   [22mbegin indented paragraph
     [1mld   [22mreset localization and date registers and strings[1m*[0m
     [1mll   [22mset line length
     [1mlp   [22mbegin fully left‐aligned paragraph
     [1mnp   [22mbegin numbered paragraph
     [1mof   [22mset odd‐numbered page footer
     [1moh   [22mset odd‐numbered page header
     [1mpd   [22moutput delayed text
     [1mpp   [22mbegin first‐line indented paragraph
     [1mq    [22mquote argument
     [1mr    [22mset argument in roman
     [1mre   [22mreset tab stops
     [1msh   [22mbegin numbered section
     [1msm   [22mset argument at smaller type size
     [1msx   [22mchange section depth
     [1msz   [22mset type size and vertical spacing
     [1mtp   [22mbegin title page
     [1mu    [22munderline argument
     [1muh   [22mbegin unnumbered section
     [1mxl   [22mset line length (current environment only)
     [1mxp   [22moutput index

     Some  macros  are provided for “old” ]8;;man:roff(1)\[4mroff[24m(1)]8;;\ compatibility.  The “[4mme[24m Refer‐
     ence Manual” describes alternatives for modern documents.

     [1mar   [22muse Arabic numerals for page numbers
     [1mbl   [22minsert space (even at page top; cf. [1msp[22m)
     [1mix   [22mset indentation without break
     [1mm1   [22mset page top to header distance
     [1mm2   [22mset header to text distance
     [1mm3   [22mset text to footer distance
     [1mm4   [22mset footer to page bottom distance
     [1mn1   [22mbegin output line numbering
     [1mn2   [22mend or alter output line numbering
     [1mpa   [22mbegin page
     [1mro   [22muse Roman numerals for page numbers
     [1msk   [22mskip next page

   [1mRegisters[0m
     [1m$0   [22msection depth
     [1m$1   [22mfirst section number component
     [1m$2   [22msecond section number component
     [1m$3   [22mthird section number component
     [1m$4   [22mfourth section number component
     [1m$5   [22mfifth section number component
     [1m$6   [22msixth section number component
     [1m$c   [22mcurrent column number
     [1m$d   [22mdelayed text number
     [1m$f   [22mfootnote number
     [1m$i   [22mparagraph base indentation
     [1m$l   [22mcolumn width
     [1m$m   [22mnumber of available columns
     [1m$p   [22mnumbered paragraph number
     [1m$s   [22mcolumn spacing (indentation)
     [1mbi   [22mdisplay (block) indentation
     [1mbm   [22mdistance from text area to page bottom
     [1mbs   [22mdisplay (block) pre/post space
     [1mbt   [22mblock threshold for keeps
     [1mch   [22mcurrent chapter number
     [1mdf   [22mdisplay font
     [1mdv   [22mvertical spacing of displayed text (as percentage)[1m*[0m
     [1mes   [22mequation pre/post space
     [1mff   [22mfootnote font
     [1mfi   [22mfootnote indentation (first line only)
     [1mfm   [22mfooter margin
     [1mfp   [22mfootnote type size in points
     [1mfs   [22mfootnote prespace
     [1mfu   [22mfootnote undent (right indentation)
     [1mhm   [22mheader margin
     [1mii   [22mindented paragraph indentation
     [1mno   [22mline numbering offset[1m*[0m
     [1mpf   [22mparagraph font
     [1mpi   [22mparagraph indentation
     [1mpo   [22mpage offset
     [1mpp   [22mparagraph type size in points
     [1mps   [22mparagraph prespace
     [1mqi   [22mlong quotation left/right indentation
     [1mqp   [22mlong quotation type size in points
     [1mqs   [22mlong quotation pre/post space
     [1msf   [22msection title font
     [1msi   [22msection indentation per level of depth
     [1mso   [22madditional section title offset
     [1msp   [22msection title type size in points
     [1mss   [22msection prespace
     [1msx   [22msuper/subscript line height increase[1m*[0m
     [1mtf   [22mtitle font
     [1mtm   [22mdistance from page top to text area
     [1mtp   [22mtitle type size in points
     [1mtv   [22mvertical spacing of text (as percentage)[1m*[0m
     [1mxs   [22mindex entry prespace
     [1mxu   [22mindex undent (right indentation)
     [1my2   [22myear of the century[1m*[0m
     [1my4   [22myear[1m*[0m
     [1myr   [22myear minus 1900
     [1mzs   [22mfloating keep pre/post space

   [1mStrings[0m
     [1m#    [22mdelayed text marker
     [1m$n   [22mcatenated section number
     [1m*    [22mfootnote marker
     [1m-    [22mem dash
     [1m<    [22mbegin subscripting
     [1m>    [22mend subscripting
     [1mdw   [22mweekday name
     [1mlq   [22mleft double quotation mark
     [1mmo   [22mmonth name
     [1mrq   [22mright double quotation mark
     [1mtd   [22mdate
     [1mwa   [22mterm for “appendix” used by [1m.$c*[0m
     [1mwc   [22mterm for “chapter” used by [1m.$c*[0m
     [1m{    [22mbegin superscripting
     [1m}    [22mend superscripting

[1mFiles[0m
     [4m/usr/share/groff/1.24.1/tmac/e.tmac[0m
            implements the package.

     [4m/usr/share/groff/1.24.1/tmac/refer-me.tmac[0m
            implements ]8;;man:refer(1)\[4mrefer[24m(1)]8;;\ support for [4mme[24m.

     [4m/usr/share/groff/1.24.1/tmac/me.tmac[0m
            is a wrapper enabling the package to be loaded with the  option  “[1m-m[0m
            [1mme[22m”.

[1mNotes[0m
     Some  early  [4mroff[24m  macro  packages  limited their names to a single letter,
     which followed the formatter’s [1mm [22moption, resulting  in  “names”  like  [4m-mm[24m,
     [4m-ms[24m, [4m-mv[24m, and [4m-mn[24m.  [4mme[24m’s “e” stands for “Eric P. Allman”, the author of the
     original macro package and the technical papers documenting it.

[1mSee also[0m
     Two  manuals  are  available  in source and rendered form.  On your system,
     they may be compressed and/or available in additional formats.

     [4m/usr/share/doc/groff-1.24.1/meintro.me[0m
     [4m/usr/share/doc/groff-1.24.1/meintro.ps[0m
            is “Writing Papers with [4mGroff[24m Using -[4mme[24m”, by Eric P. Allman, adapted
            for [4mgroff[24m by James Clark.

     [4m/usr/share/doc/groff-1.24.1/meref.me[0m
     [4m/usr/share/doc/groff-1.24.1/meref.ps[0m
            is the “[4mme[24m Reference Manual”, by Eric P. Allman, adapted  for  [4mgroff[0m
            by James Clark and G. Branden Robinson.

     [4mGroff:[24m  [4mThe[24m [4mGNU[24m [4mImplementation[24m [4mof[24m [4mtroff[24m, by Trent A. Fisher and Werner Lem‐
     berg, is the primary [4mgroff[24m manual.  You can browse  it  interactively  with
     “info groff”.

     For  preprocessors  supported  by [4mme[24m, see ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\, ]8;;man:grn(1)\[4mgrn[24m(1)]8;;\, ]8;;man:pic(1)\[4mpic[24m(1)]8;;\, ]8;;man:refer(1)\[4mrefer[24m(1)]8;;\,
     and ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\.

     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\, ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\

groff 1.24.1                       2026‐03‐20                        [4mgroff_me[24m(7)
────────────────────────────────────────────────────────────────────────────────
[4mgroff_mm[24m(7)             Miscellaneous Information Manual             [4mgroff_mm[24m(7)

[1mName[0m
     groff_mm - memorandum macros for GNU [4mroff[0m

[1mSynopsis[0m
     [1mgroff -mm [22m[[4moption[24m ...] [[4mfile[24m ...]
     [1mgroff -m mm [22m[[4moption[24m ...] [[4mfile[24m ...]

[1mDescription[0m
     The [4mmm[24m macro package distributed with the [4mgroff[24m document formatting  system
     is suitable for the composition of letters, memoranda, reports, and books.

     Call  an [4mmm[24m macro at the beginning of a document to initialize the package.
     A simple [4mmm[24m document might use only [1mP [22mfor paragraphing.  Set  numbered  and
     unnumbered  section headings with [1mH [22mand [1mHU[22m, respectively.  Change the style
     of the typeface with [1mB[22m, [1mI[22m, and [1mR[22m; you can alternate styles  within  a  word
     with [1mBI[22m, [1mBR[22m, [1mIB[22m, [1mIR[22m, [1mRB[22m, and [1mRI[22m.  Several nestable list types are available
     via  [1mAL[22m, [1mBL[22m, [1mBVL[22m, [1mDL[22m, [1mML[22m, [1mRL[22m, and [1mVL[22m; each of these begins a list, to which
     [1mLI [22madds an item and [1mLE [22mends the (nested) list.  [1mLB [22mbegins a list with  cus‐
     tomizable layout parameters.  [1mDS [22mand [1mDF [22mstart static and floating displays,
     respectively; [1mDE [22mterminates either.

     [4mgroff[24m  [4mmm[24m  is intended to be compatible with the [4mmm[24m implementation found in
     the AT&T Documenter’s Workbench 3.3 (“DWB”), with the following limitations
     and changes.

     •  Omitted features include the logo and company name strings, [1m}Z  [22mand  [1m]S[22m,
        respectively;  the encoded company site location addresses recognized as
        the third argument to the [1mAU [22mmacro; the [1mPv [22m(“private” heading) register;
        and the [1mOK [22m(other keywords) and [1mPM [22m(proprietary markings) macros.

     •  [4mgroff[24m [4mmm[24m implements the [1mCS [22m(output cover page or “sheet”) macro only for
        memorandum type 4.

     •  The [4mgrap[24m preprocessor is not explicitly supported; [4mgroff[24m [4mmm[24m  defines  no
        [1mG1 [22mor [1mG2 [22mmacros.

     •  Registers [1mA[22m, [1mC[22m, [1mT[22m, and [1mU[22m, set from the [4mtroff[24m or [4mnroff[24m command lines with
        DWB, are not recognized.

     •  When setting the registers [1mL [22mor [1mW [22mfrom the command line, use an explicit
        scaling unit to avoid surprises.

     •  The  [1mLe [22mregister defaults to [1m1[22m, consistently with [1mLf[22m, [1mLt[22m, and [1mLx [22min DWB;
        equations captioned with [1mEC [22mappear in tables of contents produced by [1mTC[22m.

     •  The [1mLi [22mregister configures the text indentation of [1mRL  [22mlist  items;  DWB
        used a hard‐coded value of 6 ens.

     •  [4mgroff[24m  [4mmm[24m  uses the same adjustment and font style defaults in [4mnroff[24m and
        [4mtroff[24m modes.

     •  Cut marks are not supported.

     DWB supported only seven heading levels.  As a compatible extension,  [4mgroff[0m
     [4mmm[24m supports fourteen, introducing new registers [1mH8 [22mthrough [1mH14[22m, and affect‐
     ing the interpretation of the [1mHF [22mand [1mHP [22mstrings.

     [4mgroff[24m  [4mmm[24m  features a citation (or “bookmark”) system, permitting the docu‐
     ment to make (customizable) internal references like “See chapter  5,  page
     128.”.   Forward  references  require  two‐pass  formatting.  See the [1mINITR[0m
     macro description below and ]8;;man:mmroff(1)\[4mmmroff[24m(1)]8;;\.

     Macro, register, and string descriptions in this  page  frequently  mention
     each  other;  most references are to macros.  Where a register or string is
     referenced, its type is explicitly identified.  [4mmm[24m’s macro names  are  usu‐
     ally in full capitals; registers and strings tend to have mixed‐case names.

     Except where noted, [4mmm[24m assumes that horizontal measurements are reckoned in
     ens  (scaling unit [1mn[22m) and vertical ones in vees (scaling unit [1mv[22m).  [4mgroff[24m [4mmm[0m
     permits use of non‐integral [4mtypographical[24m [4mpoints[24m (scaling unit [1mz[22m).  Use ex‐
     plicit scaling units for clarity and predictable behavior.

   [1mDocument styles[0m
     [4mgroff[24m [4mmm[24m offers three frameworks for document  organization.   [1mCOVER[22m/[1mCOVEND[0m
     is  a  flexible  means  of  preparing  any document requiring a cover page.
     [1mLT[22m/[1mLO [22maids preparation of typical Anglophone correspondence (business  let‐
     ters, for example).  The [1mMT [22mmemorandum type mechanism implements a group of
     formal  styles  historically used by AT&T Bell Laboratories.  Your document
     can select at most one of these approaches; when used,  each  disables  the
     others.

   [1mLocalization[0m
     [4mgroff[24m [4mmm[24m is designed to be easily localized.  For languages other than Eng‐
     lish,  strings  that  can  appear in output are collected in the file [4m/usr/[0m
     [4mshare/groff/1.24.1/tmac/[24mxx[4m.tmac[24m, where [4mxx[24m is an ISO 639 two‐letter language
     identifier.  Localization packages should be loaded after [4mmm[24m; for  example,
     you might format a Swedish [4mmm[24m document with the command “[1mgroff -mm -msv[22m”.

     This package can also be localized by site or territory; for example, [4m/usr/[0m
     [4mshare/groff/1.24.1/tmac/mse.tmac[24m  illustrates  how to adapt the output to a
     national standard using its ISO 3166 territory code.  Such  a  package  can
     define  a  string that causes a macro file [4m/usr/share/groff/1.24.1/tmac/mm/[0m
     territory[4m_locale[24m to be loaded at package initialization.  If this mechanism
     is not used, [4m/usr/share/groff/1.24.1/tmac/mm/locale[24m is loaded instead.   No
     diagnostic is produced if these files do not exist.

   [1mRegisters and strings[0m
     Much  [4mmm[24m  behavior  can be configured by registers and strings.  The [1mnr [22mre‐
     quest assigns a value to a register.

            [1m.nr [4m[22mident[24m [[1m±[22m][4mn[24m [[4mi[24m]

     [4mident[24m is the name of the register, and [4mn[24m is the value to be assigned.  Pre‐
     fixing [4mn[24m with a plus or minus sign increments or decrements  (respectively)
     its  existing value.  If assignment of a (possibly) negative [4mn[24m is required,
     further prefix it with a zero or enclose it in parentheses.  If [4mi[24m is speci‐
     fied, the register’s value automatically changes by [4mi[24m prior  to  interpola‐
     tion if a plus or minus sign is included in the escape sequence as follows.

            [1m\n[22m[[1m±[22m][1m[[4m[22mident[24m[1m][0m

     [4mi[24m  can be negative; it combines algebraically with the sign in the interpo‐
     lation escape sequence.  The brackets around [4mident[24m are literal.

     Many of the registers [4mmm[24m provides are as Boolean‐valued, meaning that  they
     are  considered  “true”  (on, enabled) when they have a positive value, and
     “false” (off, disabled) otherwise.

     Define strings with the [1mds [22mrequest.

            [1m.ds [4m[22mident[24m [4mcontents[0m

     [4mcontents[24m consumes everything up to the end of the line, including  trailing
     spaces.   It  is  a good practice to end [4mcontents[24m with a comment escape se‐
     quence ([1m\"[22m) so that extraneous spaces do not intrude during document  main‐
     tenance.   To  include  leading spaces in [4mcontents[24m, prefix it with a double
     quote.  Interpolate strings with the [1m\* [22mescape sequence.

            [1m\*[[4m[22mident[24m[1m][0m

     Register and string name spaces are distinct, but strings and macros  share
     a  name  space.  Defining a string with the same name as an [4mmm[24m macro is not
     supported and may cause incorrect rendering,  the  emission  of  diagnostic
     messages, and an error exit status from [4mtroff[24m.

   [1mRegister format[0m
     A  register  is  interpolated  using Arabic numerals if no other format has
     been assigned to it.  Assign a format to a register with the [1maf [22mrequest.

            [1m.af [4m[22mR[24m [4mc[0m

     [4mR[24m is the name of the register, and [4mc[24m is the format.  If [4mc[24m is a sequence  of
     Arabic numerals, their quantity defines a zero‐padded minimum width for the
     interpolated register value.

            [1mForm   Sequence[0m
            1      0, 1, 2, 3, ..., 10, ...
            001    000, 001, 002, 003, ..., 1000, ...
            i      0, i, ii, iii, iv, ...
            I      0, I, II, III, IV, ...
            a      0, a, b, c, ..., z, aa, ab, ...
            A      0, A, B, C, ..., Z, AA, AB, ...

   [1mFonts[0m
     [4mmm[24m  assumes  that  the  font styles [1mR [22m(roman), [1mI [22m(italic), and [1mB [22m(bold) are
     mounted at font positions [1m1[22m, [1m2[22m, and [1m3[22m, respectively.  Use the [1mfp [22mrequest to
     mount substitute fonts at these positions as  desired.   The  default  font
     family  is  “[1mT[22m” (Times).  To select a different one, invoke [4mgroff[24m’s [1mfam [22mre‐
     quest or use its [1m-f [22mcommand‐line option.

[1mMacros[0m
     Double‐quote macro arguments that contain space characters.  An  explicitly
     empty  argument  may  be specified with an empty pair of double quotes; for
     example, the following macro call has three arguments.

            .XX "foo bar" "" baz

     Some macros are documented as causing a page break; this does not occur  if
     such a macro is called when the drawing position is already at the top of a
     page (after a page heading, if any).

     [4mHook[24m macros are undefined by default; [4mmm[24m calls them to enable customization
     of its behavior.  (DWB termed these “exits”.)

     Macro  names  longer than two characters are extensions; some shorter names
     were not part of DWB’s published interface but are  documented  aspects  of
     [4mgroff[24m [4mmm.[0m

     [1m1C [22m[[1m1[22m]  Format  page  text in one column (the default layout).  The page is
             broken.  A [1m1 [22margument suppresses this break; its use may cause body
             text and a pending footnote to overprint.  See [1m2C[22m, [1mMC[22m, and [1mNCOL[22m.

     [1m2C      [22mBegin two‐column formatting.  This is a special case of [1mMC[22m.  See [1m1C[0m
             and [1mNCOL[22m.

     [1mAE      [22mAbstract end; stop collecting abstract text.  See [1mAS[22m.

     [1mAF [22m[[4morg‐name[24m]
             Specify a memorandum’s organizational affiliation.  At most one can
             be declared; [4morg‐name[24m is used by  [1mMT  [22mmemoranda  and  available  to
             cover pages.  See [1mCOVER[22m.

     [1mAFX     [22mDefine  this hook macro to assume responsibility for formatting the
             affiliated firm name defined by [1mAF [22min memorandum types 0 and 4  and
             documents  using  the [4mms[24m cover page style.  If not defined (the de‐
             fault), internally defined macros handle this task; see  subsection
             “Internals”  and  section “Files” below.  Applications include set‐
             ting the firm name in a different font family or at a  larger  type
             size,  drawing  a  rule across the page, and including a logo image
             using  [4mgroff[24m’s  [1mPDFPIC  [22mor  [1mPSPIC  [22mmacros.   See  [1mMT[22m,  [1mCOVER[22m,   and
             ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\.

     [1mAL [22m[[4mnumber‐format[24m [[4mtext‐indent[24m [[1m1[22m]]]
             Begin  an auto‐incrementing numbered list, where item numbers start
             at one and are followed by a dot.  [4mnumber‐format[24m assigns the regis‐
             ter format (see above) [4mmm[24m uses for the list item enumerators.   The
             default  is  [1m0[22m.   A  [4mtext‐indent[24m argument overrides register [1mLi[22m.  A
             third argument suppresses the vertical space that normally precedes
             each list item; see register [1mLsp[22m.  Vertical space in the amount  of
             [1mLsp [22mprecedes the list itself, but does not accumulate with pre‐item
             space  when this list is nested in another.  [1mAL [22mcalls [1mLB[22m; use [1mLI [22mto
             declare list items, and [1mLE [22mto end the list.

     [1mAPP [22m[[4msequence‐number[24m [[4mtitle[24m]]
             Begin an appendix.  If [4msequence‐number[24m is  omitted,  it  increments
             (or  is  initialized to [1m1[22m, if necessary).  The register format used
             for [4msequence‐number[24m is “A”.  The page is broken.  The register  [1mAph[0m
             determines  whether  an  appendix  heading is then formatted.  This
             heading uses the string [1mApp [22mfollowed  by  [4msequence‐number[24m.   Appen‐
             dices  appear in any table of contents (see [1mTC[22m).  The string [1mApptxt[0m
             is set to [4mtitle[24m if the latter is present, and made empty otherwise.

     [1mAPPSK [4m[22msequence‐number[24m [4mn[24m [[4mtitle[24m]
             As [1mAPP[22m, but increment the page number by  [4mn[24m.   Use  this  macro  to
             “skip  pages”  when  diagrams  or  other materials not formatted by
             [4mtroff[24m are included in appendices.

     [1mAS [22m[[4mplacement[24m [[4mindentation[24m]]
             Abstract start; begin collecting abstract.  Input up to the next [1mAE[0m
             call is included in the abstract.  [4mplacement[24m influences  the  loca‐
             tion  of  the  abstract on the cover page of a memorandum (see [1mMT[22m).
             [1mCOVER[22m, by contrast, ignores [4mplacement[24m by default, but can  be  cus‐
             tomized to interpret it.

             [4m[1mplacement[24m   Effect[0m
             0           The  abstract  appears  on page 1 and cover page if the
                         document is a “released paper”  memorandum  (“[1m.MT  4[22m”);
                         otherwise, it appears on page 1 without a cover page.
             1           The  abstract  appears  only on the cover page (“[1m.MT 4[22m”
                         only).

             An abstract does not appear at all in external letters  (“[1m.MT  5[22m”).
             A [4mplacement[24m of [1m2 [22mwas supported by DWB, but is not by [4mgroff[24m [4mmm[24m.

             A  second argument increases the indentation by [4mindentation[24m and re‐
             duces the line length by twice this amount.  The default is [1m0[22m.

     [1mAT [4m[22mtitle[24m ...
             Specify author’s title(s).  If present, [1mAT [22mmust appear  just  after
             the  corresponding author’s [1mAU[22m.  Each [4mtitle[24m occupies an output line
             beneath the author’s name in the signature block used by [1mLT [22mletters
             (see [1mSG[22m) and in [1mMT [22mmemoranda.  The [4mms[24m cover page style also formats
             these data.

     [1mAU [22m[[4mname[24m [[4minitials[24m [[4mloc[24m [[4mdept[24m [[4mext[24m [[4mroom[24m [[4marg1[24m [[4marg2[24m [[4marg3[24m]]]]]]]]]
             Specify author.  [1mAU [22mterminates a document title  started  with  [1mTL[22m,
             and  can  be called without arguments for that purpose.  Author in‐
             formation is used by cover pages, [1mMT [22mmemoranda,  and  [1mSG[22m.   Further
             arguments comprise initials, location, department, telephone exten‐
             sion,  room  number or name, and up to three additional items.  Re‐
             peat [1mAU [22mto identify multiple authors.

             Use [1mWA[22m/[1mWE [22minstead to identify the author  for  documents  employing
             [1mLT[22m.

     [1mAV [22m[[4mname[24m [[1m1[22m]]
             Format  approval  lines  for a handwritten signature and date.  Two
             horizontal rules are drawn, with the specified [4mname[24m and the text of
             the string [1mLetdate[22m, respectively, beneath them.  Above these rules,
             [4mmm[24m formats the text in the string [1mLetapp[22m;  a  second  argument  re‐
             places this text with one vee of vertical space.  See [1mLT[22m.

     [1mAVL [22m[[4mname[24m]
             As  [1mAV[22m, but omitting the approval notation (the [1mLetapp [22mstring), the
             date rule, and the label below the date rule (the [1mLetdate [22mstring).

     [1mB [22m[[4mbold‐text[24m [[4mprevious‐font‐text[24m]] ...
             Join [4mbold‐text[24m in boldface with [4mprevious‐font‐text[24m in the  previous
             font, without space between the arguments.  If no arguments, switch
             font to bold style.

     [1mB1      [22mBegin  boxed  static  display.  The text is indented by [1m1n[22m, and the
             line length reduced by [1m2n[22m.  See [1mDS[22m.  This is a [4mgroff[24m [4mmm[24m extension.

     [1mB2      [22mEnd boxed static display.  See [1mB1[22m.  This is a [4mgroff[24m [4mmm[24m extension.

     [1mBE      [22mEnd bottom block; see [1mBS[22m.

     [1mBI [22m[[4mbold‐text[24m [[4mitalic‐text[24m]] ...
             Join [4mbold‐text[24m in boldface with  [4mitalic‐text[24m  in  italics,  without
             space between the arguments.

     [1mBL [22m[[4mtext‐indent[24m [[1m1[22m]]
             Begin  bulleted  list.   [4mmm[24m  marks each item with the string [1mBU[22m.  A
             [4mtext‐indent[24m argument overrides register [1mPi[22m.  A second argument sup‐
             presses the vertical space that normally precedes each  list  item;
             see register [1mLsp[22m.  Vertical space in the amount of [1mLsp [22mprecedes the
             list  itself, but does not accumulate with pre‐item space when this
             list is nested in another.  [1mBL [22mcalls [1mLB[22m; use  [1mLI  [22mto  declare  list
             items, and [1mLE [22mto end the list.

     [1mBR [22m[[4mbold‐text[24m [[4mroman‐text[24m]] ...
             Join  [4mbold‐text[24m in boldface with [4mroman‐text[24m in roman style, without
             space between the arguments.

     [1mBS      [22mBegin bottom block.  [4mmm[24m collects input into the bottom block  until
             the document calls [1mBE[22m, and outputs it between the footnote area and
             footer of each page.

     [1mBVL [22m[[4mtext‐indent[24m [[4mmark‐indent[24m [[1m1[22m]]]
             Begin  broken  variable‐item  (or “tagged”) list.  Each item should
             supply its own mark.  The line is always  broken  after  the  mark;
             contrast  [1mVL[22m.   A [4mtext‐indent[24m argument overrides register [1mPi[22m; [4mmark‐[0m
             [4mindent[24m sets the distance from the indentation of the  current  list
             to  the  mark.  A third argument suppresses the vertical space that
             normally precedes each list item; see register [1mLsp[22m.  Vertical space
             in the amount of [1mLsp [22mprecedes the list itself, but does not accumu‐
             late with pre‐item space when this list is nested in another.   [1mBVL[0m
             calls [1mLB[22m; use [1mLI [22mto declare list items, and [1mLE [22mto end the list.

     [1mCOVER [22m[[4mstyle[24m]
             Begin  a cover page description.  [1mCOVER [22mmust appear before the body
             text (or main matter) of a document.  The argument [4mstyle[24m is used to
             construct the file  name  [4m/usr/share/groff/1.24.1/tmac/mm/[24mstyle[4m.cov[0m
             and  load  it with the [1mmso [22mrequest.  The default [4mstyle[24m is “[1mms[22m”; the
             [4mms.cov[24m file prepares a cover page resembling that of the  [4mms[24m  pack‐
             age.  A [4m.cov[24m file must define a [1mCOVEND [22mmacro, which a document must
             call  at  the  end of the cover description.  Use cover description
             macros in the following order; only [1mTL [22mand [1mAU [22mare required.

             .COVER
             .AF
             .TL
             .AU
             .AT
             .\" Add additional AU and AT calls as needed.
             .AS
             .AE
             .COVEND

     [1mCOVEND  [22mEnd the cover description.

     [1mDE      [22mEnd static or floating display begun with [1mDS [22mor [1mDF[22m.

     [1mDF [22m[[4mformat[24m [[4mfill[24m [[4mright‐indentation[24m]]]
             Begin floating display.  A floating display is saved in a queue and
             output in the order entered.   Arguments  are  handled  as  in  [1mDS[22m.
             Floating displays cannot be nested.  Placement of floating displays
             is controlled by the registers [1mDe [22mand [1mDf[22m.

     [1mDL [22m[[4mtext‐indent[24m [[1m1[22m]]
             Begin dashed list.  [4mmm[24m marks each item with the string [1mEM[22m.  A [4mtext‐[0m
             [4mindent[24m  argument  overrides  register  [1mPi[22m.   A second argument sup‐
             presses the vertical space that normally precedes each  list  item;
             see register [1mLsp[22m.  Vertical space in the amount of [1mLsp [22mprecedes the
             list  itself, but does not accumulate with pre‐item space when this
             list is nested in another.  [1mDL [22mcalls [1mLB[22m; use  [1mLI  [22mto  declare  list
             items, and [1mLE [22mto end the list.

     [1mDS [22m[[4mformat[24m [[4mfill[24m [[4mright‐indentation[24m]]]
             Begin  static  display.  [4mmm[24m collects input into a display until the
             document calls [1mDE[22m.  The display is output on a single  page  unless
             it  is  taller than the height of the page.  [1mDS [22mcan be nested (con‐
             trast with [1mDF[22m).

             [4m[1mformat[24m   Effect[0m
             [4mnone[24m     Do not indent the display.
             L        Do not indent the display.
             I        Indent text by [1m\n[Si][22m.
             C        Center each line.
             CB       Center the whole display as a block.
             R        Right‐align each line.
             RB       Right‐align the whole display as a block.

             The values “L”, “I”, “C”, and “CB” can also be  specified  as  “0”,
             “1”, “2”, and “3”, respectively, for compatibility with DWB.

             [4m[1mfill[24m   Effect[0m
             [4mnone[24m   Disable filling.
             N      Disable filling.
             F      Enable filling.

             “N” and “F” can also be specified as “0” and “1”, respectively, for
             compatibility with DWB.

             A third argument reduces the line length by [4mright‐indentation.[0m

             [4mmm[24m  normally  places  vertical  space before and after the display.
             Set register [1mDs [22mto “0” to suppress it.

     [1mEC [22m[[4mtitle[24m [[4moverride[24m [[4mflag[24m [[4mref‐name[24m]]]]
             Caption an equation.  A caption comprises the string [1mCapec [22mfollowed
             by an automatically incrementing counter stored in the register [1mEc[22m,
             punctuation configured by the register [1mOf[22m,  then  [4mtitle[24m  (if  any).
             Use  the  [1maf [22mrequest to configure [1mEc[22m’s number format.  [4moverride[24m and
             [4mflag[24m alter the equation number as follows.  Omitting [4mflag[24m and spec‐
             ifying [1m0 [22min its place are equivalent.

             [4m[1mflag[24m   Effect[0m
             0      Prefix number with [4moverride[24m.
             1      Suffix number with [4moverride[24m.
             2      Replace number with [4moverride[24m.

             [4mmm[24m centers equation captions irrespective of the alignment  of  any
             enclosing display.

             Specifying [4mref‐name[24m stores the equation number as if by “[1m.SETR [4m[22mref‐[0m
             [4mname[24m  [1m\n[Ec][22m”.   Recognition  of this argument is a [4mgroff[24m [4mmm[24m exten‐
             sion.

             The package lists captioned equations in a table of  contents  (see
             [1mTC[22m)  if  the  Boolean  register [1mLe [22mis true.  The string [1mLe [22mcaptions
             this list.

     [1mEF [22m[[1m"'[4m[22mleft[24m[1m'[4m[22mcenter[24m[1m'[4m[22mright[24m[1m'"[22m]
             Define the even‐page footer, which is formatted just above the nor‐
             mal page footer on even‐numbered pages.  See [1mPF[22m.   [1mEF  [22mdefines  the
             string [1mEOPef[22m.

     [1mEH [22m[[1m"'[4m[22mleft[24m[1m'[4m[22mcenter[24m[1m'[4m[22mright[24m[1m'"[22m]
             Define the even‐page header, which is formatted just below the nor‐
             mal  page  header  on even‐numbered pages.  See [1mPH[22m.  [1mEH [22mdefines the
             string [1mTPeh[22m.

     [1mEN      [22mEnd mathematical expression input preprocessed by ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\; see [1mEQ[22m.

     [1mEOP     [4m[22mgroff[24m [4mmm[24m calls this hook macro in lieu of normal page  footer  lay‐
             out.  The package uses a separate environment to format headers and
             footers.  See [1mTP[22m.

             [1mStrings available to EOP[0m
             ─────────────────────────
             [1mEOPf     [22margument to [1mPF[0m
             [1mEOPef    [22margument to [1mEF[0m
             [1mEOPof    [22margument to [1mOF[0m

     [1mEPIC [22m[[1m-L[22m] [4mwidth[24m [4mheight[24m [[4mname[24m]
             Draw  a box with the given [4mwidth[24m and [4mheight[24m.  The text [4mname[24m (or de‐
             fault text) is formatted inside the box; no attempt is made to size
             the box to fit the text.  An application of this macro is to  indi‐
             cate  the  placement  of an image to be determined later, or exter‐
             nally composited in postprocessing.  [1m-L [22mas the first argument left‐
             aligns the box; the default is to center it.  See [1mPIC[22m.

     [1mEQ [22m[[4mlabel[24m]
             Start mathematical expression input preprocessed by ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\.  [1mEQ [22mand
             [1mEN [22mmacro calls bracket an equation region.  Such  regions  must  be
             contained  in displays ([1mDS[22m/[1mDE[22m), except when the region is used only
             to configure [4meqn[24m and not to produce output.  If present, [4mlabel[24m  ap‐
             pears  aligned to the right and centered vertically within the dis‐
             play; see register [1mEq[22m.  If multiple [4meqn[24m regions occur within a dis‐
             play, only the last [4mlabel[24m (if any) is used.

     [1mEX [22m[[4mtitle[24m [[4moverride[24m [[4mflag[24m [[4mref‐name[24m]]]]
             Caption an exhibit.  Arguments are handled analogously to [1mEC[22m.   The
             register  [1mEx [22mis the exhibit counter.  The string [1mCapex [22mprecedes the
             exhibit number and any [4mtitle.[24m  [4mmm[24m centers  exhibit  captions  irre‐
             spective of the alignment of any enclosing display.

             The  package  lists  captioned exhibits in a table of contents (see
             [1mTC[22m) if the Boolean register [1mLx [22mis true.   The  string  [1mLx  [22mcaptions
             this list.

     [1mFC [22m[[4mclosing‐text[24m]
             Output the string [1mLetfc[22m, or the specified [4mclosing‐text,[24m as the for‐
             mal closing of a letter or memorandum.  See [1mLT [22mand [1mMT[22m.

     [1mFD [22m[[4marg[24m [[1m1[22m]]
             Configure display of footnotes.  The first argument encodes enable‐
             ment of automatic hyphenation, adjustment to both margins, indenta‐
             tion  of  footnote text, and left‐ vs. right‐alignment of the foot‐
             note label within the space allocated for it.

             [4m[1marg[24m   Hyphenate?   Adjust?   Indent?   Label alignment[0m
             0     no           yes       yes       left
             1     yes          yes       yes       left
             2     no           no        yes       left
             3     yes          no        yes       left
             4     no           yes       no        left
             5     yes          yes       no        left
             6     no           no        no        left
             7     yes          no        no        left
             8     no           yes       yes       right
             9     yes          yes       yes       right
             10    no           no        yes       right
             11    yes          no        yes       right

             An [4marg[24m greater than 11 is treated as [1m0[22m.  [4mmm[24m’s default is [1m0[22m.

             A second argument resets  footnote  numbering  when  a  first‐level
             heading is encountered.  See [1mFS[22m.

     [1mFE      [22mEnd footnote; see [1mFS[22m.

     [1mFG [22m[[4mtitle[24m [[4moverride[24m [[4mflag[24m [[4mref‐name[24m]]]]
             Caption  a  figure.   Arguments are handled analogously to [1mEC[22m.  The
             register [1mFg [22mis the figure counter.  The string [1mCapfg  [22mprecedes  the
             figure  number and any [4mtitle.[24m  [4mmm[24m centers figure captions irrespec‐
             tive of the alignment of any enclosing display.

             The package lists captioned figures in a table of contents (see [1mTC[22m)
             if the Boolean register [1mLf [22mis true.  The string  [1mLf  [22mcaptions  this
             list.

     [1mFS [22m[[4mmark[24m]
             Start  footnote.  [4mmm[24m collects input into a footnote until the docu‐
             ment calls [1mFE[22m, outputting it when  the  vertical  drawing  position
             nears  the page bottom.  By default, [4mmm[24m automatically numbers foot‐
             notes starting at 1; the number is available in register [1mFtnum [22mand,
             with a trailing period, in string [1mF[22m.  If desired, interpolate  this
             string  in  the body text to format the footnote mark.  [4mmm[24m interpo‐
             lates string [1mF [22mprior to the footnote text.   Footnotes  are  verti‐
             cally  separated  by the product of registers [1mFs [22mand [1mLsp[22m.  In [4mgroff[0m
             [4mmm[24m, footnotes may be used in displays.

             A [4mmark[24m argument, which need not be numeric,  replaces  the  default
             footnote  mark, leaving the string [1mF [22munchanged.  In that event, you
             must explicitly write any footnote mark to appear in  the  footnote
             itself.

     [1mGETHN [4m[22mref‐name[24m [[4mstring[24m]
             Interpolate  [4mref‐name[24m’s  heading  mark, or, if [4mstring[24m is specified,
             store it there.  In neither case does [1mGETHN [22msuffix  the  interpola‐
             tion with space.  See [1mINITR[22m.

     [1mGETPN [4m[22mref‐name[24m [[4mstring[24m]
             Interpolate  [4mref‐name[24m’s  page  number,  or, if [4mstring[24m is specified,
             store it there.  In neither case does [1mGETPN [22msuffix  the  interpola‐
             tion with space.  See [1mINITR[22m.

     [1mGETR [4m[22mref‐name[0m
             Retrieve location data for reference [4mref‐name[24m, call [1mGETHN [22mand [1mGETPN[0m
             to  populate  strings  [1mQrfh [22mand [1mQrfn[22m, respectively, and interpolate
             string [1mQrf [22mas an internal reference to it.  See [1mINITR[22m.

     [1mGETST [4m[22mref‐name[24m [[4mstring[24m]
             Interpolate [4mref‐name[24m’s auxiliary reference datum, or, if [4mstring[24m  is
             specified,  store  it there.  In neither case does [1mGETST [22msuffix the
             interpolation with space.  See [1mINITR[22m.

     [1mH [4m[22mlevel[24m [[4mtitle[24m [[4msuffix[24m]]
             Set a numbered section heading at [4mlevel[24m.  [4mmm[24m calls [1mLC [22mto clear  any
             lists,  then  produces numbered [4mheading[24m [4mmarks[24m of the form [4ma[24m.[4mb[24m.[4mc[24m...,
             with up to fourteen levels of nesting.  Each level’s number  incre‐
             ments  automatically  with  each [1mH [22mcall and is reset to zero when a
             more significant [4mlevel[24m is specified.  “[1m1[22m” is the  most  significant
             or coarsest division of the document.  Text after an [1mH [22mcall is for‐
             matted as a paragraph; calling [1mP [22mis unnecessary.

             The optional [4mtitle[24m must be double‐quoted if it contains spaces.  [4mmm[0m
             appends  [4msuffix[24m  to [4mtitle[24m in the body of the document, but omits it
             from any table of contents (see [1mTC[22m).  This facility can be used  to
             annotate  the heading title with a footnote.  [4msuffix[24m should not in‐
             terpolate the [1mF [22mstring; specify a footnote  mark  explicitly.   See
             [1mFS[22m.

             Heading  behavior  is  configurable.  Several registers set [4mthresh‐[0m
             [4molds,[24m where heading levels at or below a threshold value  are  han‐
             dled in one way, and those above it another.  For example, [4mmm[24m popu‐
             lates  a  table of contents (see [1mTC[22m) with the title of a heading if
             its level is within the [1mCl [22mregister threshold.

             [4mHeading[24m [4mlayout.[24m  Register [1mEj [22msets a  threshold  for  page  breaking
             (ejection)  prior to a heading.  If not preceded by a page break, a
             heading level within the threshold in register [1mHps [22mis  preceded  by
             the amount of vertical space in register [1mHps1[22m, and by the amount in
             [1mHps2  [22motherwise.  The [1mHb [22mregister sets a threshold at which a break
             occurs after the heading, and register [1mHs [22msets a  threshold  within
             which  vertical  space  follows  it.  If the heading level is above
             both of these, and the paragraph is not  numbered,  [4mmm[24m  produces  a
             [4mrun‐in[24m  [4mheading[24m;  paragraph  text  follows on the same output line.
             Otherwise, register [1mHi [22mconfigures the  indentation  of  text  after
             headings.   Threshold  register  [1mHc [22mpermits centering; [4mmm[24m centers a
             heading with a level within both of the [1mHb [22mand [1mHc [22mthresholds.

             [4mHeading[24m [4mtypeface[24m [4mand[24m [4msize.[24m  The [1mHF [22mstring configures the fonts used
             for heading marks and titles at each level.  The string [1mHP [22mlikewise
             assigns a type size to each heading  level.   The  hook  macros  [1mHX[0m
             and/or [1mHZ [22mcan control the vertical spacing used by headings.

             [4mHeading[24m  [4mnumber[24m [4mformat.[24m  Registers named [1mH1 [22mthrough [1mH14 [22mstore coun‐
             ters for each heading level.  Their values are printed using Arabic
             numerals by default; see [1mHM[22m.  The heading levels are catenated with
             dots for formatting; to typeset only the deepest, set the [1mHt [22mregis‐
             ter.  Heading numbers are not suffixed with a trailing  dot  except
             when  only the first level is output; to omit a dot in this case as
             well, clear the [1mH1dot [22mregister.

             [4mCustomizing[24m [4mheading[24m [4mbehavior.[24m  [1mH [22mcalls [1mHX[22m, [1mHY[22m, and [1mHZ  [22mhook  macros
             to further customize headings.  These can change the heading’s [4mmark[0m
             (the numbered portion before any heading title), its vertical spac‐
             ing,  and its vertical space requirements (for instance, to require
             a minimum quantity of subsequent output lines on the page, breaking
             the page otherwise).  Define hook macros in expectation of the fol‐
             lowing parameters.  The argument [4mdeclared‐level[24m is the [4mlevel[24m  argu‐
             ment  to [1mH[22m, or [1m0 [22mfor unnumbered headings (see [1mHU[22m).  [4mactual‐level[24m is
             the same as [4mdeclared‐level[24m for numbered headings, and the value  of
             register  [1mHu  [22mfor unnumbered headings.  [4mtitle‐suffix[24m is the catena‐
             tion of the corresponding arguments to [1mH [22mor [1mHU[22m.

             [1mHX [4m[22mdeclared‐level[24m [4mactual‐level[24m [4mtitle‐suffix[0m
                    [4mmm[24m calls [1mHX [22mbefore setting the heading.  Your definition may
                    alter [1m}0[22m, [1m}2[22m, and [1m;3[22m.

                    [1m}0 [22m(string)
                           contains the heading mark  plus  two  spaces  if  [4mde‐[0m
                           [4mclared‐level[24m is non‐zero, and otherwise is empty.

                    [1m;0 [22m(register)
                           encodes  a  position  for the text after the heading.
                           0 means that the heading is to be  run  in,  1  means
                           that a break is to occur before the text, and 2 means
                           that vertical space is to separate heading and text.

                    [1m}2 [22m(string)
                           is  the  suffix  that separates a run‐in heading from
                           the text.  It contains  two  spaces  if  register  [1m;0[0m
                           is 0, and otherwise is empty.

                    [1m;3 [22m(register)
                           contains  the vertical space required for the heading
                           to be typeset.  If that amount is not available,  the
                           page  is broken prior to the heading.  The default is
                           [1m2v[22m.

             [1mHY [4m[22mdeclared‐level[24m [4mactual‐level[24m [4mtitle‐suffix[0m
                    [4mmm[24m calls [1mHY [22mafter determining the heading typeface and size.
                    It could be used to change indentation.

             [1mHZ [4m[22mdeclared‐level[24m [4mactual‐level[24m [4mtitle‐suffix[0m
                    [4mmm[24m calls [1mHZ [22mafter formatting the heading, just before  [1mH  [22mor
                    [1mHU  [22mreturns.   It could be used to change the page header to
                    include a section heading.

     [1mHC [22m[[4mhyphenation‐character[24m]
             Set hyphenation character, selecting the default, “\%”,  if  called
             without argument.

     [1mHM [22m[[4marg1[24m [[4marg2[24m [... [[4marg14[24m]]]]
             Set  the  heading  mark style.  Each argument assigns the specified
             register format (see above) to  the  corresponding  heading  level.
             The default is [1m1 [22mfor all levels.  An explicitly empty argument also
             indicates the default.

     [1mHU [4m[22mtitle[24m [[4msuffix[24m]
             Set an unnumbered section heading with [4mtitle[24m and, as a [4mgroff[24m [4mmm[24m ex‐
             tension,  an optional [4msuffix.[24m  The heading is treated as a numbered
             heading of the level stored in register [1mHu[22m, but no heading mark  is
             output; see [1mH[22m.

     [1mI [22m[[4mitalic‐text[24m [[4mprevious‐font‐text[24m]] ...
             Join [4mitalic‐text[24m in italics with [4mprevious‐font‐text[24m in the previous
             font, without space between the arguments.  If no arguments, switch
             font to italic style.

     [1mIA [22m[[4mrecipient‐name[24m [[4mtitle[24m]]
             Specify  the  inside  address in a letter.  The arguments give each
             recipient a name and title.  [4mmm[24m collects input into the inside  ad‐
             dress  until the document calls [1mIE[22m, then outputs it.  You can spec‐
             ify multiple recipients with empty [1mIA[22m/[1mIE [22mpairs; [4mmm[24m  uses  only  the
             last address.  See [1mLT[22m.

     [1mIB [22m[[4mitalic‐text[24m [[4mbold‐text[24m]] ...
             Join  [4mitalic‐text[24m  in  italics  with [4mbold‐text[24m in boldface, without
             space between the arguments.

     [1mIE      [22mEnd the inside address begun with [1mIA[22m.

     [1mIND [4m[22margument[24m ...
             If the Boolean register [1mRef [22mis true, write an index entry as a spe‐
             cially prepared [4mroff[24m comment to the  standard  error  stream,  with
             each  [4margument[24m  separated  from its predecessor by a tab character.
             The entry’s location information is arranged as configured  by  the
             most recent [1mINITI [22mcall.

     [1mINDP    [22mOutput  the  index  set up by [1mINITI [22mand populated by [1mIND [22mcalls.  By
             default, [1mINDP [22mcalls [1mSK [22mand writes a centered caption  interpolating
             the  string  [1mIndex[22m.   It then disables filling and calls [1m2C[22m; after‐
             ward, it restores filling and calls [1m1C[22m.

             Define macros to customize this behavior.  [1mINDP [22mcalls [1mTXIND  [22mbefore
             the  caption, [1mTYIND [4m[22minstead[24m of writing the caption, and [1mTZIND [22mafter
             formatting the index.

     [1mINITI [4m[22mlocation‐type[24m [4mfile‐name[24m [[4mmacro[24m]
             Initialize [4mgroff[24m [4mmm[24m’s indexing system.  Argument [4mlocation‐type[24m  se‐
             lects  how the location of each index entry is reported.  [4mfile‐name[0m
             populates an internal string used later by [1mINDP[22m.

             [4m[1mlocation‐type[24m   Entry format[0m
             N               page number
             H               heading mark
             B               page number, tab character, heading mark

             If [4mmacro[24m is specified, [4mgroff[24m [4mmm[24m calls it for each index entry  with
             the arguments given to [1mIND[22m.

     [1mINITR [4m[22mfile‐name‐prefix[0m
             Initialize  the internal reference macros.  Internal references are
             written to the standard error stream, which  should  be  redirected
             into a file named file‐name‐prefix[4m.qrf[24m.  ]8;;man:mmroff(1)\[4mmmroff[24m(1)]8;;\ handles this and
             the  two  formatting passes it requires.  The first pass identifies
             internal references; the second includes them.   See  [1mSETR[22m,  [1mGETHN[22m,
             [1mGETPN[22m, and [1mGETST[22m.

     [1mIR [22m[[4mitalic‐text[24m [[4mroman‐text[24m]] ...
             Join [4mitalic‐text[24m in italics with [4mroman‐text[24m in roman style, without
             space between the arguments.

     [1mLB [4m[22mtext‐indent[24m [4mmark‐indent[24m [4mpad[24m [4mtype[24m [[4mmark‐or‐format[24m [[4mpre‐item‐space[24m [[4mpre‐[0m
     [4mlist‐space[24m]]]
             Begin  list.  The macros [1mAL[22m, [1mBL[22m, [1mBVL[22m, [1mDL[22m, [1mML[22m, [1mRL[22m, and [1mVL [22mcall [1mLB [22min
             various ways; they are simpler to use and may be preferred if  they
             suit the desired purpose.

             [4mmm[24m  tracks  the nesting level of lists; the outermost is 0.  It in‐
             dents each list item (text formatted after an [1mLI [22mcall) by  [4mtext‐in‐[0m
             [4mdent.[24m   The  mark is left‐aligned at [4mmark‐indent[24m, and padded on the
             left with [4mpad[24m ens of space.  [4mtype[24m determines the mark’s format.

             [4m[1mtype[24m   Output for a mark “x”[0m
             0      x
             1      x.
             2      x)
             3      (x)
             4      [x]
             5      <x>
             6      {x}

             If [4mtype[24m is [1m0[22m, [4mmark‐or‐format[24m specifies each item’s mark (which  can
             be  overridden  by  an argument to [1mLI[22m).  If [4mmark‐or‐format[24m is empty
             (or the dummy character “[1m\&[22m”) [4mmm[24m sets items at [4mmark‐indent[24m  with  a
             hanging indent at [4mtext‐indent.[0m

             If  [4mtype[24m  is greater than zero, [4mmm[24m supplies an automatically incre‐
             menting numeric mark, and interprets [4mmark‐or‐format[24m as  a  register
             format.

             A  [4mtype[24m of [1m-1 [22mcauses [4mgroff[24m [4mmm[24m to break the line after the mark even
             if it fits within [4mtext‐indent;[24m this is a [4mgroff[24m [4mmm[24m extension.

             The last two arguments manage  vertical  space.   Unless  a  list’s
             nesting  level  is greater than the value of register [1mLs[22m, its items
             are preceded by [4mpre‐item‐space[24m multiplied by the register [1mLsp[22m;  the
             default is [1m1[22m.  [1mLB [22mprecedes the list by [4mpre‐list‐space[24m multiplied by
             the register [1mLsp[22m; the default is [1m0[22m.

     [1mLC [22m[[4mlist‐level[24m]
             Clear  list  state.  Active lists are terminated as if with [1mLE[22m, ei‐
             ther all (the default) or only those from the current level down to
             [4mlist‐level[24m if specified.

     [1mLE [22m[[1m1[22m]  End list.  The current list is terminated.  An argument of [1m1 [22mcauses
             vertical space in the amount of register [1mLsp [22mto follow the list.

     [1mLI [22m[[4mmark[24m [[4mpad‐prefix[24m]]
             Begin a list item.  [4mmm[24m collects input into a list  item  until  the
             document  terminates  the  current  list or calls [1mLI [22magain.  By de‐
             fault, the item’s text is preceded by any mark  configured  by  the
             current  list.   If [4mmark[24m is the only argument, it replaces the mark
             configured in the corresponding [1mLB [22mcall.  If the width of the  mark
             plus any [4mpad[24m specified in the [1mLB [22mcall exceeds the text indentation,
             [4mgroff[24m  [4mmm[24m warns and uses one en of padding between the mark and the
             text.  The presence of a second argument prefixes [4mmark[24m to  the  [1mLB[22m‐
             configured mark and, as a [4mgroff[24m [4mmm[24m extension, conditionally puts an
             unbreakable  space  between  the prefix and mark per the argument’s
             Boolean value.

     [1mLO [4m[22moption[24m [[4mvalue[24m]
             Specify letter options; see [1mLT[22m.  By default, [4mmm[24m recognizes the fol‐
             lowing [4moption[24m values.  See [1mIA  [22mregarding  the  inside  address  and
             string [1mDT [22mregarding the date.

             [4m[1moption[24m   Meaning and Effect[0m
             AT       Attention;  put  contents  of string [1mLetAT [22mand [4mvalue[24m left‐
                      aligned after the inside address.
             CN       Confidential; put [4mvalue,[24m  or  contents  of  string  [1mLetCN[22m,
                      left‐aligned after the date.
             RN       Reference;  put  contents  of string [1mLetRN [22mand [4mvalue[24m after
                      the confidential notation (if any) and the  date,  aligned
                      with the latter.
             SA       Salutation;  put [4mvalue,[24m or contents of string [1mLetSA[22m, left‐
                      aligned after the inside address and the confidential  no‐
                      tation (if any).
             SJ       Subject;  put  contents  of  string  [1mLetSJ [22mand [4mvalue[24m left‐
                      aligned after the inside address  and  the  attention  and
                      salutation notations (if any).  In letter type “SP”, [1mLetSJ[0m
                      is ignored and [4mvalue[24m is set in full capitals.

     [1mLT [22m[[4mstyle[24m]
             Format  a letter in the designated [4mstyle,[24m defaulting to [1mBL [22m(see be‐
             low).  A letter begins with the writer’s address ([1mWA[22m/[1mWE[22m),  followed
             by  the date ([1mND[22m), the inside address ([1mIA[22m/[1mIE[22m), the body of the let‐
             ter ([1mP [22mand other general‐purpose [4mmm[24m  macros),  the  formal  closing
             ([1mFC[22m),  the signature ([1mSG[22m), and notations ([1mNS[22m/[1mNE[22m).  Any of these ex‐
             cept the body text may be omitted.  Letter options  specified  with
             [1mLO  [22madd  further  annotations, which are extensible; see subsection
             “Internals” below.

             [4m[1mstyle[24m   Description[0m
             BL      Blocked: the writer’s address, date,  formal  closing,  and
                     signature  are  indented to the center of the line.  Every‐
                     thing else is left‐aligned.
             SB      Semi‐blocked: as [1mBL[22m, but the first line of  each  paragraph
                     is indented by [1m\n[Pi] [22mens.
             FB      Fully blocked: everything is left‐aligned.
             SP      Simplified: as [1mFB[22m, but a formal closing is omitted, and the
                     signature is set in full capitals.

     [1mMC [4m[22mcolumn‐width[24m [[4mgutter‐width[24m]
             Begin  multi‐column  layout.   [4mgroff[24m  [4mmm[24m creates as many columns of
             [4mcolumn‐width[24m as the line length will permit.  [4mgutter‐width[24m  is  the
             interior  spacing between columns.  It defaults to [4mcolumn‐width[24m/15.
             [1mNCOL [22mmoves to the next column, and [1m1C [22mreturns to single‐column lay‐
             out.  [1mMC [22mis a [4mgroff[24m [4mmm[24m extension, generalizing [1m2C[22m.  See [1mMULB [22mfor an
             alternative.

     [1mML [4m[22mmark[24m [[4mtext‐indent[24m [[1m1[22m]]
             Start a [4mmarked[24m [4mlist;[24m the [4mmark[24m argument precedes each  item.   [4mtext‐[0m
             [4mindent[24m  overrides  the default indentation of the list items, which
             is the width of [4mmark[24m plus one en.  A third argument suppresses  the
             vertical  space that normally precedes each list item; see register
             [1mLsp[22m.  Vertical space in the amount of [1mLsp [22mprecedes the list itself,
             but does not accumulate with  pre‐item  space  when  this  list  is
             nested  in another.  [1mML [22mcalls [1mLB[22m; use [1mLI [22mto declare list items, and
             [1mLE [22mto end the list.

     [1mMT [22m[[4mtype[24m [[4maddressee[24m]]
             Select memorandum type.  These correspond to formats used  by  AT&T
             Bell  Laboratories,  where  the [4mmm[24m package was initially developed,
             affecting the document layout.  Some of these included a cover page
             with a caption categorizing the document.  [4mgroff[24m [4mmm[24m  uses  [4mtype[24m  to
             construct the file name [4m/usr/share/groff/1.24.1/tmac/mm/[24mtype[4m.MT[24m and
             load  it  with  the  [1mmso [22mrequest.  Memorandum types 0 to 5 are sup‐
             ported; any other value of [4mtype[24m is mapped to type 6.  Omitting [4mtype[0m
             implies [1m1[22m.  [4maddressee[24m sets a string analogous to one used  by  AT&T
             cover page macros not implemented in [4mgroff[24m [4mmm[24m.

             [4m[1mtype[24m     Description[0m
             0        normal memorandum; no caption
             1        captioned “TECHNICAL MEMORANDUM”
             2        captioned “INTERNAL MEMORANDUM”
             3        captioned “ADMINISTRATIVE MEMORANDUM”
             4        released paper
             5        external letter
             [4mstring[24m   captioned [4mstring[0m

             See [1mCOVER [22mfor a more flexible cover page mechanism.

     [1mMOVE [4m[22my‐pos[24m [[4mx‐pos[24m [[4mline‐length[24m]]
             Move  to  a position, setting page offset to [4mx‐pos[24m.  If [4mline‐length[0m
             is not given, the difference between current and new page offset is
             used.  Use [1mPGFORM [22mwithout arguments to return to normal.

     [1mMULB [4m[22mcw1[24m [4msp1[24m [[4mcw2[24m [4msp2[24m] ... [4mcwn[0m
             Begin alternative multi‐column mode.  All column widths [4mcw[24mi must be
             specified, as must the amount of  space  [4msp[24mi  between  each  column
             pair.   [1mMULB  [22muses  a diversion and operates in a separate environ‐
             ment.

     [1mMULE    [22mEnd alternative multi‐column mode and emit the columns.

     [1mMULN    [22mStart next column in alternative column mode.

     [1mNCOL    [22mStart next column (only when using [1m2C [22mor [1mMC[22m).  Contrast with [1mMULN[22m.

     [1mND [22m[[4marg[24m]
             Set the document’s date.  [4mmm[24m does not interpret [4marg[24m; it  can  be  a
             revision identifier (or empty).  [4mmm[24m calls [1mND [22mitself when initializ‐
             ing.

     [1mNE      [22mEnd notation begun with [1mNS[22m; filling is enabled.

     [1mnP [22m[[4mtype[24m]
             As  [1mP[22m,  but set a paragraph number in the form [4mx[24m.[4myy[24m, where [4mx[24m is the
             number of the second heading level, and [4myy[24m increments with each  [1mnP[0m
             call;  its  value is not reset when the second‐level heading number
             changes.  [4mmm[24m uses a register format of “00” for [4myy.[0m

     [1mNS [22m[[4mcode[24m [[1m1[22m]]
             Declare notations, typically for letters or memoranda, of the  type
             specified  by  [4mcode[24m.  The text corresponding to [4mcode[24m is output, and
             filling is disabled until the document calls [1mNE[22m.  Typically, a list
             of names or attachments lies within [1mNS[22m/[1mNE[22m.  If [4mcode[24m  is  absent  or
             does  not match one of the values listed under the [1mLetns [22mstring de‐
             scription below, each line  of  notations  is  formatted  as  “Copy
             ([4mline[24m) to”.  If a second argument, conventionally [1m1[22m, is given, [4mcode[0m
             becomes  the entire notation and [1mNE [22mis not necessary.  In [4mgroff[24m [4mmm[24m,
             you can set up further notations to be recognized by  [1mNS[22m;  see  the
             strings [1mLetns [22mand [1mLetnsdef [22mbelow.

     [1mOF [22m[[1m"'[4m[22mleft[24m[1m'[4m[22mcenter[24m[1m'[4m[22mright[24m[1m'"[22m]
             Define  the odd‐page footer, which is formatted just above the nor‐
             mal page footer on odd‐numbered pages.  See  [1mPF[22m.   [1mOF  [22mdefines  the
             string [1mEOPof[22m.

     [1mOH [22m[[1m"'[4m[22mleft[24m[1m'[4m[22mcenter[24m[1m'[4m[22mright[24m[1m'"[22m]
             Define  the odd‐page header, which is formatted just below the nor‐
             mal page header on odd‐numbered pages.  See  [1mPH[22m.   [1mOH  [22mdefines  the
             string [1mTPoh[22m.

     [1mOP      [22mEnsure  that subsequent text is formatted at the top of an odd‐num‐
             bered page; no page break is performed if the drawing  position  is
             already there.

     [1mP [22m[[4mtype[24m]
             Begin new paragraph.  If [4mtype[24m is missing or [1m0[22m, [1mP [22msets the paragraph
             fully  left-aligned.   A  [4mtype[24m of [1m1 [22mindents the first line by [1m\[Pi][0m
             ens.  Set the register [1mPt [22mto select a default paragraph indentation
             style.  The register [1mPs [22mdetermines the amount of vertical space be‐
             tween paragraphs.

             To set a paragraph with a hanging indent, use [1mVL [22mwith  the  desired
             indentation as the argument, [1mLI [22m(with no argument), and [1mLE[22m.

     [1mPE      [22mEnd picture input preprocessed by ]8;;man:pic(1)\[4mpic[24m(1)]8;;\; see [1mPS[22m.

     [1mPF [22m[[1m"'[4m[22mleft[24m[1m'[4m[22mcenter[24m[1m'[4m[22mright[24m[1m'"[22m]
             Define  the  page footer.  The footer is formatted at the bottom of
             each page; the argument is otherwise as described in  [1mPH[22m.   [1mPF  [22mde‐
             fines the string [1mEOPf[22m.  See [1mEF[22m, [1mOF[22m, and [1mEOP[22m.

     [1mPGFORM [22m[[4mline‐length[24m [[4mpage‐length[24m [[4mpage‐offset[24m [[1m1[22m]]]]
             Set  line  length, page length, and/or page offset.  This macro can
             be used for letterheads and similar.   It  is  normally  the  first
             macro  call  in  a file, though it is not necessary.  [1mPGFORM [22mcan be
             used without arguments to reset everything after a  [1mMOVE  [22mcall.   A
             line  break  is done unless the fourth argument is given.  This can
             be used to avoid the page number on the first  page  while  setting
             new width and length.  (It seems as if this macro sometimes doesn’t
             work  too  well.   Use  the  command‐line  arguments to change line
             length, page length, and page offset instead.)

     [1mPGNH    [22mSuppress header on the next page.  To  suppress  a  header  on  the
             first  page,  call  this  macro prior to formatting any text in the
             document.  Also see register [1mN[22m.

     [1mPH [22m[[1m"'[4m[22mleft[24m[1m'[4m[22mcenter[24m[1m'[4m[22mright[24m[1m'"[22m]
             Define the page header, formatted at the top of each page,  as  the
             argument,  where [4mleft[24m, [4mcenter[24m, and [4mright[24m are aligned to the respec‐
             tive locations on the line.  A “[1m%[22m” character in [4marg[24m is replaced  by
             the page number.  If the argument is absent, no page header is set.
             The default page header is
                    "''- % -''"
             which  centers  the page number between hyphens and formats nothing
             at the upper left and right.  Header macros call  [1mPX  [22m(if  defined)
             after  formatting  the header.  [1mPH [22mdefines the string [1mTPh[22m.  See [1mEH[22m,
             [1mOH[22m, and [1mTP[22m.

     [1mPIC [22m[[1m-B[22m] [[1m-C[22m|[1m-I [4m[22mn[24m|[1m-L[22m|[1m-R[22m] [4mfile[24m [[4mwidth[24m [[4mheight[24m]]
             Include PostScript document [4mfile[24m.  The optional [1m-B [22margument draws a
             box around the picture.  The optional [1m-L[22m, [1m-C[22m, [1m-R[22m, and  [1m-I  [4m[22mn[24m  argu‐
             ments align the picture or indent it by [4mn[24m.  By default, the picture
             is  left‐aligned.   Optional  [4mwidth[24m and [4mheight[24m arguments resize the
             picture.  Use of this macro requires two‐pass processing; see [1mINITR[0m
             and ]8;;man:mmroff(1)\[4mmmroff[24m(1)]8;;\.

     [1mPS      [22mStart picture input preprocessed by ]8;;man:pic(1)\[4mpic[24m(1)]8;;\.

     [1mPY      [22mAs [1mPE[22m, but with “flyback”, returning the drawing position to  where
             it was prior to the picture.  This is a [4mgroff[24m [4mmm[24m extension.

     [1mR [22m[[4mroman‐text[24m [[4mprevious‐font‐text[24m]] ...
             Join  [4mroman‐text[24m in roman style with [4mprevious‐font‐text[24m in the pre‐
             vious font, without space between the arguments.  If no  arguments,
             switch font to roman style.

     [1mRB [22m[[4mroman‐text[24m [[4mbold‐text[24m]] ...
             Join  [4mroman‐text[24m in roman style with [4mbold‐text[24m in boldface, without
             space between the arguments.

     [1mRD [22m[[4mprompt[24m [[4mdiv[24m [[4mstr[24m]]]
             Write [4mprompt[24m (if specified, a tab and colon “:” to the standard er‐
             ror stream and read response from standard input stream, optionally
             into a diversion [4mdiv[24m and/or string [4mstr.[24m  Interpolate the saved text
             by calling its name like a macro.  If [4mstring[24m is present, the  input
             is also stored in a string of that name.

     [1mRF      [22mEnd a bibliographic reference citiation started with [1mRS[22m.  See [1mRP[22m.

     [1mRI [22m[[4mroman‐text[24m [[4mitalic‐text[24m]] ...
             Join [4mroman‐text[24m in roman style with [4mitalic‐text[24m in italics, without
             space between the arguments.

     [1mRL [22m[[4mtext‐indent[24m [[1m1[22m]]
             Begin  an auto‐incrementing numbered list, where item numbers start
             at one and set between square  brackets.   A  [4mtext‐indent[24m  argument
             overrides  register  [1mLi[22m.  A second argument suppresses the vertical
             space that normally precedes each  list  item;  see  register  [1mLsp[22m.
             Vertical  space  in the amount of [1mLsp [22mprecedes the list itself, but
             does not accumulate with pre‐item space when this list is nested in
             another.  [1mRL [22mcalls [1mLB[22m; use [1mLI [22mto declare list items, and [1mLE [22mto  end
             the  list.  “RL” is a mnemonic for “reference list”, but this macro
             has no relationship with [4mmm[24m’s bibliographic reference list  facili‐
             ties.

     [1mRP [22m[[4msuppress‐counter‐reset[24m [[4mpage‐ejection‐policy[24m]]
             Format  a  reference  list,  listing items accumulated within [1mRS[22m/[1mRF[0m
             pairs.  The reference counter is reset unless  the  first  argument
             is  [1m1[22m.  Normally, page breaks occur before and after the references
             are output; the register [1mRpej [22mconfigures this behavior, and a  sec‐
             ond  argument  overrides  its  value.  [1mTC [22mcalls [1mRP [22mautomatically if
             references have accumulated.

             [4mgroff[24m [4mmm[24m calls [1mLB [22mto format the reference list;  the  [1mRpfmt  [22mstring
             configures  the  list’s  appearance.  Setting register [1mLs [22mto [1m0 [22msup‐
             presses spacing after the list.  The string [1mRp [22mcontains the  refer‐
             ence list caption.

     [1mRPX     [22mThis  hook  macro assumes responsibility for formatting the heading
             of the reference page that [1mRP [22mproduces.  If not  defined  (the  de‐
             fault),  [4mmm[24m  sets the reference list caption in the string [1mRp [22mafter
             two vees of space, centered in italics, followed by another vee  of
             space.

     [1mRS [22m[[4mreference‐string[24m]
             Begin citation of an automatically numbered bibliographic reference
             entry.  [4mmm[24m collects input into a reference entry until the document
             calls  [1mRF[22m.   A  subsequent  [1mRP  [22mcall emits the accumulated entries.
             References are numbered starting at 1; the register [1m:R  [22mstores  the
             most recently assigned number.  Interpolate the string [1mRf [22mwhere the
             reference  mark  should  be, then place the entry between [1mRS [22mand [1mRF[0m
             calls on text lines after the reference mark.  The [1mRfstyle [22mregister
             determines whether the mark is bracketed, superscripted,  or  both.
             If [4mreference‐string[24m is specified, [4mmm[24m also stores the reference mark
             in a string of that name.

     [1mS [22m[[4mtype‐size[24m [[4mvertical‐spacing[24m]]
             Set  type size and vertical spacing.  Each argument is a [4mgroff[24m mea‐
             surement, using an appropriate scaling unit and an optional [1m+ [22mor  [1m-[0m
             prefix to increment or decrement the current value.  An argument of
             [1mP  [22mrestores  the previous value, [1mC [22mretains the current value, and [1mD[0m
             requests the default.  [4mmm[24m treats an empty or omitted argument as [1mP[22m.

     [1mSA [22m[[4mmode[24m]
             Set or restore the default enablement of adjustment.  Specify [1m0  [22mor
             [1m1  [22mas [4mmode[24m to set a document’s default explicitly; [4mgroff[24m [4mmm[24m assumes
             [1m1[22m.  Invoke the [1mna [22mrequest as desired to temporarily suspend adjust‐
             ment.  [1mH [22mand [1mHU[22m, and [1mSA [22mwhen called without a  [4mmode[24m  argument,  re‐
             store the default adjustment.

     [1mSETR [4m[22mref‐name[24m [[4mstring[24m]
             Create  reference  [4mref‐name[24m,  storing its heading and page numbers.
             If [4mstring[24m is present, [4mgroff[24m [4mmm[24m saves it as an auxiliary  datum  for
             retrieval by [1mGETST[22m.  See [1mINITR[22m.

     [1mSG [22m[[4marg[24m [[1m1[22m]]
             Output  author  signature  block(s) in [1mLT [22mletters and [1mMT [22mmemoranda.
             The format of a signature block depends on the letter or memorandum
             type.  See subsection “Internals” below.

             [1mLT [22mletters emit a signature for one author at most (see  [1mWA[22m).   The
             author’s  title, if any, is set on the next line, indented to align
             with the name, except in letter type “SP”, where it is set in  full
             capitals (like the name) after a comma and space.

             Memorandum  type  4  uses  no signature block.  In other memoranda,
             each of an author’s titles is set on a subsequent line, indented to
             align with the name.  They furthermore encode a secretarial annota‐
             tion including the location, department, and initials specified  in
             each  author’s [1mAU [22mcall, followed by any [4marg[24m, writing it at the left
             margin preceding the last author’s name, or preceding the first  if
             a second [1mSG [22margument is present.

     [1mSK [22m[[4mn[24m]  Skip  [4mn[24m  pages.  If [4mn[24m is [1m0 [22mor omitted, [4mmm[24m breaks the page if neces‐
             sary.  Otherwise, [4mmm[24m prints [4mn[24m pages, blank except for  any  headers
             and footers.

     [1mSM [4m[22mtext[24m [[4mpost[24m]
     [1mSM [4m[22mpre[24m [4mtext[24m [4mpost[0m
             Format  [4mtext[24m  at a smaller type size, joined with any specified [4mpre[0m
             and [4mpost[24m at normal size, without space between the arguments.

     [1mSP [22m[[4mdistance[24m]
             Space downward by [4mdistance.[24m  Multiple [1mSP [22mcalls in sequence  produce
             only  the largest of the specified [4mdistances.[24m  [1mSP [22maccepts boundary‐
             relative motions specified with a prefixed [1m| [22moperator, but not neg‐
             ative ones.

             [1mSP [22mhas no effect when the drawing position is at  the  top  of  the
             page.   Put  the dummy character escape sequence [1m\& [22m(followed by [1m\c[0m
             if desired to prevent a break) on a text line prior to an  [1mSP  [22mcall
             to overcome this restriction.

     [1mTAB     [22mReset tab stops to every 5 ens.  The [1mta [22mrequest customizes them.

     [1mTB [22m[[4mtitle[24m [[4moverride[24m [[4mflag[24m [[4mref‐name[24m]]]]
             Caption  a  table.   Arguments  are handled analogously to [1mEC[22m.  The
             register [1mTb [22mis the table counter.  The string  [1mCaptb  [22mprecedes  the
             table number and any [4mtitle.[24m  [4mmm[24m centers table captions irrespective
             of the alignment of any enclosing display.

             The  package lists captioned tables in a table of contents (see [1mTC[22m)
             if the Boolean register [1mLt [22mis true.  The string  [1mLt  [22mcaptions  this
             list.

     [1mTC [22m[[4mslevel[24m [[4mspacing[24m [[4mtlevel[24m [[4mtab[24m [[4mh1[24m [[4mh2[24m [[4mh3[24m [[4mh4[24m [[4mh5[24m]]]]]]]]]
             Output  table  of contents.  This macro is normally the last called
             in the document.  It flushes any pending displays and, if any  ref‐
             erences  are pending (see [1mRS[22m), calls [1mRP[22m.  It then begins a new page
             with the contents caption, stored in the string [1mCaptc[22m, centered  at
             the top.  The entries follow after three vees of space.  Each entry
             is  a  saved  section (number and) heading title (see the [1mCl [22mregis‐
             ter), along with its associated page number.  By  default,  [4mmm[24m  in‐
             dents  an entry by an amount corresponding to its heading level and
             the maximum heading length encountered at that  heading  level;  if
             defined,  the  string  [1mCi [22moverrides these indentations.  Entries at
             heading levels up to and including [4mslevel[24m are preceded  by  [4mspacing[0m
             vees  of  space.   Entries  at  heading  levels up to and including
             [4mtlevel[24m are followed by a leader and a  right‐aligned  page  number.
             If  the Boolean‐valued [4mtab[24m argument is true, the leader is replaced
             with horizontal motion in the same amount.  For entries above head‐
             ing level [4mtlevel[24m, the page number follows the heading text after  a
             word  space.   Each  argument  [4mh1[24m...[4mh5[24m  appears in order on its own
             line,  centered,  above  the  contents  caption.   Page   numbering
             restarts at 1, in register format “i”.  If the [1mOc [22mregister is true,
             numbering of these pages is suppressed.

             If  the document calls [1mTC [22mwith at most four arguments, [4mmm[24m calls the
             hook macro [1mTX [22mprior to formatting the contents caption, and [1mTY  [22m(if
             defined) [4minstead[24m of formatting the contents caption.

             [4mmm[24m then presents lists of figures, tables, equations, and exhibits,
             in  that order.  A list appears only if at least one such captioned
             item is present, and if its corresponding register ([1mLe[22m, [1mLf[22m, [1mLt[22m,  or
             [1mLx[22m) is set.  [1mTX[4m[22mxx[24m and [1mTY[4m[22mxx[24m macros, where [4mxx[24m is “FG”, “TB”, “EC”, or
             “EX”,  and  strings [1mCapfg[22m, [1mCaptb[22m, [1mCapec[22m, and [1mCapex [22manalogously con‐
             figure the output of each captioned list.

     [1mTE      [22mEnd ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\ table.  See [1mTS[22m.

     [1mTH      [22mMark the end of a [1mTS[22m/[1mTE [22mtable heading.  When a table spans multiple
             pages, the heading repeats at the top of each page.  [4mgroff[24m [4mmm[24m  does
             not implement the [1mN [22margument supported by DWB.

     [1mTL [22m[[4mcharging‐case‐number[24m [[4mfiling‐case‐number[24m]]
             Begin  document  title.   [4mmm[24m  collects input into the title until a
             subsequent [1mAU [22mcall and formats it as directed by the [1mMT  [22mmemorandum
             type  or cover page macros.  [4mmm[24m saves [4mcharging‐case‐number[24m and [4mfil‐[0m
             [4ming‐case‐number[24m for use in all memorandum types except 4.

     [1mTM [4m[22mnumber[24m ...
             Declare technical memorandum number(s) used with [1mMT [22mmemoranda.

     [1mTP      [4m[22mmm[24m calls this hook macro in lieu of normal page header layout.  The
             package uses a separate environment to format headers and  footers.
             See [1mEOP[22m.

             [1mStrings available to TP[0m
             ────────────────────────
             [1mTPh     [22margument to [1mPH[0m
             [1mTPeh    [22margument to [1mEH[0m
             [1mTPoh    [22margument to [1mOH[0m

     [1mTS [22m[[1mH[22m]  Start ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\ table.  Argument “H” tells [4mmm[24m that the table’s heading
             should repeat after page breaks.  See [1mTE[22m, [1mTH[22m, and ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\.

     [1mVERBON [22m[[4mformat[24m [[4mtype‐size[24m [[4mfont[24m]]]
             Begin display of verbatim content.  [4mformat[24m controls several parame‐
             ters.   Add  up  the  values of desired features; the default is [1m0[22m.
             Further arguments configure the [4mtype‐size[24m in  typographical  points
             (on  typesetting devices), and the face ([4mfont[24m).  On typesetting de‐
             vices, the default face is [1mCR [22m(Courier roman), a  monospaced  font:
             all glyphs are equally wide.

             [1mValue   Effect[0m
             1       Disable the formatter’s escape character (\).
             2       Vertically space before the display.
             4       Vertically space after the display.
             8       Number output lines; call formatter’s [1mnm [22mrequest with argu‐
                     ments in string [1mVerbnm[22m.
             16      Indent by the amount stored in register [1mVerbin[22m.

     [1mVERBOFF[0m
             End verbatim display.

     [1mVL [22m[[4mtext‐indent[24m [[4mmark‐indent[24m [[1m1[22m]]]
             Begin  variable‐item  (or  “tagged”) list.  Each item should supply
             its own mark, or tag.  A [4mtext‐indent[24m  argument  overrides  register
             [1mPi[22m;  [4mmark‐indent[24m sets the distance from the indentation of the cur‐
             rent list to the mark.  A third argument  suppresses  the  vertical
             space  that  normally  precedes  each  list item; see register [1mLsp[22m.
             Vertical space in the amount of [1mLsp [22mprecedes the list  itself,  but
             does not accumulate with pre‐item space when this list is nested in
             another.   [1mRL [22mcalls [1mLB[22m; use [1mLI [22mto declare list items, and [1mLE [22mto end
             the list.

     [1mVM [22m[[1m-T[22m] [[4mtop[24m [[4mbottom[24m]]
             Configure vertical margins.

             Without a [1m-T [22margument, increment the top and bottom margins by  [4mtop[0m
             and  [4mbottom[24m, respectively.  If absent, set the corresponding margin
             to zero.

             With the [1m-T [22margument, set the top and bottom  margins  to  [4mtop[24m  and
             [4mbottom[24m,  respectively.  If absent, set the respective margin to the
             default (top: [1m7v[22m, bottom: [1m6v[22m).

             We recommend defining the hook macros [1mTP [22mand/or [1mEOP [22mif using [1m-T [22mand
             setting top and/or bottom margin to values less than  the  default.
             [4mgroff[24m [4mmm[24m exposes this undocumented DWB macro to enable greater user
             control of page layout.

     [1mWA [22m[[4mwriter’s‐name[24m [[4mtitle[24m]]
             Specify  the writer(s) of an [1mLT [22mletter.  [4mmm[24m collects input into the
             writer’s address until the document calls [1mWE[22m, then outputs it.  You
             can specify multiple writers with empty [1mWA[22m/[1mWE [22mpairs; only the  last
             address is used.  The arguments give each writer a name and title.

     [1mWC [22m[[4mformat[24m ...]
             Control width of footnotes and displays.

             [4m[1mformat[24m   Effect[0m
             [1mN        [22mequivalent to “[1m-WF -FF -WD[22m” (default)
             [1mWF       [22mset footnotes at full line length, even in two‐column mode
             [1m-WF      [22mset footnotes using column line length
             [1mFF       [22mapply width of first footnote to encountered to subsequent
                      ones
             [1m-FF      [22mfootnote width determined by [1mWF [22mand [1m-WF[0m
             [1mWD       [22mset displays at full line length, even in two‐column mode
             [1m-WD      [22mset displays using column line length

     [1mWE      [22mEnd the writer’s address begun with [1mWA[22m.

[1mStrings[0m
     Many [4mmm[24m strings interpolate predefined, localizable text.  We present their
     contents in quotation marks.

     [1mAbstract  [22m“ABSTRACT”

     [1mApp       [22m“APPENDIX”

     [1mApptxt    [22mstores the [4mtitle[24m argument to the most recent [1mAPP [22mcall.

     [1mAumt      [22mlists  space‐separated  indices of positional arguments to the [1mAU[0m
               macro that should be suppressed from appearance in  the  document
               heading  on  the first page of [1mMT [22mmemorandum types 0–3 and 6.  By
               default, it is undefined; all arguments are formatted except  the
               second (author initials).

     [1mBU        [22minterpolates a bullet mark, [1m\[bu][22m.

     [1mCapec     [22m“Equation”

     [1mCapex     [22m“Exhibit”

     [1mCapfg     [22m“Figure”

     [1mCaptb     [22m“Table”

     [1mCaptc     [22m“CONTENTS”

     [1mCi        [22massigns  indentation amounts used by each heading level listed in
               a table of contents,  in  one‐to‐one  correspondence,  overriding
               those computed by [1mTC[22m.  Each word must be a horizontal measurement
               (like “[1m1i[22m”).

     [1mDT        [22mstores  the  date  or  other identifier set by [1mND[22m, if called, and
               otherwise one constructed using the formatter’s  date  registers;
               see ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\.  The [4mgroff[24m locale determines its format, but regis‐
               ter [1mIsodate [22mmay override it.

     [1mEM        [22minterpolates an em dash, [1m\[em][22m.

     [1mF         [22minterpolates  an automatically numbered footnote mark; the number
               is used by the next [1mFS [22mcall without an argument.  In [4mtroff[24m  mode,
               the  mark  is  superscripted;  in [4mnroff[24m mode, it is surrounded by
               square brackets.

     [1mH1txt     [22mstores the text of the current first‐level heading; [1mH [22mand [1mHU  [22mup‐
               date it, as does [1mTC [22mwhen processing table of contents entries and
               captions of displayed figures, tables, equations, and exhibits.

     [1mHF        [22massigns  font identifiers, separated by spaces, to heading levels
               in one‐to‐one correspondence.  Each  identifier  may  be  a  font
               mounting  position, font name, or style name.  Omitted values are
               assumed to be 1.  The default is “[1m2 2 2 2 2 2 2 2 2 2 2 2  2  2[22m”,
               which places all headings in italics.  DWB’s default was “[1m3 3 2 2[0m
               [1m2 2 2[22m”.

     [1mHP        [22massigns  type  sizes,  separated  by spaces, to heading levels in
               one‐to‐one correspondence.  [4mgroff[24m [4mmm[24m interprets each size in  ty‐
               pographical  points, translating zero values to [1m10[22m.  Omitted val‐
               ues are assumed to be 0 (and are  translated  accordingly).   The
               default is “[1m0 0 0 0 0 0 0 0 0 0 0 0 0 0[22m”.

     [1mIndex     [22m“INDEX”

     [1mLe        [22m“LIST OF EQUATIONS”

     [1mLetfc     [22m“Yours very truly,” (see [1mFC[22m)

     [1mLetapp    [22m“APPROVED:” (see [1mAV[22m)

     [1mLetAT     [22m“ATTENTION:” (see [1mLO[22m)

     [1mLetCN     [22m“CONFIDENTIAL” (see [1mLO[22m)

     [1mLetdate   [22m“Date” (see [1mAV[22m)

     [1mLetns     [22mis  a  group of strings structuring the notations produced by [1mNS[22m.
               If the [4mcode[24m argument to [1mNS [22mhas no corresponding string, the nota‐
               tion is included between parentheses, prefixed  with  [1mLetns!copy[22m,
               and  suffixed with [1mLetns!to[22m.  Observe the spaces after “Copy” and
               before “to”.

               [1mNS code   String       Contents[0m
               0         Letns!0      Copy to
               1         Letns!1      Copy (with att.) to
               2         Letns!2      Copy (without att.) to
               3         Letns!3      Att.
               4         Letns!4      Atts.
               5         Letns!5      Enc.
               6         Letns!6      Encs.
               7         Letns!7      Under separate cover
               8         Letns!8      Letter to
               9         Letns!9      Memorandum to
               10        Letns!10     Copy (with atts.) to
               11        Letns!11     Copy (without atts.) to
               12        Letns!12     Abstract Only to
               13        Letns!13     Complete Memorandum to
               14        Letns!14     CC
               ——        Letns!copy   Copy [4m(with[24m [4mtrailing[24m [4mspace)[0m
               ——        Letns!to      to [4m(note[24m [4mleading[24m [4mspace)[0m

     [1mLetnsdef  [22mselects the notation format when [1mNS [22mis given  no  argument.   The
               default is [1m0[22m.

     [1mLetRN     [22m“In reference to:” (see [1mLO[22m)

     [1mLetSA     [22m“To Whom It May Concern:” (see [1mLO[22m)

     [1mLetSJ     [22m“SUBJECT:” (see [1mLO[22m)

     [1mLf        [22m“LIST OF FIGURES”

     [1mLt        [22m“LIST OF TABLES”

     [1mLx        [22m“LIST OF EXHIBITS”

     [1mMO1[0m
     ...
     [1mMO12      [22m“January” through “December”

     [1mQrf       [22m“See  chapter  \E*[Qrfh], page \En[Qrfp].”  If your document uses
               multiple heading levels, you might redefine this  string  to  use
               the word “section” instead of “chapter”.

     [1mQrfh      [22mstores  the  heading  mark  corresponding to the most recent [1mGETR[0m
               call.

     [1mQrfp      [22mstores the page number corresponding  to  the  most  recent  [1mGETR[0m
               call.

     [1mRf        [22minterpolates an automatically numbered reference mark; the number
               is used by the next [1mRS [22mcall.

     [1mRp        [22m“REFERENCES”

     [1mRpfmt     [22mspecifies the [1mLB [22marguments that [4mgroff[24m [4mmm[24m uses to format the items
               in an [1mRP [22mreference list.  The default is “[1m\\n[Li] 0 1 0 \& 0[22m”.

     [1mRg        [22minterpolates the registered (trade) mark sign.

     [1mSm        [22minterpolates the service mark sign.

     [1mTcstatus  [22minterpolates  an  indicator  of the [1mTC [22mmacro’s processing status.
               If [1mTC [22mis not operating, it is  empty.   User‐defined  [1mTP  [22mor  [1mEOP[0m
               macros might condition page headers or footers on its contents.

               [1mValue   Meaning[0m
               co      Table of contents
               fg      List of figures
               tb      List of tables
               ec      List of equations
               ex      List of exhibits
               ap      Appendix

     [1mTm        [22minterpolates ™, the trade mark sign.

     [1mVerbnm    [22msupplies  argument(s)  to  the  [1mnm [22mrequest employed by the [1mVERBON[0m
               macro.  The default is [1m1[22m.

[1mRegisters[0m
     Default register values, where meaningful, are shown in parentheses.

     [1m.mgm     [22mindicates that [4mgroff[24m [4mmm[24m is in use (Boolean‐valued; [1m1[22m).

     [1mAph      [22mformats an appendix heading (and  title,  if  supplied);  see  [1mAPP[0m
              (Boolean‐valued; [1m1[22m).

     [1mAu       [22mincludes supplemental author information (the third and subsequent
              arguments  to  [1mAU[22m) in memorandum “from” information; see [1mCOVER [22mand
              [1mMT[22m, and the [1mAumt [22mstring (Boolean‐valued; [1m1[22m).

     [1mCl       [22msets the threshold for inclusion of headings in a  table  of  con‐
              tents.   Headings  at  levels above this value are excluded; see [1mH[0m
              and [1mTC[22m.  The [1mCl [22mregister controls whether a heading is  [4msaved[24m  for
              output  in the table of contents at the time [1mH [22mor [1mHU [22mis called; if
              you change [1mCl[22m’s value immediately prior to calling [1mTC[22m, you are un‐
              likely to get the result you want ([1m2[22m).

     [1mCp       [22msuppresses page breaks before lists of  captioned  equations,  ex‐
              hibits,  figures, and tables, and before an index; see [1mEC[22m, [1mEX[22m, [1mFG[22m,
              [1mTB[22m, and [1mINDP [22m(Boolean‐valued; [1m0[22m).

     [1mD        [22mproduces debugging information for the [4mmm[24m package on the  standard
              error  stream.  A value of 0 outputs nothing; 1 reports formatting
              progress.  Higher values communicate internal state information of
              increasing verbosity ([1m0[22m).

     [1mDe       [22mcauses a page break after a floating display  is  output;  see  [1mDF[0m
              (Boolean‐valued; [1m0[22m).

     [1mDf       [22mconfigures  the  behavior  of [1mDF[22m.  The following values are recog‐
              nized; 4 and 5 do not override the [1mDe [22mregister ([1m5[22m).

              [1mValue   Effect[0m
              0       Flush pending displays at the end  of  each  section  when
                      section‐page  numbering is active, otherwise at the end of
                      the document.
              1       Flush a pending display on the current page or  column  if
                      there  is  enough space, otherwise at the end of the docu‐
                      ment.
              2       Flush one pending display at the top of each page or  col‐
                      umn.
              3       Flush  a  pending display on the current page or column if
                      there is enough space, otherwise at the top of the next.
              4       Flush as many pending displays as possible in a  new  page
                      or column.
              5       Fill columns or pages with flushed displays until none re‐
                      main.

     [1mDs       [22mputs  vertical space in the amount of register [1mDsp [22m(if defined) or
              [1mLsp [22mbefore and after each static display; see [1mDS  [22m(Boolean‐valued;
              [1m1[22m).

     [1mDsp      [22mconfigures  the  amount  of vertical space placed before and after
              static displays; see [1mDS [22mand register [1mDs [22m([4mundefined[24m).

     [1mEc       [22mis an auto‐incrementing equation counter; see [1mEC[22m.

     [1mE        [22mdetermines the font style used by [1mMT [22mmemoranda,  [1mLT  [22mletters,  and
              the [4mms.cov[24m cover page style to set the date and certain other doc‐
              ument data; [1m0 [22mselects roman, and [1m1 [22mbold (Boolean‐valued; [1m1[22m).

     [1mEj       [22msets  the threshold for page breaks (ejection) prior to the format
              of headings.  Headings at levels above this value are set  on  the
              same page and column as any preceding text if possible; see [1mH [22m([1m0[22m).

     [1mEq       [22maligns  an  equation label to the left of a display instead of the
              right (Boolean‐valued; [1m0[22m).

     [1mEx       [22mis an auto‐incrementing exhibit counter; see [1mEX[22m.

     [1mFg       [22mis an auto‐incrementing figure counter; see [1mFG[22m.

     [1mFs       [22mis multiplied by register [1mLsp [22mto  vertically  separate  footnotes;
              see [1mFS [22m([1m1[22m).

     [1mFtnum    [22mis an auto‐incrementing footnote counter; see [1mFS[22m.  [4mgroff[24m [4mmm[24m recog‐
              nizes [1m:p [22mas an alias of [1mFtnum [22mfor DWB compatibility.

     [1mH1[0m
     ...
     [1mH14      [22mare  auto‐incrementing  counters  corresponding  to  each  heading
              level; see [1mH[22m.

     [1mH1dot    [22mappends a period to the number of  a  level  one  heading;  see  [1mH[0m
              (Boolean‐valued; [1m1[22m).

     [1mH1h      [22mis a copy of register [1mH1[22m, but it is incremented just before a page
              break.  This can be useful in hook macros; see [1mH [22mand [1mHX[22m.

     [1mHb       [22msets  the threshold for breaking the line after formatting a head‐
              ing.  Text after headings at levels above this value is set on the
              same output line if possible.  Paragraphs numbered via [1mnP  [22mor  the
              [1mNp [22mregister cause a break regardless; see [1mH [22m([1m2[22m).

     [1mHc       [22msets  the  threshold  for centering a heading.  Headings at levels
              above this value use the prevailing alignment (that is,  they  are
              not centered); see [1mH [22m([1m0[22m).

     [1mHi       [22mselects  an  indentation policy for text formatted after headings.
              It does not affect “run‐in” headings.  The  following  values  are
              recognized; see [1mH [22mand [1mP [22m([1m1[22m).

              [1mValue   Effect[0m
              0       no indentation
              1       indent per the paragraph type
              2       indent to align with heading title

     [1mHps      [22msets the heading level threshold for application of preceding ver‐
              tical  space; see [1mH[22m.  Headings at levels above the value in regis‐
              ter [1mHps [22muse the amount of space in register [1mHps1[22m;  otherwise  that
              in [1mHps2[22m.  The value of [1mHps [22mshould be strictly greater than that of
              [1mEj [22m([1m1[22m).

     [1mHps1     [22mconfigures  the amount of vertical space preceding a heading above
              the [1mHps [22mthreshold; see [1mH [22m([4mtroff[24m devices: [1m0.5v[22m; [4mnroff[24m devices: [1m1v[22m).

     [1mHps2     [22mconfigures the amount of vertical space preceding a heading within
              the [1mHps [22mthreshold; see [1mH [22m([4mtroff[24m devices: [1m1v[22m; [4mnroff[24m devices: [1m2v[22m).

     [1mHs       [22msets the heading level threshold  for  application  of  succeeding
              vertical  space.   If  the  heading  level is greater than [1mHs[22m, the
              heading is followed by vertical space  in  the  amount  of  regis‐
              ter [1mHss[22m; see [1mH [22m([1m2[22m).

     [1mHss      [22mis  multiplied  by  register  [1mLsp  [22mto produce vertical space after
              headings above the threshold in register [1mHs[22m; see [1mH [22m([1m1[22m).

     [1mHt       [22msuppresses output of heading level counters above the deepest when
              a heading mark is formatted; see [1mH [22m(Boolean‐valued; [1m0[22m).

     [1mHu       [22msets the heading level used by unnumbered headings; see [1mHU [22m([1m2[22m).

     [1mHy       [22menables automatic hyphenation of words (Boolean‐valued; [1m0[22m).

     [1mIsodate  [22mconfigures the use of ISO 8601 date format;  that  is,  [4mYYYY[24m‐[4mMM[24m‐[4mDD[0m
              instead of the format specified by the localization file.  Call [1mND[0m
              without arguments after updating its value (Boolean‐valued; [1m0[22m).

     [1mL        [22mdefines the page length for the document, and must be set from the
              command  line.  A scaling unit should be appended.  The default is
              that of the selected [4mgroff[24m output device.

     [1mLe[0m
     [1mLf[0m
     [1mLt[0m
     [1mLx       [22mconfigure the report of lists of equation, figure, table, and  ex‐
              hibit  captions,  respectively,  after a table of contents; see [1mTC[0m
              (all: Boolean‐valued; [1m1[22m).

     [1mLetwam   [22msets the maximum number of input lines permitted in a writer’s ad‐
              dress; see [1mWA [22mand [1mWE [22m([1m14[22m).

     [1mLi       [22mconfigures the text indentation (in  ens)  applied  to  enumerated
              list  types; that is, to items in [1mAL [22mand [1mRL [22mlists, and in [1mLB [22mlists
              whose [4mtype[24m argument is greater than zero ([1m5[22m).

     [1mLs       [22msets a threshold for  placement  of  vertical  space  before  list
              items.   If  the list nesting level is greater than this value, no
              such spacing occurs; see [1mLI [22m([1m\n[.R][22m).

     [1mLsp      [22mconfigures the base amount of vertical space used  for  separation
              in  the document.  [4mmm[24m applies this spacing to many contexts, some‐
              times with multipliers; see [1mDS[22m, [1mFS[22m, [1mH[22m, [1mLI[22m, and [1mP  [22m([4mtroff[24m  devices:
              [1m0.5v[22m; [4mnroff[24m devices: [1m1v[22m).

     [1mN        [22mconfigures  the  header and footer placements used by [1mPH[22m.  The de‐
              fault footer is empty.  If “section‐page” numbering  is  selected,
              the  default  header  becomes empty and the default footer becomes
              “[4mx[24m‐[4my[24m”, where [4mx[24m is is the section number (the number of the current
              first‐level heading) and [4my[24m the page  number  within  the  section.
              The  following  values  are recognized; for finer control, see [1mPH[22m,
              [1mPF[22m, [1mEH[22m, [1mEF[22m, [1mOH[22m, and [1mOF[22m, and registers [1mSectf [22mand [1mSectp[22m.  Value 5 is
              a [4mgroff[24m [4mmm[24m extension ([1m0[22m).

              [1mValue   Effect[0m
              0       Set header on all pages.
              1       Move header to footer on page 1.
              2       Omit header on page 1.
              3       Use “section‐page” numbering style on all pages.
              4       Omit header on all pages.
              5       Use “section‐page” and “section‐figure” numbering style on
                      all pages.

     [1mNp       [22mnumbers paragraphs with a leading mark in the  format  [4ms[24m.[4mp[24m,  where
              [4ms[24m  is is first‐level heading number and [4mp[24m is the paragraph number,
              starting at 1; see [1mH [22mand [1mP [22m(Boolean‐valued; [1m0[22m).

     [1mO        [22mdefines the page offset of the document, and must be set from  the
              command  line.   A  scaling  unit should be appended.  The default
              is [1m.75i [22mon terminal devices.  On typesetters, it is [1m.963i  [22mor  set
              to [1m1i [22mby the [4mpapersize.tmac[24m package; see ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\.

     [1mOc       [22msuppresses  the  appearance  of  page numbers in the table of con‐
              tents; see [1mTC [22m(Boolean‐valued; [1m0[22m).

     [1mOf       [22mselects a separator format within equation, exhibit,  figure,  and
              table  captions;  see  [1mEC[22m, [1mEX[22m, [1mFG[22m, and [1mTB[22m.  The punctuation in the
              separator is either a dot or the [1mEM [22mstring.  The following  values
              are recognized; the spaces shown are unpaddable ([1m0[22m).

              [1mValue   Effect[0m
              0       ".  "
              1       " —— "

     [1mP        [22minterpolates the current page number; it is the same as register [1m%[0m
              except when “section‐page” numbering is enabled.

     [1mPi       [22mconfigures  the  indentation (in ens) applied to the first line of
              an unnumbered paragraph that has such (see [1mP[22m); and the text inden‐
              tation of non‐enumerated list items; that is, to items in [1mBL[22m, [1mBVL[22m,
              [1mDL[22m, and [1mVL [22mlists (but not [1mML[22m), and in [1mLB [22mlists whose [4mtype[24m argument
              is zero or less ([1m5[22m).

     [1mPgps     [22mcauses the type size and vertical spacing set by  [1mS  [22mto  apply  to
              headers  and  footers,  overriding  the  [1mHP [22mstring.  If not set, [1mS[0m
              calls affect headers and footers only when followed by [1mPH[22m, [1mPF[22m, [1mOH[22m,
              [1mEH[22m, [1mOF[22m, or [1mEF [22mcalls (Boolean‐valued; [1m1[22m).

     [1mPs       [22mis multiplied by register [1mLsp [22mto vertically  separate  paragraphs;
              see [1mP [22m([1m1[22m).

     [1mPt       [22mdetermines  when  a  first‐line  indentation is applied to a para‐
              graph; see [1mP [22m([1m0[22m).

              [1mValue   Effect[0m
              0       never
              1       always
              2       always, except immediately after [1mH[22m, [1mHU[22m, [1mDE[22m, or [1mLE[0m

     [1mRef      [22mis used internally to control ]8;;man:mmroff(1)\[4mmmroff[24m(1)]8;;\’s two‐pass approach to in‐
              dex and reference management; see [1mIND[22m, [1mINDP[22m, [1mINITI[22m, [1mINITR[22m, and [1mPIC[0m
              (Boolean‐valued; [1m0[22m).

     [1mRfnum    [22mis an auto‐incrementing reference counter; see [1mRS[22m.  [4mgroff[24m [4mmm[24m  rec‐
              ognizes [1m:R [22mas an alias of [1mRfnum [22mfor DWB compatibility.

     [1mRfstyle  [22mdetermines  the  format  of the reference number in the [1mRf [22mstring.
              [4mgroff[24m [4mmm[24m maps [1m0 [22mto [1m1 [22min [4mnroff[24m mode and [1m2 [22min [4mtroff[24m mode ([1m0[22m).

              [1mValue   Meaning[0m
              0       automatic
              1       bracketed
              2       superscripted
              3       bracketed and superscripted

              Changes to [1mRfstyle[22m’s value may not  take  effect  until  the  next
              heading or paragraphing macro call.

     [1mRpej     [22mconfigures  the  default page ejection policy for reference pages;
              see [1mRP [22m([1m0[22m).

              [1mValue   Effect[0m
              0       Break the page before and after the reference list.
              1       Suppress page break after the list.
              2       Suppress page break before the list.
              3       Suppress page breaks before and after the list.

     [1mS        [22mdefines the type size for the document, and must be set  from  the
              command  line.   A  scaling  unit should be appended; [1mp [22mis typical
              ([1m10p[22m).

     [1mSectf    [22mselects the “section‐figure” numbering style.  Its  default  is  [1m0[0m
              unless  register  [1mN  [22mis set to [1m5 [22mat the command line (Boolean‐val‐
              ued).

     [1mSectp    [22mselects the “section‐page” numbering style.  Its default is [1m0  [22mun‐
              less register [1mN [22mis set to [1m3 [22mor [1m5 [22mat the command line (Boolean‐val‐
              ued).

     [1mSi       [22mconfigures the amount of display indentation in ens; see [1mDS [22m([1m5[22m).

     [1mTb       [22mis an auto‐incrementing table counter; see [1mTB[22m.

     [1mV        [22mdefines  the  vertical  spacing  for the document, and must be set
              from the command line.  A scaling unit should be  appended;  [1mp  [22mis
              typical.   The  default vertical spacing is 120% of the type size.
              This register is a [4mgroff[24m [4mmm[24m extension.

     [1mVerbin   [22mconfigures the amount of indentation for  verbatim  displays  when
              indentation is selected; see [1mVERBON [22m([1m5n[22m).

     [1mW        [22mdefines  the  “width”  of  the document (that is, the length of an
              output line with no indentation); it must be set from the  command
              line.   A  scaling  unit should be appended.  The default is [1m6i [22mor
              assigned by the [4mpapersize.tmac[24m package; see ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\.

   [1mInternals[0m
     The argument (if any) to a [1mCOVER [22mor [1mMT [22mcall determines the file that  [4mgroff[0m
     [4mmm[24m loads to configure the document’s layout; see section “Files” below.

     [1mLT[22m’s  behavior  depends  on the [4mstyle[24m argument given to it; it calls macros
     with names suffixed accordingly.  It is therefore possible to define  addi‐
     tional letter types, either in the territory‐specific macro file, or as lo‐
     cal  additions.   [1mLT [22msets the registers [1mPt [22mand [1mPi [22mto 0 and 5, respectively.
     (DWB used a value of 3 for [1mPi[22m.)  It then calls an initialization macro cor‐
     responding to the type.  Define the following macros to support a new  let‐
     ter type.

     [1mlet@init_[4m[22mtype[0m
            initializes any registers and other data needed by the letter type.

     [1mlet@head_[4m[22mtype[0m
            formats  the  letterhead;  it  is  called  instead of the usual page
            header macro.  Its definition should remove the alias [1mlet@header [22mun‐
            less the letterhead is desired on subsequent pages.

     [1mlet@sg_[4m[22mtype[24m [4mname[24m [4mtitle[24m [4mn[24m [4mis‐final[24m [[4mSG‐arg[24m ...]
            is called by [1mSG [22monly for [1mLT [22mletters; [1mMT  [22mmemoranda  implement  their
            own  signature  processing.   [4mname[24m  and  [4mtitle[24m are specified through
            [1mWA[22m/[1mWE[22m.  [4mn[24m is the index of the [4mn[24mth writer, and [4mis‐final[24m is  true  for
            the  last writer to be listed.  Further [1mSG [22marguments are appended to
            the signature line.

     [1mlet@fc_[4m[22mtype[24m [4mclosing[0m
            is called by [1mFC[22m, and takes the formal closing as its argument.

     [1mLO [22mimplements letter options.  It requires that a string named  [1mLet[4m[22mtype[24m  be
     defined,  where  [4mtype[24m is the letter type.  [1mLO [22mthen assigns its second argu‐
     ment ([4mvalue[24m) to the string [1mlet*lo-[4m[22mtype[24m.

[1mFiles[0m
     [4m/usr/share/groff/1.24.1/tmac/m.tmac[0m
            is the [4mgroff[24m implementation of the memorandum macros.

     [4m/usr/share/groff/1.24.1/tmac/mm.tmac[0m
            is a wrapper enabling the package to be loaded with the  option  “[1m-m[0m
            [1mmm[22m”.

     [4m/usr/share/groff/1.24.1/tmac/refer-mm.tmac[0m
            implements ]8;;man:refer(1)\[4mrefer[24m(1)]8;;\ support for [4mmm[24m.

     [4m/usr/share/groff/1.24.1/tmac/mm/ms.cov[0m
            implements an [4mms[24m‐like cover page.

     [4m/usr/share/groff/1.24.1/tmac/mm/0.MT[0m
            implements memorandum types 0–3 and 6.

     [4m/usr/share/groff/1.24.1/tmac/mm/4.MT[0m
            implements memorandum type 4.

     [4m/usr/share/groff/1.24.1/tmac/mm/5.MT[0m
            implements memorandum type 5.

     [4m/usr/share/groff/1.24.1/tmac/mm/locale[0m
            performs any (further) desired localization if present.

     [4m/usr/share/doc/groff-1.24.1/examples/letter.mm[0m
            illustrates features of the [1mLT [22mletter formats.

     [4m/usr/share/doc/groff-1.24.1/examples/memorandum.mm[0m
            illustrates features of the [1mMT [22mmemorandum formats.

     [4m/usr/share/doc/groff-1.24.1/examples/story.mm[0m
            illustrates use of [4mmm[24m for literary purposes.

[1mAuthors[0m
     ]8;;mailto:jh@axis.se\Jörgen Hägg]8;;\ of Lund, Sweden, wrote the version of the [4mmm[24m macro package dis‐
     tributed  with  [4mgroff[24m based on an early version of [4mgroff[24m [4mms[24m by ]8;;mailto:jjc@jclark.com\James Clark]8;;\.
     ]8;;mailto:wl@gnu.org\Werner Lemberg]8;;\ and ]8;;mailto:g.branden.robinson@gmail.com\G. Branden Robinson]8;;\ revised and updated it.

[1mSee also[0m
     ]8;;https://tkurtbond.github.io/troff/mm-all.pdf\[4mMM[24m [4m-[24m [4mA[24m [4mMacro[24m [4mPackage[24m [4mfor[24m [4mGenerating[24m [4mDocuments[24m]8;;\, the DWB 3.3 [4mmm[24m  manual,  in‐
     troduces the package but does not document [4mgroff[24m [4mmm[24m extensions.

     [4mGroff:[24m  [4mThe[24m [4mGNU[24m [4mImplementation[24m [4mof[24m [4mtroff[24m, by Trent A. Fisher and Werner Lem‐
     berg, is the primary [4mgroff[24m manual.  You can browse  it  interactively  with
     “info groff”.

     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\, ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\, ]8;;man:pic(1)\[4mpic[24m(1)]8;;\, ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\, ]8;;man:refer(1)\[4mrefer[24m(1)]8;;\, ]8;;man:groff_mmse(7)\[4mgroff_mmse[24m(7)]8;;\

groff 1.24.1                       2026‐03‐20                        [4mgroff_mm[24m(7)
────────────────────────────────────────────────────────────────────────────────
[4mgroff_mmse[24m(7)            Handbok för diverse information           [4mgroff_mmse[24m(7)

[1mNamn[0m
     groff_mmse - svenska ”memorandum” makro för GNU [4mroff[0m

[1mSyntax[0m
     [1mgroff -mmse [22m[[4mflaggor[24m ...] [[4mfiler[24m ...]
     [1mgroff -m mmse [22m[[4mflaggor[24m ...] [[4mfiler[24m ...]

[1mBeskrivning[0m
     [4mmmse[24m  är  en svensk variant av [4mmm[24m. Alla texter är översatta. En A4 sida får
     text som är 13 cm bred, 3,5 cm indragning samt är 28,5 cm  hög.  Det  finns
     stöd  för  brevuppställning enligt svensk standard för vänster och högerju‐
     sterad text.

     [1mCOVER [22mkan använda [4mse_ms[24m som argument. Detta ger ett  svenskt  försättsblad.
     Se ]8;;man:groff_mm(7)\[4mgroff_mm[24m(7)]8;;\ för övriga detaljer.

[1mBrev[0m
     Tillgängliga brevtyper:

     [1m.LT SVV[0m
            Vänsterställd löptext med adressat i position T0 (vänsterställt).

     [1m.LT SVH[0m
            Högerställd  löptext  med  adressat i position T4 (passar fönsterku‐
            vert).

     Följande extra LO‐variabler används.

     [1m.LO DNAMN [4m[22mnamn[0m
            Anger dokumentets namn.

     [1m.LO MDAT [4m[22mdatum[0m
            Mottagarens datum, anges under [1mErt datum: [22m([1mLetMDAT[22m).

     [1m.LO BIL [4m[22msträng[0m
            Anger bilaga, nummer eller sträng med [1mBilaga [22m([1mLetBIL[22m) som prefix.

     [1m.LO KOMP [4m[22mtext[0m
            Anger kompletteringsuppgift.

     [1m.LO DBET [4m[22mbeteckning[0m
            Anger dokumentbeteckning eller dokumentnummer.

     [1m.LO BET [4m[22mbeteckning[0m
            Anger beteckning (ärendebeteckning i form av diarienummer eller lik‐
            nande).

     [1m.LO SIDOR [4m[22mantal[0m
            Anger totala antalet sidor och skrivs ut efter sidnumret inom paren‐
            teser.

     Om makrot [1m.TP [22mär definierat anropas det efter utskrift av brevhuvudet.  Där
     lägger man lämpligen in postadress och annat som brevfot.

[1mSkrivet av[0m
     ]8;;mailto:Jorgen.Hagg@axis.se\Jörgen Hägg]8;;\, Lund, Sweden

[1mFiler[0m
     [4m/usr/share/groff/1.24.1/tmac/mse.tmac[0m

     [4m/usr/share/groff/1.24.1/tmac/mm/se_[24m*[4m.cov[0m

[1mSe också[0m
     ]8;;man:groff_mm(7)\[4mgroff_mm[24m(7)]8;;\

groff 1.24.1                       2026‐03‐20                      [4mgroff_mmse[24m(7)
────────────────────────────────────────────────────────────────────────────────
[4mgroff_mom[24m(7)            Miscellaneous Information Manual            [4mgroff_mom[24m(7)

[1mName[0m
     groff_mom - modern macros for document composition with GNU [4mroff[0m

[1mSynopsis[0m
     [1mgroff -mom [22m[[4moption[24m ...] [[4mfile[24m ...]
     [1mgroff -m mom [22m[[4moption[24m ...] [[4mfile[24m ...]

[1mDescription[0m
     [4mmom[24m  is  a macro set for [4mgroff[24m, designed primarily to prepare documents for
     PDF and PostScript output.  [4mmom[24m provides macros in two categories: typeset‐
     ting and document processing.  The former provide access to  [4mgroff[24m’s  type‐
     setting  capabilities  in  ways that are simpler to master than [4mgroff[24m’s re‐
     quests and escape sequences.  The latter provide highly customizable markup
     tags that allow the user to design and  output  professional‐looking  docu‐
     ments with a minimum of typesetting intervention.

     Files  processed  with  ]8;;man:pdfmom(1)\[4mpdfmom[24m(1)]8;;\ produce PDF documents.  The documents in‐
     clude a PDF outline that appears in the navigation pane panel  of  document
     viewers, and may contain clickable internal and external links.

     Normally,  [4mgroff[24m’s  native  PDF  driver, ]8;;man:gropdf(1)\[4mgropdf[24m(1)]8;;\, is used to generate the
     output.  When [4mpdfmom[24m is given the “[1m-T ps[22m” option, it  still  produces  PDF,
     but  processing is delegated to [4mpdfroff[24m, which uses [4mgroff[24m’s PostScript dri‐
     ver, ]8;;man:grops(1)\[4mgrops[24m(1)]8;;\.  Not all PDF features are available when [1m-T ps [22mis given; its
     primary use is to allow processing of files with  embedded  PostScript  im‐
     ages.

     Files processed with [1mgroff -mom [22m(or [1m-m mom[22m) format for the device specified
     with  the  [1m-T  [22moption.  (In this installation, [1mps [22mis the default output de‐
     vice.)

     [4mmom[24m comes with her own comprehensive documentation in HTML.  A PDF  manual,
     “Producing PDFs with [4mgroff[24m and [4mmom[24m”, discusses preparation of PDF documents
     with [4mmom[24m in detail.

[1mFiles[0m
     [4m/usr/share/groff/1.24.1/tmac/mom.tmac[0m
            is  a  wrapper enabling the package to be loaded with the option “[1m-m[0m
            [1mmom[22m”.

     [4m/usr/share/groff/1.24.1/tmac/om.tmac[0m
            implements the package.

     [4m/usr/share/doc/groff-1.24.1/html/mom/toc.html[0m
            is the entry point to the HTML documentation.

     [4m/usr/share/doc/groff-1.24.1/pdf/mom-pdf.pdf[0m
            is “Producing PDFs with [4mgroff[24m and [4mmom[24m”,  by  Deri  James  and  Peter
            Schaffter.

     [4m/usr/share/doc/groff-1.24.1/examples/mom/[24m*[4m.mom[0m
            are examples of [4mmom[24m usage.

[1mReference[0m
   [1mEscape sequences[0m
     [1m\*[[4m[22m<colorname>[24m[1m][0m
            begin using an initialized colour inline

     [1m\*[BCK [4m[22mn[24m[1m][0m
            move backward in a line

     [1m\*[BOLDER][0m
            invoke pseudo bold inline (related to macro [1m.SETBOLDER[22m)

     [1m\*[BOLDERX][0m
            off pseudo bold inline (related to macro [1m.SETBOLDER[22m)

     [1m\*[BU [4m[22mn[24m[1m][0m
            move  characters  pairs  closer  together  inline  (related to macro
            [1m.KERN[22m)

     [1m\*[COND][0m
            invoke pseudo condensing inline (related to macro [1m.CONDENSE[22m)

     [1m\*[CONDX][0m
            off pseudo condensing inline (related to macro [1m.CONDENSE[22m)

     [1m\*[CONDSUP][22m...[1m\*[CONDSUPX][0m
            pseudo‐condensed superscript

     [1m\*[DOWN [4m[22mn[24m[1m][0m
            temporarily move downward in a line

     [1m\*[EN-MARK][0m
            mark initial line of a range of line numbers (for use with line num‐
            bered endnotes)

     [1m\*[EXT][0m
            invoke pseudo extending inline (related to macro [1m.EXTEND[22m)

     [1m\*[EXTX][0m
            off pseudo condensing inline (related to macro [1m.EXTEND[22m)

     [1m\*[EXTSUP][22m...[1m\*[EXTSUPX][0m
            pseudo extended superscript

     [1m\*[FU [4m[22mn[24m[1m][0m
            move characters pairs further apart inline (related to macro [1m.KERN[22m)

     [1m\*[FWD [4m[22mn[24m[1m][0m
            move forward in a line

     [1m\*[LEADER][0m
            insert leaders at the end of a line

     [1m\*[RULE][0m
            draw a full measure rule

     [1m\*[SIZE [4m[22mn[24m[1m][0m
            change the point size inline (related to macro [1m.PT_SIZE[22m)

     [1m\*[SLANT][0m
            invoke pseudo italic inline (related to macro [1m.SETSLANT[22m)

     [1m\*[SLANTX][0m
            off pseudo italic inline (related to macro [1m.SETSLANT[22m)

     [1m\*[ST[4m[22m<n>[24m[1m][22m...[1m\*[ST[4m[22m<n>[24m[1mX][0m
            string tabs (mark tab positions inline)

     [1m\*[SUP][22m...[1m\*[SUPX][0m
            superscript

     [1m\*[TB+][0m
            inline escape for [1m.TN [22m([4mTab[24m [4mNext[24m)

     [1m\*[UL][22m...[1m\*[ULX][0m
            invoke underlining inline (fixed width fonts only)

     [1m\*[UP [4m[22mn[24m[1m][0m
            temporarily move upward in a line

   [1mMacros[0m
     [1m.AUTOLEAD[0m
            set the linespacing relative to the point size

     [1m.B_MARGIN[0m
            set a bottom margin

     [1m.BR    [22mbreak a justified line

     [1m.CENTER[0m
            set line‐by‐line quad centre

     [1m.CONDENSE[0m
            set the amount to pseudo condense

     [1m.EL    [22mbreak a line without advancing on the page

     [1m.EXTEND[0m
            set the amount to pseudo extend

     [1m.FALLBACK_FONT[0m
            establish a fallback font (for missing fonts)

     [1m.FAM   [22malias to [1m.FAMILY[0m

     [1m.FAMILY [4m[22m<family>[0m
            set the [4mfamily[24m [4mtype[0m

     [1m.FT    [22mset the font style (roman, italic, etc.)

     [1m.HI [ [4m[22m<measure>[24m [1m][0m
            hanging indent

     [1m.HY    [22mautomatic hyphenation on/off

     [1m.HY_SET[0m
            set automatic hyphenation parameters

     [1m.IB [ [4m[22m<left[24m [4mmeasure>[24m [4m<right[24m [4mmeasure>[24m [1m][0m
            indent both

     [1m.IBX [ CLEAR ][0m
            exit indent both

     [1m.IL [ [4m[22m<measure>[24m [1m][0m
            indent left

     [1m.ILX [ CLEAR ][0m
            exit indent left

     [1m.IQ [ CLEAR ][0m
            quit any/all indents

     [1m.IR [ [4m[22m<measure>[24m [1m][0m
            indent right

     [1m.IRX [ CLEAR ][0m
            exit indent right

     [1m.JUSTIFY[0m
            justify text to both margins

     [1m.KERN  [22mautomatic character pair kerning on/off

     [1m.L_MARGIN[0m
            set a left margin (page offset)

     [1m.LEFT  [22mset line‐by‐line quad left

     [1m.LL    [22mset a line length

     [1m.LS    [22mset a linespacing (leading)

     [1m.PAGE  [22mset explicit page dimensions and margins

     [1m.PAGEWIDTH[0m
            set a custom page width

     [1m.PAGELENGTH[0m
            set a custom page length

     [1m.PAPER [4m[22m<paper_type>[0m
            set common paper sizes (letter, A4, etc)

     [1m.PT_SIZE[0m
            set the point size

     [1m.QUAD  [22m"justify" text left, centre, or right

     [1m.R_MARGIN[0m
            set a right margin

     [1m.RIGHT[0m
            set line‐by‐line quad right

     [1m.SETBOLDER[0m
            set the amount of emboldening

     [1m.SETSLANT[0m
            set the degree of slant

     [1m.SPREAD[0m
            force justify a line

     [1m.SS    [22mset the sentence space size

     [1m.T_MARGIN[0m
            set a top margin

     [1m.TI [ [4m[22m<measure>[24m [1m][0m
            temporary left indent

     [1m.WS    [22mset the minimum word space size

[1mDocumentation of details[0m
   [1mDetails of inline escape sequences in alphabetical order[0m
     [1m\*[[4m[22m<colorname>[24m[1m][0m
            begin using an initialized colour inline

     [1m\*[BCK [4m[22mn[24m[1m][0m
            move backward in a line

     [1m\*[BOLDER][0m
     [1m\*[BOLDERX][0m
            Emboldening on/off

            [1m\*[BOLDER] [22mbegins emboldening type.  [1m\*[BOLDERX] [22mturns  the  feature
            off.   Both  are inline escape sequences; therefore, they should not
            appear as separate lines, but rather be embedded in text lines, like
            this:
                   Not [1m\*[BOLDER][22meverything[1m\*[BOLDERX] [22mis as it seems.

            Alternatively, if you wanted the whole line emboldened,  you  should
            do
                   [1m\*[BOLDER][22mNot everything is as it seems.[1m\*[BOLDERX][0m
            Once [1m\*[BOLDER] [22mis invoked, it remains in effect until turned off.

            Note:   If   you’re   using  the  document  processing  macros  with
            [1m.PRINTSTYLE TYPEWRITE[22m, [4mmom[24m ignores [1m\*[BOLDER] [22mrequests.

     [1m\*[BU [4m[22mn[24m[1m][0m
            move characters pairs  closer  together  inline  (related  to  macro
            [1m.KERN[22m)

     [1m\*[COND][0m
     [1m\*[CONDX][0m
            Pseudo‐condensing on/off

            [1m\*[COND] [22mbegins pseudo‐condensing type.  [1m\*[CONDX] [22mturns the feature
            off.   Both  are inline escape sequences; therefore, they should not
            appear as separate lines, but rather be embedded in text lines, like
            this:
                   [1m\*[COND][4m[22mNot[24m [4meverything[24m [4mis[24m [4mas[24m [4mit[24m [4mseems.[24m[1m\*[CONDX][0m
            [1m\*[COND] [22mremains in effect until you turn it off with [1m\*[CONDX][22m.

            IMPORTANT: You must turn [1m\*[COND] [22moff before making any  changes  to
            the  point  size of your type, either via the [1m.PT_SIZE [22mmacro or with
            the [1m\s [22minline escape sequence.  If you wish the new point size to be
            pseudo‐condensed,  simply  reinvoke  [1m\*[COND]  [22mafterward.   Equally,
            [1m\*[COND]  [22mmust be turned off before changing the condense percentage
            with [1m.CONDENSE[22m.

            Note:  If  you’re  using  the  document   processing   macros   with
            [1m.PRINTSTYLE TYPEWRITE[22m, [4mmom[24m ignores [1m\*[COND] [22mrequests.

     [1m\*[CONDSUP][22m...[1m\*[CONDSUPX][0m
            pseudo‐condensed superscript

     [1m\*[DOWN [4m[22mn[24m[1m][0m
            temporarily move downward in a line

     [1m\*[EN-MARK][0m
            mark initial line of a range of line numbers (for use with line num‐
            bered endnotes)

     [1m\*[EXT][0m
     [1m\*[EXTX][0m
            Pseudo‐extending on/off

            [1m\*[EXT]  [22mbegins  pseudo‐extending  type.  [1m\*[EXTX] [22mturns the feature
            off.  Both are inline escape sequences; therefore, they  should  not
            appear as separate lines, but rather be embedded in text lines, like
            this:
                   [1m\*[EXT][4m[22mNot[24m [4meverything[24m [4mis[24m [4mas[24m [4mit[24m [4mseems.[24m[1m\*[EXTX][0m
            [1m\*[EXT] [22mremains in effect until you turn it off with [1m\*[EXTX][22m.

            IMPORTANT:  You  must  turn [1m\*[EXT] [22moff before making any changes to
            the point size of your type, either via the [1m.PT_SIZE [22mmacro  or  with
            the [1m\s [22minline escape sequence.  If you wish the new point size to be
            [4mpseudo‐extended[24m,   simply   reinvoke  [1m\*[EXT]  [22mafterward.   Equally,
            [1m\*[EXT] [22mmust be turned off before  changing  the  extend  percentage
            with [1m.EXTEND[22m.

            Note:   If  you  are  using  the  document  processing  macros  with
            [1m.PRINTSTYLE TYPEWRITE[22m, [4mmom[24m ignores [1m\*[EXT] [22mrequests.

     [1m\*[EXTSUP][22m...[1m\*[EXTSUPX][0m
            pseudo extended superscript

     [1m\*[FU [4m[22mn[24m[1m][0m
            move characters pairs further apart inline (related to macro [1m.KERN[22m)

     [1m\*[FWD [4m[22mn[24m[1m][0m
            move forward in a line

     [1m\*[LEADER][0m
            insert leaders at the end of a line

     [1m\*[RULE][0m
            draw a full measure rule

     [1m\*[SIZE [4m[22mn[24m[1m][0m
            change the point size inline (related to macro [1m.PT_SIZE[22m)

     [1m\*[SLANT][0m
     [1m\*[SLANTX][0m
            Pseudo italic on/off

            [1m\*[SLANT] [22mbegins [4mpseudo‐italicizing[24m [4mtype[24m.  [1m\*[SLANTX] [22mturns the fea‐
            ture off.  Both are inline escape sequences; therefore, they  should
            not  appear as separate lines, but rather be embedded in text lines,
            like this:
                   Not [1m\*[SLANT][22meverything[1m\*[SLANTX] [22mis as it seems.

            Alternatively, if you wanted the whole line [4mpseudo‐italicized[24m, you’d
            do
                   [1m\*[SLANT][22mNot everything is as it seems.[1m\*[SLANTX][0m

            Once [1m\*[SLANT] [22mis invoked, it remains in effect until turned off.

            Note:  If  you’re  using  the  document   processing   macros   with
            [1m.PRINTSTYLE TYPEWRITE[22m, [4mmom[24m underlines pseudo‐italics by default.  To
            change this behaviour, use the special macro [1m.SLANT_MEANS_SLANT[22m.

     [1m\*[ST[4m[22m<number>[24m[1m][22m...[1m\*[ST[4m[22m<number>[24m[1mX][0m
            Mark positions of string tabs

            The  [4mquad[24m direction must be [1mLEFT [22mor [1mJUSTIFY [22m(see [1m.QUAD [22mand [1m.JUSTIFY[22m)
            or the [4mno‐fill[24m [4mmode[24m set to [1mLEFT [22min order for these inlines to  func‐
            tion properly.  Please see [4mIMPORTANT[24m, below.

            String  tabs  need to be marked off with inline escape sequences be‐
            fore being set up with the [1m.ST [22mmacro.  Any input  line  may  contain
            string  tab  markers.  [4m<number>[24m, above, means the numeric identifier
            of the tab.

            The following shows a sample input line with string tab markers.
                   [1m\*[ST1][22mDe minimus[1m\*[ST1X][22mnon curat[1m\*[ST2][22mlex[1m\*[ST2X][22m.

            String [4mtab[24m [4m1[24m begins at the start of the line and ends after the word
            [4mtime[24m.  String [4mtab[24m [4m2[24m starts at [4mgood[24m and ends after [4mmen[24m.   [4mInline[24m  [4mes‐[0m
            [4mcape[24m  [4msequences[24m  (e.g.,  [4mfont[24m  or  [4mpoint[24m [4msize[24m [4mchanges[24m, or horizontal
            movements, including padding) are taken into account when [4mmom[24m deter‐
            mines the [4mposition[24m and [4mlength[24m of [4mstring[24m [4mtabs[24m.

            Up to nineteen string tabs may be marked (not necessarily all on the
            same line, of course), and they must be numbered between 1 and 19.

            Once string tabs have been marked in input lines, they  have  to  be
            [4mset[24m with [1m.ST[22m, after which they may be called, by number, with [1m.TAB[22m.

            Note:  Lines  with  string  tabs marked off in them are normal input
            lines, i.e. they get printed, just like any input line.  If you want
            to set up string tabs without the line  printing,  use  the  [1m.SILENT[0m
            macro.

            [4mIMPORTANT:[24m  Owing  to  the way [4mgroff[24m processes input lines and turns
            them into output lines, it is not possible for [4mmom[24m to [4mguess[24m the cor‐
            rect starting position of string tabs marked off in lines  that  are
            centered or set flush right.

            Equally,  she  cannot guess the starting position if a line is fully
            justified and broken with [1m.SPREAD[22m.

            In other words, in order to use string tabs, [1mLEFT  [22mmust  be  active,
            or,  if  [1m.QUAD  LEFT  [22mor  [1mJUSTIFY  [22mare active, the line on which the
            [4mstring[24m [4mtabs[24m are marked must be broken [4mmanually[24m  with  [1m.BR  [22m(but  not
            [1m.SPREAD[22m).

            To  circumvent  this  behaviour, I recommend using the [1mPAD [22mto set up
            string tabs in centered or flush right lines.  Say, for example, you
            want to use a [4mstring[24m [4mtab[24m to [4munderscore[24m the text of a  centered  line
            with a rule.  Rather than this,
                   [1m.CENTER[0m
                   [1m\*[ST1]A line of text\*[ST1X]\c[0m
                   [1m.EL[0m
                   [1m.ST 1[0m
                   [1m.TAB 1[0m
                   [1m.PT_SIZE 24[0m
                   [1m.ALD 3p[0m
                   [1m\*[RULE][0m
                   [1m.RLD 3p[0m
                   [1m.TQ[0m
            you should do:
                   .QUAD CENTER
                   .PAD "#\*[ST1]A line of text\*[ST1X]#"
                   .EL
                   .ST 1
                   .TAB 1
                   .PT_SIZE 24
                   .ALD 3p
                   \" You can't use \*[UP] or \*[DOWN] with \*[RULE].
                   .RLD 3p
                   .TQ

     [1m\*[SUP][22m...[1m\*[SUPX][0m
            superscript

     [1m\*[TB+][0m
            Inline escape for [1m.TN [22m([4mTab[24m [4mNext[24m)

     [1m\*[UL][22m...[1m\*[ULX][0m
            invoke underlining inline (fixed width fonts only)

     [1m\*[UP [4m[22mn[24m[1m][0m
            temporarily move upward in a line

   [1mDetails of macros in alphabetical order[0m
     [1m.AUTOLEAD[0m
            set the linespacing relative to the point size

     [1m.B_MARGIN [4m[22m<bottom[24m [4mmargin>[0m
            Bottom Margin

            Requires a unit of measure

            [1m.B_MARGIN  [22msets  a nominal position at the bottom of the page beyond
            which you don’t want your type to go.  When  the  bottom  margin  is
            reached,  [4mmom[24m  starts a new page.  [1m.B_MARGIN requires a unit of mea‐[0m
            [1msure.  [22mDecimal fractions are allowed.  To set a nominal bottom  mar‐
            gin of 3/4 inch, enter
                   [1m.B_MARGIN .75i[0m

            Obviously,  if you haven’t spaced the type on your pages so that the
            last lines fall perfectly at the bottom margin, the margin will vary
            from page to page.  Usually, but not always, the last line  of  type
            that  fits  on a page before the bottom margin causes mom to start a
            new page.

            Occasionally, owing to a peculiarity in [4mgroff[24m, an  extra  line  will
            fall  below the nominal bottom margin.  If you’re using the document
            processing macros, this is unlikely to happen; the document process‐
            ing macros are very hard‐nosed about aligning bottom margins.

            Note: The meaning of [1m.B_MARGIN [22mis slightly different when you’re us‐
            ing the document processing macros.

     [1m.FALLBACK_FONT [4m[22m<fallback[24m [4mfont>[24m [1m[ ABORT | WARN ][0m
            Fallback Font

            In the event that you pass an invalid argument to  [1m.FAMILY  [22m(i.e.  a
            non‐existent  [4mfamily[24m),  [4mmom[24m,  by  default,  uses  the [4mfallback[24m [4mfont[24m,
            [1mCourier Medium Roman [22m([1mCR[22m), in  order  to  continue  processing  your
            file.

            If  you’d prefer another [4mfallback[24m [4mfont[24m, pass [1m.FALLBACK_FONT [22mthe full
            [4mfamily+font[24m [4mname[24m of the [4mfont[24m you’d  like.   For  example,  if  you’d
            rather the [4mfallback[24m [4mfont[24m were [1mTimes Roman Medium Roman[22m,
                   [1m.FALLBACK_FONT TR[0m
            would do the trick.

            [1mMom [22missues a warning whenever a [4mfont[24m [4mstyle[24m [4mset[24m with [1m.FT [22mdoes not ex‐
            ist,  either because you haven’t registered the style or because the
            [4mfont[24m [4mstyle[24m does not exist in the current [4mfamily[24m  [4mset[24m  with  [1m.FAMILY[22m.
            By  default,  [1mmom [22mthen aborts, which allows you to correct the prob‐
            lem.

            If you’d prefer that [1mmom [22mnot abort on non‐existent [4mfonts[24m, but rather
            continue  processing  using  a   [4mfallback[24m   [4mfont[24m,   you   can   pass
            [1m.FALLBACK_FONT  [22mthe  argument [1mWARN[22m, either by itself, or in conjunc‐
            tion with your chosen [4mfallback[24m [4mfont[24m[1m.[0m

            Some examples of invoking [1m.FALLBACK_FONT[22m:

            [1m.FALLBACK_FONT WARN[0m
                   [4mmom[24m will issue a warning whenever you try to access a non‐ex‐
                   istent [4mfont[24m but will continue processing your file  with  the
                   default [4mfallback[24m [4mfont[24m, [1mCourier Medium Roman[22m.

            [1m.FALLBACK_FONT TR WARN[0m
                   [1mmom [22mwill issue a warning whenever you try to access a non‐ex‐
                   istent  [4mfont[24m  but  will  continue processing your file with a
                   [4mfallback[24m [4mfont[24m of [1mTimes Roman Medium Roman[22m;  additionally,  [1mTR[0m
                   will be the [4mfallback[24m [4mfont[24m whenever you try to access a [4mfamily[0m
                   that does not exist.

            [1m.FALLBACK_FONT TR ABORT[0m
                   [1mmom  [22mwill  abort  whenever  you  try to access a non‐existent
                   [1mfont[22m, and will use the [4mfallback[24m [4mfont[24m [1mTR [22mwhenever you  try  to
                   access  a  [4mfamily[24m  that does not exist.  If, for some reason,
                   you want to  revert  to  [1mABORT[22m,  just  enter  [1m".FALLBACK_FONT[0m
                   [1mABORT" [22mand [4mmom[24m will once again abort on [4mfont[24m [4merrors[24m.

     [1m.FAM [4m[22m<family>[0m
            Type Family, alias of [1m.FAMILY[0m

     [1m.FAMILY [4m[22m<family>[0m
            Type Family, alias of [1m.FAM[0m

            [1m.FAMILY  [22mtakes one argument: the name of the [4mfamily[24m you want.  [4mGroff[0m
            comes with a small set of basic families, each identified by  a  1‐,
            2‐ or 3‐letter mnemonic.  The standard families are:
                   [1mA   = Avant Garde[0m
                   [1mBM  = Bookman[0m
                   [1mH   = Helvetica[0m
                   [1mHN  = Helvetica Narrow[0m
                   [1mN   = New Century Schoolbook[0m
                   [1mP   = Palatino[0m
                   [1mT   = Times Roman[0m
                   [1mZCM = Zapf Chancery[0m

            The  argument  you pass to [1m.FAMILY [22mis the identifier at left, above.
            For example, if you want [1mHelvetica[22m, enter
                   [1m.FAMILY H[0m

            Note: The font macro ([1m.FT[22m) lets you specify both the type [4mfamily[24m and
            the desired font with a single macro.  While this saves a  few  key‐
            strokes, I recommend using [1m.FAMILY for [4m[22mfamily[24m, and [1m.FT for [4m[22mfont[24m, ex‐
            cept  where  doing  so is genuinely inconvenient.  [1mZCM[22m, for example,
            only exists in one style: [1mItalic [22m([1mI[22m).

            Therefore,
                   [1m.FT ZCMI[0m
            makes more sense than setting the [4mfamily[24m to [1mZCM[22m,  then  setting  the
            [4mfont[24m to [4mI[24m.

            Additional note: If you are running a [4mgroff[24m version prior to 1.19.2,
            you  must  follow all [1m.FAMILY [22mrequests with a [1m.FT [22mrequest, otherwise
            [4mmom[24m will set all type up to the next [1m.FT  [22mrequest  in  the  fallback
            font.

            When  running [4mgroff[24m 1.19.2 or later, and you call the [1m.FAMILY [22mmacro,
            [4mmom[24m [4mremembers[24m the font style (such as roman or italic) currently  in
            use  (if  the  font style exists in the new [4mfamily[24m) and continues to
            use the same font style in the new family.  For example:
                   [1m.FAMILY BM [4m[22m\"[24m [4mBookman[24m [4mfamily[0m
                   [1m.FT I [4m[22m\"[24m [4mMedium[24m [4mItalic[0m
                   [4m<some[24m [4mtext>[24m [4m\"[24m [4mBookman[24m [4mMedium[24m [4mItalic[0m
                   [1m.FAMILY H [4m[22m\"[24m [4mHelvetica[24m [4mfamily[0m
                   [4m<more[24m [4mtext>[24m [4m\"[24m [4mHelvetica[24m [4mMedium[24m [4mItalic[0m

            However, if the font style does not exist in  the  new  family,  [4mmom[0m
            sets  all  subsequent type in the fallback font (by default, [1mCourier[0m
            [1mMedium Roman[22m) until she encounters a [1m.FT [22mcall that’s valid  for  the
            [4mfamily[24m.

            For example, assuming you don’t have the font [1mMedium Condensed Roman[0m
            ([4mmom[24m extension [4mCD[24m) in the [4mHelvetica[24m [4mfamily[24m:
                   [1m.FAMILY UN [4m[22m\"[24m [4mUnivers[24m [4mfamily[0m
                   [1m.FT CD [4m[22m\"[24m [4mMedium[24m [4mCondensed[0m
                   [4m<some[24m [4mtext>[24m [4m\"[24m [4mUnivers[24m [4mMedium[24m [4mCondensed[0m
                   [1m.FAMILY H [4m[22m\"[24m [4mHelvetica[24m [4mfamily[0m
                   [4m<more[24m [4mtext>[24m [4m\"[24m [4mCourier[24m [4mMedium[24m [4mRoman![0m

            In  the  above example, you must follow [1m.FAMILY H [22mwith a [1m.FT [22mrequest
            that’s valid for [1mHelvetica[22m.

            Please see the Appendices, [4mAdding[24m [4mfonts[24m [4mto[24m [4mgroff[24m, for information on
            adding fonts and families to [4mgroff[24m,[4mas[24mwell[4mas[24mto see a list of the  ex‐
            tensions [4mmom[24m provides to [4mgroff[24m’s basic [1mR[22m, [1mI[22m, [1mB[22m, [1mBI [22mstyles.

            Suggestion: When adding [4mfamilies[24m [4mto[24m [4mgroff[24m, I recommend following the
            established  standard  for the naming families and fonts.  For exam‐
            ple, if you add the [1mGaramond [22mfamily, name the font files
                   [1mGARAMONDR[0m
                   [1mGARAMONDI[0m
                   [1mGARAMONDB[0m
                   [1mGARAMONDBI[0m
            [1mGARAMOND then becomes a valid [4m[22mfamily[24m [4mname[24m you can pass  to  [1m.FAMILY[22m.
            (You could, of course, shorten [1mGARAMOND [22mto just [1mG[22m, or [1mGD[22m.)  [1mR[22m, [1mI[22m, [1mB[22m,
            and  [1mBI  [22mafter  [1mGARAMOND [22mare the [4mroman[24m, [4mitalic[24m, [4mbold[24m and [4mbold‐italic[0m
            fonts respectively.

     [1m.FONT R | B | BI | [4m[22m<any[24m [4mother[24m [4mvalid[24m [4mfont[24m [4mstyle>[0m
            Alias to [1m.FT[0m

     [1m.FT R | B | BI | [4m[22m<any[24m [4mother[24m [4mvalid[24m [4mfont[24m [4mstyle>[0m
            Set font

            By default, [4mgroff[24m permits [1m.FT [22mto take one of four possible arguments
            specifying the desired font:
                   [1mR = (Medium) Roman[0m
                   [1mI = (Medium) Italic[0m
                   [1mB = Bold (Roman)[0m
                   [1mBI = Bold Italic[0m

            For example, if your [4mfamily[24m is [1mHelvetica[22m, entering
                   [1m.FT B[0m
            will give  you  the  [4mHelvetica[24m  [4mbold[24m  [4mfont[24m.   If  your  [4mfamily[24m  were
            [1mPalatino[22m, you’d get the [4mPalatino[24m [4mbold[24m [4mfont[24m.

            [1mMom [22mconsiderably extends the range of arguments you can pass to [1m.FT[22m,
            making  it  more  convenient  to  add  and access fonts of differing
            weights and shapes within the same family.

            Have a look here for a list of the weight/style  arguments  [4mmom[24m  al‐
            lows.  Be aware, though, that you must have the fonts, correctly in‐
            stalled and named, in order to use the arguments.  (See [4mAdding[24m [4mfonts[0m
            [4mto[24m  [4mgroff[24m  for  instructions and information.)  Please also read the
            [4mADDITIONAL[24m [4mNOTE[24m found in the description of the [1m.FAMILY [22mmacro.

            How [4mmom[24m reacts to an invalid argument to [1m.FT [22mdepends on  which  ver‐
            sion  of  [4mgroff[24m  you’re  using.   If your [4mgroff[24m version is 1.19.2 or
            later, [4mmom[24m will issue a warning and, depending on how you’ve set  up
            the  fallback  font,  either  continue processing using the fallback
            font, or abort (allowing you to correct the  problem).   In  earlier
            versions,  [4mmom[24m  will  silently continue processing, using either the
            fallback font or the font that was in effect prior  to  the  invalid
            [1m.FT [22mcall.

            [1m.FT [22mwill also accept, as an argument, a full [4mfamily[24m and [4mfont[24m [4mname[24m.

            For example,
                   [1m.FT HB[0m
            will set subsequent type in [4mHelvetica[24m [4mBold[24m.

            However,  I  strongly recommend keeping [4mfamily[24m and [4mfont[24m separate ex‐
            cept where doing so is genuinely inconvenient.

            For inline control of [4mfonts[24m, see [4mInline[24m [4mEscapes[24m, font control.

     [1m.HI [ [4m[22m<measure>[24m [1m][0m
            Hanging indent —— the optional argument requires a unit of measure.

            A hanging indent looks like this:
                   The thousand injuries of Fortunato I had borne as best I
                     could, but when he ventured upon insult, I vowed
                     revenge.  You who so well know the nature of my soul
                     will not suppose, however, that I gave utterance to a
                     threat, at length I would be avenged...
            The first line of text [4mhangs[24m outside the [4mleft[24m [4mmargin[24m.

            In order to use [4mhanging[24m [4mindents[24m, you must first have a  [4mleft[24m  [4mindent[0m
            active (set with either [1m.IL [22mor [1m.IB[22m).  [1mMom [22mwill not hang text outside
            the  [4mleft[24m  [4mmargin[24m [4mset[24m with [1m.L_MARGIN [22mor outside the [4mleft[24m [4mmargin[24m of a
            [4mtab[24m.

            The first time you invoke [1m.HI[22m, you must give it a [1mmeasure[22m.   If  you
            want the first line of a paragraph to [4mhang[24m [4mby[24m, say, [4m1[24m [4mpica[24m, do
                   [1m.IL 1P[0m
                   [1m.HI 1P[0m
            Subsequent  invocations  of  [1m.HI [22mdo not require you to supply a [4mmea‐[0m
            [4msure[24m; [4mmom[24m keeps track of the last measure you gave it.

            Generally speaking, you should invoke [1m.HI [22mimmediately prior  to  the
            line  you  want  hung  (i.e. without any intervening control lines).
            And because [4mhanging[24m [4mindents[24m affect only one line, there’s no need to
            turn them off.

            [4mIMPORTANT:[24m Unlike [1mIL[22m, [1mIR [22mand [1mIB[22m, measures given to [1m.HI [22mare NOT addi‐
            tive.  Each time you pass a measure to [1m.HI[22m, the measure  is  treated
            literally.  [4mRecipe:[24m A numbered list using [4mhanging[24m [4mindents[0m

            [4mNote:[24m  [4mmom[24m  has  macros  for  setting  lists.  This recipe exists to
            demonstrate the use of [4mhanging[24m [4mindents[24m only.
                   .PAGE 8.5i 11i 1i 1i 1i 1i
                   .FAMILY  T
                   .FT      R
                   .PT_SIZE 12
                   .LS      14
                   .JUSTIFY
                   .KERN
                   .SS 0
                   .IL \w'\0\0.'
                   .HI \w'\0\0.'
                   1.\0The most important point to be considered is whether
                   the answer to the meaning of Life, the Universe, and
                   Everything really is 42.  We have no one's word on the
                   subject except Mr. Adams's.
                   .HI
                   2.\0If the answer to the meaning of Life, the Universe,
                   and Everything is indeed 42, what impact does this have on
                   the politics of representation?  42 is, after all not a
                   prime number.  Are we to infer that prime numbers don't
                   deserve equal rights and equal access in the universe?
                   .HI
                   3.\0If 42 is deemed non‐exclusionary, how do we present
                   it as the answer and, at the same time, forestall debate
                   on its exclusionary implications?

            First, we invoke a left indent with a measure equal to the width  of
            2  figures  spaces  plus  a period (using the \w inline escape).  At
            this point, the left indent is active; text afterward would normally
            be indented.  However, we invoke a hanging  indent  of  exactly  the
            same width, which hangs the first line (and first line only!) to the
            left  of  the  indent by the same distance (in this case, that means
            “out to the left margin”).  Because we begin the first line  with  a
            number,  a period, and a figure space, the actual text ([4mThe[24m [4mmost[24m [4mim‐[0m
            [4mportant[24m [4mpoint...[24m) starts at exactly the same spot  as  the  indented
            lines that follow.

            Notice that subsequent invocations of [1m.HI [22mdon’t require a [4mmeasure[24m to
            be given.

            Paste the example above into a file and preview it with
                   [1mpdfmom filename.mom | ps2pdf - filename.pdf[0m
            to see hanging indents in action.

     [1m.IB [ [4m[22m<left[24m [4mmeasure>[24m [4m<right[24m [4mmeasure>[24m [1m][0m
            Indent both —— the optional argument requires a unit of measure

            [1m.IB  [22mallows  you  to  set or invoke a left and a right indent at the
            same time.

            At its first invocation, you must supply a measure for both indents;
            at subsequent invocations when you wish to supply  a  measure,  both
            must be given again.  As with [1m.IL [22mand [1m.IR[22m, the measures are added to
            the  values  previously  passed to the macro.  Hence, if you wish to
            change just one of the values, you must give an argument of zero  to
            the other.

            [4mA[24m  [4mword[24m  [4mof[24m [4madvice:[24m If you need to manipulate left and right indents
            separately, use a combination of [1m.IL [22mand [1m.IR [22minstead of [1m.IB[22m.  You’ll
            save yourself a lot of grief.

            A [4mminus[24m [4msign[24m may be prepended to  the  arguments  to  subtract  from
            their  current  values.  The \w inline escape may be used to specify
            text‐dependent measures, in which case no unit  of  measure  is  re‐
            quired.  For example,
                   [1m.IB \w'margarine' \w'jello'[0m
            left  indents  text by the width of the word [4mmargarine[24m and right in‐
            dents by the width of [4mjello[24m.

            Like [1m.IL [22mand [1m.IR[22m, [1m.IB [22mwith no argument indents by  its  last  active
            values.   See  the  brief explanation of how mom handles indents for
            more details.

            [4mNote:[24m Calling a [4mtab[24m (with [1m.TAB <n>[22m) automatically cancels any active
            indents.

            [4mAdditional[24m [4mnote:[24m Invoking [1m.IB [22mautomatically turns off [1m.IL [22mand [1m.IR[22m.

     [1m.IL [ [4m[22m<measure>[24m [1m][0m
            Indent left —— the optional argument requires a unit of measure

            [1m.IL [22mindents text from the left margin of the page, or if you’re in a
            [4mtab[24m, from the left edge of the [4mtab[24m.  Once [4mIL[24m is on, the [4mleft[24m  [4mindent[0m
            is  applied  uniformly to every subsequent line of text, even if you
            change the line length.

            The first time you invoke [1m.IL[22m, you must give it a  measure.   Subse‐
            quent invocations with a measure add to the previous measure.  A mi‐
            nus  sign may be prepended to the argument to subtract from the cur‐
            rent measure.  The [1m\w [22minline escape may be used to specify  a  text‐
            dependent  measure,  in  which  case no unit of measure is required.
            For example,
                   [1m.IL \w'margarine'[0m
            indents text by the width of the word [4mmargarine[24m.

            With no argument, [1m.IL [22mindents by its last  active  value.   See  the
            brief explanation of how [4mmom[24m handles indents for more details.

            [4mNote:[24m Calling a [4mtab[24m (with [1m.TAB <n>[22m) automatically cancels any active
            indents.

            [4mAdditional[24m [4mnote:[24m Invoking [1m.IL [22mautomatically turns off [1mIB[22m.

     [1m.IQ [ [4m[22m<measure>[24m [1m][0m
            IQ —— quit any/all indents

            [4mIMPORTANT[24m [4mNOTE:[24m The original macro for quitting all indents was [1m.IX[22m.
            This  usage  has been deprecated in favour of [1mIQ[22m.  [1m.IX [22mwill continue
            to behave as before, but [4mmom[24m will issue a warning to [4mstderr[24m indicat‐
            ing that you should update your documents.

            As a consequence of this change, [1m.ILX[22m, [1m.IRX [22mand [1m.IBX [22mmay now also be
            invoked as [1m.ILQ[22m, [1m.IRQ [22mand [1m.IBQ[22m.  Both forms are acceptable.

            Without an argument, the macros to quit indents merely restore  your
            original margins and line length.  The measures stored in the indent
            macros  themselves are saved so you can call them again without hav‐
            ing to supply a measure.

            If you pass these macros the optional argument [1mCLEAR[22m, they not  only
            restore  your  original  left margin and line length, but also clear
            any values associated with a particular indent style.  The next time
            you need an indent of the same style, you have to supply  a  measure
            again.

            [1m.IQ CLEAR[22m, as you’d suspect, quits and clears the values for all in‐
            dent styles at once.

     [1m.IR [ [4m[22m<measure>[24m [1m][0m
            Indent right —— the optional argument requires a unit of measure

            [1m.IR  [22mindents text from the [4mright[24m [4mmargin[24m of the page, or if you’re in
            a [4mtab[24m, from the end of the [4mtab[24m.

            The first time you invoke [1m.IR[22m, you must give it a  measure.   Subse‐
            quent invocations with a measure add to the previous indent measure.
            A  [4mminus[24m  [4msign[24m may be prepended to the argument to subtract from the
            current indent measure.  The \w inline escape may be used to specify
            a text‐dependent measure, in which case no [4munit[24m [4mof[24m  [4mmeasure[24m  is  re‐
            quired.  For example,
                   [1m.IR \w'jello'[0m
            indents text by the width of the word [4mjello[24m.

            With  no  argument,  [1m.IR  [22mindents by its last active value.  See the
            brief explanation of how [4mmom[24m handles indents for more details.

            [4mNote:[24m Calling a [4mtab[24m (with [1m.TAB <n>[22m) automatically cancels any active
            indents.

            [4mAdditional[24m [4mnote:[24m Invoking [1m.IR [22mautomatically turns off [1mIB[22m.

     [1m.L_MARGIN [4m[22m<left[24m [4mmargin>[0m
            Left Margin

            L_MARGIN establishes the distance from the left edge of the  printer
            sheet  at  which  you  want  your type to start.  It may be used any
            time, and remains in effect until you enter a new value.

            Left indents and tabs are calculated from  the  value  you  pass  to
            [1m.L_MARGIN[22m,  hence it’s always a good idea to invoke it before start‐
            ing any serious typesetting.  A unit of measure is required.   Deci‐
            mal  fractions  are allowed.  Therefore, to set the left margin at 3
            picas (1/2 inch), you’d enter either
                   [1m.L_MARGIN 3P[0m
            or
                   [1m.L_MARGIN .5i[0m

            If you use the macros [1m.PAGE[22m, [1m.PAGEWIDTH [22mor [1m.PAPER  [22mwithout  invoking
            [1m.L_MARGIN  [22m(either  before  or  afterward),  [4mmom[24m  automatically sets
            [1m.L_MARGIN [22mto [4m1[24m [4minch[24m.

            Note: [1m.L_MARGIN [22mbehaves in a special way when you’re using the docu‐
            ment processing macros.

     [1m.MCO   [22mBegin multi‐column setting.

            [1m.MCO [22m([4mMulti‐Column[24m [4mOn[24m) is the [4mmacro[24m you use  to  begin  [4mmulti‐column[0m
            [4msetting[24m.   It marks the current baseline as the top of your columns,
            for use later with [1m.MCR[22m.  See the introduction to columns for an ex‐
            planation of [4mmulti‐columns[24m and some sample input.

            [4mNote:[24m Do not confuse [1m.MCO [22mwith the [1m.COLUMNS [22mmacro  in  the  document
            processing macros.

     [1m.MCR   [22mOnce  you’ve turned [4mmulti‐columns[24m on (with [1m.MCO[22m), [1m.MCR[22m, at any time,
            returns you to the [4mtop[24m [4mof[24m [4myour[24m [4mcolumns[24m.

     [1m.MCX [ [4m[22m<distance[24m [4mto[24m [4madvance[24m [4mbelow[24m [4mlongest[24m [4mcolumn>[24m [1m][0m
            Optional argument requires a unit of measure.

            Exit multi‐columns.

            [1m.MCX [22mtakes you out of any [4mtab[24m you were in (by silently invoking [1m.TQ[22m)
            and advances to the bottom of the longest column.

            Without an argument, [1m.MCX [22madvances [4m1[24m  [4mlinespace[24m  below  the  longest
            column.

            Linespace,  in this instance, is the leading in effect at the moment
            [1m.MCX [22mis invoked.

            If you pass the [4m<distance>[24m argument to [1m.MCX[22m, it advances [4m1[24m [4mlinespace[0m
            below the longest column (see above) [4mPLUS[24m the distance specified  by
            the  argument.   The argument requires a unit of measure; therefore,
            to advance an extra 6 points below where [1m.MCX [22mwould  normally  place
            you, you’d enter
                   [1m.MCX 6p[0m

            [4mNote:[24m  If  you wish to advance a precise distance below the baseline
            of the longest column, use [1m.MCX [22mwith an argument of [1m0 [22m(zero; no [4munit[0m
            [4mof[24m [4mmeasure[24m required) in conjunction with the [1m.ALD [22mmacro, like this:
                   [1m.MCX 0[0m
                   [1m.ALD 24p[0m
            The above advances to precisely [4m24[24m [4mpoints[24m below the baseline of  the
            longest column.

     [1m.NEWPAGE[0m

            Whenever  you want to start a new page, use [1m.NEWPAGE[22m, by itself with
            no argument.  [1mMom [22mwill finish up processing  the  current  page  and
            move you to the top of a new one (subject to the top margin set with
            [1m.T_MARGIN[22m).

     [1m.PAGE [4m[22m<width>[24m [1m[ [4m[22m<length>[24m [1m[ [4m[22m<lm>[24m [1m[ [4m[22m<rm>[24m [1m[ [4m[22m<tm>[24m [1m[ [4m[22m<bm>[24m [1m] ] ] ] ][0m

            All arguments require a unit of measure

            [4mIMPORTANT:[24m  If  you’re  using  the document processing macros, [1m.PAGE[0m
            must come after [1m.START[22m.  Otherwise, it should go at  the  top  of  a
            document,  prior  to  any text.  And remember, when you’re using the
            document processing macros, top margin and bottom margin mean  some‐
            thing slightly different than when you’re using just the typesetting
            macros (see Top and bottom margins in document processing).

            [1m.PAGE  [22mlets  you  establish paper dimensions and page margins with a
            single macro.  The only required argument is page width.   The  rest
            are  optional, but they must appear in order and you can’t skip over
            any.  [4m<lm>[24m, [4m<rm>[24m, [4m<tm>[24m and [4m<bm>[24m refer to the left,  right,  top  and
            bottom margins respectively.

            Assuming your page dimensions are 11 inches by 17 inches, and that’s
            all you want to set, enter
                   [1m.PAGE 11i 17i[0m
            If  you  want  to  set the left margin as well, say, at 1 inch, [1mPAGE[0m
            would look like this:
                   [1m.PAGE 11i 17i 1i[0m

            Now suppose you also want to set  the  top  margin,  say,  at  1–1/2
            inches.   [4m<tm>[24m  comes  after [4m<rm>[24m in the optional arguments, but you
            can’t skip over any arguments, therefore to set the top margin,  you
            must  also  give  a  right  margin.  The [1m.PAGE [22mmacro would look like
            this:
                   .PAGE 11i 17i 1i 1i 1.5i
                                    |   |
                   required right---+   +---top margin
                           margin

            Clearly, [1m.PAGE [22mis best used when you want a convenient way  to  tell
            [4mmom[24m just the dimensions of your printer sheet (width and length), or
            when  you want to tell her everything about the page (dimensions and
            all the margins), for example
                   [1m.PAGE 8.5i 11i 45p 45p 45p 45p[0m
            This sets up an 8½ by  11  inch  page  with  margins  of  45  points
            (5/8‐inch) all around.

            Additionally,  if  you  invoke [1m.PAGE [22mwith a top margin argument, any
            macros you invoke after [1m.PAGE [22mwill almost certainly move  the  base‐
            line  of  the  first line of text down by one linespace.  To compen‐
            sate, do
                   [1m.RLD 1v[0m
            immediately before entering any text, or,  if  it’s  feasible,  make
            [1m.PAGE [22mthe last macro you invoke prior to entering text.

            Please  read the [4mImportant[24m [4mnote[24m on page dimensions and papersize for
            information on ensuring [4mgroff[24m respects  your  [1m.PAGE  [22mdimensions  and
            margins.

     [1m.PAGELENGTH [4m[22m<length[24m [4mof[24m [4mprinter[24m [4msheet>[0m
            tells  [4mmom[24m  how  long  your  printer  sheet  is.  It works just like
            [1m.PAGEWIDTH[22m.

            Therefore, to tell [4mmom[24m your printer sheet is 11 inches long, you en‐
            ter
                   [1m.PAGELENGTH 11i[0m
            Please read the important note on page dimensions and papersize  for
            information on ensuring [4mgroff[24m respects your [4mPAGELENGTH[24m.

     [1m.PAGEWIDTH [4m[22m<width[24m [4mof[24m [4mprinter[24m [4msheet>[0m

            The argument to [1m.PAGEWIDTH [22mis the width of your printer sheet.

            [1m.PAGEWIDTH  [22mrequires  a  unit of measure.  Decimal fractions are al‐
            lowed.  Hence, to tell [4mmom[24m that the width of your printer  sheet  is
            8½ inches, you enter
                   .PAGEWIDTH 8.5i

            Please  read the Important note on page dimensions and papersize for
            information on ensuring [4mgroff[24m respects your [4mPAGEWIDTH[24m.

     [1m.PAPER [4m[22m<paper[24m [4mtype>[0m
            provides a convenient way to set the page dimensions for some common
            printer sheet sizes.  The argument [4m<paper[24m [4mtype>[24m can be one of:  [1mLET‐[0m
            [1mTER[22m,  [1mLEGAL[22m,  [1mSTATEMENT[22m,  [1mTABLOID[22m, [1mLEDGER[22m, [1mFOLIO[22m, [1mQUARTO[22m, [1mEXECUTIVE[22m,
            [1m10x14[22m, [1mA3[22m, [1mA4[22m, [1mA5[22m, [1mB4[22m, [1mB5[22m.

     [1m.PRINTSTYLE[0m

     [1m.PT_SIZE [4m[22m<size[24m [4mof[24m [4mtype[24m [4min[24m [4mpoints>[0m
            Point size of type, does not require a [4munit[24m [4mof[24m [4mmeasure[24m.

            [1m.PT_SIZE [22m([4mPoint[24m [4mSize[24m) takes  one  argument:  the  [4msize[24m  [4mof[24m  [4mtype[24m  in
            [4mpoints[24m.  Unlike most other macros that establish the [4msize[24m or [4mmeasure[0m
            of  something,  [1m.PT_SIZE  [22mdoes not require that you supply a [4munit[24m [4mof[0m
            [4mmeasure[24m since it’s a near universal convention  that  [4mtype[24m  [4msize[24m  is
            measured  in [4mpoints[24m.  Therefore, to change the [4mtype[24m [4msize[24m to, say, [4m11[0m
            [4mpoints[24m, enter
                   [1m.PT_SIZE 11[0m
            [4mPoint[24m [4msizes[24m may be [4mfractional[24m (e.g., [4m10.25[24m or [4m12.5[24m).

            You can prepend a [4mplus[24m or a [4mminus[24m [4msign[24m to the argument to  [1m.PT_SIZE[22m,
            in  which case the [4mpoint[24m [4msize[24m will be changed by [4m+[24m or [4m-[24m the original
            value.  For example, if the [4mpoint[24m [4msize[24m is [4m12[24m, and you want  [4m14[24m,  you
            can do
                   [1m.PT_SIZE +2[0m
            then later reset it to [4m12[24m with
                   [1m.PT_SIZE -2[0m
            The [4msize[24m [4mof[24m [4mtype[24m can also be changed inline.

            [4mNote:[24m  It is unfortunate that the [1mpic [22mpreprocessor has already taken
            the name, PS, and thus [4mmom[24m’s macro for setting [4mpoint[24m [4msizes[24m can’t use
            it.  However, if you aren’t using  [1mpic[22m,  you  might  want  to  alias
            [1m.PT_SIZE [22mas [1m.PS[22m, since there’d be no conflict.  For example
                   [1m.ALIAS PS PT_SIZE[0m
            would allow you to set [4mpoint[24m [4msizes[24m with [1m.PS[22m.

     [1m.R_MARGIN [4m[22m<right[24m [4mmargin>[0m
            Right Margin

            Requires a unit of measure.

            IMPORTANT:  [1m.R_MARGIN[22m,  if used, must come after [1m.PAPER[22m, [1m.PAGEWIDTH[22m,
            [1m.L_MARGIN[22m, and/or [1m.PAGE [22m(if a right margin  isn’t  given  to  PAGE).
            The reason is that [1m.R_MARGIN [22mcalculates line length from the overall
            page dimensions and the left margin.

            Obviously, it can’t make the calculation if it doesn’t know the page
            width and the left margin.

            [1m.R_MARGIN  [22mestablishes  the amount of space you want between the end
            of typeset lines and the right hand edge of the printer  sheet.   In
            other  words, it sets the line length.  [1m.R_MARGIN [22mrequires a unit of
            measure.  Decimal fractions are allowed.

            The line length macro (LL) can be used in place  of  [1m.R_MARGIN[22m.   In
            either  case, the last one invoked sets the line length.  The choice
            of which to use is up to you.  In some instances, you  may  find  it
            easier  to  think of a section of type as having a right margin.  In
            others, giving a line length may make more sense.

            For example, if you’re setting a page of type you know  should  have
            6‐pica  margins  left  and right, it makes sense to enter a left and
            right margin, like this:
                   [1m.L_MARGIN 6P[0m
                   [1m.R_MARGIN 6P[0m

            That way, you don’t have to worry about calculating the line length.
            On the other hand, if you know the line length for a patch  of  type
            should be 17 picas and 3 points, entering the line length with LL is
            much easier than calculating the right margin, e.g.,
                   [1m.LL 17P+3p[0m

            If  you  use  the macros [1m.PAGE[22m, [1m.PAGEWIDTH [22mor [1mPAPER [22mwithout invoking
            [1m.R_MARGIN [22mafterward, [4mmom[24m automatically sets [1m.R_MARGIN [22mto [4m1[24m [4minch[24m.  If
            you set a line length after these macros (with [1m.LL[22m), the line length
            calculated by [1m.R_MARGIN [22mis, of course, overridden.

            Note: [1m.R_MARGIN [22mbehaves in a special way when you’re using the docu‐
            ment processing macros.

     [1m.ST [4m[22m<tab[24m [4mnumber>[24m [1mL | R | C | J [ QUAD ][0m

            After [4mstring[24m [4mtabs[24m have  been  marked  off  on  an  input  line  (see
            [1m\*[ST]...\*[STX][22m),  you  need to [4mset[24m them by giving them a direction
            and, optionally, the [1mQUAD [22margument.

            In this respect, [1m.ST [22mis like [1m.TAB_SET [22mexcept that you don’t have  to
            give  [1m.ST  [22man indent or a line length (that’s already taken care of,
            inline, by [1m\*[ST]...\*[STX][22m).

            If you want string [4mtab[24m [4m1[24m to be [1mleft[22m, enter
                   [1m.ST 1 L[0m
            If you want it to be [4mleft[24m and [4mfilled[24m, enter
                   [1m.ST 1 L QUAD[0m
            If you want it to be justified, enter
                   [1m.ST 1 J[0m

     [1m.TAB [4m[22m<tab[24m [4mnumber>[0m
            After [4mtabs[24m have been defined (either with  [1m.TAB_SET  [22mor  [1m.ST[22m),  [1m.TAB[0m
            moves to whatever [4mtab[24m [4mnumber[24m you pass it as an argument.

            For example,
                   [1m.TAB 3[0m
            moves you to [4mtab[24m [4m3[24m.

            Note:  [1m.TAB  [22mbreaks  the line preceding it and advances 1 linespace.
            Hence,
                   [1m.TAB 1[0m
                   [1mA line of text in tab 1.[0m
                   [1m.TAB 2[0m
                   [1mA line of text in tab 2.[0m
            produces, on output
                   [1mA line of text in tab 1.[0m
                                                [1mA line of text in tab 2.[0m

            If you want the tabs to line up, use [1m.TN [22m(“Tab Next”) or, more  con‐
            veniently, the inline escape sequence [1m\*[TB+][22m:
                   [1m.TAB [22m1
                   A line of text in tab 1.\*[TB+]
                   A line of text in tab 2.
            which produces
                   [1mA line of text in tab 1.   A line of text in tab 2.[0m

            If  the  text  in  your tabs runs to several lines, and you want the
            first lines of each tab to align,  you  must  use  the  multi‐column
            macros.

            [4mAdditional[24m  [4mnote:[24m  Any  indents in effect prior to calling a tab are
            automatically turned off by [1mTAB[22m.  If you were happily  zipping  down
            the page with a left indent of [4m2[24m [4mpicas[24m turned on, and you call a [4mtab[0m
            whose indent from the left margin is [4m6[24m [4mpicas[24m, your new distance from
            the  [4mleft[24m  [4mmargin[24m will be [4m6[24m [4mpicas[24m, not I 6 picas plus the 2 pica in‐
            dent.

            [4mTabs[24m are not by nature columnar, which is to say that  if  the  text
            inside a [4mtab[24m runs to several lines, calling another [4mtab[24m does not au‐
            tomatically  move  to the baseline of the first line in the [4mprevious[0m
            [4mtab[24m.  To demonstrate:
                   TAB 1
                   Carrots
                   Potatoes
                   Broccoli
                   .TAB 2
                   $1.99/5 lbs
                   $0.25/lb
                   $0.99/bunch
            produces, on output
                   Carrots
                   Potatoes
                   Broccoli
                               $1.99/5 lbs
                               $0.25/lb
                               $0.99/bunch

     [1m.TB [4m[22m<tab[24m [4mnumber>[0m
            Alias to [1m.TAB[0m

     [1m.TI [ [4m[22m<measure>[24m [1m][0m
            Temporary left indent —— the optional argument requires  a  [4munit[24m  [4mof[0m
            [4mmeasure[0m

            A  temporary  indent  is  one that applies only to the first line of
            text that comes after it.  Its chief use is indenting the first line
            of paragraphs.  ([1mMom’s .PP [22mmacro, for example, uses a [4mtemporary[24m  [4min‐[0m
            [4mdent[24m.)

            The  first  time you invoke [1m.TI[22m, you must give it a measure.  If you
            want to [4mindent[24m the first line of a paragraph by, say, 2 ems, do
                   [1m.TI 2m[0m

            Subsequent invocations of [1m.TI [22mdo not require you to  supply  a  mea‐
            sure; [4mmom[24m keeps track of the last measure you gave it.

            Because  [4mtemporary[24m  [4mindents[24m  are  temporary, there’s no need to turn
            them off.

            [4mIMPORTANT:[24m Unlike [1m.IL[22m, [1m.IR [22mand [1mIB[22m, measures given to [1m.TI [22mare NOT ad‐
            ditive.  In the following example, the second [1m".TI 2P" [22mis exactly  [4m2[0m
            [4mpicas[24m.
                   [1m.TI 1P[0m
                   [1mThe beginning of a paragraph...[0m
                   [1m.TI 2P[0m
                   [1mThe beginning of another paragraph...[0m

     [1m.TN    [22mTab Next

            Inline escape [1m\*[TB+][0m

            [1mTN  [22mmoves over to the [4mnext[24m [4mtab[24m in numeric sequence ([4mtab[24m [4mn+1[24m) without
            advancing on the page.  See the [4mNOTE[24m in the description of the  [1m.TAB[0m
            macro for an example of how [1mTN [22mworks.

            In [4mtabs[24m that aren’t given the [1mQUAD [22margument when they’re set up with
            [1m.TAB_SET  [22mor  [1mST[22m, you must terminate the line preceding [1m.TN [22mwith the
            [1m\c [22minline escape sequence.  Conversely, if you did give a [1mQUAD [22margu‐
            ment to [1m.TAB_SET [22mor [1mST[22m, the [1m\c must not be used.[0m

            If you find remembering whether to put in the [1m\c [22mbothersome, you may
            prefer to use the inline escape alternative to [1m.TN[22m,  [1m\*[TB+][22m,  which
            works consistently regardless of the fill mode.

            [4mNote:[24m  You  must  put  text in the input line immediately after [1m.TN[22m.
            Stacking of [1m.TN[22m’s is not allowed.  In other words, you cannot do
                   .TAB 1
                   Some text\c
                   .TN
                   Some more text\c
                   .TN
                   .TN
                   Yet more text
            The above example, assuming [4mtabs[24m numbered from [4m1[24m to [4m4[24m, should be en‐
            tered
                   .TAB 1
                   Some text\c
                   .TN
                   Some more text\c
                   .TN
                   \&\c
                   .TN
                   Yet more text
            \& is a zero‐width, non‐printing character that [4mgroff[24m recognizes  as
            valid  input,  hence  meets the requirement for input text following
            [1m.TN[22m.

     [1m.TQ    TQ [22mtakes you out of whatever [4mtab[24m you were in, advances [4m1[24m  [4mlinespace[24m,
            and  restores  the [4mleft[24m [4mmargin[24m, [4mline[24m [4mlength[24m, [4mquad[24m [4mdirection[24m and [4mfill[0m
            [4mmode[24m that were in effect prior to invoking any [4mtabs[24m.

     [1m.T_MARGIN [4m[22m<top[24m [4mmargin>[0m
            Top margin

            Requires a unit of measure

            [1m.T_MARGIN [22mestablishes the distance from the top of the printer sheet
            at which you want your type to start.  It requires a  unit  of  mea‐
            sure,  and decimal fractions are allowed.  To set a top margin of 2½
            centimetres, you’d enter
                   [1m.T_MARGIN 2.5c[0m
            [1m.T_MARGIN [22mcalculates the vertical position of the first line of type
            on a page by treating the top edge of the printer sheet as  a  base‐
            line.  Therefore,
                   [1m.T_MARGIN 1.5i[0m
            puts  the  baseline  of the first line of type 1½ inches beneath the
            top of the page.

            Note: [1m.T_MARGIN [22mmeans something slightly different when you’re using
            the document processing macros.  See Top and bottom margins in docu‐
            ment processing for an explanation.

            IMPORTANT: [1m.T_MARGIN [22mdoes two things: it establishes the top  margin
            for  pages  that  come after it and it moves to that position on the
            current page.  Therefore, [1m.T_MARGIN [22mshould only be used at  the  top
            of a file (prior to entering text) or after NEWPAGE, like this:
                   [1m.NEWPAGE[0m
                   [1m.T_MARGIN 6P[0m
                   [4m<text>[0m

[1mAuthors[0m
     ]8;;mailto:peter@schaffter.ca\Peter  Schaffter]8;;\  wrote  [4mmom[24m.   ]8;;mailto:deri@chuzzlewit.myzen.co.uk\Deri James]8;;\ added PDF support.  ]8;;mailto:groff-bernd.warken-72@web.de\Bernd Warken]8;;\
     contributed this man page.

[1mSee also[0m
     [4m/usr/share/doc/groff-1.24.1/html/mom/toc.html[0m
            [4mmom[24m manual (installed version)

     ]8;;http://www.schaffter.ca/mom/momdoc/toc.html\[4mmom[24m manual]8;;\
            (latest version)

     ]8;;http://www.schaffter.ca/mom/\[4mmom[24m homepage]8;;\

     [4mGroff:[24m [4mThe[24m [4mGNU[24m [4mImplementation[24m [4mof[24m [4mtroff[24m, by Trent A. Fisher and Werner  Lem‐
     berg,  is  the  primary [4mgroff[24m manual.  You can browse it interactively with
     “info groff”.

     ]8;;man:pdfmom(1)\[4mpdfmom[24m(1)]8;;\, ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\

groff 1.24.1                       2026‐03‐20                       [4mgroff_mom[24m(7)
────────────────────────────────────────────────────────────────────────────────
[4mgroff_ms[24m(7)             Miscellaneous Information Manual             [4mgroff_ms[24m(7)

[1mName[0m
     groff_ms - GNU [4mroff[24m manuscript macro package for formatting documents

[1mSynopsis[0m
     [1mgroff -ms [22m[[4moption[24m ...] [[4mfile[24m ...]
     [1mgroff -m ms [22m[[4moption[24m ...] [[4mfile[24m ...]

[1mDescription[0m
     The GNU implementation of the [4mms[24m macro package is part of the  [4mgroff[24m  docu‐
     ment  formatting system.  The [4mms[24m package is suitable for the composition of
     letters, memoranda, reports, and books.

     These [4mgroff[24m macros support cover page and table of contents generation, au‐
     tomatically numbered headings, several paragraph styles, a variety of  text
     styling options, footnotes, and multi‐column page layouts.  [4mms[24m supports the
     ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\, ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\, ]8;;man:pic(1)\[4mpic[24m(1)]8;;\, and ]8;;man:refer(1)\[4mrefer[24m(1)]8;;\ preprocessors for inclusion of tables,
     mathematical  equations, diagrams, and consistently formatted bibliographic
     citations.

     [4mgroff[24m [4mms[24m is mostly compatible with the documented interface and behavior of
     AT&T Unix Version 7 [4mms[24m.  It recreates most extensions from  4.2BSD  (Berke‐
     ley) and Research Tenth Edition Unix.

[1mDocument structure[0m
     The  [4mms[24m  macro package expects a certain amount of structure: a well‐formed
     document contains at least one paragraphing or heading macro call.  To com‐
     pose a simple document from scratch, begin it by calling [1mLP [22mor  [1mPP[22m.   Orga‐
     nize longer documents as follows.

     [1mDocument type[0m
            Calling the [1mRP [22mmacro at the beginning of your document puts the doc‐
            ument description (see below) on a cover page.  Otherwise, [4mms[24m places
            this information on the first page, followed immediately by the body
            text.   Some  document  types  found in other [4mms[24m implementations are
            specific to AT&T or Berkeley, and are not supported in [4mgroff[24m [4mms[24m.

     [1mFormat and layout[0m
            By setting registers and strings, you can configure your  document’s
            typeface,  margins,  spacing,  headers  and  footers,  and  footnote
            arrangement.  See subsection “Document control settings” below.

     [1mDocument description[0m
            A document description consists of any of: a title, one or more  au‐
            thors’ names and affiliated institutions, an abstract, and a date or
            other  identifier.  See subsection “Document description macros” be‐
            low.

     [1mBody text[0m
            The main matter of your document follows its description  (if  any).
            [4mms[24m  supports  highly structured text consisting of paragraphs inter‐
            spersed with multi‐level headings (chapters, sections,  subsections,
            and  so  forth) and augmented by lists, footnotes, tables, diagrams,
            and similar material.  The preponderance of subsections below covers
            these matters.

     [1mTable of contents[0m
            Macros enable the collection of entries for a table of contents  (or
            index)  as  the  material  they  discuss appears in the document.  A
            macro call at the end of the document emits the  collected  entries.
            This  material  necessarily  follows  the rest of the text since GNU
            [4mtroff[24m is a single‐pass formatter; it cannot determine the page  num‐
            ber  of  a  division  of  the text until it has been set and output.
            Since [4mms[24m output was designed for the production of  hard  copy,  the
            traditional  procedure was to manually relocate the pages containing
            the table of contents between the cover page and the body text.  To‐
            day, page resequencing is more often done in the digital domain.  An
            index works similarly, but because it typically needs to  be  sorted
            after collection, its preparation requires separate processing.

   [1mDocument control settings[0m
     The following tables list the document control registers, strings, and spe‐
     cial characters.  For any parameter whose default is unsatisfactory, define
     it before calling any [4mms[24m macro other than [1mRP[22m.

                                  [1mMargin settings[0m
     [1mParameter              Definition                Effective       Default[0m
     ───────────────────────────────────────────────────────────────────────────
     \n[PO]      Page offset (left margin)          next page        1i (0)
     \n[LL]      Line length                        next paragraph   6.5i (65n)
     \n[LT]      Title line length                  next paragraph   6.5i (65n)
     \n[HM]      Top (header) margin                next page        1i
     \n[FM]      Bottom (footer) margin             next page        1i
     ───────────────────────────────────────────────────────────────────────────

                             [1mTitles (headers, footers)[0m
     [1mParameter                 Definition                  Effective    Default[0m
     ───────────────────────────────────────────────────────────────────────────
     \*[LH]      Left header text                         next header   [4mempty[0m
     \*[CH]      Center header text                       next header   -\n[%]-
     \*[RH]      Right header text                        next header   [4mempty[0m
     \*[LF]      Left footer text                         next footer   [4mempty[0m
     \*[CF]      Center footer text                       next footer   [4mempty[0m
     \*[RF]      Right footer text                        next footer   [4mempty[0m
     ───────────────────────────────────────────────────────────────────────────

                                   [1mText settings[0m
     [1mParameter               Definition                  Effective      Default[0m
     ───────────────────────────────────────────────────────────────────────────
     \n[PS]      Point (type) size                     next paragraph   10p
     \n[VS]      Vertical spacing (leading)            next paragraph   12p
     \n[HY]      Hyphenation mode                      next paragraph   6
     \*[FAM]     Font family                           next paragraph   T
     ───────────────────────────────────────────────────────────────────────────

                                 [1mParagraph settings[0m
      [1mParameter              Definition                Effective       Default[0m
     ───────────────────────────────────────────────────────────────────────────
     \n[PI]        Indentation                       next paragraph   5n
     \n[PD]        Paragraph distance (spacing)      next paragraph   0.3v (1v)
     \n[QI]        Quotation indentation             next paragraph   5n
     \n[PORPHANS]  # of initial lines kept           next paragraph   1
     ───────────────────────────────────────────────────────────────────────────

                                  [1mHeading settings[0m
      [1mParameter               Definition               Effective      Default[0m
     ───────────────────────────────────────────────────────────────────────────
     \n[PSINCR]     Point (type) size increment       next heading   1p
     \n[GROWPS]     Size increase depth limit         next heading   0
     \n[HORPHANS]   # of following lines kept         next heading   1
     \*[SN-STYLE]   Numbering style (alias)           next heading   \*[SN-DOT]
     ───────────────────────────────────────────────────────────────────────────

     [1m\*[SN-STYLE]  [22mcan  alternatively be made an alias of [1m\*[SN-NO-DOT] [22mwith the
     [1mals [22mrequest.

                                 [1mFootnote settings[0m
     [1mParameter              Definition                 Effective      Default[0m
     ───────────────────────────────────────────────────────────────────────────
     \n[FI]      Indentation                         next footnote   2n
     \n[FF]      Format                              next footnote   0
     \n[FPS]     Point (type) size                   next footnote   \n[PS]-2p
     \n[FVS]     Vertical spacing (leading)          next footnote   \n[FPS]+2p
     \n[FPD]     Paragraph distance (spacing)        next footnote   \n[PD]/2
     \*[FR]      Line length ratio                   [4mspecial[24m         11/12
     ───────────────────────────────────────────────────────────────────────────

                                  [1mDisplay settings[0m
     [1mParameter                 Definition                 Effective    Default[0m
     ───────────────────────────────────────────────────────────────────────────
     \n[DD]      Display distance (spacing)               [4mspecial[24m     0.5v (1v)
     \n[DI]      Display indentation                      [4mspecial[24m     0.5i
     ───────────────────────────────────────────────────────────────────────────

                                   [1mOther settings[0m
       [1mParameter                Definition                Effective     Default[0m
     ───────────────────────────────────────────────────────────────────────────
     \n[MINGW]       Minimum gutter width                next page      2n
     \n[TC-MARGIN]   TOC page number margin width        next [1mPX [22mcall   \w'000'
     \[TC-LEADER]    TOC leader character                next [1mPX [22mcall   .\h'1m'
     ───────────────────────────────────────────────────────────────────────────

     For entries marked “[4mspecial[24m” in the “Effective” column, see the  discussion
     in the applicable section below.  The [1mPO[22m, [1mLL[22m, and [1mLT [22mregister defaults vary
     by output device and paper format; the values shown are for typesetters us‐
     ing  U.S.  letter paper, and then terminals.  See section “Paper format” of
     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\.  The [1mPD [22mand [1mDD [22mregisters use the larger value if the vertical mo‐
     tion quantum of the output device is too coarse for the smaller  one;  usu‐
     ally, this is the case only for output to terminals.  The “gutter” affected
     by  [1m\n[MINGW]  [22mis  the gap between columns in multiple‐column page arrange‐
     ments.  The [1mTC-MARGIN [22mregister and [1mTC-LEADER [22mspecial character  affect  the
     formatting of tables of contents assembled by the [1mXS[22m, [1mXA[22m, and [1mXE [22mmacros.

   [1mDocument description macros[0m
     Define  information  describing the document by calling the macros below in
     the order shown; [1mDA [22mor [1mND [22mcan be called to set the document date (or  other
     identifier) at any time before (a) the abstract, if present, or (b) its in‐
     formation  is  required  in a header or footer.  Use of these macros is op‐
     tional, except that [1mTL [22mis mandatory if any of [1mRP[22m, [1mAU[22m, [1mAI[22m, or [1mAB [22mis  called,
     and [1mAE [22mis mandatory if [1mAB [22mis called.

     [1m.RP [22m[[1mno-repeat-info[22m] [[1mno-renumber[22m]
            Use  the “report” (AT&T: “released paper”) format for your document,
            creating a separate cover page.  The default arrangement is to place
            most of the document description (title, author names  and  institu‐
            tions, and abstract, but not the date) at the top of the first page.
            If  the  optional  [1mno-repeat-info  [22margument  is given, [4mms[24m produces a
            cover page but does not repeat any of its  information  subsequently
            (but  see the [1mDA [22mmacro below regarding the date).  Normally, [1mRP [22msets
            the page number following the cover page to 1.  Specifying  the  op‐
            tional  [1mno-renumber  [22margument  suppresses this alteration.  Optional
            arguments can occur in any order.  [4mms[24m recognizes [1mno [22mas a synonym  of
            [1mno-repeat-info  [22mto  maintain AT&T compatibility.  Options other than
            [1mno [22mare GNU extensions.

     [1m.TL    [22mSpecify the document title.  [4mms[24m collects text on input lines follow‐
            ing this call into the title until reaching [1mAU[22m, [1mAB[22m, or a heading  or
            paragraphing macro call.

     [1m.AU    [22mSpecify an author’s name.  [4mms[24m collects text on input lines following
            this  call into the author’s name until reaching [1mAI[22m, [1mAB[22m, another [1mAU[22m,
            or a heading or paragraphing macro  call.   Call  it  repeatedly  to
            specify multiple authors.

     [1m.AI    [22mSpecify  the  preceding  author’s  institutional affiliation.  An [1mAU[0m
            call is usefully followed by at most one [1mAI [22mcall; if there are more,
            the last [1mAI [22mcall controls.  [4mms[24m collects text on input lines  follow‐
            ing  this  call into the author’s institution until reaching [1mAU[22m, [1mAB[22m,
            or a heading or paragraphing macro call.

     [1m.DA [22m[[4mx[24m ...]
            Typeset the current date, or any arguments [4mx[24m, in the center  footer,
            and,  if  [1mRP [22mis also called, left‐aligned at the end of the document
            description on the cover page.

     [1m.ND [22m[[4mx[24m ...]
            Typeset the current date, or any arguments [4mx[24m, if [1mRP [22mis also  called,
            left‐aligned  at  the  end  of the document description on the cover
            page.  This is [4mgroff[24m [4mms[24m’s default.

     [1m.AB [22m[[1mno[22m]
            Begin the abstract.  [4mms[24m collects text on input lines following  this
            call  into  the  abstract until reaching an [1mAE [22mcall.  By default, [4mms[0m
            places the word “ABSTRACT” centered and in italics above the text of
            the abstract.  The optional argument “[1mno[22m” suppresses this heading.

     [1m.AE    [22mEnd the abstract.

   [1mText settings[0m
     The [1mFAM [22mstring, a GNU extension, sets the font family for  body  text;  the
     default  is  “[1mT[22m”.   The  [1mPS [22mand [1mVS [22mregisters set the type size and vertical
     spacing (distance between text baselines), respectively.  The  font  family
     and  type  size  are ignored on terminals.  Set these parameters before the
     first call of a heading, paragraphing, or (non‐date)  document  description
     macro to apply them to headers, footers, and (for [1mFAM[22m) footnotes.

     The [1mHY [22mregister defines the automatic hyphenation mode used with the [1mhy [22mre‐
     quest.   Setting [1m\n[HY] [22mto [1m0 [22mdisables automatic hyphenation.  This is a Re‐
     search Tenth Edition Unix extension.

   [1mTypographical symbols[0m
     [4mms[24m provides a few strings to obtain typographical symbols  not  easily  en‐
     tered  with  the  keyboard.  These and many others are available as special
     character escape sequences——see ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\.

     [1m\*[-]  [22mInterpolate an em dash.

     [1m\*[Q][0m
     [1m\*[U]  [22mInterpolate typographer’s quotation marks where available, and  neu‐
            tral double quotes otherwise.  [1m\*[Q] [22mis the left quote and [1m\*[U] [22mthe
            right.

   [1mParagraphs[0m
     Paragraphing  macros [4mbreak[24m, or terminate, any pending output line so that a
     new paragraph can begin.  Several paragraph types are available,  differing
     in how indentation applies to them: to left, right, or both margins; to the
     first output line of the paragraph, all output lines, or all but the first.
     These  calls insert vertical space in the amount stored in the [1mPD [22mregister,
     except at page or column breaks, or adjacent to displays.

     The [1mPORPHANS [22mregister defines the minimum number of initial  lines  of  any
     paragraph  that must be kept together to avoid isolated lines at the bottom
     of a page.  If a new paragraph starts close to the bottom of  a  page,  and
     there is insufficient space to accommodate [1m\n[PORPHANS] [22mlines before an au‐
     tomatic  page  break,  [4mgroff[24m  [4mms[24m  forces a page break before formatting the
     paragraph.  This is a GNU extension.

     [1m.LP    [22mSet a paragraph without any (additional) indentation.

     [1m.PP    [22mSet a paragraph with a first‐line left  indentation  in  the  amount
            stored in the [1mPI [22mregister.

     [1m.IP [22m[[4mmark[24m [[4mwidth[24m]]
            Set  a  paragraph with a left indentation.  The optional [4mmark[24m is not
            indented, is useful in the construction of lists, and  is  empty  by
            default.   [4mwidth[24m overrides the indentation amount in [1m\n[PI][22m; its de‐
            fault unit is “[1mn[22m”.  Once specified,  [4mwidth[24m  applies  to  further  [1mIP[0m
            calls  until  specified again or a heading or different paragraphing
            macro is called.

     [1m.QP    [22mSet a paragraph indented from both left and right margins by [1m\n[QI][22m.

     [1m.QS[0m
     [1m.QE    [22mBegin ([1mQS[22m) and end ([1mQE[22m) a region where each  paragraph  is  indented
            from  both  margins  by  [1m\n[QI][22m.   The text between [1mQS [22mand [1mQE [22mcan be
            structured further by use of other paragraphing macros.

     [1m.XP    [22mSet an “exdented” paragraph——one with a left indentation  of  [1m\n[PI][0m
            on  every  line  [4mexcept[24m  the first (also known as a hanging indent).
            This is a Berkeley extension.

   [1mHeadings[0m
     Use headings to create a hierarchical structure for your document.  The  [4mms[0m
     macros  print  headings in [1mbold [22musing the same font family and, by default,
     type size as the body text.  Headings are available with and without  auto‐
     matic  numbering.  Text on input lines following the macro call becomes the
     heading’s title.  Call a paragraphing macro to end  the  heading  text  and
     start the section’s content.

     [1m.NH [22m[[4mdepth[24m]
            Set an automatically numbered heading.  [4mms[24m produces a numbered head‐
            ing  in  the form [4ma[24m.[4mb[24m.[4mc[24m..., to any level desired, with the numbering
            of each depth increasing automatically and being reset to zero  when
            a  more significant depth is increased.  “[1m1[22m” is the most significant
            or coarsest division of the document.  Only non‐zero values are out‐
            put.  If [4mdepth[24m is omitted, [4mms[24m assumes “[1m1[22m”.   If  you  specify  [4mdepth[0m
            such that an ascending gap occurs relative to the previous [1mNH [22mcall——
            that  is,  you “skip a depth”, as by “[1m.NH 1[22m” and then “[1m.NH 3[22m”, [4mgroff[0m
            [4mms[24m emits a warning on the standard error stream.

     [1m.NH S [4m[22mheading‐depth‐index[24m ...
            Alternatively, you can give [1mNH [22ma first argument of “[1mS[22m”, followed  by
            integers to number the heading depths explicitly.  Further automatic
            numbering,  if  used,  resumes  using the specified indices as their
            predecessors.  This feature is a Berkeley extension.

     After [1mNH [22mis called, the assigned number is made available  in  the  strings
     [1mSN-DOT  [22m(as  it  appears in a printed heading with default formatting, fol‐
     lowed by a terminating period) and [1mSN-NO-DOT [22m(with the  terminating  period
     omitted).  These, and [1mSN-STYLE[22m, are GNU extensions.

     You  can  control  the style used to print numbered headings by defining an
     appropriate alias for the string [1mSN-STYLE[22m.   By  default,  [1m\*[SN-STYLE]  [22mis
     aliased  to  [1m\*[SN-DOT][22m.  If you prefer to omit the terminating period from
     numbers appearing in numbered headings, you may alias it to  [1m\*[SN-NO-DOT][22m.
     Any  such  change in numbering style becomes effective from the next use of
     [1mNH [22mfollowing redefinition of the alias  for  [1m\*[SN-STYLE][22m.   The  formatted
     number of the current heading is available in [1m\*[SN] [22m(a feature first docu‐
     mented by Berkeley); this string facilitates its inclusion in, for example,
     table captions, equation labels, and [1mXS[22m/[1mXA[22m/[1mXE [22mtable of contents entries.

     [1m.SH [22m[[4mdepth[24m]
            Set an unnumbered heading.  The optional [4mdepth[24m argument is a GNU ex‐
            tension  indicating the heading depth corresponding to the [4mdepth[24m ar‐
            gument of [1mNH[22m.  It matches the type size at which the heading is  set
            to  that of a numbered heading at the same depth when the [1m\n[GROWPS][0m
            and [1m\n[PSINCR] [22mheading size adjustment mechanism is in effect.

     The [1mPSINCR [22mregister defines an increment in type size to be  applied  to  a
     heading  at a lesser depth than that specified in [1m\n[GROWPS][22m.  The value of
     [1m\n[PSINCR] [22mshould be specified in points with the “[1mp[22m” scaling unit and  may
     include a fractional component.

     The [1mGROWPS [22mregister defines the heading depth above which the type size in‐
     crement  set  by [1m\n[PSINCR] [22mbecomes effective.  For each heading depth less
     than the value of [1m\n[GROWPS][22m, the type size  is  increased  by  [1m\n[PSINCR][22m.
     Setting  [1m\n[GROWPS] [22mto a value less than 2 disables the incremental heading
     size feature.

     In other words, if the value of [1mGROWPS [22mregister is greater than  the  [4mdepth[0m
     argument  to  a [1mNH [22mor [1mSH [22mcall, the type size of a heading produced by these
     macros increases by [1m\n[PSINCR] [22munits over [1m\n[PS] [22mmultiplied by the  differ‐
     ence of [1m\n[GROWPS] [22mand [4mdepth[24m.  [1mGROWPS [22mand [1mPSINCR [22mare GNU extensions.

     In  [4mgroff[24m [4mms,[24m the [1mNH [22mand [1mSH [22mmacros consult the [1mHORPHANS [22mregister to prevent
     the output of isolated headings at the bottom of a page; it  specifies  the
     minimum  number  of  lines of the subsequent paragraph that must be kept on
     the same page as the heading.  If insufficient space remains on the current
     page to accommodate the heading and this number of lines of paragraph text,
     [4mgroff[24m [4mms[24m forces a page break before setting the heading.  Any display macro
     call or [4mtbl[24m, [4mpic[24m, or [4meqn[24m region between  the  heading  and  the  subsequent
     paragraph suppresses this grouping.  This is a GNU extension.

   [1mTypeface and decoration[0m
     The  [4mms[24m  macros provide a variety of ways to style text.  Attend closely to
     the ordering of arguments labeled [4mpre[24m and [4mpost,[24m  which  is  not  intuitive.
     Support for [4mpre[24m arguments is a GNU extension.

     [1m.B [22m[[4mtext[24m [[4mpost[24m [[4mpre[24m]]]
            Style  [4mtext[24m  in  bold,  followed  by [4mpost[24m in the previous font style
            without intervening space, and preceded by [4mpre[24m  similarly.   Without
            arguments,  [4mms[24m  styles  subsequent text in bold until the next para‐
            graphing, heading, or no‐argument typeface macro call.

     [1m.R [22m[[4mtext[24m [[4mpost[24m [[4mpre[24m]]]
            As [1mB[22m, but use the roman style (upright text of  normal  weight)  in‐
            stead of bold.  Argument recognition is a GNU extension.

     [1m.I [22m[[4mtext[24m [[4mpost[24m [[4mpre[24m]]]
            As [1mB[22m, but use an italic or oblique style instead of bold.

     [1m.BI [22m[[4mtext[24m [[4mpost[24m [[4mpre[24m]]]
            As [1mB[22m, but use a bold italic or bold oblique style instead of upright
            bold.  This is a Research Tenth Edition Unix extension.

     [1m.CW [22m[[4mtext[24m [[4mpost[24m [[4mpre[24m]]]
            As  [1mB[22m,  but use a constant‐width (monospaced) roman typeface instead
            of bold.  This is a Research Tenth Edition Unix extension.

     [1m.BX [22m[[4mtext[24m]
            Typeset [4mtext[24m and draw a box around it.  On terminals, reverse  video
            is used instead.  If you want [4mtext[24m to contain space, use unbreakable
            space or horizontal motion escape sequences ([1m\~[22m, [1m\[4m[22mspace[24m, [1m\^[22m, [1m\|[22m, [1m\0[22m,
            or [1m\h[22m).

     [1m.UL [22m[[4mtext[24m [[4mpost[24m]]
            Typeset  [4mtext[24m  with  an  underline.  On terminals, [4mtext[24m is bracketed
            with underscores (“_”).  [4mpost,[24m if present, is set after [4mtext[24m with no
            intervening space.

     [1m.LG    [22mSet subsequent text in larger type (2 points larger than the current
            size) until the next type size, paragraphing, or heading macro call.
            Call the macro multiple times to enlarge the type size further.

     [1m.SM    [22mSet subsequent text in smaller type (2 points smaller than the  cur‐
            rent  size) until the next type size, paragraphing, or heading macro
            call.  Call the macro multiple times to reduce the  type  size  fur‐
            ther.

     [1m.NL    [22mSet subsequent text at the normal type size ([1m\n[PS][22m).

     When [4mpre[24m is used, a hyphenation control escape sequence [1m\% [22mthat would ordi‐
     narily start [4mtext[24m must start [4mpre[24m instead.

     [4mgroff[24m  [4mms[24m  also  offers  strings  to begin and end super‐ and subscripting.
     These are GNU extensions.

     [1m\*{[0m
     [1m\*}    [22mBegin and end superscripting, respectively.

     [1m\*<[0m
     [1m\*>    [22mBegin and end subscripting, respectively.

   [1mIndented regions[0m
     You can indent a region of text while  otherwise  formatting  it  normally.
     Such indented regions can be nested.

     [1m.RS    [22mBegin a region where headings, paragraphs, and displays are indented
            (further) by [1m\n[PI][22m.

     [1m.RE    [22mEnd the (next) most recent indented region.

   [1mKeeps, boxed keeps, and displays[0m
     On  occasion,  you may want to [4mkeep[24m several lines of text, or a region of a
     document, together on a single page, preventing  an  automatic  page  break
     within  certain  boundaries.   This can cause a page break to occur earlier
     than it normally would.

     You can alternatively specify a [4mfloating[24m [4mkeep:[24m if a keep cannot fit on  the
     current  page, [4mms[24m holds it, allowing text following the keep (in the source
     document) to fill in the remainder of the  current  page.   When  the  page
     breaks  by  reaching its bottom or by [1mbp [22mrequest, [4mms[24m puts the floating keep
     at the beginning of the next page.

     [1m.KS    [22mBegin a keep.

     [1m.KF    [22mBegin a floating keep.

     [1m.KE    [22mEnd (floating) keep.

     As an alternative to the keep mechanism, the [1mne [22mrequest forces a page break
     if there is not at least the amount of vertical space specified in its  ar‐
     gument remaining on the page.

     A [4mboxed[24m [4mkeep[24m has a frame drawn around it.

     [1m.B1    [22mBegin a keep with a box drawn around it.

     [1m.B2    [22mEnd boxed keep.

     Boxed  keep  macros  cause breaks; to box words within a line, recall [1mBX [22min
     section “Highlighting” above.  [4mms[24m draws box lines close to  the  text  they
     enclose  so  that  they  are  usable within paragraphs.  When boxing entire
     paragraphs thus, you may improve their appearance by calling [1mB1  [22mafter  the
     first paragraphing macro, and invoking the [1msp [22mrequest before calling [1mB2[22m.

     If  you  want  a  boxed keep to float, enclose the [1mB1 [22mand [1mB2 [22mcalls within a
     pair of [1mKF [22mand [1mKE [22mcalls.

     [4mDisplays[24m turn off filling; lines of verse or program code  are  shown  with
     their  lines broken as in the source document without requiring [1mbr [22mrequests
     between lines.  Displays can be kept on a single page or allowed  to  break
     across  pages.   The [1mDS [22mmacro begins a kept display of the layout specified
     in its first argument; non‐kept displays are begun  with  dedicated  macros
     corresponding to their layout.

     [1m.DS L[0m
     [1m.LD    [22mBegin ([1mDS[22m: kept) left‐aligned display.

     [1m.DS [22m[[1mI [22m[[4mindent[24m]]
     [1m.ID [22m[[4mindent[24m]
            Begin  ([1mDS[22m:  kept)  display  indented by [4mindent[24m if specified, [1m\n[DI][0m
            otherwise.

     [1m.DS B[0m
     [1m.BD    [22mBegin ([1mDS[22m: kept) block display: the entire display is  left‐aligned,
            but  indented  such that the longest line in the display is centered
            on the page.

     [1m.DS C[0m
     [1m.CD    [22mBegin ([1mDS[22m: kept) centered display: each line in the display is  cen‐
            tered.

     [1m.DS R[0m
     [1m.RD    [22mBegin ([1mDS[22m: kept) right‐aligned display.  This is a GNU extension.

     [1m.DE    [22mEnd any display.

     [4mgroff[24m  [4mms[24m  inserts the distance stored in [1m\n[DD] [22mbefore and after each pair
     of display macros; this is a Berkeley extension.   This  distance  replaces
     any adjacent inter‐paragraph distance or subsequent spacing prior to a sec‐
     tion heading.  The [1mDI [22mregister is a GNU extension; its value is an indenta‐
     tion  applied  to  displays  created  with  [1mDS [22mand [1mID [22mwithout arguments, to
     “[1m.DS I[22m” without an indentation argument, and to equations set with “[1m.EQ I[22m”.
     Changes to either register take effect at the next display boundary.

   [1mTables, figures, equations, and references[0m
     [4mms[24m often sees use with the [4mtbl[24m, [4mpic[24m, [4meqn[24m, and [4mrefer[24m  preprocessors.   [4mgroff[0m
     [4mms[24m applies the [1m\n[DD] [22mdistance to regions of the document preprocessed with
     [4meqn[24m,  [4mpic[24m,  and  [4mtbl[24m.  Mark text meant for preprocessors by enclosing it in
     pairs of tokens as follows, with nothing between  the  dot  and  the  macro
     name.  Preprocessors match these tokens only at the start of an input line.
     The formatter interprets them as macro calls.

     [1m.TS [22m[[1mH[22m]
     [1m.TE    [22mDemarcate  a table to be processed by the [4mtbl[24m preprocessor.  The op‐
            tional [1mH [22margument instructs [4mms[24m to repeat table  rows  (often  column
            headings)  at  the top of each new page the table spans, if applica‐
            ble; calling the [1mTH [22mmacro marks the end of such rows.   ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\  pro‐
            vides a comprehensive reference to the preprocessor and offers exam‐
            ples of its use.

     [1m.PS [4m[22mh[24m [4mv[0m
     [1m.PE[0m
     [1m.PF    PS [22mmarks the start of a ]8;;man:pic(1)\[4mpic[24m(1)]8;;\ preprocessor diagram; either of [1mPE [22mor
            [1mPF  [22mends  it,  the latter with “flyback” to the vertical position at
            its top.  [4mh[24m and [4mv[24m are the horizontal and vertical dimensions of  the
            picture; [4mpic[24m supplies them automatically.

     [1m.EQ [22m[[4malign[24m [[4mlabel[24m]]
     [1m.EN    [22mDemarcate  mathematics  to be processed by the [4meqn[24m preprocessor.  [4mms[0m
            centers the equation by default; [4malign[24m can be [1mC[22m, [1mL[22m, or [1mI [22mto (explic‐
            itly) center, left‐align, or indent it by [1m\n[DI][22m, respectively.   [4mms[0m
            right‐aligns any [4mlabel[24m.  See ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\.

     [1m.[[0m
     [1m.]     [22mDemarcate a bibliographic citation to be processed by the [4mrefer[24m pre‐
            processor.   ]8;;man:refer(1)\[4mrefer[24m(1)]8;;\ provides a comprehensive reference to the pre‐
            processor and the format of its bibliographic database.

     When [4mrefer[24m emits collected references (as might be done on a “Works  Cited”
     page),  it  interpolates the string [1m\*[REFERENCES] [22mas an unnumbered heading
     ([1m.SH[22m).

     Attempting to place a multi‐page table inside a keep can lead to unpleasant
     results, particularly if the [4mtbl[24m “[1mallbox[22m” option is used.

   [1mFootnotes[0m
     A footnote is typically anchored to a place in the text with a [4mmark,[24m  which
     is a small integer, a symbol, or arbitrary user‐specified text.

     [1m\**    [22mPlace  an [4mautomatic[24m [4mnumber,[24m an automatically generated numeric foot‐
            note mark, in the text.  Each time this string is interpolated,  the
            number it produces increments by one.  Automatic numbers start at 1.
            This is a Berkeley extension.

     Enclose the footnote text in [1mFS [22mand [1mFE [22mmacro calls to set it at the nearest
     available “foot”, or bottom, of a text column or page.

     [1m.FS [22m[[4mmark[24m]
            Begin  a  footnote.  The [1mFS-MARK [22mhook (see below) is called with any
            supplied [4mmark[24m argument, which is then also placed at  the  beginning
            of  the  footnote  text.  If [4mmark[24m is omitted, the next pending auto‐
            matic number enqueued by interpolation of the [1m* [22mstring is used,  and
            if none exists, nothing is prefixed.

     [1m.FE    [22mEnd footnote text.

     [4mgroff[24m  [4mms[24m provides a hook macro, [1mFS-MARK[22m, for user‐determined operations to
     be performed when the [1mFS [22mmacro is called.  It is passed the same  arguments
     as  [1mFS [22mitself.  By default, this macro has an empty definition.  [1mFS-MARK [22mis
     a GNU extension.

     Footnote text is formatted as paragraphs are, using  analogous  parameters.
     The  registers  [1mFI[22m, [1mFPD[22m, [1mFPS[22m, and [1mFVS [22mcorrespond to [1mPI[22m, [1mPD[22m, [1mPS[22m, and [1mVS[22m, re‐
     spectively; [1mFPD[22m, [1mFPS[22m, and [1mFVS [22mare GNU extensions.

     The [1mFF [22mregister controls the formatting of automatically numbered  footnote
     paragraphs,  and those for which [1mFS [22mis given a [4mmark[24m argument, at the bottom
     of a column or page as follows.

            0      Set an automatic number, or a specified [1mFS [4m[22mmark[24m argument,  as
                   a superscript (on typesetters) or surrounded by square brack‐
                   ets  (on  terminals).   The footnote paragraph is indented as
                   with [1mPP [22mif there is an [1mFS [22margument or  an  automatic  number,
                   and as with [1mLP [22motherwise.  This is the default.

            1      As  [1m0[22m,  but set [4mmark[24m as regular text, and follow an automatic
                   number with a period.

            2      As [1m1[22m, but without indentation (like [1mLP[22m).

            3      As [1m1[22m, but set the footnote paragraph with [4mmark[24m hanging  (like
                   [1mIP[22m).

   [1mLanguage and localization[0m
     [4mgroff[24m  [4mms[24m provides several strings that you can customize for your own pur‐
     poses, or redefine to adapt the macro package to languages other than  Eng‐
     lish.  It is already localized for Czech, German, Spanish, French, Italian,
     Polish,  Russian, and Swedish.  Load the desired localization macro package
     after [4mms[24m; see ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\.

                [1mString            Default[0m
            ───────────────────────────────────
            \*[REFERENCES]   References
            \*[ABSTRACT]     \f[I]ABSTRACT\f[]
            \*[TOC]          Table of Contents
            \*[MONTH1]       January
            \*[MONTH2]       February
            \*[MONTH3]       March
            \*[MONTH4]       April
            \*[MONTH5]       May
            \*[MONTH6]       June
            \*[MONTH7]       July
            \*[MONTH8]       August
            \*[MONTH9]       September
            \*[MONTH10]      October
            \*[MONTH11]      November
            \*[MONTH12]      December
            ───────────────────────────────────
     The default for [1mABSTRACT [22mincludes font selection escape  sequences  to  set
     the word in italics.

   [1mHeaders and footers[0m
     There  are  multiple ways to produce headers and footers.  One is to define
     the strings [1mLH[22m, [1mCH[22m, and [1mRH [22mto set the left, center, and right headers,  re‐
     spectively;  and [1mLF[22m, [1mCF[22m, and [1mRF [22mto set the left, center, and right footers.
     This approach suffices for documents that do not distinguish odd‐ and even‐
     numbered pages.

     Another method is to call macros that set headers or footers  for  odd‐  or
     even‐numbered pages.  Each such macro takes a delimited argument separating
     the  left,  center,  and right header or footer texts from each other.  You
     can replace the neutral apostrophes (') shown below with any character  not
     appearing  in  the header or footer text.  These macros are Berkeley exten‐
     sions.

     [1m.OH [22m'[4mleft[24m'[4mcenter[24m'[4mright[24m'
     [1m.OF [22m'[4mleft[24m'[4mcenter[24m'[4mright[24m'
     [1m.EH [22m'[4mleft[24m'[4mcenter[24m'[4mright[24m'
     [1m.EF [22m'[4mleft[24m'[4mcenter[24m'[4mright[24m'
            The [1mOH [22mand [1mEH [22mmacros define headers for odd‐ (recto)  and  even‐num‐
            bered (verso) pages, respectively; the [1mOF [22mand [1mEF [22mmacros define foot‐
            ers for them.

     With  either  method, a percent sign [1m% [22min header or footer text is replaced
     by the current page number.  By default, [4mms[24m places no header on a page num‐
     bered “1” (regardless of its number format).

     [1m.P1    [22mTypeset the header even on page 1.  To be effective, this macro must
            be called before the header trap is sprung on any page numbered “1”.
            This is a Berkeley extension.

     For even greater flexibility, [4mms[24m is designed to permit the redefinition  of
     the  macros  that are called when formatter traps that ordinarily cause the
     headers and footers to be output are sprung.  [1mPT [22m(“page trap”) is called by
     [4mms[24m when the header is to be written, and [1mBT [22m(“bottom trap”) when the footer
     is to be.  The [4mgroff[24m page location trap that  [4mms[24m  sets  up  to  format  the
     header  also  calls the (normally undefined) [1mHD [22mmacro after [1mPT[22m; you can de‐
     fine [1mHD [22mif you need additional processing after setting the header.  The [1mHD[0m
     hook is a Berkeley extension.  Any such macros you (re)define  must  imple‐
     ment any desired specialization for odd‐, even‐, or first numbered pages.

   [1mTab stops[0m
     Use the [1mta [22mrequest to set tab stops as needed.

     [1m.TA    [22mReset  the tab stops to the [4mms[24m default (every 5 ens).  Redefine this
            macro to create a different set of default tab stops.

   [1mMargins[0m
     Control margins using the registers summarized in the “Margins” portion  of
     the  table  in section “Document control settings” above.  There is no set‐
     ting for the right margin; the combination of page offset [1m\n[PO]  [22mand  line
     length [1m\n[LL] [22mdetermines it.

   [1mMultiple columns[0m
     [4mms[24m can set text in as many columns as reasonably fit on the page.  The fol‐
     lowing  macros  force  a page break if a multi‐column layout is active when
     they are called.  [1m\n[MINGW] [22mis the default minimum gutter width;  it  is  a
     GNU  extension.   When  multiple columns are in use, keeps and the [1mHORPHANS[0m
     and [1mPORPHANS [22mregisters work with respect to column breaks instead  of  page
     breaks.

     [1m.1C    [22mArrange page text in a single column (the default).

     [1m.2C    [22mArrange page text in two columns.

     [1m.MC [22m[[4mcolumn‐width[24m [[4mgutter‐width[24m]]
            Arrange page text in multiple columns.  If you specify no arguments,
            it  is  equivalent  to the [1m2C [22mmacro.  Otherwise, [4mcolumn‐width[24m is the
            width of each column and [4mgutter‐width[24m is the  minimum  distance  be‐
            tween columns.

   [1mCreating a table of contents[0m
     Define  an  entry to appear in the table of contents by bracketing its text
     between calls to the [1mXS [22mand [1mXE [22mmacros.  A typical application  is  to  call
     them  immediately  after  [1mNH [22mor [1mSH [22mand repeat the heading text within them.
     The [1mXA [22mmacro, used within [1mXS[22m/[1mXE [22mpairs, supplements an entry——for  instance,
     when  it  requires  multiple output lines, whether because a heading is too
     long to fit or because style dictates that page numbers  not  be  repeated.
     You  may  wish to indent the text thus wrapped to correspond to its heading
     depth; this can be done in the entry text by prefixing it with tabs or hor‐
     izontal motion escape sequences, or by providing a second argument  to  the
     [1mXA [22mmacro.  [1mXS [22mand [1mXA [22mautomatically associate the page number where they are
     called  with the text following them, but they accept arguments to override
     this behavior.  At the end of the document, call [1mTC [22mor [1mPX [22mto emit the table
     of contents; [1mTC [22mresets the page number to [1mi [22m(Roman numeral one),  and  then
     calls [1mPX[22m.  All of these macros are Berkeley extensions.

     [1m.XS [22m[[4mpage‐number[24m]
     [1m.XA [22m[[4mpage‐number[24m [[4mindentation[24m]]
     [1m.XE    [22mBegin, supplement, and end a table of contents entry.  Each entry is
            associated  with  [4mpage‐number[24m (otherwise the current page number); a
            [4mpage‐number[24m of “[1mno[22m” prevents a leader and  page  number  from  being
            emitted  for that entry.  Use of [1mXA [22mwithin [1mXS[22m/[1mXE [22mis optional; it can
            be repeated.  If [4mindentation[24m is present, a supplemental entry is in‐
            dented by that amount; ens are assumed  if  no  unit  is  indicated.
            Text  on input lines between [1mXS [22mand [1mXE [22mis stored for later recall by
            [1mPX[22m.

     [1m.PX [22m[[1mno[22m]
            Switch to single‐column layout.  Unless “[1mno[22m”  is  specified,  center
            and  interpolate [1m\*[TOC] [22min bold and two points larger than the body
            text.  Emit the table of contents entries.

     [1m.TC [22m[[1mno[22m]
            Set the page number to 1, the page number format to lowercase  Roman
            numerals, and call [1mPX [22m(with a “[1mno[22m” argument, if present).

     The remaining features in this subsection are GNU extensions.  [4mgroff[24m [4mms[24m ob‐
     viates  the need to repeat heading text after [1mXS [22mcalls.  Call [1mXN [22mand [1mXH [22maf‐
     ter [1mNH [22mand [1mSH[22m, respectively.  Text to be appended to the formatted  section
     heading, but not to appear in the table of contents entry, can follow these
     calls.

     [1m.XN [4m[22mheading‐text[0m
            Format [4mheading‐text[24m and create a corresponding table of contents en‐
            try; the indentation is computed from the [4mdepth[24m argument of the pre‐
            ceding [1mNH [22mcall.

     [1m.XH [4m[22mdepth[24m [4mheading‐text[0m
            As [1mXN[22m, but use [4mdepth[24m to determine the indentation.

     [4mgroff[24m  [4mms[24m  encourages  customization of table of contents entry production.
     (Re‐)define any of the following macros as desired.

     [1m.XN-REPLACEMENT [4m[22mheading‐text[0m
     [1m.XH-REPLACEMENT [4m[22mdepth[24m [4mheading‐text[0m
            These hook macros implement [1mXN [22mand [1mXH[22m, and call [1mXN-INIT [22mand [1mXH-INIT[22m,
            respectively, then call [1mXH-UPDATE-TOC [22mwith the arguments given them.

     [1m.XH-INIT[0m
     [1m.XN-INIT[0m
            These hook macros do nothing by default.

     [1m.XH-UPDATE-TOC [4m[22mdepth[24m [4mheading‐text[0m
            Bracket [4mheading‐text[24m with [1mXS [22mand [1mXE [22mcalls, indenting it by 2 ens per
            level of [4mdepth[24m beyond the first.

     You can customize the style of the leader that bridges each table  of  con‐
     tents entry with its page number; define the [1mTC-LEADER [22mspecial character by
     using the [1mchar [22mrequest.  A typical leader combines the dot glyph “[1m.[22m” with a
     horizontal  motion  escape  sequence  to spread the dots.  The width of the
     page number field is stored in the [1mTC-MARGIN [22mregister.

[1mDifferences from AT&T [4mms[0m
     The [4mgroff[24m [4mms[24m macros are an  independent  reimplementation,  using  no  AT&T
     code.   Since  they  take advantage of the extended features of [4mgroff[24m, they
     cannot be used with AT&T [4mtroff[24m.  [4mgroff[24m [4mms[24m supports features described above
     as Berkeley and Research Tenth Edition Unix extensions, and adds several of
     its own.

     •  The internals of [4mgroff[24m [4mms[24m differ from those of AT&T [4mms[24m.  Documents  that
        depend  upon  implementation  details of AT&T [4mms[24m may not format properly
        with [4mgroff[24m [4mms[24m.  Such details include macros whose function was not docu‐
        mented in the AT&T [4mms[24m manual (“Typing Documents on the UNIX System:  Us‐
        ing the -ms Macros with Troff and Nroff”, M. E. Lesk, Bell Laboratories,
        1978).

     •  The  error‐handling  policy  of [4mgroff[24m [4mms[24m is to detect and report errors,
        rather than to ignore them silently.

     •  Research Tenth Edition Unix supported [1mP1[22m/[1mP2 [22mmacros to bracket code exam‐
        ples; [4mgroff[24m [4mms[24m does not.

     •  [4mgroff[24m [4mms[24m does not work in  GNU  [4mtroff[24m’s  AT&T  compatibility  mode.   If
        loaded when that mode is enabled, it aborts processing with a diagnostic
        message.

     •  Multiple  line  spacing is not supported.  Use a larger vertical spacing
        instead.

     •  [4mgroff[24m [4mms[24m uses the same header and footer  defaults  in  both  [4mnroff[24m  and
        [4mtroff[24m  modes as AT&T [4mms[24m does in [4mtroff[24m mode; AT&T’s default in [4mnroff[24m mode
        is to put the date,  in  U.S.  traditional  format  (e.g.,  “January  1,
        2021”), in the center footer (the [1mCF [22mstring).

     •  Many [4mgroff[24m [4mms[24m macros, including those for paragraphs, headings, and dis‐
        plays,  cause  a reset of paragraph rendering parameters, and may change
        the indentation; they do so not by incrementing or decrementing it,  but
        by  setting  it  absolutely.  This can cause problems for documents that
        define additional macros of their own that manipulate indentation.   Use
        [1mRS [22mand [1mRE [22minstead of the [1min [22mrequest.

     •  AT&T [4mms[24m interpreted the values of the registers [1mPS [22mand [1mVS [22min points, and
        did not support the use of scaling units with them.  [4mgroff[24m [4mms[24m interprets
        values  of  the  registers  [1mPS[22m,  [1mVS[22m,  [1mFPS[22m,  and  [1mFVS[22m, equal to or larger
        than 1,000 (one thousand) as  decimal  fractions  multiplied  by  1,000.
        (Register  values are converted to and stored as basic units.  See “Mea‐
        surements” in the [4mgroff[24m Texinfo manual or in ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\).  This  threshold
        makes  use  of  a scaling unit with these parameters practical for high‐
        resolution devices while preserving  backward  compatibility.   It  also
        permits  expression  of  non‐integral  type  sizes.  For example, “[1mgroff[0m
        [1m-rPS=10.5p[22m” at the shell prompt is equivalent to placing “[1m.nr PS  10.5p[22m”
        at the beginning of the document.

     •  AT&T  [4mms[24m’s [1mAU [22mmacro supported arguments whose values were used with some
        non‐[1mRP [22mdocument types; that of [4mgroff[24m [4mms[24m does not.

     •  Right‐aligned displays are available.  The AT&T [4mms[24m manual observes  that
        “it  is  tempting to assume that “[1m.DS R[22m” will right adjust lines, but it
        doesn’t work”.  In [4mgroff[24m [4mms[24m, it does.

     •  To make [4mgroff[24m [4mms[24m use the default page offset (which also  specifies  the
        left  margin),  the  [1mPO  [22mregister must stay undefined until the first [4mms[0m
        macro is called.  This implies that [1m\n[PO] [22mshould not be used  early  in
        the document, unless it is changed also: accessing an undefined register
        automatically defines it.

     •  [4mgroff[24m  [4mms[24m supports the [1mPN [22mregister, but it is not necessary; you can ac‐
        cess the page number via the usual [1m% [22mregister and invoke the [1maf  [22mrequest
        to  assign a different format to it if desired.  (If you redefine the [4mms[0m
        [1mPT [22mmacro and desire special  treatment  of  certain  page  numbers——like
        “[1m1[22m”——you  may  need  to handle a non‐Arabic page number format, as [4mgroff[0m
        [4mms[24m’s [1mPT [22mdoes; see the macro package source.  [4mgroff[24m  [4mms[24m  aliases  the  [1mPN[0m
        register to [1m%[22m.)

     •  The  AT&T [4mms[24m manual documents registers [1mCW [22mand [1mGW [22mas setting the default
        column width and “intercolumn gap”, respectively, and which applied when
        [1mMC [22mwas called with fewer than two arguments.  [4mgroff[24m [4mms[24m instead treats [1mMC[0m
        without arguments as synonymous with [1m2C[22m; there is thus no occasion for a
        default column width register.  Further, the [1mMINGW [22mregister and the sec‐
        ond argument to [1mMC [22mspecify a [4mminimum[24m  space  between  columns,  not  the
        fixed gutter width of AT&T [4mms[24m.

     •  The  AT&T [4mms[24m manual did not document the [1mQI [22mregister; Berkeley and [4mgroff[0m
        [4mms[24m do.

     •  [4mgroff[24m [4mms[24m sets the register [1mGS [22mto 1; the AT&T [4mms[24m package does not use it.
        A document can test its value to determine whether it is being formatted
        with [4mgroff[24m [4mms[24m or another implementation.

   [1mUnix Version 7 macros unimplemented by [4mgroff[24m [4mms[0m
     Several macros described in the Unix Version 7 [4mms[24m documentation  are  unim‐
     plemented by [4mgroff[24m [4mms[24m because they are specific to the requirements of doc‐
     uments produced internally by Bell Laboratories, some of which also require
     a glyph for the Bell System logo that [4mgroff[24m does not support.  These macros
     implemented  several  document  type formats ([1mEG[22m, [1mIM[22m, [1mMF[22m, [1mMR[22m, [1mTM[22m, [1mTR[22m), were
     meaningful only in conjunction with the use of certain document types  ([1mAT[22m,
     [1mCS[22m,  [1mCT[22m,  [1mOK[22m,  [1mSG[22m), stored the postal addresses of Bell Labs sites ([1mHO[22m, [1mIH[22m,
     [1mMH[22m, [1mPY[22m, [1mWH[22m), or lacked a stable definition over time ([1mUX[22m).

[1mLegacy features[0m
     [4mgroff[24m [4mms[24m retains some legacy features solely to support formatting of  his‐
     torical  documents;  contemporary ones should not use them because they can
     render poorly.  See ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\ instead.

   [1mAT&T [4mms[24m accent mark strings[0m
     AT&T [4mms[24m defined accent mark strings as follows.

     [1mString   Description[0m
     ──────────────────────────────────────────────────────
     \*[']    Apply acute accent to subsequent glyph.
     \*[`]    Apply grave accent to subsequent glyph.
     \*[:]    Apply dieresis (umlaut) to subsequent glyph.
     \*[^]    Apply circumflex accent to subsequent glyph.
     \*[~]    Apply tilde accent to subsequent glyph.
     \*[C]    Apply caron to subsequent glyph.
     \*[,]    Apply cedilla to subsequent glyph.

   [1mBerkeley [4mms[24m accent mark and glyph strings[0m
     Berkeley [4mms[24m offered an [1mAM [22mmacro; calling it redefined the AT&T accent  mark
     strings  (except for [1m\*C[22m), applied them to the [4mpreceding[24m glyph, and defined
     additional strings, some for spacing glyphs.

     [1m.AM    [22mEnable alternative accent mark and glyph‐producing strings.

     [1mString   Description[0m
     ───────────────────────────────────────────────────────────────
     \*[']    Apply acute accent to preceding glyph.
     \*[`]    Apply grave accent to preceding glyph.
     \*[:]    Apply dieresis (umlaut) to preceding glyph.
     \*[^]    Apply circumflex accent to preceding glyph.
     \*[~]    Apply tilde accent to preceding glyph.
     \*[,]    Apply cedilla to preceding glyph.
     \*[/]    Apply stroke (slash) to preceding glyph.
     \*[v]    Apply caron to preceding glyph.
     \*[_]    Apply macron to preceding glyph.
     \*[.]    Apply underdot to preceding glyph.
     \*[o]    Apply ring accent to preceding glyph.
     ───────────────────────────────────────────────────────────────
     \*[?]    Interpolate inverted question mark.
     \*[!]    Interpolate inverted exclamation mark.
     \*[8]    Interpolate small letter sharp s.
     \*[q]    Interpolate small letter o with hook accent (ogonek).
     \*[3]    Interpolate small letter yogh.
     \*[d-]   Interpolate small letter eth.
     \*[D-]   Interpolate capital letter eth.
     \*[th]   Interpolate small letter thorn.
     \*[TH]   Interpolate capital letter thorn.
     \*[ae]   Interpolate small ae ligature.
     \*[AE]   Interpolate capital ae ligature.
     \*[oe]   Interpolate small oe ligature.
     \*[OE]   Interpolate capital oe ligature.

[1mNaming conventions[0m
     External names available to documents that use the [4mgroff[24m [4mms[24m macros  contain
     only  uppercase  letters and digits.  The package reserves for internal use
     the following identifiers:

     •  those containing the characters [1m*[22m, [1m@[22m, and [1m:[22m; and

     •  those containing only uppercase letters and digits.

     When selecting a name for your document’s own macros, strings,  and  regis‐
     ters, avoid those reserved by [4mgroff[24m [4mms[24m and those defined by GNU [4mtroff[24m.  See
     ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\ for complete lists thereof.

     [4mgroff[24m  [4mms[24m  organizes  most  of its internal names into modules.  The naming
     convenion is as follows.

     •  Names used only within one module are of the form [4mmodule[24m[1m*[4m[22mname[24m.

     •  Names used outside the module in which they are defined are of the  form
        [4mmodule[24m[1m@[4m[22mname[24m.

     •  Names   associated  with  a  particular  environment  are  of  the  form
        [4menvironment[24m[1m:[4m[22mname[24m; these are used only within the [1mpar [22mmodule.

     •  [4mname[24m does not have a module prefix.

     •  Names constructed to implement arrays are of the form [4marray[24m[1m![4m[22mindex[24m.

[1mFiles[0m
     [4m/usr/share/groff/1.24.1/tmac/s.tmac[0m
            implements the package.

     [4m/usr/share/groff/1.24.1/tmac/refer-ms.tmac[0m
            implements ]8;;man:refer(1)\[4mrefer[24m(1)]8;;\ support for [4mms[24m.

     [4m/usr/share/groff/1.24.1/tmac/ms.tmac[0m
            is a wrapper enabling the package to be loaded with the  option  “[1m-m[0m
            [1mms[22m”.

[1mAuthors[0m
     The GNU version of the [4mms[24m macro package was written by James Clark and con‐
     tributors.   This document was written by Clark, ]8;;mailto:lkollar@despammed.com\Larry Kollar]8;;\, and ]8;;mailto:g.branden.robinson@gmail.com\G. Bran‐
     den Robinson]8;;\.

[1mSee also[0m
     A manual is available in source and rendered form.  On your system, it  may
     be compressed and/or available in additional formats.

     [4m/usr/share/doc/groff-1.24.1/ms.ms[0m
     [4m/usr/share/doc/groff-1.24.1/ms.ps[0m
            “Using [4mgroff[24m with the [4mms[24m Macro Package”; Larry Kollar and G. Branden
            Robinson.

     [4m/usr/share/doc/groff-1.24.1/msboxes.ms[0m
     [4m/usr/share/doc/groff-1.24.1/msboxes.pdf[0m
            “Using  PDF  boxes  with  [4mgroff[24m  and  the  [4mms[24m  macros”;  Deri James.
            [1mBOXSTART [22mand [1mBOXSTOP [22mmacros are available via the  [4msboxes[24m  extension
            package, enabling colored, bordered boxes when the [1mpdf [22moutput device
            is used.

     [4mGroff:[24m  [4mThe[24m [4mGNU[24m [4mImplementation[24m [4mof[24m [4mtroff[24m, by Trent A. Fisher and Werner Lem‐
     berg, is the primary [4mgroff[24m manual.  You can browse  it  interactively  with
     “info groff”.

     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\, ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\, ]8;;man:pic(1)\[4mpic[24m(1)]8;;\, ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\, ]8;;man:refer(1)\[4mrefer[24m(1)]8;;\

groff 1.24.1                       2026‐03‐20                        [4mgroff_ms[24m(7)
────────────────────────────────────────────────────────────────────────────────
[4mgroff_rfc1345[24m(7)        Miscellaneous Information Manual        [4mgroff_rfc1345[24m(7)

[1mName[0m
     groff_rfc1345 - special character names from RFC 1345 and Vim digraphs

[1mDescription[0m
     The  file  [4mrfc1345.tmac[24m  defines  special  character  escape  sequences for
     ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\ based on the glyph mnemonics specified in RFC 1345 and the digraph
     table of the text editor Vim.  Each escape sequence translates to a Unicode
     code point, and will render correctly if the underlying font is  a  Unicode
     font that covers the code point.

     For  example,  “[1m\[Rx][22m”  is  the “recipe” or “prescription take” symbol, and
     maps to the code point U+211E.  [4mgroff[24m lets you write it as “[1m\[u211E][22m”,  but
     “[1m\[Rx][22m” is more mnemonic.

     For  a  list of the glyph names provided, please see the file [4mrfc1345.tmac[24m,
     which contains definitions of the form
            .char \[Rx] \[u211E]    \" PRESCRIPTION TAKE
     where [1m.char[22m’s first argument defines a [4mgroff[24m special character  escape  se‐
     quence with a mnemonic glyph name, its second argument is a special charac‐
     ter  escape sequence based on the code point, and the comment describes the
     glyph defined.

     The RFC 1345 glyph names cover a wide range of Unicode code points, includ‐
     ing  supplemental  Latin,  Greek,  Cyrillic,  Hebrew,   Arabic,   Hiragana,
     Katakana,  and  Bopomofo letters, punctuation, math notation, currency sym‐
     bols, industrial and entertainment icons, and box‐drawing symbols.

     The Vim digraph table is largely a subset of RFC  1345  (being  limited  to
     two‐character  mnemonics),  but,  as  a  newer implementation, adds several
     mnemonics not specified in the RFC (Latin capital and small letters W and Y
     with grave accent,  bullet,  horizontal  ellipsis,  quadruple  prime,  “ap‐
     proaches  the limit”, and two mappings each for the Euro and rouble signs).
     These have also been added to [4mrfc1345.tmac[24m.

     [4mrfc1345.tmac[24m contains about 1,700 glyph names.  It is not an error to  load
     [4mrfc1345.tmac[24m  if your font does not have all the glyphs, as long as it con‐
     tains the glyphs that you actually use in your document.

     The RFC 1345 mnemonics are not identical in every case to the mappings  for
     special  character  glyph  names  that  are built in to [4mgroff[24m; for example,
     “[1m\[<<][22m” means the “much less than” sign (U+226A) when [4mrfc1345.tmac[24m  is  not
     loaded and this special character is not otherwise defined by a document or
     macro package.  [4mrfc1345.tmac[24m redefines “[1m\[<<][22m” to the “left‐pointing double
     angle  quotation  mark”  (U+00AB).   See ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\ for the full list of
     predefined special character escape sequences.

   [1mUsage[0m
     Load the [4mrfc1345.tmac[24m file.  This  can  be  done  by  either  adding  “[1m.mso[0m
     [1mrfc1345.tmac[22m”  to  your  document  before the first use of any of the glyph
     names the macro file defines, or by using the ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ option “[1m-m  rfc1345[22m”
     from the shell.

[1mBugs[0m
     As  the [4mgroff[24m Texinfo manual notes, “[o]nly the current font is checked for
     ligatures and kerns; neither special fonts nor entities  defined  with  the
     [1mchar [22mrequest (and its siblings) are taken into account.”  Many of the char‐
     acters  defined in [4mrfc1345.tmac[24m are accented Latin letters, and will be af‐
     fected by this deficiency, ]8;;https://savannah.gnu.org/bugs/?59932\producing subpar typography]8;;\.

[1mFiles[0m
     [4m/usr/share/groff/1.24.1/tmac/rfc1345.tmac[0m
            implements the character mappings.

[1mAuthors[0m
     [4mrfc1345.tmac[24m was contributed by ]8;;mailto:ds26gte@yahoo.com\Dorai Sitaram]8;;\.

[1mSee also[0m
     ]8;;https://tools.ietf.org/html/rfc1345\RFC 1345]8;;\, by Keld Simonsen, June 1992.

     The Vim digraph table  can  be  listed  using  the  ]8;;man:vim(1)\[4mvim[24m(1)]8;;\  command  “[1m:help[0m
     [1mdigraph-table[22m”.

     ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\

groff 1.24.1                       2026‐03‐20                   [4mgroff_rfc1345[24m(7)
────────────────────────────────────────────────────────────────────────────────
[4mgroff_trace[24m(7)          Miscellaneous Information Manual          [4mgroff_trace[24m(7)

[1mName[0m
     groff_trace - macros for debugging GNU [4mroff[24m documents

[1mSynopsis[0m
     [1mgroff -m trace [22m[[4moption[24m ...] [[4mfile[24m ...]

[1mDescription[0m
     [4mtrace[24m  is  a macro package for the ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\ document formatting system, de‐
     signed as an aid for debugging documents written in its language.   It  is‐
     sues  a  message  to  the standard error stream upon entry to and exit from
     each macro call.  This can ease the process of isolating  errors  in  macro
     definitions.

     Activate  the  package  by specifying the command‐line option “[1m-m trace[22m” to
     the formatter program (often ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\).  You can achieve finer  control  by
     including the macro file within the document; invoke the [1mmso [22mrequest, as in
     “[1m.mso  trace.tmac[22m”.  Only macros that are defined after this invocation are
     traced.  If the [1mtrace-full [22mregister is set to a true  value,  as  with  the
     command‐line  option  “[1m-r  trace-full=1[22m”,  register and string assignments,
     along with some other requests, are traced also.  If another macro  package
     should be traced as well, specify it after “[1m-m trace[22m” on the command line.

     The macro file [4mtrace.tmac[24m is unusual because it does not contain any macros
     to  be  called by a user.  Instead, [4mgroff[24m’s macro definition and alteration
     facilities are wrapped such that they display diagnostic messages.

   [1mLimitations[0m
     Because [4mtrace.tmac[24m wraps the [1mde [22mrequest (and its cousins), macro  arguments
     are expanded one level more.  This causes problems if an argument uses four
     or more backslashes to delay interpretation of an escape sequence.  For ex‐
     ample, the macro call
            .foo \\\\n[bar]
     normally passes “\\n[bar]” to macro “foo”, but with [1mde [22mredefined, it passes
     “\n[bar]” instead.

     The  solution  to this problem is to use [4mgroff[24m’s [1m\E [22mescape sequence, an es‐
     cape character that is not interpreted in copy mode.
            .foo \En[bar]

[1mFiles[0m
     [4m/usr/share/groff/1.24.1/tmac/trace.tmac[0m
            implements the package.

[1mExamples[0m
     We will illustrate [4mtrace.tmac[24m using the shell’s “here document” feature  to
     supply  [4mgroff[24m  with  a document on the standard input stream.  Since we are
     interested only in diagnostic messages  appearing  on  the  standard  error
     stream,  we discard the formatted output by redirecting the standard output
     stream to [4m/dev/null[24m.

   [1mObserving nested macro calls[0m
     Macro calls can be nested, even with themselves.   Tracing  recurses  along
     with them; this feature can help to detangle complex call stacks.

            $ [1mcat <<EOF | groff -m trace > /dev/null[0m
            [1m.de countdown[0m
            [1m. nop \\$1[0m
            [1m. nr count (\\$1 ‐ 1)[0m
            [1m. if \\n[count] .countdown \\n[count][0m
            [1m..[0m
            [1m.countdown 3[0m
            [1mblastoff[0m
            [1mEOF[0m
             *** .de countdown
             *** de trace enter: .countdown "3"
              *** de trace enter: .countdown "2"
               *** de trace enter: .countdown "1"
               *** trace exit: .countdown "1"
              *** trace exit: .countdown "2"
             *** trace exit: .countdown "3"

   [1mTracing with the mso request[0m
     Now  let  us  activate tracing within the document, not with a command‐line
     option.  We might do so when employing a macro package like [4mms[24m or  [4mmom[24m,  to
     avoid distraction by traces of macros we didn’t write.

            $ [1mcat <<EOF | groff ‐ms > /dev/null[0m
            [1m.LP[0m
            [1mThis is my introductory paragraph.[0m
            [1m.mso trace.tmac[0m
            [1m.de Mymac[0m
            [1m..[0m
            [1m.Mymac[0m
            [1m.PP[0m
            [1mLet us review the existing literature.[0m
            [1mEOF[0m
             *** .de Mymac
             *** de trace enter: .Mymac
             *** trace exit: .Mymac

     As  tracing  was  not yet active when the macros “LP” and “PP” were defined
     (by [4ms.tmac[24m), their calls were not traced; contrast with the macro “Mymac”.

[1mAuthors[0m
     [4mtrace.tmac[24m was written by James Clark.  This document was written by  ]8;;mailto:groff-bernd.warken-72@web.de\Bernd
     Warken]8;;\ and ]8;;mailto:g.branden.robinson@gmail.com\G. Branden Robinson]8;;\.

[1mSee also[0m
     [4mGroff:[24m  [4mThe[24m [4mGNU[24m [4mImplementation[24m [4mof[24m [4mtroff[24m, by Trent A. Fisher and Werner Lem‐
     berg, is the primary [4mgroff[24m manual.  You can browse  it  interactively  with
     “info groff”.

     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\
            gives an overview of the [4mgroff[24m document formatting system.

     ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\
            supplies details of the [1m-m [22mcommand‐line option.

     ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\
            offers a survey of [4mgroff[24m macro packages.

     ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\
            is a reference manual for the [4mgroff[24m language.

groff 1.24.1                       2026‐03‐20                     [4mgroff_trace[24m(7)
────────────────────────────────────────────────────────────────────────────────
[4mgroff_www[24m(7)            Miscellaneous Information Manual            [4mgroff_www[24m(7)

[1mName[0m
     groff_www - GNU [4mroff[24m macros for authoring web pages

[1mSynopsis[0m
     [1mgroff -m www [22m[[4moption[24m ...] [[4mfile[24m ...]

[1mDescription[0m
     This  manual page describes the GNU [4mwww[24m macro package, which is part of the
     ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\ document formatting system.   This  macro  file  is  automatically
     loaded by the default [4mtroffrc[24m file when the formatter (usually ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\) is
     called with either of the options “[1m-T html[22m” or “[1m-T xhtml[22m”.  The HTML output
     driver ]8;;man:grohtml(1)\[4mgrohtml[24m(1)]8;;\ is in a beta state; [4mgroff[24m distributes these macros to en‐
     courage its testing.

     Macro       Meaning
     ────────────────────────────────────────────────────────────
     [1mJOBNAME     [22msplit output into multiple files
     [1mHX          [22mautomatic heading level cut‐off
     [1mBCL         [22mspecify colours on a web page
     [1mBGIMG       [22mspecify background image
     [1mURL         [22mcreate a URL using two parameters
     [1mMTO         [22mcreate an HTML email address
     [1mTAG         [22mgenerate an HTML name
     [1mIMG         [22minclude an image file
     [1mPIMG        [22minclude PNG image
     [1mMPIMG       [22mplace PNG on the margin and wrap text around it
     [1mHnS         [22mbegin heading
     [1mHnE         [22mend heading
     [1mLK          [22memit automatically collected links
     [1mHR          [22mproduce a horizontal rule
     [1mNHR         [22msuppress automatic generation of rules
     [1mHTL         [22mrecord document title as HTML metadata only
     [1mHEAD        [22madd data to <head> block
     [1mULS         [22munordered list begin
     [1mULE         [22munordered list end
     [1mOLS         [22mordered list begin
     [1mOLE         [22mordered list end
     [1mDLS         [22mdefinition list begin
     [1mDLE         [22mdefinition list end
     [1mLI          [22minsert a list item
     [1mDC          [22mgenerate a drop capital
     [1mHTML        [22mtransmit raw HTML to output driver
     [1mCDS         [22mcode example begin
     [1mCDE         [22mcode example end
     [1mALN         [22mplace links on left of main text
     [1mLNS         [22mstart two‐column table with links on the left
     [1mLNE         [22mend two‐column table started with [1m.LNS[0m
     [1mLINKSTYLE   [22minitialize default URL attributes

[1mMacros[0m
     [1mJOBNAME [4m[22mfile‐name‐stem[0m
              Split output into multiple HTML files.  In [4mms[24m documents, a file is
              split  whenever  an [1m.SH [22mor “[1m.NH 1[22m” call is encountered.  Its argu‐
              ment is the file name stem used for output files.  This option  is
              equivalent to [4mgrohtml[24m’s [1m-j [22moption.

     [1mHX [4m[22mn[24m     Set  section heading level above which [4mgrohtml[24m is not to automati‐
              cally generate links to  [4mn.[24m   For  example,  when  used  with  the
              ]8;;man:groff_ms(7)\[4mgroff_ms[24m(7)]8;;\  package, “[1m.HX 2[22m” causes [4mgrohtml[24m to generate a list of
              links for [4mms[24m macro calls “[1m.NH 1[22m” and “[1m.NH 2[22m” but not for “[1m.NH  3[22m”,
              whereas “[1m.HX 0[22m” generates no hyperlinks to section headings.  Giv‐
              ing [4mgroff[24m the option “[1m-P -l[22m” disables automatic heading linkage.

     [1mBCL [4m[22mforeground[24m [4mbackground[24m [4mactive[24m [4mnot‐visited[24m [4mvisited[0m
              Configure  colours  used for page foreground, page background, ac‐
              tive hypertext link, hypertext links not yet visited, and  visited
              hypertext links.

     [1mBGIMG [4m[22mfile[0m
              Set the background image to [4mfile.[0m

     [1mURL [4m[22murl[24m [[4mlink‐text[24m [[4mpost[24m]]
              Generate a hyperlink to [4murl[24m with optional [4mlink‐text[24m followed imme‐
              diately by non‐linked text [4mpost.[0m

              If  [4mlink‐text[24m  is  absent, [4murl[24m is formatted as the link text.  Hy‐
              phenation is disabled while  formatting  a  URL;  insert  explicit
              break points with the [1m\: [22mescape sequence.

     [1mMTO [4m[22maddress[24m [[4mlink‐text[24m [[4mpost[24m]]
              Generate  an  email  hyperlink  to [4maddress[24m with optional [4mlink‐text[0m
              followed immediately by non‐linked text [4mpost.[0m

              If [4mlink‐text[24m is absent, [4maddress[24m is formatted  as  the  link  text.
              Hyphenation  is  disabled  while formatting a URL; insert explicit
              break points with the [1m\: [22mescape sequence.

     [1mTAG [4m[22mname[0m
              Generate an anchor [4mname[24m marking its location in the document as  a
              target for hyperlinks.

     [1mIMG [4m[22mfile‐name[24m [[1m-C[22m|[1m-L[22m|[1m-R[22m] [[4mwidth[24m [[4mheight[24m]]
              Insert  graphical  image  [4mfile‐name.[24m  The optional second argument
              aligns the image to the center ([1m-C[22m; default), left ([1m-L[22m), or  right
              ([1m-R[22m).  The optional [4mwidth[24m defaults to 100 units (in the context of
              the HTML renderer) and the optional [4mheight[24m to the same measurement
              as [4mwidth[24m [4m.[0m

     [1mPIMG [22m[[1m-C[22m|[1m-L[22m|[1m-R[22m] [4mfile‐name[24m [[4mwidth[24m [[4mheight[24m]]
              Insert  graphical  image  [4mfile‐name,[24m  assumed to be in PNG format.
              Compared to [1mIMG[22m, this macro has the advantage of working with both
              PostScript and HTML devices since it converts [4mfile‐name[24m  into  EPS
              format  using ]8;;man:pngtopnm(1)\[4mpngtopnm[24m(1)]8;;\, ]8;;man:pnmcrop(1)\[4mpnmcrop[24m(1)]8;;\, and ]8;;man:pnmtops(1)\[4mpnmtops[24m(1)]8;;\.  [4mheight[24m and
              [4mwidth[24m may be given as percentages (of the line length  [1m\n[.l]  [22mand
              page length [1m\n[.p][22m, respectively).

              If  the document isn’t processed with “[1m-T html[22m” or “[1m-T xhtml[22m”, you
              must use ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\’s [1m-U [22moption.

     [1mMPIMG [22m[[1m-L[22m|[1m-R[22m] [[1m-G [4m[22mgap[24m] [4mfile‐name[24m [[4mwidth[24m [[4mheight[24m]]
              As [1mPIMG[22m, but place the image at a margin and wrap text around  it.
              The  image  is aligned the to the left ([1m-L[22m, default) or right ([1m-R[22m)
              margin.  [1m-G [4m[22mgap[24m imposes horizontal space of [4mgap[24m pixels between the
              picture and the text that wraps around it.   The  default  [4mgap[24m  is
              zero.

     [1mHnS [4m[22mn[24m    Begin heading at level [4mn.[0m

     [1mHnE      [22mEnd heading text.

     [1mLK       [22mDirect  [4mgrohtml[24m to emit the list of automatically generated hyper‐
              links at this location.

     [1mHR       [22mGenerate a full‐width horizontal rule when used with “[1m-T html[22m”  or
              “[1m-T xhtml[22m”.

     [1mNHR      [22mSuppress  the  horizontal  rules  at the document’s top and bottom
              that [4mgrohtml[24m emits by default.

     [1mHTL      [22mGenerate an HTML title only.  This differs from  ]8;;man:groff_ms(7)\[4mgroff_ms[24m(7)]8;;\’s  [1mTL[0m
              macro,  which  generates  both  an HTML title and an <H1> heading.
              Use it to provide an HTML title as document metadata  but  not  as
              formatted  text.   The  title  ends when vertical space ([1m.sp[22m) or a
              break ([1m.br[22m) is seen.

     [1mHEAD     [22mAdd arbitrary data to the HTML <head>  element.   Ignored  if  not
              processed with “[1m-T html[22m” or “[1m-T xhtml[22m”.

     [1mHTML     [22mAll  text after this macro is treated as raw HTML.  Ignored if not
              processed with “[1m-T html[22m” or “[1m-T xhtml[22m”.

     [1mDC [4m[22mL[24m [4mtext[24m [[4mcolor[24m]
              Format a “drop cap”——a large character [4mL[24m (usually a  capital  let‐
              ter) at a larger size and with a lower text baseline than the fol‐
              lowing [4mtext,[24m such that the cap‐heights of [4mL[24m and [4mtext[24m align, in the
              specified [4mcolor[24m (default: black).

     [1mCDS      [22mBegin  code  display; a monospaced font is selected and filling is
              disabled.

     [1mCDE      [22mEnd code display.

     [1mALN [22m[[4mcolor[24m [[4mwidth‐percentage[24m]]
              Enable a “navigation pane” containing links to  section  headings,
              aligned  to  the left of running text, and configure its rendering
              parameters.  Columnation is achieved with an  HTML  table.   [4mcolor[0m
              indicates  an  HTML  background color to be used in the navigation
              column; the default is [1m#eeeeee[22m.   [4mwidth‐percentage[24m  allocates  the
              given  percentage  of  the navigation pane’s table column; the de‐
              fault is [1m30[22m.  Call this macro at most once, at  the  beginning  of
              the document.

     [1mLNS      [22mBegin text indexed by the navigation pane configured by [1mALN[22m.

     [1mLNE      [22mEnd text indexed by navigation pane started by [1mLNS[22m.

     [1mLINKSTYLE [4m[22mcolor[24m [[4mfont‐style[24m [[4mopen‐glyph[24m [4mclose‐glyph[24m]]
              Configure  rendering  of  formatted  hyperlink targets for devices
              other than [1mhtml [22mand [1mxhtml[22m; render targets in [4mcolor[24m (default: blue)
              using the typeface [4mfont‐style[24m (default: [1mCR[22m) bracketed  with  [4mopen‐[0m
              [4mglyph[24m and [4mclose‐glyph[24m (defaults: [1m\[la] [22mand [1m\[ra][22m, respectively).

[1mSection heading links[0m
     By default [4mgrohtml[24m generates links to all section headings and places these
     at  the  top  of the HTML document.  Configure this behavior with [1mHX [22mand/or
     [1mLK[22m.

[1mLimitations of [4mgrohtml[0m
     ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\ tables are rendered as PNG images.

     All URLs currently are treated as consuming  no  textual  space  in  [4mgroff[24m.
     This  could  be considered as a bug since it causes some problems.  To cir‐
     cumvent this, [4mwww.tmac[24m inserts a zero‐width character which  expands  to  a
     harmless space (only if run with [1m-Thtml [22mor [1m-Txhtml[22m).

     Some  of  the  macros, like [1mALN[22m, [1mLNS[22m, and [1mLNE[22m, are integrated only with the
     ]8;;man:groff_ms(7)\[4mgroff_ms[24m(7)]8;;\ package.

[1mFiles[0m
     [4m/usr/share/groff/1.24.1/tmac/www.tmac[0m

[1mAuthors[0m
     The [4mwww[24m macro package was written by ]8;;mailto:gaius@glam.ac.uk\Gaius Mulley]8;;\, with additions by ]8;;mailto:wl@gnu.org\Werner
     Lemberg]8;;\ and ]8;;mailto:groff-bernd.warken-72@web.de\Bernd Warken]8;;\.

[1mSee also[0m
     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\, ]8;;man:grohtml(1)\[4mgrohtml[24m(1)]8;;\, ]8;;man:netpbm(1)\[4mnetpbm[24m(1)]8;;\

groff 1.24.1                       2026‐03‐20                       [4mgroff_www[24m(7)
────────────────────────────────────────────────────────────────────────────────
[4mroff[24m(7)                 Miscellaneous Information Manual                 [4mroff[24m(7)

[1mName[0m
     roff - concepts and history of [4mroff[24m typesetting

[1mDescription[0m
     The term [4mroff[24m denotes a family of  document  formatting  systems  known  by
     names  like [4mtroff[24m, [4mnroff[24m, and [4mditroff[24m.  A [4mroff[24m system consists of an inter‐
     preter for an extensible text formatting language and a set of programs for
     preparing output for various devices and file formats.  Unix‐like operating
     systems often distribute a [4mroff[24m system.  The manual pages on  Unix  systems
     (“man  pages”)  and  bestselling  books  on software engineering, including
     Brian Kernighan and Dennis Ritchie’s [4mThe[24m  [4mC[24m  [4mProgramming[24m  [4mLanguage[24m  and  W.
     Richard  Stevens’s  [4mAdvanced[24m [4mProgramming[24m [4min[24m [4mthe[24m [4mUnix[24m [4mEnvironment[24m, have been
     written using [4mroff[24m systems.  GNU [4mroff[24m——[4mgroff[24m——is arguably  the  most  wide‐
     spread [4mroff[24m implementation.

     Below  we  present typographical concepts foundational to understanding any
     [4mroff[24m implementation, narrate the development history of some [4mroff[24m  systems,
     detail the command pipeline managed by ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, survey the formatting lan‐
     guage,  suggest  tips for editing [4mroff[24m input, and recommend further reading
     materials.

[1mConcepts[0m
     AT&T [4mtroff[24m was designed to take input as it would be composed  on  a  type‐
     writer, including the teletypewriters used as early computer terminals, and
     relieve  the  user  drafting  a  document of concern with details like line
     length maintenance, hyphenation breaking, and consistent paragraph indenta‐
     tion.  Early in its development, the program gained the ability to  prepare
     output  for a phototypesetter; a document could then be prepared for output
     to a teletypewriter, a phototypesetter, or both.  GNU [4mtroff[24m continues  this
     tradition  of  permitting an author to compose a single master version of a
     document which can then be rendered upon a variety of output formats or de‐
     vices, including PDF, HTML, laser printers, and terminal displays.

     [4mroff[24m input contains text interspersed with instructions to control the for‐
     matter.  Even in the absence of such instructions, a [4mroff[24m  formatter  still
     processes its input in several ways, by filling, hyphenating, breaking, and
     adjusting  it,  and  supplementing  it  with  inter‐sentence  space.  These
     processes are basic to typesetting, and can be controlled at the input doc‐
     ument’s discretion.

     Instructions to [4mroff[24m take two forms.  One is the [4mrequest[24m, which occupies an
     input line and starts with the [4mcontrol[24m [4mcharacter[24m, a dot “[1m.[22m”.  The other  is
     the  [4mescape[24m  [4msequence[24m,  which can occur almost anywhere and starts with the
     [4mescape[24m [4mcharacter[24m, a backslash “[1m\[22m”.  Both characters are configurable.

            .br \" break the output line

     When a device‐independent [4mroff[24m formatter starts up, it obtains  information
     about  the  device  for  which it is preparing output from the latter’s de‐
     scription file (see ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\).  An essential property is the length of
     the output line, such as “6.5 inches”.

     The formatter interprets plain text files employing  the  Unix  line‐ending
     convention.   It  reads input a character at a time, collecting words as it
     goes, and fits as many words together on an output line as it can——this  is
     known  as [4mfilling.[24m  To a [4mroff[24m system, a [4mword[24m is any sequence of one or more
     characters that aren’t spaces or newlines.  The exceptions separate words.

     A [4mroff[24m formatter attempts to detect boundaries between sentences, and  sup‐
     plies  supplemental  inter‐sentence  space  between them.  It flags certain
     characters (normally “[1m![22m”, “[1m?[22m”, and “[1m.[22m”) as potentially ending  a  sentence.
     When  the  formatter  encounters one of these [4mend‐of‐sentence[24m [4mcharacters[24m at
     the end of an input line, or one of them is  followed  by  two  (unescaped)
     spaces  on  the same input line, it appends an inter‐word space followed by
     an inter‐sentence space in the output.  The dummy character escape sequence
     [1m\& [22mcan be used after an end‐of‐sentence character to defeat end‐of‐sentence
     detection on a per‐instance basis.  Normally, the occurrence of  a  visible
     non‐end‐of‐sentence  character  (as  opposed to a space or tab) immediately
     after an end‐of‐sentence character cancels detection of the end of  a  sen‐
     tence.   However, the formatter treats several characters [4mtransparently[24m af‐
     ter the occurrence of an end‐of‐sentence character——it does not cancel end‐
     of‐sentence status upon encountering them.  Such characters are often  used
     as  footnote  marks or to close quotations and parentheticals.  The default
     set is [1m"[22m, [1m'[22m, [1m)[22m, [1m][22m, [1m*[22m, [1m\[dg][22m, [1m\[dd][22m, [1m\[rq][22m, and [1m\[cq][22m.  The  last  four  are
     examples of [4mspecial[24m [4mcharacters,[24m escape sequences whose purpose is to obtain
     glyphs  that  are  not  easily typed at the keyboard, or which have special
     meaning to the formatter (like [1m\ [22mitself).

     When an output line is nearly full, it is uncommon for the next  word  col‐
     lected  from  the  input to exactly fill it——often, there is room left over
     for only part of the next word.  [4mHyphenation[24m is the process of splitting  a
     word  so that it appears partially on one line, followed by a hyphen to in‐
     dicate to the reader that the word has been broken, and that its  remainder
     lies  on the next.  Hyphenation break points can be manually specified; GNU
     [4mtroff[24m also uses a hyphenation algorithm and language‐specific pattern files
     (based on TeX’s) to decide which words can be hyphenated  and  where.   Hy‐
     phenation  does not always occur even when the hyphenation rules for a word
     allow it; it can be disabled, and when not disabled there are several para‐
     meters that can prevent it in certain circumstances.

     Once an output line is full, the formatter places the next word (or remain‐
     der of a hyphenated one) on a different  output  line;  this  is  called  a
     [4mbreak.[24m   In  this  document and in [4mroff[24m discussions generally, a “break” if
     not further qualified always refers to the termination of an  output  line.
     When  the  formatter is filling text, it introduces breaks automatically to
     keep output lines from exceeding the configured line length.  After an  au‐
     tomatic  break,  the  formatter [4madjusts[24m the line if applicable (see below),
     and then resumes collecting and filling text on the next output line.

     Sometimes, a line cannot be broken automatically.  This  usually  does  not
     happen  with  natural  language text unless the output line length has been
     manipulated to be extremely short, but it can with  specialized  text  like
     program source code.  [4mgroff[24m provides a means of telling the formatter where
     the line may be broken without hyphens.  This is done with the non‐printing
     break point escape sequence [1m\:[22m.

     There are several ways to cause a break at a predictable location.  A blank
     input  line  not only causes a break, but by default it also outputs a one‐
     line vertical space (effectively a blank output line).  Macro packages  may
     discourage  or disable this “blank line method” of paragraphing in favor of
     their own macros.  A line that begins with one  or  more  spaces  causes  a
     break.  The spaces are output at the beginning of the next line without be‐
     ing  [4madjusted[24m (see below).  Again, macro packages may provide other methods
     of producing indented paragraphs.  Trailing spaces on [4mtext[24m [4mlines[24m  (see  be‐
     low)  are  discarded.  The formatter breaks the pending output line without
     adjustment upon encountering the end of input.

     After performing an automatic break, the  formatter  may  then  [4madjust[24m  the
     line,  widening  inter‐word spaces until the text reaches the right margin.
     Extra spaces between words are preserved.  Leading and trailing spaces  are
     handled  as  noted  above.   You can align text to the left or right margin
     only, or center it, using [4mrequests.[0m

     A [4mroff[24m formatter translates horizontal tab characters, also  called  simply
     “tabs”, in the input into movements to the next tab stop.  Tab stops are by
     default  located  every half inch measured from the drawing position corre‐
     sponding to the beginning of the input line; see subsection “Page geometry”
     below.  With them, simple tables can be made.  However, this method can  be
     deceptive,  as  the appearance (and width) of the text in an editor and the
     results from the formatter can vary greatly, particularly when proportional
     typefaces are used.  A tab character does not cause a break  and  therefore
     does  not interrupt filling.  The formatter provides facilities for sophis‐
     ticated table composition; there are many details to track when  using  the
     “tab” and “field” low‐level features, so most users turn to the ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\ pre‐
     processor to lay out tables.

   [1mRequests and macros[0m
     A  [4mrequest[24m  is  an instruction to the formatter that occurs after a [4mcontrol[0m
     [4mcharacter,[24m which is recognized at the beginning of an input line.  The reg‐
     ular control character is a dot “[1m.[22m”.  Its counterpart, the [4mno‐break[24m [4mcontrol[0m
     [4mcharacter,[24m a neutral apostrophe “[1m'[22m”, suppresses the break implied  by  some
     requests.  These characters were chosen because it is uncommon for lines of
     text  in  natural languages to begin with them.  If you require a formatted
     period or apostrophe (closing single quotation mark)  where  the  formatter
     expects  a control character, prefix the dot or neutral apostrophe with the
     dummy character escape sequence, “[1m\&[22m”.

     An input line beginning with a control character is called a [4mcontrol[24m  [4mline.[0m
     Every line of input that is not a control line is a [4mtext[24m [4mline.[0m

     Requests  often  take [4marguments,[24m words (separated from the request name and
     each other by spaces) that specify details of the  action  you  expect  the
     formatter to perform.  If a request is meaningless without arguments, it is
     typically ignored.  Requests and escape sequences comprise the control lan‐
     guage  of  the  formatter.   Of key importance are the requests that define
     macros.  Macros are invoked like requests, enabling the request  repertoire
     to  be extended or overridden.  (Argument handling in macros is more flexi‐
     ble but also more complex.)

     A [4mmacro[24m can be thought of as an abbreviation you can define for  a  collec‐
     tion  of  control  and  text lines.  When the macro is [4mcalled[24m by giving its
     name after a control character, it is replaced with  what  it  stands  for.
     The  process  of textual replacement is known as [4minterpolation.[24m  Interpola‐
     tions are handled as soon as they are recognized,  and  once  performed,  a
     [4mroff[24m formatter scans the replacement for further requests, macro calls, and
     escape sequences.  In [4mroff[24m systems, the “[1mde[22m” request defines a macro.

   [1mPage geometry[0m
     [4mroff[24m  systems  format  text under certain assumptions about the size of the
     output medium, or page.  For the formatter to correctly break a line it  is
     filling,  it  must  know  the  line  length, which it derives from the page
     width.  For it to decide whether to write an output  line  to  the  current
     page  or wait until the next one, it must know the page length.  A device’s
     [4mresolution[24m converts practical units like inches  or  centimeters  to  [4mbasic[0m
     [4munits,[24m  a  convenient  length measure for the output device or file format.
     The formatter and output driver use basic units  to  reckon  page  measure‐
     ments.   The device description file defines its resolution and page dimen‐
     sions (see ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\).

     A [4mpage[24m is a two‐dimensional structure upon which a [4mroff[24m  system  imposes  a
     rectangular  coordinate system with its its origin near the upper left cor‐
     ner.  Coordinate values are in basic units and increase  down  and  to  the
     right.  Useful ones are typically positive and within numeric ranges corre‐
     sponding to the page boundaries.

     Text  is  arranged  on a one‐dimensional lattice of text baselines from the
     top to the bottom of the page.  A [4mtext[24m [4mbaseline[24m is  a  (usually  invisible)
     line  upon which the glyphs of a typeface are aligned.  [4mVertical[24m [4mspacing[24m is
     the distance between adjacent text baselines.  Typographic  tradition  sets
     this quantity to 120% of the type size.  The initial vertical drawing posi‐
     tion is one unit of vertical spacing below the page top.  Typographers term
     this unit a [4mvee.[0m

     While  the  formatter  (and, later, output driver) is processing a page, it
     keeps track of its [4mdrawing[24m [4mposition,[24m which is the  location  at  which  the
     next glyph will be written, from which the next motion will be measured, or
     where  a  geometric object will commence rendering.  Notionally, glyphs are
     drawn from the text baseline upward and to the right.  ([4mgroff[24m does not  yet
     support  right‐to‐left scripts.)  A glyph therefore “starts” at its bottom‐
     left corner.  The formatter’s origin is one vee below the page top to  pre‐
     vent a glyph from lying partially or wholly off the page.

     Further,  it  is  conventional not to write or draw at the extreme edges of
     the page.  Typesetters configure a [4mpage[24m [4moffset,[24m a rightward shift from  the
     left  edge that defines the zero point from which the formatter reckons the
     line indentation and length.  ([4mgroff[24m’s terminal output  devices  have  page
     offsets of zero.)

     Combining  the  foregoing  facts results in an origin that lies at the page
     offset in the horizontal dimension and at the text baseline (using the  de‐
     fault  vertical  spacing) in the vertical dimension.  A document can change
     these prior to its first written or drawn output.

     Vertical spacing has an impact on page‐breaking decisions.  Generally, when
     a break occurs, the formatter automatically moves the drawing  position  to
     the  next text baseline.  If the formatter were already writing to the last
     line that fits on the page, advancing by one vee would place the next  text
     baseline  off the page.  To avoid that, [4mroff[24m formatters instruct the output
     driver to eject the page, start a new one, and again place the drawing  po‐
     sition at the page offset one vee below the page top; this is a [4mpage[24m [4mbreak.[0m

     When  the  last line of input text corresponds to the last output line that
     fits on the page, the break caused by the end  of  input  also  breaks  the
     page, producing a useless blank one.  Macro packages keep users from having
     to  confront this difficulty by setting “traps”; moreover, all but the sim‐
     plest page layouts tend to have headers and footers, or at least bear  ver‐
     tical margins of at least one vee.

   [1mOther language elements[0m
     [4mEscape[24m  [4msequences[24m  start  with the [4mescape[24m [4mcharacter,[24m a backslash [1m\[22m, and are
     followed by at least one additional character.  They can appear anywhere in
     the input.

     With requests, the escape and control characters can be  changed;  further,
     escape sequence recognition can be turned off and back on.

     [4mStrings[24m  store  character  sequences.   In [4mgroff[24m, they can be parameterized
     (given arguments) as macros can.

     [4mRegisters[24m store numerical values, including measurements.  The  latter  are
     generally  in basic units; [4mscaling[24m [4munits[24m can be appended to numeric expres‐
     sions to clarify their meaning when stored or interpolated.  Each  register
     can be assigned a [4mformat,[24m causing its value to interpolate with leading ze‐
     roes,  in  Roman numerals, or alphabetically.  Some read‐only registers are
     string‐valued, meaning that they interpolate text and lack a format.

     [4mFonts[24m are identified either by a name or by a [4mmounting[24m [4mposition[24m (a non‐neg‐
     ative number).  Four styles are available on all devices.   [1mR  [22mis  “roman”:
     normal,  upright  text.   [1mB  [22mis  [1mbold[22m,  an  upright typeface with a heavier
     weight.  [1mI [22mis [4mitalic[24m, a face that is oblique on typesetter  output  devices
     and  usually  underlined  instead  on terminal devices.  [1mBI [22mis [4m[1mbold‐italic[24m[22m,
     combining both of the  foregoing  style  variations.   Typesetting  devices
     group  these  four  styles into [4mfamilies[24m of text fonts; they also typically
     offer  one  or  more  [4mspecial[24m  fonts  that  provide  unstyled  glyphs;  see
     ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\.

     [4mgroff[24m  supports  named  [4mcolors[24m for glyph rendering and drawing of geometric
     objects.  Stroke and fill colors are distinct; the stroke color is used for
     glyphs.

     [4mGlyphs[24m are visual representation forms of [4mcharacters.[24m  In [4mgroff,[24m  the  dis‐
     tinction  between those two elements is not always obvious (and a full dis‐
     cussion is beyond our scope).  In brief, “A” is a character  when  we  con‐
     sider  it  in  the  abstract: to make it a glyph, we must select a typeface
     with which to render it, and determine its type size and color.   The  for‐
     matting  process  turns input characters into output glyphs.  A few charac‐
     ters commonly seen on keyboards are treated specially by the [4mroff[24m  language
     and may not look correct in output if used unthinkingly; they are the (dou‐
     ble)  quotation  mark  ([1m"[22m), the neutral apostrophe ([1m'[22m), the minus sign ([1m-[22m),
     the backslash ([1m\[22m), the caret or circumflex accent  ([1m^[22m),  the  grave  accent
     ([1m`[22m), and the tilde ([1m~[22m).  All of these and more can be produced with [4mspecial[0m
     [4mcharacter[24m escape sequences; see ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\.

     [4mgroff[24m offers [4mstreams[24m, identifiers for writable files, but for security rea‐
     sons this feature is disabled by default.

     A further few language elements arise as page layouts become more sophisti‐
     cated  and demanding.  [4mEnvironments[24m collect formatting parameters like line
     length and typeface.  A [4mdiversion[24m stores formatted output for later use.  A
     [4mtrap[24m is a condition on the input or output,  tested  automatically  by  the
     formatter,  that  is  associated  with  a  macro:  fulfilling the condition
     [4msprings[24m the trap——calls the macro.

     Footnote support often exercises all three of the  foregoing  features.   A
     simple  implementation  might work as follows.  The author writes a pair of
     macros: one starts a footnote and the other ends it.  They  further  set  a
     trap  a  small  distance  above the page bottom, reserving a footnote area.
     The author calls the first macro where a footnote  mark  is  desired.   The
     macro establishes a diversion so that the footnote text is collected at the
     place  in  the  body text where its corresponding mark appears.  It further
     creates an environment for the footnote so that it sets at a smaller  type‐
     face.   The footnote text is formatted in the diversion using that environ‐
     ment, but it does not yet appear in the output.  The document author  calls
     the  footnote end macro, which returns to the previous environment and ends
     the diversion.  Later, after body text nearly  fills  the  page,  the  trap
     springs.   The  macro  called  by the trap draws a line across the page and
     emits the stored diversion by calling it like a macro.  Thus, the  footnote
     is rendered.

[1mHistory[0m
     Computer‐driven document formatting dates back to the 1960s.  The [4mroff[24m sys‐
     tem is intimately connected with Unix, but its origins lie with the earlier
     operating systems CTSS, GECOS, and Multics.

   [1mThe predecessor——[4mRUNOFF[0m
     [4mroff[24m’s  ancestor [4mRUNOFF[24m was written in the MAD language by Jerry Saltzer to
     prepare his Ph.D. thesis on the Compatible Time Sharing  System  (CTSS),  a
     project  of  the Massachusetts Institute of Technology (MIT).  This program
     is referred to in full capitals, both to distinguish it from its  many  de‐
     scendants, and because bits were expensive in those days; five‐ and six‐bit
     character  encodings  were still in widespread usage, and mixed‐case alpha‐
     betics in file names seen as a luxury.  [4mRUNOFF[24m introduced a syntax  of  in‐
     lining formatting directives amid document text, by beginning a line with a
     period  (an  unlikely  occurrence in human‐readable material) followed by a
     “control word”.  Control words with obvious meaning like “.line  length  [4mn[24m”
     were  supported as well as an abbreviation system; the latter came to over‐
     whelm the former in popular usage and later derivatives of the program.   A
     sample  of  control  words  from a ]8;;http://web.mit.edu/Saltzer/www/publications/ctss/AH.9.01.html\[4mRUNOFF[24m manual of December 1966]8;;\ was docu‐
     mented as follows (with the parameter notation slightly altered).  The  ab‐
     breviations will be familiar to [4mroff[24m veterans.

                           Abbreviation   Control word
                           ───────────────────────────────
                                    [1m.ad   [22m.adjust
                                    [1m.bp   [22m.begin page
                                    [1m.br   [22m.break
                                    [1m.ce   [22m.center
                                    [1m.in   [22m.indent [4mn[0m
                                    [1m.ll   [22m.line length [4mn[0m
                                    [1m.nf   [22m.nofill
                                    [1m.pl   [22m.paper length [4mn[0m
                                    [1m.sp   [22m.space [[4mn[24m]

     In 1965, MIT’s Project MAC teamed with Bell Telephone Laboratories and Gen‐
     eral  Electric  (GE) to inaugurate the ]8;;http://www.multicians.org\Multics]8;;\ project.  After a few years,
     Bell Labs discontinued its participation in Multics, famously prompting the
     development of Unix.  Meanwhile, Saltzer’s [4mRUNOFF[24m proved influential,  see‐
     ing many ports and derivations elsewhere.

     In  1969,  Doug McIlroy wrote one such reimplementation, adding extensions,
     in the BCPL language for a GE 645 running GECOS at the Bell  Labs  location
     in  Murray  Hill,  New  Jersey.   In  its manual, the control commands were
     termed “requests”, their two‐letter names were canonical, and  the  control
     character  was  configurable  with  a [1m.cc [22mrequest.  Other familiar requests
     emerged at this time; no‐adjust ([1m.na[22m), need ([1m.ne[22m), page offset  ([1m.po[22m),  tab
     configuration  ([1m.ta[22m, though it worked differently), temporary indent ([1m.ti[22m),
     character translation ([1m.tr[22m), and automatic underlining ([1m.ul[22m; on [4mRUNOFF[24m  you
     had  to  backspace  and  underscore  in the input yourself).  [1m.fi [22mto enable
     filling of output lines got the name it retains  to  this  day.   McIlroy’s
     program  also featured a heuristic system for automatically placing hyphen‐
     ation points, designed and implemented by Molly Wagner.  It furthermore in‐
     troduced numeric variables, termed registers.  By 1971,  this  program  had
     been  ported to Multics and was known as [4mroff[24m, a name McIlroy attributes to
     Bob Morris, to distinguish it from CTSS [4mRUNOFF[24m.

   [1mUnix and [4mroff[0m
     McIlroy’s [4mroff[24m was one of the first Unix programs.  In Ritchie’s  term,  it
     was  “transliterated”  from  BCPL  to  DEC  PDP‐7 assembly language for the
     fledgling Unix operating system.  Automatic hyphenation  was  managed  with
     [1m.hc [22mand [1m.hy [22mrequests, line spacing control was generalized with the [1m.ls [22mre‐
     quest, and what later [4mroff[24ms would call diversions were available via “foot‐
     note”  requests.  This [4mroff[24m indirectly funded operating systems research at
     Murray Hill; AT&T prepared patent applications to the U.S. government  with
     it.   This arrangement enabled the group to acquire a PDP‐11; [4mroff[24m promptly
     proved equal to the task of formatting the manual  for  what  would  become
     known as “First Edition Unix”, dated November 1971.

     Output  from all of the foregoing programs was limited to line printers and
     paper terminals such as the IBM 2471 (based on the Selectric line of  type‐
     writers) and the Teletype Corporation Model 37.  Proportionally spaced type
     was unavailable.

   [1mNew [4mroff[24m and Typesetter [4mroff[0m
     The  first years of Unix were spent in rapid evolution.  The practicalities
     of preparing standardized documents like patent applications (and Unix man‐
     ual pages), combined with McIlroy’s enthusiasm for macro languages, perhaps
     created an irresistible pressure to make [4mroff[24m  extensible.   Joe  Ossanna’s
     [4mnroff[24m,  literally  a  “new roff”, was the outlet for this pressure.  By the
     time of Unix Version 3 (February 1973)——and still in PDP‐11  assembly  lan‐
     guage——it sported a swath of features now considered essential to [4mroff[24m sys‐
     tems:  definition of macros ([1m.de[22m), diversion of text thither ([1m.di[22m), and re‐
     moval thereof ([1m.rm[22m); trap  planting  ([1m.wh[22m;  “when”)  and  relocation  ([1m.ch[22m;
     “change”); conditional processing ([1m.if[22m); and environments ([1m.ev[22m).  Incremen‐
     tal  improvements  included  assignment  of the next page number ([1m.pn[22m); no‐
     space mode ([1m.ns[22m) and restoration of  vertical  spacing  ([1m.rs[22m);  the  saving
     ([1m.sv[22m)  and  output  ([1m.os[22m)  of  vertical space; specification of replacement
     characters for tabs ([1m.tc[22m) and leaders ([1m.lc[22m); configuration of the  no‐break
     control  character ([1m.c2[22m); shorthand to disable automatic hyphenation ([1m.nh[22m);
     a condensation of what were formerly six different requests for  configura‐
     tion  of  page  “titles” (headers and footers) into one ([1m.tl[22m) with a length
     controlled separately from the line length ([1m.lt[22m); automatic line  numbering
     ([1m.nm[22m);  interactive  input ([1m.rd[22m), which necessitated buffer‐flushing ([1m.fl[22m),
     and was made convenient with early program cessation ([1m.ex[22m); source file in‐
     clusion in its modern form ([1m.so[22m; though [4mRUNOFF[24m  had  an  “.append”  control
     word  for  a  similar  purpose) and early advance to the next file argument
     ([1m.nx[22m); ignorable content ([1m.ig[22m); and programmable abort ([1m.ab[22m).

     Third Edition Unix also brought the  ]8;;man:pipe(2)\[4mpipe[24m(2)]8;;\  system  call,  the  explosive
     growth of a componentized system based around it, and a “filter model” that
     remains perceptible today.  Equally importantly, the Bell Labs site in Mur‐
     ray Hill acquired a Graphic Systems C/A/T phototypesetter, and with it came
     the necessity of expanding the capabilities of a [4mroff[24m system to cope with a
     variety  of  proportionally  spaced  typefaces  at multiple sizes.  Ossanna
     wrote a parallel implementation of [4mnroff[24m for the C/A/T,  dubbing  it  [4mtroff[0m
     (for  “typesetter  roff”).  Unfortunately, surviving documentation does not
     illustrate what requests were implemented at this time for  C/A/T  support;
     the  ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ man page in Fourth Edition Unix (November 1973) does not fea‐
     ture a request list, unlike ]8;;man:nroff(1)\[4mnroff[24m(1)]8;;\.  Apart  from  typesetter‐driven  fea‐
     tures, Unix Version 4 [4mroff[24ms added string definitions ([1m.ds[22m); made the escape
     character  configurable ([1m.ec[22m); and enabled the user to write diagnostics to
     the standard error stream ([1m.tm[22m).  Around 1974, empowered with multiple type
     sizes, italics, and a symbol font specially commissioned by Bell Labs  from
     Graphic  Systems, Kernighan and Lorinda Cherry implemented [4meqn[24m for typeset‐
     ting mathematics.  In the same year, for Fifth Edition Unix,  Ossanna  com‐
     bined  and  reimplemented  the  two  [4mroff[24ms in C, using that language’s pre‐
     processor to generate both from a single source tree.

     Ossanna documented the syntax of the input language to the [4mnroff[24m and  [4mtroff[0m
     programs  in  the “Troff User’s Manual”, first published in 1976, with fur‐
     ther revisions as late as 1992 by Kernighan.  (The original version was en‐
     titled “Nroff/Troff User’s Manual”, which may partially  explain  why  [4mroff[0m
     practitioners  have  tended to refer to it by its AT&T document identifier,
     “CSTR #54”.)  Its final revision serves as the [4mde[24m  [4mfacto[24m  specification  of
     AT&T [4mtroff[24m, and all subsequent implementors of [4mroff[24m systems have done so in
     its shadow.

     A  small  and simple set of [4mroff[24m macros was first used for the manual pages
     of Unix Version 4 and persisted for two further  releases,  but  the  first
     macro package to be formally described and installed was [4mms[24m by Michael Lesk
     in  Version  6.  He also wrote a manual, “Typing Documents on the Unix Sys‐
     tem”, describing [4mms[24m and basic [4mnroff[24m/[4mtroff[24m usage, updating it as the package
     accrued features.  Sixth Edition (1975) additionally saw the debut  of  the
     [4mtbl[24m preprocessor for formatting tables, also by Lesk.

     For Unix Version 7 (January 1979), McIlroy designed, implemented, and docu‐
     mented  the  [4mman[24m macro package, introducing most of the macros described in
     ]8;;man:groff_man(7)\[4mgroff_man[24m(7)]8;;\ today, and edited volume 1 of the Version 7 manual  using  it.
     Documents composed using [4mms[24m featured in volume 2, edited by Kernighan.

     Meanwhile,  [4mtroff[24m proved popular even at Unix sites that lacked a C/A/T de‐
     vice.  Tom Ferrin of the University of California at San Francisco combined
     it with Allen Hershey’s popular  vector  fonts  to  produce  [4mvtroff[24m,  which
     translated [4mtroff[24m’s output to the command language used by Versatec and Ben‐
     son‐Varian plotters.

     Ossanna had passed away unexpectedly in 1977, and after the release of Ver‐
     sion  7,  with  the C/A/T typesetter becoming supplanted by alternative de‐
     vices such as the  Autologic  APS‐5  and  the  Mergenthaler  Linotron  202,
     Kernighan  undertook  a revision and rewrite of [4mtroff[24m to generalize its de‐
     sign.  To implement this revised architecture, he developed  the  font  and
     device  description file formats and the page description language that re‐
     main in use today.  He described these novelties in the article “A Typeset‐
     ter‐independent TROFF”, last revised in 1982, and like the [4mtroff[24m manual it‐
     self, it is widely known by a shorthand, “CSTR #97”.

     Kernighan’s innovations prepared [4mtroff[24m well for  the  introduction  of  the
     Adobe  PostScript  language  in 1982 and a vibrant market in laser printers
     with built‐in interpreters for it.  An output driver for PostScript, [4mdpost[24m,
     was swiftly developed.  However, AT&T’s software licensing  practices  kept
     Ossanna’s  [4mtroff[24m,  with  its tight coupling to the C/A/T’s capabilities, in
     parallel distribution with device‐independent [4mtroff[24m throughout  the  1980s.
     Today,  however,  all actively maintained [4mtroff[24ms follow Kernighan’s device‐
     independent design.

   [4m[1mgroff[24m——a free [4mroff[24m from GNU[0m
     The most important free [4mroff[24m project historically has been [4mgroff[24m,  the  GNU
     implementation of [4mtroff[24m, developed by James Clark starting in 1989 and dis‐
     tributed  under  ]8;;http://www.gnu.org/copyleft\copyleft]8;;\  licenses,  ensuring  to  all the availability of
     source code and the freedom to modify and redistribute it,  properties  un‐
     precedented  in  [4mroff[24m  systems to that point.  [4mgroff[24m rapidly attracted con‐
     tributors, and has served as a replacement for almost all  applications  of
     AT&T  [4mtroff.[24m   (Exceptions  include  [4mmv[24m, a macro package for preparation of
     viewgraphs and slides, and the [4mideal[24m preprocessor, which produces  diagrams
     from  mathematical  constraints.)   Beyond that, it has added numerous fea‐
     tures; see ]8;;man:groff_diff(7)\[4mgroff_diff[24m(7)]8;;\.  Since its inception and for at least the follow‐
     ing three decades, it has been used by practically all  GNU/Linux  and  BSD
     operating systems.

     [4mgroff[24m continues to be developed, is available for almost all operating sys‐
     tems  in  common use (along with several obscure ones), and is free.  These
     factors make [4mgroff[24m the [4mde[24m [4mfacto[24m [4mroff[24m standard today.

   [1mOther free [4mroff[24ms[0m
     In 2007, Caldera/SCO and Sun Microsystems, having acquired rights  to  AT&T
     Unix System V [4mtroff[24m, which was based on Documenter’s Workbench (“DWB”) 2.0,
     itself  a descendant of Bell Labs device‐independent [4mtroff[24m, released it un‐
     der a free but GPL‐incompatible license.  Gunnar Ritter and  later  Carsten
     Kunze then enhanced it to produce ]8;;https://github.com/n-t-roff/heirloom-doctools\Heirloom Doctools [4mtroff[24m]8;;\.  Sometime later,
     AT&T  Software  Technology  made  available  a subsequent revision of Docu‐
     menter’s Workbench [4mtroff[24m, ]8;;https://github.com/n-t-roff/DWB3.3\DWB 3.3]8;;\, under yet another free but GPL‐incompat‐
     ible license.  Kunze again ported the software to modern POSIX systems.

     In July 2013, Ali Gholami Rudi announced ]8;;https://github.com/aligrudi/neatroff\[4mneatroff[24m]8;;\, a permissively  licensed
     new implementation.

     Another  descendant  of DWB [4mtroff[24m is part of ]8;;https://9fans.github.io/plan9port/\Plan 9 from User Space]8;;\.  Since
     2021, this [4mtroff[24m has been available under permissive terms.

[1mUsing [4mroff[0m
     When you read a man page, often a [4mroff[24m is the program rendering  it.   Some
     [4mroff[24m  implementations provide wrapper programs that make it easy to use the
     [4mroff[24m system from the shell’s command line.  These  can  be  specific  to  a
     macro package, like ]8;;man:mmroff(1)\[4mmmroff[24m(1)]8;;\, or more general.  ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ provides command‐
     line  options  sparing the user from constructing the long, order‐dependent
     pipelines familiar to AT&T [4mtroff[24m  users.   Further,  a  heuristic  program,
     ]8;;man:grog(1)\[4mgrog[24m(1)]8;;\, is available to infer from a document’s contents which [4mgroff[24m argu‐
     ments should be used to process it.

   [1mThe [4mroff[24m pipeline[0m
     A typical [4mroff[24m document is prepared by running one or more preprocessors in
     series,  followed  by  a  a formatter program and then an output driver (or
     “device postprocessor”).  Commonly, these programs are  structured  into  a
     pipeline;  that  is, each is run in sequence such that the output of one is
     taken as the input to the next, without passing through secondary  storage.
     (Non‐Unix systems may simulate pipelines with temporary files.)

            $ [4mpreproc1[24m [1m< [4m[22minput‐file[24m [1m| [4m[22mpreproc2[24m [1m| [22m... [1m| troff [22m[[4moption[24m] ... [1m\[0m
                [1m| [4m[22moutput‐driver[0m

     Once  all  preprocessors have run, they deliver pure [4mroff[24m language input to
     the formatter, which in turn generates a document  in  a  page  description
     language that is then interpreted by a postprocessor for viewing, printing,
     or further handling.

     Each program interprets input in a language that is independent of the oth‐
     ers;  some are purely descriptive, as with ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\ and [4mroff[24m output, and some
     permit the definition of macros, as with ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\ and [4mroff[24m input.  Most  [4mroff[0m
     input  employs the macros of a document formatting package, intermixed with
     instructions for one or more preprocessors, and is seasoned with escape se‐
     quences and requests from the [4mroff[24m language.  Some  documents  are  simpler
     still,  since  their  formatting packages discourage direct use of [4mroff[24m re‐
     quests; man pages are a prominent example.  Many features of the [4mroff[24m  lan‐
     guage  are seldom needed by users; only authors of macro packages require a
     substantial command of them.

   [1mPreprocessors[0m
     A [4mroff[24m preprocessor is a program that, directly  or  ultimately,  generates
     output  in  the [4mroff[24m language.  Typically, each preprocessor defines a lan‐
     guage of its own that transforms its input into that for  [4mroff[24m  or  another
     preprocessor.   As an example of the latter, [4mchem[24m produces [4mpic[24m input.  Pre‐
     processors must consequently be run in an appropriate order; ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\  han‐
     dles this automatically for all preprocessors supplied by the GNU [4mroff[24m sys‐
     tem.

     Portions  of  the  document  written  in preprocessor languages are usually
     bracketed by tokens that look like [4mroff[24m  macro  calls.   [4mroff[24m  preprocessor
     programs  transform  only  the  regions  of the document intended for them.
     When a preprocessor language is used by a document, its corresponding  pro‐
     gram  must  process it before the input is seen by the formatter, or incor‐
     rect rendering is almost guaranteed.

     GNU [4mroff[24m provides several preprocessors,  including  [4meqn[24m,  [4mgrn[24m,  [4mpic[24m,  [4mtbl[24m,
     [4mrefer[24m,  and [4msoelim[24m.  See ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ for a complete list.  Other preprocessors
     for [4mroff[24m systems are known.

            [4mdformat[24m   depicts data structures;
            [4mgrap[24m      constructs statistical charts; and
            [4mideal[24m     draws diagrams using a constraint‐based language.

   [1mFormatter programs[0m
     A [4mroff[24m formatter transforms [4mroff[24m language input into a  single  file  in  a
     page description language, described in ]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\, intended for process‐
     ing by a selected device.  This page description language is specialized in
     its  parameters, but not its syntax, for the selected device; the format is
     device‐[4mindependent[24m, but not device‐[4magnostic[24m.  The parameters the  formatter
     uses  to  arrange  the  document  are stored in [4mdevice[24m and [4mfont[24m [4mdescription[0m
     [4mfiles[24m; see ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

     AT&T Unix had two formatters——[4mnroff[24m for terminals, and [4mtroff[24m  for  typeset‐
     ters.  Often, the name [4mtroff[24m is used loosely to refer to both.  When gener‐
     alizing  thus,  [4mgroff[24m  documentation prefers the term “[4mroff[24m”.  In GNU [4mroff[24m,
     the formatter program is always ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\.

   [1mDevices and output drivers[0m
     To a [4mroff[24m system, a [4mdevice[24m is a hardware interface like a printer,  a  text
     or  graphical  terminal, or a standardized file format that unrelated soft‐
     ware can interpret.  An [4moutput[24m [4mdriver[24m is a program that parses  the  output
     of [4mtroff[24m and produces instructions or markup specific to the device or file
     format  it supports.  An output driver might support multiple devices, par‐
     ticularly if they are similar.

     The names of the devices and their driver programs  are  not  standardized.
     Technological fashions evolve; the devices popular for document preparation
     when  AT&T  [4mtroff[24m was first written in the 1970s are no longer used in pro‐
     duction environments.  Device capabilities have tended to increase, improv‐
     ing resolution and font repertoire, and adding color output and  hyperlink‐
     ing.   Further,  to reduce file size and processing time, AT&T [4mtroff[24m’s page
     description language placed low limits on the magnitudes of some quantities
     it could represent.  Its PostScript output driver, ]8;;man:dpost(1)\[4mdpost[24m(1)]8;;\, had a  resolu‐
     tion of 720 units per inch; [4mgroff[24m’s ]8;;man:grops(1)\[4mgrops[24m(1)]8;;\ uses 72,000.

[4m[1mroff[24m programming[0m
     Documents using [4mroff[24m are normal text files interleaved with [4mroff[24m formatting
     elements.  The [4mroff[24m language is powerful enough to support arbitrary compu‐
     tation  and  it  supplies facilities that encourage extension.  The primary
     such facility is macro definition; with this feature, macro  packages  have
     been developed that are tailored for particular applications.

   [1mMacro packages[0m
     Macro  packages  can  have a much smaller vocabulary than [4mroff[24m itself; this
     trait combined with their domain‐specific nature can make them easy to  ac‐
     quire  and  master.  The implementation of a package [4mname[24m is typically kept
     in a file called “name[4m.tmac[24m” (historically, “[4mtmac.[24mname”).  Find details  on
     the naming and placement of macro packages in ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\.

     A  macro  package  anticipated for use in a document can be declared to the
     formatter by the command‐line option [1m-m[22m; see  ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\.   It  can  alterna‐
     tively  be  specified  within a document using the [1mmso [22mrequest of the [4mgroff[0m
     language; see ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\.

     Well‐known packages include [4mman[24m for traditional man pages and [4mmdoc[24m for BSD‐
     style manual pages.  Packages for typesetting books, articles, and  letters
     include  [4mms[24m (from “manuscript macros”), [4mme[24m (named by a system administrator
     from the first name of its creator,  Eric  Allman),  [4mmm[24m  (from  “memorandum
     macros”),  and  [4mmom[24m, a punningly named package exercising many [4mgroff[24m exten‐
     sions.  See ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\ for more.

   [1mThe [4mroff[24m formatting language[0m
     The [4mroff[24m language provides requests, escape sequences, macro definition fa‐
     cilities, string variables, registers for storage of numbers or dimensions,
     and control of execution flow.  The theoretically minded will observe  that
     a  [4mroff[24m is not a mere markup language, but Turing‐complete.  It has storage
     (registers), it can perform  tests  (as  in  conditional  expressions  like
     “[1m(\n[i]  >=  1)[22m”), its “[1mif[22m” and related requests alter the flow of control,
     and macro definition permits unbounded recursion.

     [4mRequests[24m and [4mescape[24m [4msequences[24m are instructions,  predefined  parts  of  the
     language,  that perform formatting operations, interpolate stored material,
     or otherwise change the state of the parser.  The user can define their own
     request‐like elements by composing together text, requests, and escape  se‐
     quences  [4mad[24m [4mlibitum.[24m  A document writer will not (usually) note any differ‐
     ence in usage for requests or macros; both  are  found  on  control  lines.
     However, there is a distinction; requests take either a fixed number of ar‐
     guments (sometimes zero), silently ignoring any excess, or consume the rest
     of  the input line, whereas macros can take a variable number of arguments.
     Since arguments are separated by spaces, macros require a means  of  embed‐
     ding  a space in an argument; in other words, of quoting it.  This then de‐
     mands a mechanism of embedding the quoting character itself, in case [4mit[24m  is
     needed literally in a macro argument.  AT&T [4mtroff[24m had complex rules involv‐
     ing  the placement and repetition of the double quote to achieve both aims.
     [4mgroff[24m cuts this knot by supporting a special character escape sequence  for
     the  neutral  double  quote,  “[1m\[dq][22m”,  which never performs quoting in the
     typesetting language, but is simply a glyph, ‘[1m"[22m’.

     [4mEscape[24m [4msequences[24m start with a backslash, “[1m\[22m”.  They can appear almost  any‐
     where, even in the midst of text on a line, and implement various features,
     including  the  insertion  of  special  characters with “[1m\([4mxx[24m[22m” or “[1m\[[4mxxx[24m][22m”,
     break suppression at input line endings with “[1m\c[22m”, font changes with  “[1m\f[22m”,
     type size changes with “[1m\s[22m”, in‐line comments with “[1m\"[22m”, and many others.

     [4mStrings[24m  store  text.   They are populated with the [1mds [22mrequest and interpo‐
     lated using the [1m\* [22mescape sequence.

     [4mRegisters[24m store numbers and measurements.  A register can be set  with  the
     request [1mnr [22mand its value can be retrieved by the escape sequence [1m\n[22m.

[1mFile naming conventions[0m
     The  structure  or  content of a file name, beyond its location in the file
     system, is not significant to [4mroff[24m tools.  [4mroff[24m documents employing  “full‐
     service”  macro packages (see ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\) tend to be named with a suffix
     identifying the package; we thus see file names ending in [4m.man[24m,  [4m.ms[24m,  [4m.me[24m,
     [4m.mm[24m,  and  [4m.mom[24m,  for instance.  When installed, man pages tend to be named
     with the manual’s section number as the suffix.  For example, the file name
     for this document is [4mroff.7[24m.  Practice for “raw”  [4mroff[24m  documents  is  less
     consistent; they are sometimes seen with a [4m.t[24m suffix.

[1mInput conventions[0m
     Since a [4mroff[24m formatter fills text automatically, its experienced users tend
     to  avoid visual composition of text in input files: the esthetic appeal of
     the formatted output is what matters.   Therefore,  [4mroff[24m  input  should  be
     arranged  such  that  it is easy for authors and maintainers to compose and
     develop the document, understand the syntax of [4mroff[24m requests, macro  calls,
     and preprocessor languages used, and predict the behavior of the formatter.
     Several traditions have accrued in service of these goals.

     •  Follow  sentence endings in the input with newlines to ease their recog‐
        nition.  It is frequently convenient to end text lines after colons  and
        semicolons  as  well,  as  these  typically precede independent clauses.
        Consider doing so after commas; they often occur in  lists  that  become
        easy  to  scan  when  itemized by line, or constitute supplements to the
        sentence that are added, deleted, or updated to clarify it.  Parentheti‐
        cal and quoted phrases are also good candidates for  placement  on  text
        lines by themselves.

     •  Set  your  text  editor’s line length to 72 characters or fewer; see the
        subsections below.  This limit, combined with the previous item  of  ad‐
        vice, makes it less common that an input line will wrap in your text ed‐
        itor,  and thus will help you perceive excessively long constructions in
        your text.  Recall that natural languages originate in speech, not writ‐
        ing, and that punctuation is correlated with pauses  for  breathing  and
        changes in prosody.

     •  Use  [1m\& [22mafter “[1m![22m”, “[1m?[22m”, and “[1m.[22m” if they are followed by space or newline
        characters and don’t end a sentence.

     •  In filled text lines, use [1m\& [22mbefore “[1m.[22m” and “[1m'[22m” if they are preceded  by
        space,  so  that  revisions  to  the  input don’t turn them into control
        lines.

     •  Do not use spaces to perform indentation or align columns  of  a  table.
        Leading  spaces are reliable when text is not being filled.  (Exception:
        when laying out a table with GNU [4mtbl[24m, specifying the [1mnospaces [22mregion op‐
        tion causes the program to ignore spaces  at  the  boundaries  of  table
        cells.)

     •  Comment your document.  It is never too soon to apply comments to record
        information of use to future document maintainers (including your future
        self).   The  [1m\"  [22mescape sequence causes the formatter to ignore the re‐
        mainder of the input line.

     •  Use the empty request——a control character  followed  immediately  by  a
        newline——to  visually  manage separation of material in the input.  Many
        of the [4mgroff[24m project’s own documents use an empty request  between  sen‐
        tences,  after macro definitions, and where a break is expected, and two
        empty requests between paragraphs or other requests or macro calls  that
        will  introduce  vertical  space into the document.  You can combine the
        empty request with the comment escape  sequence  to  include  whole‐line
        comments in your document, and even “comment out” sections of it.

     An example sufficiently long to illustrate most of the above suggestions in
     practice follows.  An arrow → indicates a tab character.

            .\"   nroff this_file.roff | less
            .\"   groff -T ps this_file.roff > this_file.ps
            →The theory of relativity is intimately connected with
            the theory of space and time.
            .
            I shall therefore begin with a brief investigation of
            the origin of our ideas of space and time,
            although in doing so I know that I introduce a
            controversial subject.  \" remainder of paragraph elided
            .
            .

            →The experiences of an individual appear to us arranged
            in a series of events;
            in this series the single events which we remember
            appear to be ordered according to the criterion of
            \[lq]earlier\[rq] and \[lq]later\[rq], \" punct swapped
            which cannot be analysed further.
            .
            There exists,
            therefore,
            for the individual,
            an I-time,
            or subjective time.
            .
            This itself is not measurable.
            .
            I can,
            indeed,
            associate numbers with the events,
            in such a way that the greater number is associated with
            the later event than with an earlier one;
            but the nature of this association may be quite
            arbitrary.
            .
            This association I can define by means of a clock by
            comparing the order of events furnished by the clock
            with the order of a given series of events.
            .
            We understand by a clock something which provides a
            series of events which can be counted,
            and which has other properties of which we shall speak
            later.
            .\" Albert Einstein, _The Meaning of Relativity_, 1922

   [1mEditing with Emacs[0m
     Official  GNU doctrine holds that the best program for editing a [4mroff[24m docu‐
     ment is Emacs; see ]8;;man:emacs(1)\[4memacs[24m(1)]8;;\.  It provides an [4mnroff[24m major mode that is suit‐
     able for all kinds of [4mroff[24m dialects.  This mode can  be  activated  by  the
     following methods.

     When  editing  a  file  within Emacs the mode can be changed by typing “[4mM‐x[0m
     [1mnroff-mode[22m”, where [4mM‐x[24m means to hold down  the  meta  key  (often  labelled
     “Alt”) while pressing and releasing the “x” key.

     It  is  also  possible  to have the mode automatically selected when a [4mroff[0m
     file is loaded into the editor.

     •  The most general approach includes file‐local variables at  the  end  of
        the file; we can also configure the fill column this way.
               .\" Local Variables:
               .\" fill-column: 72
               .\" mode: nroff
               .\" End:

     •  Certain  file name extensions, like those often used by man pages, acti‐
        vate [4mnroff[24m mode automatically.

     •  Loading a file with the sequence
               .\" -*- nroff -*-
        in its first line into an Emacs buffer causes the editor  to  enter  its
        [4mnroff[24m  major  mode.   Unfortunately,  some implementations of the ]8;;man:man(1)\[4mman[24m(1)]8;;\
        program are confused by this practice, so we discourage it.

   [1mEditing with Vim[0m
     Other editors provide support for [4mroff[24m‐style files too, such as ]8;;man:vim(1)\[4mvim[24m(1)]8;;\,  an
     extension  of  the ]8;;man:vi(1)\[4mvi[24m(1)]8;;\ program.  Vim’s highlighting can be made to recog‐
     nize [4mroff[24m files by setting the [1mfiletype [22moption in a Vim [4mmodeline[24m.  For this
     feature to work, your copy of [4mvim[24m must be built with support for, and  con‐
     figured  to enable, several features; consult the editor’s online help top‐
     ics “auto-setting”, “filetype”, and “syntax”.  Then put  the  following  at
     the end of your [4mroff[24m files, after any Emacs configuration.

                   .\" vim: set filetype=groff textwidth=72:

     Replace  “groff”  in  the  above with “nroff” if you want highlighting that
     does [4mnot[24m recognize many of the GNU extensions to  [4mroff[24m,  such  as  request,
     register, and string names longer than two characters.

[1mAuthors[0m
     This document was written by ]8;;mailto:groff-bernd.warken-72@web.de\Bernd Warken]8;;\ and ]8;;mailto:g.branden.robinson@gmail.com\G. Branden Robinson]8;;\.

[1mSee also[0m
     Much [4mroff[24m documentation is available.  The Bell Labs papers describing AT&T
     [4mtroff[24m remain available, and [4mgroff[24m is documented comprehensively.

   [1mInternet sites[0m
     ]8;;https://github.com/larrykollar/Unix-Text-Processing\[4mUnix[24m  [4mText[24m  [4mProcessing[24m]8;;\,  by  Dale  Dougherty and Tim O’Reilly, 1987, Hayden
     Books.  This well‐regarded text brings the reader from a state of no knowl‐
     edge of Unix or text editing (if necessary) to sophisticated computer‐aided
     typesetting.  It has been placed under a free software license by  its  au‐
     thors and updated by a team of [4mgroff[24m contributors and enthusiasts.

     ]8;;http://manpages.bsd.lv/history.html\“History  of  Unix  Manpages”]8;;\,  an  online article maintained by the mdocml
     project, provides an overview of [4mroff[24m development from Saltzer’s [4mRUNOFF[24m  to
     2008, with links to original documentation and recollections of the authors
     and their contemporaries.

     ]8;;http://www.troff.org/\troff.org]8;;\,  Ralph  Corderoy’s [4mtroff[24m site, provides an overview and pointers
     to much historical [4mroff[24m information.

     ]8;;http://www.multicians.org/\Multicians]8;;\, a site by Multics enthusiasts, contains a lot of information on
     the MIT projects CTSS and Multics, including [4mRUNOFF[24m; it is especially  use‐
     ful for its glossary and the many links to historical documents.

     ]8;;http://www.tuhs.org/Archive/\The Unix Archive]8;;\, curated by the Unix Heritage Society, provides the source
     code  and  some binaries of historical Unices (including the source code of
     some versions of [4mtroff[24m and its documentation) contributed  by  their  copy‐
     right holders.

     ]8;;http://web.mit.edu/Saltzer/www/publications/pubs.html\Jerry  Saltzer’s  home page]8;;\ stores some documents using the original [4mRUNOFF[0m
     formatting language.

     ]8;;http://www.gnu.org/software/groff\[4mgroff[24m]8;;\, GNU [4mroff[24m’s web site, provides convenient access  to  [4mgroff[24m’s  source
     code repository, bug tracker, and mailing lists (including archives and the
     subscription interface).

   [1mHistorical [4mroff[24m documentation[0m
     Many  AT&T  [4mtroff[24m documents are available online, and can be found at Ralph
     Corderoy’s site (see above) or via Internet search.  Of  foremost  signifi‐
     cance  are  those describing the language and its device‐independent imple‐
     mentation.

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

     “A  Typesetter‐independent  TROFF”  by  Brian W. Kernighan, 1982, AT&T Bell
     Laboratories Computing Science Technical Report No. 97.

     You can obtain many relevant Bell Labs papers in PDF  from  ]8;;https://github.com/bwarken/roff_classical.git\Bernd  Warken’s
     “roff classical” GitHub repository]8;;\.

   [1mManual pages[0m
     A  componentized  system like [4mroff[24m potentially has many man pages, each de‐
     scribing an aspect of it.  Unfortunately, there  is  no  consistent  naming
     scheme for these pages among the various implementations.

     In  GNU  [4mroff[24m,  the  ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ man page enumerates all man pages distributed
     with the system, and individual pages  frequently  refer  to  external  re‐
     sources as well as manuals on a variety of topics imbricated with [4mgroff[24m.

     In  other [4mroff[24ms, you are on your own, but ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ might be a good starting
     point.

groff 1.24.1                       2026‐03‐20                            [4mroff[24m(7)
