[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‐05‐15                       [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/opt/local/share/groff/1.24.1/font/devps/download[24m and [4m/opt/local/[0m
     [4mshare/groff/1.24.1/font/devpdf/download[24m enables it to be  embedded  in  the
     output produced 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/opt/local/share/groff/1.24.1/font/devps/DESC[0m
            describes the [1mps [22moutput device.

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

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

     [4m/opt/local/share/groff/1.24.1/font/devps/generate/dingbats.map[0m
     [4m/opt/local/share/groff/1.24.1/font/devps/generate/dingbats-reversed.map[0m
     [4m/opt/local/share/groff/1.24.1/font/devps/generate/slanted-symbol.map[0m
     [4m/opt/local/share/groff/1.24.1/font/devps/generate/symbol.map[0m
     [4m/opt/local/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‐05‐15                        [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/opt/local/share/groff/1.24.1/pic/chem.pic[0m
            A collection of [4mpic[24m macros needed by [4mchem[24m.

     [4m/opt/local/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/opt/local/share/doc/groff-1.24.1/examples/chem/[24m*[4m.chem[0m
            Example files for [4mchem[24m.

     [4m/opt/local/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‐05‐15                            [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/opt/local/share/groff/[0m
     [4msite-tmac[24m,  and  finally  in the standard macro directory [4m/opt/local/share/[0m
     [4mgroff/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/opt/local/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‐05‐15                             [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‐05‐15                       [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‐05‐15                         [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‐05‐15                       [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‐05‐15                           [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‐05‐15                         [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‐05‐15                      [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/opt/local/share/groff/site-font[24m,    [4m/opt/local/share/groff/1.24.1/[0m
             [4mfont[24m, and [4m/usr/lib/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/opt/[0m
             [4mlocal/share/groff/site-tmac[24m,   and   [4m/opt/local/share/groff/1.24.1/[0m
             [4mtmac[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/opt/local/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‐05‐15                             [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/opt/local/share/groff/1.24.1/font/devdvi/DESC[0m
            describes the [1mdvi [22moutput device.

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

     [4m/opt/local/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/opt/local/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‐05‐15                          [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, output is piped to ]8;;man:lpr(1)\[4mlpr[24m(1)]8;;\.  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:///opt/local/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/opt/local/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/opt/local/bin[0m
            Directory containing [4mgroff[24m’s executable commands.

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

     [4m/opt/local/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/opt/local/share/doc/groff-1.24.1[0m
            Documentation directory.

     [4m/opt/local/share/doc/groff-1.24.1/examples[0m
            Example directory.

     [4m/opt/local/share/groff/1.24.1/font[0m
            Font directory.

     [4m/opt/local/share/doc/groff-1.24.1/html[0m
            HTML documentation directory.

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

     [4m/opt/local/share/groff/site-font[0m
            Local font directory.

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

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

     [4m/opt/local/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/opt/local/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/opt/local/share/[0m
     [4mgroff/1.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/opt/local/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‐05‐15                           [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 /opt/local/share/doc/groff-1.24.1/meintro.me[0m
     at the command line results in
            groff -me /opt/local/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 /opt/local/share/doc/groff-1.24.1/pic.ms[0m
     outputs
            groff -e -p -t -ms /opt/local/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/opt/local/share/[0m
     [4mdoc/groff-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‐05‐15                            [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/opt/local/share/groff/1.24.1/font/devhtml/DESC[0m
            describes the [1mhtml [22moutput device.

     [4m/opt/local/share/groff/1.24.1/font/devhtml/[24mF
            describes the font known as [4mF[24m on device [1mhtml[22m.

     [4m/opt/local/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/opt/local/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‐05‐15                         [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/opt/local/share/groff/1.24.1/font/devlbp/DESC[0m
            describes the [1mlbp [22moutput device.

     [4m/opt/local/share/groff/1.24.1/font/devlbp/[24mF
            describes the font known as [4mF[24m on device [1mlbp[22m.

     [4m/opt/local/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‐05‐15                          [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/opt/local/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/opt/local/share/groff/1.24.1/font/devlj4/DESC[0m
            describes the [1mlj4 [22moutput device.

     [4m/opt/local/share/groff/1.24.1/font/devlj4/[24mF
            describes the font known as [4mF[24m on device [1mlj4[22m.

     [4m/opt/local/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‐05‐15                          [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/opt/[0m
     [4mlocal/share/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/opt/local/share/groff/1.24.1/font/devpdf/DESC[0m
            describes the [1mpdf [22moutput device.

     [4m/opt/local/share/groff/1.24.1/font/devpdf/[24mF
            describes the font known as [4mF[24m on device [1mpdf[22m.

     [4m/opt/local/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/opt/local/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/opt/local/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/opt/local/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/opt/local/share/groff/1.24.1/font/devpdf/symbolsl.pfb[0m
            supplies the slanted symbol font known to [4mgroff[24m as [1mSS[22m.

     [4m/opt/local/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/opt/local/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/opt/local/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/opt/local/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/opt/local/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/opt/local/share/doc/groff-1.24.1/sboxes/msboxes.ms[0m
     [4m/opt/local/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‐05‐15                          [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=/opt/local/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/opt/local/[0m
     [4mshare/groff/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/opt/local/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=/opt/local/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/opt/local/share/groff/1.24.1/font/devps/DESC[0m
            describes the [1mps [22moutput device.

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

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

     [4m/opt/local/share/groff/1.24.1/font/devps/prologue[0m
            is the default PostScript prologue prefixed to every output file.

     [4m/opt/local/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/opt/local/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/opt/local/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/opt/local/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/opt/local/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‐05‐15                           [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/opt/local/share/groff/1.24.1/font/devascii/DESC[0m
            describes the [1mascii [22moutput device.

     [4m/opt/local/share/groff/1.24.1/font/devascii/[24mF
            describes the font known as [4mF[24m on device [1mascii[22m.

     [4m/opt/local/share/groff/1.24.1/font/devlatin1/DESC[0m
            describes the [1mlatin1 [22moutput device.

     [4m/opt/local/share/groff/1.24.1/font/devlatin1/[24mF
            describes the font known as [4mF[24m on device [1mlatin1[22m.

     [4m/opt/local/share/groff/1.24.1/font/devutf8/DESC[0m
            describes the [1mutf8 [22moutput device.

     [4m/opt/local/share/groff/1.24.1/font/devutf8/[24mF
            describes the font known as [4mF[24m on device [1mutf8[22m.

     [4m/opt/local/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/opt/local/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‐05‐15                          [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/opt/local/share/groff/1.24.1/font/devlj4/DESC[0m
            describes the [1mlj4 [22moutput device.

     [4m/opt/local/share/groff/1.24.1/font/devlj4/[24mF
            describes the font known as [4mF[24m on device [1mlj4[22m.

     [4m/opt/local/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/opt/local/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/opt/local/share/groff/1.24.1/font/devlj4/generate/special.map[0m
     [4m/opt/local/share/groff/1.24.1/font/devlj4/generate/symbol.map[0m
     [4m/opt/local/share/groff/1.24.1/font/devlj4/generate/text.map[0m
     [4m/opt/local/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‐05‐15                        [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/opt/local/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/opt/local/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‐05‐15                         [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‐05‐15                           [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‐05‐15                         [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/opt/local/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‐05‐15                          [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‐05‐15                            [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/opt/local/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/opt/local/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‐05‐15                           [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/opt/local/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‐05‐15                          [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‐05‐15                         [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/opt/local/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/opt/local/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‐05‐15                             [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‐05‐15                       [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‐05‐15                         [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/opt/local/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‐05‐15                           [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‐05‐15                          [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‐05‐15                             [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/opt/local/share/groff/1.24.1/font/devdvi/DESC[0m
            describes the [1mdvi [22moutput device.

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

     [4m/opt/local/share/groff/1.24.1/font/devdvi/generate/ec.map[0m
     [4m/opt/local/share/groff/1.24.1/font/devdvi/generate/msam.map[0m
     [4m/opt/local/share/groff/1.24.1/font/devdvi/generate/msbm.map[0m
     [4m/opt/local/share/groff/1.24.1/font/devdvi/generate/tc.map[0m
     [4m/opt/local/share/groff/1.24.1/font/devdvi/generate/texb.map[0m
     [4m/opt/local/share/groff/1.24.1/font/devdvi/generate/texex.map[0m
     [4m/opt/local/share/groff/1.24.1/font/devdvi/generate/texi.map[0m
     [4m/opt/local/share/groff/1.24.1/font/devdvi/generate/texitt.map[0m
     [4m/opt/local/share/groff/1.24.1/font/devdvi/generate/texmi.map[0m
     [4m/opt/local/share/groff/1.24.1/font/devdvi/generate/texr.map[0m
     [4m/opt/local/share/groff/1.24.1/font/devdvi/generate/texsy.map[0m
     [4m/opt/local/share/groff/1.24.1/font/devdvi/generate/textex.map[0m
     [4m/opt/local/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‐05‐15                        [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/opt/local/share/groff/[0m
            [4msite-font[24m),  a  standard  location   ([4m/opt/local/share/groff/1.24.1/[0m
            [4mfont[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/opt/local/[0m
            [4mshare/groff/site-tmac[24m), and a standard  location  ([4m/opt/local/share/[0m
            [4mgroff/1.24.1/tmac[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/opt/local/share/groff/1.24.1/tmac/troffrc[0m
            is an initialization macro file loaded  before  any  macro  packages
            specified with [1m-m [22moptions.

     [4m/opt/local/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/opt/local/share/groff/1.24.1/tmac/[24mname[4m.tmac[0m
            are macro files distributed with [4mgroff[24m.

     [4m/opt/local/share/groff/1.24.1/font/dev[24mname[4m/DESC[0m
            describes the output device [4mname[24m.

     [4m/opt/local/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‐05‐15                           [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/opt/local/share/groff/1.24.1/font/dev[24mname[4m/DESC[0m
            describes the output device [4mname[24m.

     [4m/opt/local/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‐05‐15                      [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/opt/local/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‐05‐15                       [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:///opt/local/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‐05‐15                      [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/opt/local/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‐05‐15                           [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/opt/local/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/opt/local/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‐05‐15                      [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 +[4mij[24m−=Σ11([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‐05‐15                      [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/opt/local/share/doc/groff-1.24.1/examples/hdtbl/common.roff[24m pro‐
     vides 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‐05‐15                     [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/opt/local/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/opt/local/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/opt/local/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/opt/local/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/opt/local/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/opt/local/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‐05‐15                       [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/opt/local/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/opt/local/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/opt/local/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/opt/local/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/opt/local/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/opt/local/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‐05‐15                 [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/opt/local/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/opt/local/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/opt/local/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/opt/local/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/opt/local/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/opt/local/share/groff/1.24.1/tmac/mdoc/doc-nroff[0m
             defines parameters appropriate for rendering to terminal devices.

     [4m/opt/local/share/groff/1.24.1/tmac/mdoc/doc-ditroff[0m
             defines parameters appropriate for rendering to typesetter devices.

     [4m/opt/local/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/opt/local/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‐05‐15                      [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/opt/local/share/groff/1.24.1/tmac/e.tmac[0m
            implements the package.

     [4m/opt/local/share/groff/1.24.1/tmac/refer-me.tmac[0m
            implements ]8;;man:refer(1)\[4mrefer[24m(1)]8;;\ support for [4mme[24m.

     [4m/opt/local/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/opt/local/share/doc/groff-1.24.1/meintro.me[0m
     [4m/opt/local/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/opt/local/share/doc/groff-1.24.1/meref.me[0m
     [4m/opt/local/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‐05‐15                        [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/opt/[0m
     [4mlocal/share/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[0m
     [1m-msv[22m”.

     This package can also be localized by site or territory; for example, [4m/opt/[0m
     [4mlocal/share/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/opt/local/share/groff/1.24.1/[0m
     [4mtmac/mm/[24mterritory[4m_locale[24m  to  be loaded at package initialization.  If this
     mechanism  is  not  used,  [4m/opt/local/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/opt/local/share/groff/1.24.1/tmac/mm/[24mstyle
             [4m.cov[24m 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[0m
             package.  A [4m.cov[24m file must define a [1mCOVEND [22mmacro, which a  document
             must  call at the end of the cover description.  Use cover descrip‐
             tion 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/opt/local/share/groff/1.24.1/tmac/mm/[24mtype
             [4m.MT[24m and load it with the [1mmso [22mrequest.  Memorandum types 0 to 5  are
             supported;  any  other value of [4mtype[24m is mapped to type 6.  Omitting
             [4mtype[24m 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/opt/local/share/groff/1.24.1/tmac/m.tmac[0m
            is the [4mgroff[24m implementation of the memorandum macros.

     [4m/opt/local/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/opt/local/share/groff/1.24.1/tmac/refer-mm.tmac[0m
            implements ]8;;man:refer(1)\[4mrefer[24m(1)]8;;\ support for [4mmm[24m.

     [4m/opt/local/share/groff/1.24.1/tmac/mm/ms.cov[0m
            implements an [4mms[24m‐like cover page.

     [4m/opt/local/share/groff/1.24.1/tmac/mm/0.MT[0m
            implements memorandum types 0–3 and 6.

     [4m/opt/local/share/groff/1.24.1/tmac/mm/4.MT[0m
            implements memorandum type 4.

     [4m/opt/local/share/groff/1.24.1/tmac/mm/5.MT[0m
            implements memorandum type 5.

     [4m/opt/local/share/groff/1.24.1/tmac/mm/locale[0m
            performs any (further) desired localization if present.

     [4m/opt/local/share/doc/groff-1.24.1/examples/letter.mm[0m
            illustrates features of the [1mLT [22mletter formats.

     [4m/opt/local/share/doc/groff-1.24.1/examples/memorandum.mm[0m
            illustrates features of the [1mMT [22mmemorandum formats.

     [4m/opt/local/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‐05‐15                        [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/opt/local/share/groff/1.24.1/tmac/mse.tmac[0m

     [4m/opt/local/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‐05‐15                      [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/opt/local/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/opt/local/share/groff/1.24.1/tmac/om.tmac[0m
            implements the package.

     [4m/opt/local/share/doc/groff-1.24.1/html/mom/toc.html[0m
            is the entry point to the HTML documentation.

     [4m/opt/local/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/opt/local/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/opt/local/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‐05‐15                       [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/opt/local/share/groff/1.24.1/tmac/s.tmac[0m
            implements the package.

     [4m/opt/local/share/groff/1.24.1/tmac/refer-ms.tmac[0m
            implements ]8;;man:refer(1)\[4mrefer[24m(1)]8;;\ support for [4mms[24m.

     [4m/opt/local/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/opt/local/share/doc/groff-1.24.1/ms.ms[0m
     [4m/opt/local/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/opt/local/share/doc/groff-1.24.1/msboxes.ms[0m
     [4m/opt/local/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‐05‐15                        [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/opt/local/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‐05‐15                   [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/opt/local/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‐05‐15                     [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/opt/local/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‐05‐15                       [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‐05‐15                            [4mroff[24m(7)
