[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.0                       2025-07-04                       [4maddftinfo[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mafmtodit[24m(1)                  General Commands Manual                 [4mafmtodit[24m(1)

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

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

     [1mafmtodit --help[0m

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

     [4m/usr/share/groff/1.24.0/font/devps/generate/dingbats.map[0m
     [4m/usr/share/groff/1.24.0/font/devps/generate/dingbats-reversed.map[0m
     [4m/usr/share/groff/1.24.0/font/devps/generate/slanted-symbol.map[0m
     [4m/usr/share/groff/1.24.0/font/devps/generate/symbol.map[0m
     [4m/usr/share/groff/1.24.0/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.0                       2026-01-24                        [4mafmtodit[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mchem[24m(1)                      General Commands Manual                     [4mchem[24m(1)

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

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

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

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

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

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

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

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

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

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

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

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

     As an example,

            .cstart
            CH3
            bond
            CH3
            .cend

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

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

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

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

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

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

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

     or

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

            R1: ring pointing up
            R2: ring pointing right

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

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

     creates two benzene rings connected along a side.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

            [1mbond ; BP[0m

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

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

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

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

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

            First: bond
                   "bond 30 from First"

   [1mMiscellaneous[0m
     The specific construction

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

     is equivalent to

            bond
            moiety

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

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

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

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

     The command

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

     There is no decent primitive for brackets.

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

     A squiggle bond is needed.

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

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

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

     [4m/usr/share/doc/groff-1.24.0/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.0                       2026-01-19                            [4mchem[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4meqn[24m(1)                       General Commands Manual                      [4meqn[24m(1)

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

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

     [1meqn --help[0m

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

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

     Unless the [1m-R [22moption is used, [4meqn[24m searches for the file [4meqnrc[24m in the direc‐
     tories given with the [1m-M [22moption first, then in  [4m/usr/share/groff/site-tmac[24m,
     and  finally  in the standard macro directory [4m/usr/share/groff/1.24.0/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.

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

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

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

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

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

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

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

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

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

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

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

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

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

[1mFiles[0m
     [4m/usr/share/groff/1.24.0/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 “Customziation” 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.0                       2026-02-03                             [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.0                       2024-05-03                       [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.0                       2026-01-28                         [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.0                       2026-01-19                       [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.0                       2025-12-21                           [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.0                       2025-12-30                         [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.0                       2024-05-03                      [4mgrap2graph[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mgrn[24m(1)                       General Commands Manual                      [4mgrn[24m(1)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[1mFiles[0m
     [4m/usr/share/groff/1.24.0/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.0                       2024-12-03                             [4mgrn[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mgrodvi[24m(1)                    General Commands Manual                   [4mgrodvi[24m(1)

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

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

     [1mgrodvi --help[0m

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

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

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

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

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

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

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

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

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

     The following fonts are not members of a family.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

     [4m/usr/share/groff/1.24.0/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.0                       2026-01-29                          [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 “[1mA4[22m”.  If the
     [4mDESC[24m  file  lacks  this  information, the formatter and output driver use a
     page length of [1m“[22m11i[1m” [22m(eleven inches) for  compatibility  with  AT&T  [4mtroff[24m.
     See ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

     [1mpdf       [22mfor PDF output.

     [1mps        [22mfor PostScript output.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

            $(grog -Tutf8 foo.me)

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

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

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

     [4m/etc/X11/app-defaults[0m
            Application defaults directory for ]8;;man:gxditview(1)\[4mgxditview[24m(1)]8;;\.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   [4m[1mgroff[24m device and font description directory[0m
     Device and font description files supplied with  GNU  [4mroff[24m  are  stored  in
     [4m/usr/share/groff/1.24.0/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.0                       2026-01-24                           [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  the  ]8;;man:preconv(1;)\[4mpreconv[24m(1;)]8;;\  see the [1m-D[22m, [1m-k[22m, and [1m-K [22moptions of
     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\.  For UTF-8 input, [1m-k [22mis a good choice.

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

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

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

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

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

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

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

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

     Consider a file [4mdoc/grnexampl.me[24m, which uses the [4mgrn[24m  preprocessor  to  in‐
     clude  a  ]8;;man:gremlin(1)\[4mgremlin[24m(1)]8;;\  picture file in an [4mme[24m document.  Let's say we want to
     suppress color output, produce a DVI file, and get backtraces for  any  er‐
     rors that [4mtroff[24m encounters.  The command
            [1mgrog -bc -Idoc -Tdvi doc/grnexmpl.me[0m
     is processed by [4mgrog[24m into
            groff -bc -Idoc -Tdvi -e -g -me doc/grnexmpl.me
     where we can see that [4mgrog[24m has inferred the [4mme[24m macro package along with the
     [4meqn[24m  and  [4mgrn[24m preprocessors.  (The input file is located in [4m/usr/share/doc/[0m
     [4mgroff-1.24.0[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.0                       2025-12-21                            [4mgrog[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mgrohtml[24m(1)                   General Commands Manual                  [4mgrohtml[24m(1)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[1mEnvironment[0m
     [4mGROFF_FONT_PATH[0m
            lists directories in which to search for [4mdevhtml[24m,  [4mgrohtml[24m's  direc‐
            tory  of  device  and  font  description  files.   See  ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ and
            ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

     [4mSOURCE_DATE_EPOCH[0m
            A timestamp (expressed as seconds since the Unix epoch)  to  use  as
            the  output  creation  timestamp  in place of the current time.  The
            time  is  converted  to  human-readable  form  using  ]8;;man:gmtime(3)\[4mgmtime[24m(3)]8;;\  and
            ]8;;man:asctime(3)\[4masctime[24m(3)]8;;\, and recorded in an HTML comment.

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

[1mFiles[0m
     [4m/usr/share/groff/1.24.0/font/devhtml/DESC[0m
            describes the [1mhtml [22moutput device.

     [4m/usr/share/groff/1.24.0/font/devhtml/[24mF
            describes the font known as [4mF[24m on device [1mhtml[22m.

     [4m/usr/share/groff/1.24.0/tmac/html.tmac[0m
            defines  font  mappings, special characters, and colors for use with
            the [1mhtml [22moutput device.  It is automatically loaded by [4mtroffrc[24m  when
            either of the [1mhtml [22mor [1mxhtml [22moutput devices is selected.

     [4m/usr/share/groff/1.24.0/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.0                       2026-01-04                         [4mgrohtml[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mgrolbp[24m(1)                    General Commands Manual                   [4mgrolbp[24m(1)

[1mName[0m
     grolbp - [4mgroff[24m output driver for Canon CaPSL printers

[1mSynopsis[0m
     [1mgrolbp [22m[[1m-l[22m] [[1m-c [4m[22mnum-copies[24m] [[1m-F [4m[22mfont-directory[24m] [[1m-o [4m[22morientation[24m] [[1m-p [4m[22mpaper-[0m
            [4mformat[24m] [[1m-w [4m[22mwidth[24m] [[4mfile[24m ...]
     [1mgrolbp [22m[[1m--copies=[4m[22mnum-copies[24m] [[1m--fontdir=[4m[22mfont-directory[24m] [[1m--landscape[22m]
            [[1m--linewidth=[4m[22mwidth[24m] [[1m--orientation=[4m[22morientation[24m] [[1m--papersize=[4m[22mpaper-[0m
            [4mformat[24m] [[4mfile[24m ...]

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

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

[1mDescription[0m
     This GNU [4mroff[24m output driver translates the output of ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ into a  CaPSL
     and  VDM  format  suitable  for  Canon LBP-4 and LBP-8 printers.  Normally,
     [4mgrolbp[24m is invoked by ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ when the latter is given the “[1m-T lbp[22m” option.
     (In this installation, [1mps [22mis the default output device.)   Use  [4mgroff[24m's  [1m-P[0m
     option to pass any options shown above to [4mgrolbp[24m.  If no [4mfile[24m arguments are
     given,  or  if  [4mfile[24m  is  “-”,  [4mgrolbp[24m reads the standard input stream.  It
     writes to the standard output stream.

   [1mTypefaces[0m
     The driver supports the Dutch, Swiss, and Swiss-Narrow scalable  typefaces,
     each  in  the regular, bold, italic, and bold-italic styles.  Additionally,
     the bitmapped, monospaced Courier and Elite typefaces are available in reg‐
     ular, bold, and italic styles; Courier at 8 and 12 points, Elite at  8  and
     10 points.  The following chart summarizes the [4mgroff[24m font names used to ac‐
     cess them.

           ┌───────────────┬─────────┬────────┬──────────┬──────────────┐
           │   [1mTypeface    [22m│  [1mRoman  [22m│  [1mBold  [22m│  [1mItalic  [22m│  [1mBold-Italic [22m│
           ├───────────────┼─────────┼────────┼──────────┼──────────────┤
           │ Dutch         │  TR     │  TB    │  TI      │  TBI         │
           ├───────────────┼─────────┼────────┼──────────┼──────────────┤
           │ Swiss         │  HR     │  HB    │  HI      │  HBI         │
           ├───────────────┼─────────┼────────┼──────────┼──────────────┤
           │ Swiss Narrow  │  HNR    │  HNB   │  HNI     │  HNBI        │
           ├───────────────┼─────────┼────────┼──────────┼──────────────┤
           │ Courier       │  CR     │  CB    │  CI      │              │
           ├───────────────┼─────────┼────────┼──────────┼──────────────┤
           │ Elite         │  ER     │  EB    │  EI      │              │
           └───────────────┴─────────┴────────┴──────────┴──────────────┘

   [1mPaper format, orientation, and device description file[0m
     [4mgrolbp[24m  supports  paper  formats  “[1mA4[22m”, “[1mletter[22m”, “[1mlegal[22m”, and “[1mexecutive[22m”.
     These are matched case-insensitively.  The [1m-p[22m, [1m--papersize [22moption overrides
     any setting in the device description file [4mDESC[24m.  If  neither  specifies  a
     paper format, A4 is assumed.

     In its [4mDESC[24m file, [4mgrolbp[24m (case-insensitively) recognizes an [1morientation [22mdi‐
     rective accepting one mandatory argument, [1mportrait [22mor [1mlandscape[22m.  The first
     valid orientation directive encountered controls.  The [1m-l[22m, [1m-o[22m, and [1m--orien‐[0m
     [1mtation  [22mcommand-line  options override any setting in [4mDESC[24m.  If none of the
     foregoing specify the orientation, portrait is assumed.

   [1mFont description files[0m
     In  addition  to  the  font  description  file  directives  documented   in
     ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\, [4mgrolbp[24m recognizes [1mlbpname[22m, which maps the [4mgroff[24m font name to
     the font name used internally by the printer.  Its syntax is as follows.
            lbpname [4mprinter-font-name[0m
     [1mlbpname[22m's argument is case-sensitive.  The printer's font names are encoded
     as follows.

     For bitmapped fonts, [4mprinter-font_name[24m has the form [1mN[22m⟨[4mbase-font-name[24m⟩⟨[4mfont-[0m
     [4mstyle[24m⟩.   [4mbase-font-name[24m  is  the  font name as it appears in the printer's
     font listings without the first letter, up to (but not including) the  font
     size.   [4mfont-style[24m can be one of the letters [1mR[22m, [1mI[22m, or [1mB[22m, indicating the ro‐
     man, italic, and bold styles, respectively.  For instance, if the printer's
     “font listing A” shows “Nelite12I.ISO_USA”, the corresponding entry in  the
     [4mgroff[24m  font  description file is “[1mlbpname NeliteI[22m”.  You may need to modify
     [4mgrolbp[24m to add support for new bitmapped fonts,  since  the  available  font
     names  and  font  sizes  of bitmapped fonts (as documented above) are hard-
     coded into the program.

     For scalable fonts, [4mprinter-font-name[24m is identical to the font name  as  it
     appears  in  the  printer's  “font listing A”.  For instance, to select the
     “Swiss” font in bold-italic style, which appears in  the  font  listing  as
     “Swiss-BoldOblique”, “[1mlbpname Swiss-BoldOblique[22m” is the required directive,
     and this is what we find in the [4mgroff[24m font description file [4mHBI[24m for the [1mlbp[0m
     device.

   [1mDrawing commands[0m
     For  compatibility  with ]8;;man:grolj4(1)\[4mgrolj4[24m(1)]8;;\, an additional drawing command is avail‐
     able.

     [1m\D'R [4m[22mdh[24m [4mdv[24m[1m'[0m
            Draw a rule (solid black rectangle) with one corner at  the  drawing
            position, and the diagonally opposite corner at the drawing position
            +([4mdh[24m,[4mdv[24m).

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

     [1m-c [4m[22mnum-copies[0m
     [1m--copies=[4m[22mnum-copies[0m
            Produce [4mnum-copies[24m copies of each page.

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

     [1m-l[0m
     [1m--landscape[0m
            Format the document in landscape orientation.

     [1m-o [4m[22morientation[0m
     [1m--orientation=[4m[22morientation[0m
            Format  the  document  in  the  given  [4morientation[24m,  which  must  be
            “[1mportrait[22m” or “[1mlandscape[22m”.

     [1m-p [4m[22mpaper-format[0m
     [1m--papersize=[4m[22mpaper-format[0m
            Set the paper format to [4mpaper-format[24m, which must be  a  valid  paper
            format as described above.

     [1m-w [4m[22mwidth[0m
     [1m--linewidth=[4m[22mwidth[0m
            Set  the  default  line thickness to [4mwidth[24m thousandths of an em; the
            default is [1m40 [22m(0.04 em).

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

[1mEnvironment[0m
     [4mGROFF_FONT_PATH[0m
            lists  directories in which to seek the selected output device's di‐
            rectory of device and font  description  files.   See  ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\  and
            ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

[1mFiles[0m
     [4m/usr/share/groff/1.24.0/font/devlbp/DESC[0m
            describes the [1mlbp [22moutput device.

     [4m/usr/share/groff/1.24.0/font/devlbp/[24mF
            describes the font known as [4mF[24m on device [1mlbp[22m.

     [4m/usr/share/groff/1.24.0/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.0                       2024-11-30                          [4mgrolbp[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mgrolj4[24m(1)                    General Commands Manual                   [4mgrolj4[24m(1)

[1mName[0m
     grolj4 - [4mgroff[24m output driver for HP LaserJet 4 and compatible printers

[1mSynopsis[0m
     [1mgrolj4 [22m[[1m-l[22m] [[1m-c [4m[22mnum-copies[24m] [[1m-d [22m[[4mn[24m]] [[1m-F [4m[22mfont-directory[24m] [[1m-p [4m[22mpaper-format[24m]
            [[1m-w [4m[22mline-width[24m] [[4mfile[24m ...]

     [1mgrolj4 --help[0m

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

[1mDescription[0m
     This GNU [4mroff[24m output driver translates the output of ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ into  a  PCL5
     format suitable for a Hewlett-Packard LaserJet 4 printer.  Normally, [4mgrolj4[0m
     is  invoked  by ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ when the latter is given the “[1m-T lj4[22m” option.  (In
     this installation, [1mps [22mis the default output device.)  Use [4mgroff[24m's [1m-P [22moption
     to pass any options shown above to [4mgrolj4[24m.  If no [4mfile[24m arguments are given,
     or if [4mfile[24m is “-”, [4mgrolj4[24m reads the standard input stream.   It  writes  to
     the standard output stream.

   [1mTypefaces[0m
     [4mgrolj4[24m  supports the standard four styles: [1mR [22m(roman), [1mI [22m([4mitalic[24m), [1mB [22m([1mbold[22m),
     and [1mBI [22m([4m[1mbold-italic[24m[22m).  Fonts are grouped into families [1mA[22m, [1mC[22m, [1mG[22m, [1mO[22m,  [1mT[22m,  [1mTN[22m,
     [1mU[22m,  and  [1mUC [22mhaving members in each style.  For the convenience of a consis‐
     tent font repertoire in [4mgroff[24m, [4mlj4.tmac[24m (see section  “Files”  below)  uses
     [1mftr  [22mrequests  to remap [1mH [22m(“Helvetica”) font names to the [1mU [22mnames shown be‐
     low.

            [1mAB       [22mArial Bold
            [1mABI      [22mArial Bold Italic
            [1mAI       [22mArial Italic
            [1mAR       [22mArial Roman
            [1mCB       [22mCourier Bold
            [1mCBI      [22mCourier Bold Italic
            [1mCI       [22mCourier Italic
            [1mCR       [22mCourier Roman
            [1mGB       [22mGaramond Halbfett
            [1mGBI      [22mGaramond Kursiv Halbfett
            [1mGI       [22mGaramond Kursiv
            [1mGR       [22mGaramond Antiqua
            [1mOB       [22mCG Omega Bold
            [1mOBI      [22mCG Omega Bold Italic
            [1mOI       [22mCG Omega Italic
            [1mOR       [22mCG Omega Roman
            [1mOB       [22mCG Omega Bold
            [1mOBI      [22mCG Omega Bold Italic
            [1mOI       [22mCG Omega Italic
            [1mOR       [22mCG Omega Roman
            [1mTB       [22mCG Times Bold
            [1mTBI      [22mCG Times Bold Italic
            [1mTI       [22mCG Times Italic
            [1mTR       [22mCG Times Roman
            [1mTNRB     [22mM Times Bold
            [1mTNRBI    [22mM Times Bold Italic
            [1mTNRI     [22mM Times Italic
            [1mTNRR     [22mM Times Roman
            [1mUB       [22mUnivers Bold
            [1mUBI      [22mUnivers Bold Italic
            [1mUI       [22mUnivers Medium Italic
            [1mUR       [22mUnivers Medium
            [1mUCB      [22mUnivers Condensed Bold
            [1mUCBI     [22mUnivers Condensed Bold Italic
            [1mUCI      [22mUnivers Condensed Medium Italic
            [1mUCR      [22mUnivers Condensed Medium

     The following fonts are not members of a family.

            [1mALBB           [22mAlbertus Extra Bold
            [1mALBR           [22mAlbertus Medium
            [1mAOB            [22mAntique Olive Bold
            [1mAOI            [22mAntique Olive Italic
            [1mAOR            [22mAntique Olive Roman
            [1mCLARENDON      [22mClarendon
            [1mCORONET        [22mCoronet
            [1mLGB            [22mLetter Gothic Bold
            [1mLGI            [22mLetter Gothic Italic
            [1mLGR            [22mLetter Gothic Roman
            [1mMARIGOLD       [22mMarigold

     The special font is [1mS [22m(PostScript Symbol); [1mSYMBOL [22m(M Symbol), and [1mWINGDINGS[0m
     (Wingdings) are also available but not mounted by default.

   [1mPaper format and device description file[0m
     [4mgrolj4[24m supports paper formats “[1mA4[22m”, “[1mB5[22m”, “[1mC5[22m”, “[1mcom10[22m”, “[1mDL[22m”, “[1mexecutive[22m”,
     “[1mlegal[22m”, “[1mletter[22m”, and “[1mmonarch[22m”.  These  are  matched  case-insensitively.
     The  [1m-p  [22moption  overrides any setting in the device description file [4mDESC[24m.
     If neither specifies a paper format, “letter” is assumed.

   [1mFont description files[0m
     [4mgrolj4[24m recognizes four font description  file  directives  in  addition  to
     those documented in ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

     [1mpclweight [4m[22mn[0m
            Set  the  stroke  weight to [4mn[24m, an integer in the range -7 to +7; the
            default is 0.

     [1mpclstyle [4m[22mn[0m
            Set the style to [4mn[24m, an integer in the range 0 to 32767; the  default
            is 0.

     [1mpclproportional [4m[22mn[0m
            Set  the proportional spacing Boolean flag to [4mn[24m, which can be either
            0 or 1; the default is 0.

     [1mpcltypeface [4m[22mn[0m
            Set the typeface family to [4mn[24m, an integer in the range  0  to  65535;
            the default is 0.

   [1mDrawing commands[0m
     An  additional drawing command is recognized as an extension to those docu‐
     mented in ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\.

     [1m\D'R [4m[22mdh[24m [4mdv[24m[1m'[0m
            Draw a rule (solid black rectangle) with one corner at  the  drawing
            position, and the diagonally opposite corner at the drawing position
            +([4mdh[24m,[4mdv[24m),  at  which  the  drawing position will be afterward.  This
            generates a PCL fill rectangle command, and so will work on printers
            that do not support HP-GL/2, unlike the other [1m\D [22mcommands.

   [1mFonts[0m
     Nominally, HP LaserJet 4-series and newer printers have the  same  internal
     fonts.   45 fonts are scalable from 0.25 to 999.75 points in 0.25-point in‐
     crements.  A Lineprinter font is available only at 8.5 points.

     The LaserJet font files included with [4mgroff[24m assume that all printers  since
     the  LaserJet 4 are identical.  There are some differences between fonts in
     the earlier and more recent printers, however.  The LaserJet 4 printer used
     Agfa Intellifont technology for 35 of the internal scalable fonts; the  re‐
     maining   10   scalable   fonts   were   TrueType.    Beginning   with  the
     LaserJet 4000-series printers introduced in  1997,  all  scalable  internal
     fonts  have been TrueType.  The number of printable glyphs differs slightly
     between Intellifont and TrueType fonts (generally, the TrueType  fonts  in‐
     clude  more glyphs), and there are some minor differences in glyph metrics.
     Differences among printer models are described  in  the  [4mPCL[24m  [4m5[24m  [4mComparison[0m
     [4mGuide[24m  and  the  [4mPCL[24m  [4m5[24m  [4mComparison[24m [4mGuide[24m [4mAddendum[24m (for printers introduced
     since approximately 2001).

     LaserJet printers reference a glyph by a combination of a 256-glyph  symbol
     set  and  an index within that symbol set.  Many glyphs appear in more than
     one symbol set; all combinations of symbol set and index that reference the
     same glyph are equivalent.  For each glyph, ]8;;man:hpftodit(1)\[4mhpftodit[24m(1)]8;;\ searches a list  of
     symbol sets, and selects the first set that contains the glyph.  The print‐
     ing code generated by [4mhpftodit[24m is an integer that encodes a numerical value
     for the symbol set in the high byte(s), and the index in the low byte.  See
     ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\  for  a  complete description of the font file format; symbol
     sets are described in greater detail in the [4mPCL[24m [4m5[24m [4mPrinter[24m [4mLanguage[24m  [4mTechni‐[0m
     [4mcal[24m [4mReference[24m [4mManual[24m.

     Two  of  the  scalable  fonts, Symbol and Wingdings, are bound to 256-glyph
     symbol sets; the remaining scalable fonts, as well as the Lineprinter font,
     support numerous symbol sets, sufficient to enable printing  of  more  than
     600 glyphs.

     The metrics generated by [4mhpftodit[24m assume that the [4mDESC[24m file contains values
     of  1200 for [4mres[24m and 6350 for [4munitwidth[24m, or any combination (e.g., 2400 and
     3175) for which [4mres[24m × [4munitwidth[24m = 7620000.   Although  HP  PCL  5  LaserJet
     printers  support an internal resolution of 7200 units per inch, they use a
     16-bit signed integer for positioning; if [1mdevlj4 [22mis to support U.S.  ledger
     paper  (11  in  ×  17  in;  in  =  inch),  the maximum usable resolution is
     32767 ÷ 17, or 1927 units per inch, which rounds down  to  1200  units  per
     inch.    If   the   largest   required   paper  dimension  is  less  (e.g.,
     8.5 in × 11 in, or A5), a greater [4mres[24m (and lesser [4munitwidth[24m) can be  speci‐
     fied.

     Font  metrics  for  Intellifont  fonts  were provided by Tagged Font Metric
     (TFM) files originally developed by Agfa/Compugraphic.  The TFM files  pro‐
     vided  for  these fonts supported 600+ glyphs and contained extensive lists
     of kerning pairs.

     To accommodate developers who had become accustomed to TFM files,  HP  also
     provided  TFM  files  for the 10 TrueType fonts included in the LaserJet 4.
     The TFM files for TrueType fonts generally included less  information  than
     the Intellifont TFMs, supporting fewer glyphs, and in most cases, providing
     no  kerning  information.  By the time the LaserJet 4000 printer was intro‐
     duced, most developers had migrated to other means of obtaining  font  met‐
     rics,  and  support for new TFM files was very limited.  The TFM files pro‐
     vided for the  TrueType  fonts  in  the  LaserJet  4000  support  only  the
     ISO Latin-2 (8859-2) symbol set, and include no kerning information; conse‐
     quently,  they  are  of little value for any but the most rudimentary docu‐
     ments.

     Because the Intellifont TFM files contain  considerably  more  information,
     they  generally  are preferable to the TrueType TFM files even for use with
     the TrueType fonts in the newer printers.  The  metrics  for  the  TrueType
     fonts are very close, though not identical, to those for the earlier Intel‐
     lifont fonts of the same names.  Although most output using the Intellifont
     metrics  with the newer printers is quite acceptable, a few glyphs may fail
     to print as expected.  The differences in glyph metrics may be particularly
     noticeable with composite parentheses, brackets, and braces used by ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\.
     A script, located in [4m/usr/share/groff/1.24.0/font/devlj4/generate[24m,  can  be
     used to adjust the metrics for these glyphs in the special font “S” for use
     with printers that have all TrueType fonts.

     At  the  time  HP last supported TFM files, only version 1.0 of the Unicode
     standard was available.  Consequently, many glyphs  lacking  assigned  code
     points  were  assigned by HP to the Private Use Area (PUA).  Later versions
     of the Unicode standard included code points outside the PUA  for  many  of
     these  glyphs.  The HP-supplied TrueType TFM files use the PUA assignments;
     TFM files generated from more recent TrueType font files require the  later
     Unicode values to access the same glyphs.  Consequently, two different map‐
     ping  files may be required: one for the HP-supplied TFM files, and one for
     more recent TFM files.

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

     [1m-c [4m[22mnum-copies[0m
             Format [4mnum-copies[24m copies of each page.

     [1m-d [22m[[4mn[24m]  Use duplex mode [4mn[24m: 1 is  long-side  binding  (default),  and  2  is
             short-side binding.

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

     [1m-l      [22mFormat the document in landscape orientation.

     [1m-p [4m[22mpaper-format[0m
             Set  the  paper format to [4mpaper-format[24m, which must be a valid paper
             format as described above.

     [1m-w [4m[22mline-width[0m
             Set the default line thickness to [4mline-width[24m thousandths of an  em;
             the default is [1m40 [22m(0.04 em).

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

[1mEnvironment[0m
     [4mGROFF_FONT_PATH[0m
            lists directories in which to seek the selected output device's  di‐
            rectory  of  device  and  font  description files.  See ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ and
            ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

[1mFiles[0m
     [4m/usr/share/groff/1.24.0/font/devlj4/DESC[0m
            describes the [1mlj4 [22moutput device.

     [4m/usr/share/groff/1.24.0/font/devlj4/[24mF
            describes the font known as [4mF[24m on device [1mlj4[22m.

     [4m/usr/share/groff/1.24.0/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.0                       2026-01-29                          [4mgrolj4[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mgropdf[24m(1)                    General Commands Manual                   [4mgropdf[24m(1)

[1mName[0m
     gropdf - [4mgroff[24m output driver for Portable Document Format

[1mSynopsis[0m
     [1mgropdf [22m[[1m-delsW[22m] [{[1m-f[22m|[1m--format-options[22m} [4mbit-vector[24m] [[1m-F [4m[22mfont-directory[24m]
            [[1m-I [4m[22minclusion-directory[24m] [[1m-p [4m[22mpaper-format[24m] [[1m--pdfver [22m{[1m1.4[22m|[1m1.7[22m}]
            [[1m-u [22m[[4mcmap-file[24m]] [[1m-y [4m[22mfoundry[24m] [[4mfile[24m ...]

     [1mgropdf --help[0m

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

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

     See section “Font installation” below for a guide to installing  fonts  for
     [4mgropdf[24m.

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

     [1m-d      [22mInclude  debug  information  as comments within the PDF.  Also pro‐
             duces an uncompressed PDF.

     [1m-e      [22mForces [4mgropdf[24m to embed [4mall[24m fonts (even the 14 base PDF fonts).

     [1m--format-options [4m[22mbit-vector[0m
     [1m-f [4m[22mbit-vector[0m
             Specify  advanced  options  for  [4mgropdf.[24m   Familiarity   with   the
             ]8;;https://www.pdfa-inc.org/product/iso-32000-2-pdf-2-0-bundle-sponsored-access/\ISO 32000  PDF  standard]8;;\ is helpful.  The [4mbit-vector[24m argument is an
             integer that configures characteristics of the generated PDF.   Add
             the following values to combine them.

                    Value   Meaning
                    ────────────────────────────────────────────────────────────
                    [1m1       [22mSubset included Type 1 fonts.
                    [1m2       [22mUse more compact format for text by including space
                            as a character.  Fonts that do not include space as
                            a glyph may conflict with this feature.
                    [1m4       [22mCompress all data streams.
                    [1m8       [22mDon't  embed  font  files.  (A font required by the
                            document is not embedded; usually not useful.)

             The default feature combination is 7.  To mimic  what  [4mgropdf[24m  from
             [4mgroff[24m 1.23 produced, specify “6” to turn off subsetting.

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

     [1m-I [4m[22mdir[24m  Search  the directory [4mdir[24m for files named in [1m\X'pdf: pdfpic' [22mdevice
             extension commands.  [1m-I [22mmay be specified more than once;  each  [4mdir[0m
             is  searched in the given order.  To search the current working di‐
             rectory before others, add “[1m-I .[22m” at the desired place; it is  oth‐
             erwise searched last.

     [1m-l      [22mOrient the document in landscape format.

     [1m-p [4m[22mpaper-format[0m
             Set  the  physical dimensions of the output medium.  This overrides
             the [1mpapersize[22m, [1mpaperlength[22m, and [1mpaperwidth [22mdirectives in  the  [4mDESC[0m
             file;  it  accepts  the  same arguments as the [1mpapersize [22mdirective.
             See ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\ for details.

     [1m--pdfver [22m{[1m1.4[22m|[1m1.7[22m}
             PDF version 1.7 introduced a more compact object  format;  this  is
             now  the  default.  If you require the original format (as produced
             by [4mgropdf[24m 1.23) set the version to [1m1.4[22m.

     [1m-s      [22mAppend a comment line to end of PDF showing statistics, i.e. number
             of pages in document.  Ghostscript's [1mps2pdf  [22mcomplains  about  this
             line if it is included, but works anyway.

     [1m-u [22m[[4mcmap-file[24m]
             [4mgropdf[24m normally includes a ToUnicode CMap with any font created us‐
             ing  [4mtext.enc[24m  as the encoding file, this makes it easier to search
             for words which contain ligatures.  You can include your  own  CMap
             by  specifying  a  [4mcmap-file[24m or have no CMap at all by omitting the
             argument.

     [1m-W      [22mExit with failure status if any warnings are issued.

     [1m-y [4m[22mfoundry[0m
             Set the foundry to use for selecting fonts of the same name.

[1mUsage[0m
     [4mgropdf[24m's input must be in the format produced by ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ and described  in
     ]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\.   Further,  its  device  and font description files must meet
     certain requirements.  The device [1mresolution [22mmust be  an  integer  multiple
     of 72 times [1msizescale[22m.  By default, [4mgropdf[24m uses a [1mresolution [22mof 72000 and a
     [1msizescale  [22mof  1000.  A valid paper format is mandatory; see ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.
     While the PDF standard allows several font file formats (like TrueType), at
     present [4mgropdf[24m accepts only the same Type  1  Adobe  PostScript  format  as
     ]8;;man:grops(1)\[4mgrops[24m(1)]8;;\.   Fewer Type 1 fonts are supported natively in PDF documents than
     the standard 35 fonts supported by [4mgrops[24m and PostScript printers,  but  all
     are  available  since [4mgropdf[24m automatically embeds any that aren't specified
     by the PDF standard.

     [4mgropdf[24m supports [4mfoundries[24m that permit multiple providers to supply the same
     [4mgroff[24m font names.  [4mgroff[24m's compilation process attempts to  locate  Type  1
     fonts  on  the  system,  populates a [4mFoundry[24m file with their locations, and
     generates font description files corresponding to them.   Font  description
     files  can also be added after installation.  Each such file must contain a
     directive
            [1minternalname [4m[22mpsname[0m
     that maps the [4mgroff[24m font name (such as “TR”) to a PostScript name (such  as
     “Times-Roman”).   Lines  starting  with [1m# [22mand blank lines are ignored.  The
     code for each character given in the font file must correspond to the  code
     in  the  default  encoding for the font.  This code can be used with the [1m\N[0m
     escape sequence in [4mtroff[24m to select the character even if it lacks a special
     character name.  Every character in the font description must exist in  the
     font file, and the widths given in the description must match those used in
     the font file.  See ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

     [4mgropdf[24m  can  automatically  [4membed[24m any downloadable fonts necessary to print
     the document.  Any fonts thus required must be listed  in  the  file  [4m/usr/[0m
     [4mshare/groff/1.24.0/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
            Identifer (URI).  The [1m-P [22mand [1m-A [22marguments format their successors as
            text before and after the link text, respectively, without interven‐
            ing space.   Specifying  [1m-S  [22mprevents  [1mpdfhref  [22mfrom  “closing”  the
            hotspot,  requiring the document (or macro package wrapping [1mpdfhref[22m)
            to do so itself with “[1m\X'pdf: markend'\m[\*[pdf:curcol]][22m”.

     [1m.pdfinfo /[4m[22mfield[24m [4mcontent[24m ...
            Define PDF metadata.  [4mfield[24m may be one of  [1mTitle[22m,  [1mAuthor[22m,  [1mSubject[22m,
            [1mKeywords[22m,  or  another  datum  supported by the PDF standard or your
            reader.  [4mfield[24m must be prefixed with a slash.

     [1m.pdfnote [22m[[1m-T [4m[22mtitle[24m] [4mtext[0m
            Create an annotation in the document.  Reader support for this  fea‐
            ture  varies.   Some  place  an  icon at the current position on the
            page; hovering over the icon reveals any [4mtitle[24m,  while  clicking  on
            the icon pops up a window containing [4mtext[24m.

   [1mParameters[0m
     The following parameters, shown as [4mroff[24m control lines, affect the operation
     of [4mgropdf[24m.

     ┌─────────────────────────────────────────────────────────────────────────┐
     │        [1mParameter                     Purpose                Default     [22m│
     ├─────────────────────────────────────────────────────────────────────────┤
     │ .nr PDFNOTE.WIDTH          Set width of annotation       1c             │
     │                            icon.                                        │
     │ .nr PDFNOTE.HEIGHT         Set height of annotation      1c             │
     │                            icon.                                        │
     │ .ds PDFNOTE.COLOR          Set RGB color of annotation   1.00 1.00 0.00 │
     │                            icon (RGB)                                   │
     │ .ds PDFNOTE.OPACITY        Set opacity of annotation     0.6            │
     │                            icon (decimal value in [0,                   │
     │                            1]).                                         │
     │ .nr PDFOUTLINE.FOLDLEVEL   Set depth of visible book‐    10000          │
     │                            mark hierarchy.                              │
     │ .nr PDFHREF.VIEW.LEADING   Set position adjustment       5p             │
     │                            when clicking bookmark or                    │
     │                            internal hotspot.                            │
     │ .nr PDFHREF.LEADING        Configure size of increased   2.0p           │
     │                            clickable area around a                      │
     │                            hotspot.                                     │
     │ .ds PDFHREF.BORDER         Configure the border width    0 0 0          │
     │                            around a hotspot by speci‐                   │
     │                            fying two zeroes followed                    │
     │                            by the desired width in                      │
     │                            points.  Do not use a scal‐                  │
     │                            ing unit.                                    │
     │ .ds PDFHREF.COLOR          Set RGB color of link text.   0.00 0.35 0.60 │
     └─────────────────────────────────────────────────────────────────────────┘

     In the foregoing, you can also spell “COLOR” in string names as “COLOUR”.

   [1mImporting PDF graphics[0m
     If  you  are importing an image as a PDF file, it must be a single page and
     the drawing must just fit inside the  media  size  of  the  PDF  file.   In
     ]8;;man:inkscape(1)\[4minkscape[24m(1)]8;;\  or  ]8;;man:gimp(1)\[4mgimp[24m(1)]8;;\,  for example, make sure the canvas size just fits
     the image.

     The PDF parser [4mgropdf[24m implements has not been rigorously  tested  with  all
     applications  that  produce PDF.  If you find a single-page PDF which fails
     to import properly, try processing it with the ]8;;man:pdftk(1)\[4mpdftk[24m(1)]8;;\ program.
            pdftk [4mexisting-file[24m output [4mnew-file[0m
     You may find that [4mnew-file[24m imports successfully.

   [1mTrueType and other font formats[0m
     [4mgropdf[24m does not yet support any font formats besides Adobe Type 1  (PFA  or
     PFB).

[1mFont installation[0m
     For  your  convenience, [4mgroff[24m offers [4minstall-font.bash[24m, a shell script that
     interactively assists the configuration of fonts for use with the GNU [4mtroff[0m
     formatter and the [4mgropdf[24m output driver.  See section “Files” below.

     The following is a step-by-step font installation guide for [4mgropdf.[0m

     •  Convert your font to something [4mgroff[24m understands.  This is a  PostScript
        Type 1 font in PFA or PFB format, together with an AFM file.  A PFA file
        begins as follows.
               %!PS-AdobeFont-1.0:
        A  PFB  file contains this string as well, preceded by some non-printing
        bytes.  In the following steps, we  will  consider  the  use  of  CTAN's
        ]8;;https://ctan.org/tex-archive/fonts/brushscr\BrushScriptX-Italic]8;;\ font in PFA format.

     •  Convert  the  AFM  file  to  a  [4mgroff[24m  font  description  file  with the
        ]8;;man:afmtodit(1)\[4mafmtodit[24m(1)]8;;\ program.  For instance,
               $ [1mafmtodit BrushScriptX-Italic.afm text.map BSI[0m
        converts the Adobe Font Metric file [4mBrushScriptX-Italic.afm[24m to the [4mgroff[0m
        font description file [4mBSI[24m.

        If you have a font family which provides regular upright (roman),  bold,
        italic,  and  bold-italic  styles,  (where  “italic” may be “oblique” or
        “slanted”), we recommend using [1mR[22m, [1mB[22m, [1mI[22m, and [1mBI[22m,  respectively,  as  suf‐
        fixes  to  the  [4mgroff[24m font family name to enable [4mgroff[24m's font family and
        style selection features.  An example is [4mgroff[24m's  built-in  support  for
        Times:  the  font  family  name  is abbreviated as [1mT[22m, and the [4mgroff[24m font
        names are therefore [1mTR[22m, [1mTB[22m, [1mTI[22m, and [1mTBI[22m.  In our example,  however,  the
        BrushScriptX font is available in a single style only, italic.

     •  Install  the  [4mgroff[24m font description file(s) in a [4mdevpdf[24m subdirectory in
        the search path that [4mgroff[24m uses for device and font  file  descriptions.
        See  the  [4mGROFF_FONT_PATH[24m entry in section “Environment” of ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ for
        the current value of the font search path.  While [4mgroff[24m doesn't directly
        use AFM files, it is a good idea to store them alongside  its  font  de‐
        scription files.

     •  Register  fonts  in  the [4mdevpdf/download[24m file so they can be located for
        embedding in PDF files [4mgropdf[24m generates.  Only the first  [4mdownload[24m  file
        encountered  in the font search path is read.  If in doubt, copy the de‐
        fault [4mdownload[24m file (see section “Files” below) to the  first  directory
        in  the  font search path and add your fonts there.  The PostScript font
        name used by [4mgropdf[24m is stored in the [1minternalname  [22mfield  in  the  [4mgroff[0m
        font  description  file.   (This  name does not necessarily resemble the
        font's file name.)  If the font in our example  had  originated  from  a
        foundry named [1mZ[22m, we would add the following line to [4mdownload[24m.
               Z→BrushScriptX-Italic→BrushScriptX-Italic.pfa
        A  tab  character,  depicted  as  →,  separates the fields.  The default
        foundry has no name: its field is empty and entries corresponding to  it
        start with a tab character, as will the one in our example.

     •  Test the selection and embedding of the new font.
               printf "\\f[BSI]Hello, world!\n" | groff -T pdf -P -e >hello.pdf
               see hello.pdf

[1mExit status[0m
     0      [4mgropdf[24m successfully produced a PDF document.

     1      [4mgropdf[24m  experienced  a  critical error, or warnings were emitted and
            the [1m-W [22moption was specified.

     2      [4mgropdf[24m could not interpret its command-line arguments.

[1mEnvironment[0m
     [4mGROFF_FONT_PATH[0m
            A list of directories in which to seek the selected output  device's
            directory of device and font description files.  If, in the [4mdownload[0m
            file, the font file has been specified with a full path, no directo‐
            ries are searched.  See ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ and ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

     [4mGROPDF_NOSLIDE[0m
            If  set and evaluates to a true value (to Perl), [4mgropdf[24m ignores com‐
            mands specific to presentation PDFs, producing a normal PDF instead.

     [4mGROPDF_OPTIONS[0m
            [4mgropdf[24m interprets the contents of this  environment  variable  as  a
            space-separated list of command-line options.  Explicit command-line
            options override any settings from this environment variable.

     [4mSOURCE_DATE_EPOCH[0m
            A  timestamp  (expressed  as seconds since the Unix epoch) to use as
            the output creation timestamp in place of  the  current  time.   The
            time is converted to human-readable form using Perl's [4mgmtime()[24m func‐
            tion and recorded in a PDF comment.

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

[1mFiles[0m
     [4m/usr/share/groff/1.24.0/font/devpdf/DESC[0m
            describes the [1mpdf [22moutput device.

     [4m/usr/share/groff/1.24.0/font/devpdf/[24mF
            describes the font known as [4mF[24m on device [1mpdf[22m.

     [4m/usr/share/groff/1.24.0/font/devpdf/U-[24mF
            describes  the  font from the URW foundry (versus the Adobe default)
            known as [4mF[24m on device [1mpdf[22m.

     [4m/usr/share/groff/1.24.0/font/devpdf/download[0m
            lists fonts available for embedding  within  the  PDF  document  (by
            analogy to the [1mps [22mdevice's downloadable font support).

     [4m/usr/share/groff/1.24.0/font/devpdf/Foundry[0m
            is  a  data file used by the [4mgroff[24m build system to locate PostScript
            Type 1 fonts.

     [4m/usr/share/groff/1.24.0/font/devpdf/symbolsl.afm[0m
            provides metrics for the slanted symbol font known to [4mgroff[24m  as  [1mSS[22m.
            These data facilitate use of the font with non-[4mgroff[24m software.

     [4m/usr/share/groff/1.24.0/font/devpdf/symbolsl.pfb[0m
            supplies the slanted symbol font known to [4mgroff[24m as [1mSS[22m.

     [4m/usr/share/groff/1.24.0/font/devpdf/enc/text.enc[0m
            describes  the encoding scheme used by most PostScript Type 1 fonts;
            the [1mencoding [22mdirective of font description files for the [1mpdf  [22mdevice
            refers to it.

     [4m/usr/share/groff/1.24.0/font/devpdf/generate/symbolsl.sfd[0m
            is the source form of the [4msymbolsl.pfb[24m font, in spline font database
            (SFD) format.

     [4m/usr/share/groff/1.24.0/tmac/pdf.tmac[0m
            defines  macros for use with the [1mpdf [22moutput device.  It is automati‐
            cally loaded by [4mtroffrc[24m when the [1mpdf [22moutput device is selected.

     [4m/usr/share/groff/1.24.0/tmac/pdfpic.tmac[0m
            defines the [1mPDFPIC [22mmacro for embedding images  in  a  document;  see
            ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\.  It is automatically loaded by [4mtroffrc.[0m

     [4m/usr/share/doc/groff-1.24.0/examples/install-font.bash[0m
            This script, contributed by [4mmom[24m macro package author Peter Schaffter
            and  long  available  at  his web site, assists with making TrueType
            ([4m.ttf[24m), OpenType ([4m.otf[24m), and PostScript Type 1  ([4m.pfa[24m,  [4m.pfb[24m)  fonts
            available to [4mgroff[24m.

            Change  to  its  directory and run “[1mbash install-font.bash -H[22m” for a
            man page-like description of its features and operation.

[1mAuthors[0m
     [4mgropdf[24m was written and is maintained by ]8;;mailto:deri@chuzzlewit.myzen.co.uk\Deri James]8;;\.

[1mSee also[0m
     [4m/usr/share/doc/groff-1.24.0/sboxes/msboxes.ms[0m
     [4m/usr/share/doc/groff-1.24.0/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.0                       2026-02-20                          [4mgropdf[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mgrops[24m(1)                     General Commands Manual                    [4mgrops[24m(1)

[1mName[0m
     grops - [4mgroff[24m output driver for PostScript

[1mSynopsis[0m
     [1mgrops [22m[[1m-glm[22m] [[1m-b [4m[22mbrokenness-flags[24m] [[1m-c [4m[22mnum-copies[24m] [[1m-F [4m[22mfont-directory[24m]
           [[1m-I [4m[22minclusion-directory[24m] [[1m-p [4m[22mpaper-format[24m] [[1m-P [4m[22mprologue-file[24m]
           [[1m-w [4m[22mrule-thickness[24m] [[4mfile[24m ...]

     [1mgrops --help[0m

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

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

     When  called  with  multiple  [4mfile[24m arguments, [4mgrops[24m doesn't produce a valid
     document structure (one conforming  to  the  Document  Structuring  Conven‐
     tions).   To print such catenated output, it is necessary to deactivate DSC
     handling in the printing program or previewer.

     See section “Font installation” below for a guide to installing  fonts  for
     [4mgrops[24m.

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

     [1m-b [4m[22mn[24m    Work around problems with spoolers, previewers, and older printers.
             Normally,  [4mgrops[24m produces output at PostScript LanguageLevel 2 that
             conforms to version 3.0 of the  Document  Structuring  Conventions.
             Some  software  and  devices  can't handle such a data stream.  The
             value of [4mn[24m determines what [4mgrops[24m does to make its output acceptable
             to such consumers.  If [4mn[24m is [1m0[22m, [4mgrops[24m employs no workarounds,  which
             is the default; it can be changed by modifying the [1mbroken [22mdirective
             in [4mgrops[24m's [4mDESC[24m file.

             Add  1  to  suppress  generation of [1m%%BeginDocumentSetup [22mand [1m%%End‐[0m
             [1mDocumentSetup [22mcomments; this is needed for early versions of  Tran‐
             Script  that  get confused by anything between the [1m%%EndProlog [22mcom‐
             ment and the first [1m%%Page [22mcomment.

             Add 2 to omit lines in included files beginning with [1m%![22m, which con‐
             fuse Sun's [4mpageview[24m previewer.

             Add 4 to omit  lines  in  included  files  beginning  with  [1m%%Page[22m,
             [1m%%Trailer  [22mand  [1m%%EndProlog[22m; this is needed for spoolers that don't
             understand [1m%%BeginDocument [22mand [1m%%EndDocument [22mcomments.

             Add 8 to write [1m%!PS-Adobe-2.0 [22mrather  than  [1m%!PS-Adobe-3.0  [22mas  the
             first  line  of  the  PostScript  output; this is needed when using
             Sun's Newsprint with a printer that requires page reversal.

             Add 16 to omit media size information (that is,  output  neither  a
             [1m%%DocumentMedia  [22mcomment nor the [1msetpagedevice [22mPostScript command).
             This was the behavior of [4mgroff[24m 1.18.1 and earlier; it is needed for
             older printers that don't understand  PostScript  LanguageLevel  2,
             and is also necessary if the output is further processed to produce
             an EPS file; see subsection “Escapsulated PostScript” below.

     [1m-c [4m[22mn[24m    Output [4mn[24m copies of each page.

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

     [1m-g      [22mGenerate PostScript code to guess the page length.   The  guess  is
             correct  only  if  the imageable area is vertically centered on the
             page.  This option allows you to generate  documents  that  can  be
             printed on both U.S. letter and A4 paper formats without change.

     [1m-I [4m[22mdir[24m  Search the directory [4mdir[24m for files named in [1m\X'ps: file' [22mand [1m\X'ps:[0m
             [1mimport' [22mescape sequences.  [1m-I [22mmay be specified more than once; each
             [4mdir[24m  is searched in the given order.  To search the current working
             directory before others, add “[1m-I .[22m” at the  desired  place;  it  is
             otherwise searched last.

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

     [1m-m      [22mTurn on manual feed for the document.

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

     [1m-P [4m[22mprologue[0m
             Use the file [4mprologue[24m, sought in the [4mgroff[24m font search path, as the
             PostScript  prologue,  overriding  the default (see section “Files”
             below) and the environment variable [4mGROPS_PROLOGUE.[0m

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

[1mUsage[0m
     The input to [4mgrops[24m must be in the format output by ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\,  described  in
     ]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\.   In  addition, the device and font description files for the
     device used must meet certain requirements.  The device resolution must  be
     an integer multiple of 72 times the [1msizescale[22m.  The device description file
     must  contain  a valid paper format; see ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.  Each font descrip‐
     tion file must contain a directive
            internalname [4mpsname[0m
     which says that the PostScript name of the font is [4mpsname[24m.

     A font description file may also contain a directive
            encoding [4menc-file[0m
     which says that the PostScript font should be reencoded using the  encoding
     described  in  [4menc-file[24m; this file should consist of a sequence of lines of
     the form
            [4mpschar[24m [4mcode[0m
     where [4mpschar[24m is the PostScript name of the character, and [4mcode[24m is its posi‐
     tion in the encoding expressed as a decimal integer; valid  values  are  in
     the  range  0  to  255.  Lines starting with [1m# [22mand blank lines are ignored.
     The code for each character given in the font description file must  corre‐
     spond to the code for the character in encoding file, or to the code in the
     default  encoding  for  the  font if the PostScript font is not to be reen‐
     coded.  This code can be used with the [1m\N [22mescape sequence in [4mtroff[24m  to  se‐
     lect  the  character,  even  if it does not have a [4mgroff[24m glyph name.  Every
     character in the font description file must exist in the  PostScript  font,
     and  the  widths  given  in the font description file must match the widths
     used in the PostScript font.  [4mgrops[24m assumes that a character with  a  [4mgroff[0m
     name  of  [1mspace  [22mis  blank (makes no marks on the page); it can make use of
     such a character to generate more efficient and compact PostScript output.

     [4mgrops[24m is able to display all glyphs in a PostScript font; it is not limited
     to 256 of them.  [4menc-file[24m (or the default encoding if no encoding  file  is
     specified)  just  defines the order of glyphs for the first 256 characters;
     all other glyphs are accessed with additional encoding vectors which  [4mgrops[0m
     produces on the fly.

     [4mgrops[24m  can  embed fonts in a document that are necessary to render it; this
     is called “downloading”.  Such fonts must be in PFA format.  Use ]8;;man:pfbtops(1)\[4mpfbtops[24m(1)]8;;\
     to convert a Type 1 font in PFB format.  Downloadable fonts must be  listed
     a [4mdownload[24m file containing lines of the form
            [4mpsname[24m [4mfile[0m
     where  [4mpsname[24m  is  the PostScript name of the font, and [4mfile[24m is the name of
     the file containing it.  Blank lines and those beginning  with  [1m#  [22mare  ig‐
     nored;  fields are separated by tabs.  [4mfile[24m is sought using the same mecha‐
     nism as for [4mgroff[24m font description files.  The [4mdownload[24m file itself  is  as
     well;  currently,  the first matching file found in the device and font de‐
     scription search path is used.

     If the file containing a downloadable font or imported document conforms to
     the Adobe Document Structuring Conventions, then [4mgrops[24m interprets any  com‐
     ments  in  the files sufficiently to ensure that its own output is conform‐
     ing.  It also supplies any needed font resources that  are  listed  in  the
     [4mdownload[24m  file  as  well  as any needed file resources.  It is also able to
     handle inter-resource dependencies.  For example, suppose that you  have  a
     downloadable  font  called  Garamond,  and  also a downloadable font called
     Garamond-Outline which depends on Garamond (typically it would  be  defined
     to  copy  Garamond's font dictionary, and change the PaintType), then it is
     necessary for Garamond to appear before Garamond-Outline in the  PostScript
     document.   [4mgrops[24m handles this automatically provided that the downloadable
     font file for Garamond-Outline indicates  its  dependence  on  Garamond  by
     means  of  the  Document  Structuring Conventions, for example by beginning
     with the following lines.
            %!PS-Adobe-3.0 Resource-Font
            %%DocumentNeededResources: font Garamond
            %%EndComments
            %%IncludeResource: font Garamond
     In this case, both Garamond and Garamond-Outline would need to be listed in
     the [4mdownload[24m file.  A downloadable font should not include its own name  in
     a [1m%%DocumentSuppliedResources [22mcomment.

     [4mgrops[24m  does  not interpret [1m%%DocumentFonts [22mcomments.  The [1m%%DocumentNeeded‐[0m
     [1mResources[22m, [1m%%DocumentSuppliedResources[22m, [1m%%IncludeResource[22m, [1m%%BeginResource[22m,
     and [1m%%EndResource [22mcomments  (or  possibly  the  old  [1m%%DocumentNeededFonts[22m,
     [1m%%DocumentSuppliedFonts[22m,  [1m%%IncludeFont[22m,  [1m%%BeginFont[22m,  and  [1m%%EndFont [22mcom‐
     ments) should be used.

     The default stroke and fill colors are black.  For colors  defined  in  the
     “rgb” color space, [1msetrgbcolor [22mis used; for “cmy” and “cmyk”, [1msetcmykcolor[22m;
     and for “gray”, [1msetgray[22m.  [1msetcmykcolor [22mis a PostScript LanguageLevel 2 com‐
     mand and thus not available on some older printers.

   [1mTypefaces[0m
     Styles called [1mR[22m, [1mI[22m, [1mB[22m, and [1mBI [22mmounted at font positions 1 to 4.  Text fonts
     are grouped into families [1mA[22m, [1mBM[22m, [1mC[22m, [1mH[22m, [1mHN[22m, [1mN[22m, [1mP[22m, and [1mT[22m, each having members
     in each of these styles.

            [1mAR      [22mAvantGarde-Book
            [1mAI      [22mAvantGarde-BookOblique
            [1mAB      [22mAvantGarde-Demi
            [1mABI     [22mAvantGarde-DemiOblique
            [1mBMR     [22mBookman-Light
            [1mBMI     [22mBookman-LightItalic
            [1mBMB     [22mBookman-Demi
            [1mBMBI    [22mBookman-DemiItalic
            [1mCR      [22mCourier
            [1mCI      [22mCourier-Oblique
            [1mCB      [22mCourier-Bold
            [1mCBI     [22mCourier-BoldOblique
            [1mHR      [22mHelvetica
            [1mHI      [22mHelvetica-Oblique
            [1mHB      [22mHelvetica-Bold
            [1mHBI     [22mHelvetica-BoldOblique
            [1mHNR     [22mHelvetica-Narrow
            [1mHNI     [22mHelvetica-Narrow-Oblique
            [1mHNB     [22mHelvetica-Narrow-Bold
            [1mHNBI    [22mHelvetica-Narrow-BoldOblique
            [1mNR      [22mNewCenturySchlbk-Roman
            [1mNI      [22mNewCenturySchlbk-Italic
            [1mNB      [22mNewCenturySchlbk-Bold
            [1mNBI     [22mNewCenturySchlbk-BoldItalic
            [1mPR      [22mPalatino-Roman
            [1mPI      [22mPalatino-Italic
            [1mPB      [22mPalatino-Bold
            [1mPBI     [22mPalatino-BoldItalic
            [1mTR      [22mTimes-Roman
            [1mTI      [22mTimes-Italic
            [1mTB      [22mTimes-Bold
            [1mTBI     [22mTimes-BoldItalic

     Another text font is not a member of a family.

            [1mZCMI    [22mZapfChancery-MediumItalic

     Special  fonts include [1mS[22m, the PostScript Symbol font; [1mZD[22m, Zapf Dingbats; [1mSS[0m
     (slanted symbol), which contains oblique forms of lowercase  Greek  letters
     derived  from  Symbol; [1mEURO[22m, which offers a Euro glyph for use with old de‐
     vices lacking it; and [1mZDR[22m, a reversed version of Zapf Dingbats  (with  sym‐
     bols  flipped about the vertical axis).  Most glyphs in these fonts are un‐
     named and must be accessed using [1m\N[22m.  The last three are not standard Post‐
     Script fonts, but supplied by [4mgroff[24m and therefore included in  the  default
     [4mdownload[24m file.

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

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

   [1mDevice extension commands[0m
     [4mgrops[24m recognizes device extension commands produced by  the  [4mgroff[24m  request
     [1mdevice  [22mor  [4mroff[24m  [1m\X  [22mescape sequence, but interprets only those that begin
     with a “[1mps:[22m” tag.

     [1m\X'ps: exec [4m[22mcode[24m[1m'[0m
            Execute the arbitrary  PostScript  commands  [4mcode[24m.   The  PostScript
            [4mcurrentpoint[24m is set to the [4mgroff[24m drawing position when the [1m\X [22mescape
            sequence is interpreted before executing [4mcode[24m.  The origin is at the
            top  left  corner  of the page; [4mx[24m coordinates increase to the right,
            and [4my[24m coordinates down the page.  A procedure [1mu [22mis defined that con‐
            verts [4mgroff[24m basic units to the coordinate system in effect (provided
            the user doesn't change the scale).  For example,
                   .nr x 1i
                   \X'ps: exec \nx u 0 rlineto stroke'
            draws a horizontal line one inch long.  [4mcode[24m may make changes to the
            graphics state, but any changes persist only to the end of the page.
            A dictionary containing the definitions specified  by  the  [1mdef  [22mand
            [1mmdef  [22mcommands is on top of the dictionary stack.  If your code adds
            definitions to this dictionary, you should allocate space  for  them
            using  “[1m\X'ps: mdef [4m[22mn[24m[1m'[22m”.  Any definitions persist only until the end
            of the page.  If you use the [1m\Y [22mescape  sequence  with  an  argument
            that  names a macro, [4mcode[24m can extend over multiple lines.  For exam‐
            ple,
                   .nr x 1i
                   .de y
                   ps: exec
                   \nx u 0 rlineto
                   stroke
                   ..
                   \Yy
            is another way to draw a horizontal line one inch long.  The  single
            backslash  before  “[1mnx[22m”——the  only  reason  to  use a register while
            defining the macro “[1my[22m”——is to  convert  a  user-specified  dimension
            “[1m1i[22m”  to [4mgroff[24m basic units which are in turn converted to PostScript
            units with the [1mu [22mprocedure.

            [4mgrops[24m wraps user-specified PostScript code into a dictionary,  noth‐
            ing more.  In particular, it doesn't start and end the inserted code
            with  [1msave  [22mand [1mrestore[22m, respectively.  This must be supplied by the
            user, if necessary.

     [1m\X'ps: file [4m[22mname[24m[1m'[0m
            This is the same as the [1mexec [22mcommand except that the PostScript code
            is read from file [4mname[24m.

     [1m\X'ps: def [4m[22mcode[24m[1m'[0m
            Place a PostScript definition contained in  [4mcode[24m  in  the  prologue.
            There should be at most one definition per [1m\X [22mcommand.  Long defini‐
            tions  can be split over several [1m\X [22mcommands; all the [4mcode[24m arguments
            are simply joined together separated by newlines.   The  definitions
            are placed in a dictionary which is automatically pushed on the dic‐
            tionary  stack  when an [1mexec [22mcommand is executed.  If you use the [1m\Y[0m
            escape sequence with an argument that names a macro, [4mcode[24m can extend
            over multiple lines.

     [1m\X'ps: mdef [4m[22mn[24m [4mcode[24m[1m'[0m
            Like [1mdef[22m, except that [4mcode[24m may contain up to [4mn[24m  definitions.   [4mgrops[0m
            needs to know how many definitions [4mcode[24m contains so that it can cre‐
            ate an appropriately sized PostScript dictionary to contain them.

     [1m\X'ps: import [4m[22mfile[24m [4mllx[24m [4mlly[24m [4murx[24m [4mury[24m [4mwidth[24m [[4mheight[24m][1m'[0m
            Import a PostScript graphic from [4mfile[24m.  The arguments [4mllx[24m, [4mlly[24m, [4murx[24m,
            and  [4mury[24m  give  the bounding box of the graphic in the default Post‐
            Script coordinate system.  They should all be integers: [4mllx[24m and  [4mlly[0m
            are the [4mx[24m and [4my[24m coordinates of the lower left corner of the graphic;
            [4murx[24m and [4mury[24m are the [4mx[24m and [4my[24m coordinates of the upper right corner of
            the  graphic;  [4mwidth[24m  and  [4mheight[24m are integers that give the desired
            width and height in [4mgroff[24m basic units of the graphic.

            The graphic is scaled so that it  has  this  width  and  height  and
            translated  so  that the lower left corner of the graphic is located
            at the position associated with [1m\X [22mcommand.  If the height  argument
            is omitted it is scaled uniformly in the [4mx[24m and [4my[24m axes so that it has
            the specified width.

            The contents of the [1m\X [22mcommand are not interpreted by [4mtroff[24m, so ver‐
            tical  space  for  the  graphic  is not automatically added, and the
            [4mwidth[24m and [4mheight[24m arguments are not allowed to have attached  scaling
            indicators.

            If  the PostScript file complies with the Adobe Document Structuring
            Conventions and contains a [1m%%BoundingBox [22mcomment, then the  bounding
            box  can be automatically extracted from within [4mgroff[24m input by using
            the [1mpsbb [22mrequest.

            See ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\ for a description of the [1mPSPIC  [22mmacro  which  pro‐
            vides  a convenient high-level interface for inclusion of PostScript
            graphics.

     [1m\X'ps: invis'[0m
     [1m\X'ps: endinvis'[0m
            No output is generated for text and drawing commands that are brack‐
            eted with these [1m\X [22mcommands.  These commands are  intended  for  use
            when  output  from  [4mtroff[24m  is  previewed before being processed with
            [4mgrops[24m; if the previewer is unable to display certain  characters  or
            other constructs, then other substitute characters or constructs can
            be used for previewing by bracketing them with these [1m\X [22mcommands.

            For example, [4mgxditview[24m is not able to display a proper [1m\[em] [22mcharac‐
            ter  because  the standard X11 fonts do not provide it; this problem
            can be overcome with the following request.

                   .char \[em] \X'ps: invis'\
                   \Z'\v'-.25m'\h'.05m'\D'l .9m 0'\h'.05m''\
                   \X'ps: endinvis'\[em]

            In this case, [4mgxditview[24m is unable to display the [1m\[em] [22mcharacter and
            draws the line, whereas [4mgrops[24m prints the [1m\[em] [22mcharacter and ignores
            the line (this code is already in file [4mXps.tmac[24m, which is loaded  if
            a document intended for [4mgrops[24m is previewed with [4mgxditview[24m).

     If  a  PostScript  procedure  [1mBPhook  [22mhas  been  defined via a “[1mps: def[22m” or
     “[1mps: mdef[22m” device extension command, it is executed  at  the  beginning  of
     every page (before anything is drawn or written by [4mgroff[24m).  For example, to
     underlay  the  page contents with the word “DRAFT” in light gray, you might
     use the following.
            .de XX
            ps: def
            /BPhook
            { gsave .9 setgray clippath pathbbox exch 2 copy
              .5 mul exch .5 mul translate atan rotate pop pop
              /NewCenturySchlbk-Roman findfont 200 scalefont setfont
              (DRAFT) dup stringwidth pop -.5 mul -70 moveto show
              grestore }
            def
            ..
            .devicem XX

     Or, to cause lines and polygons  to  be  drawn  with  square  linecaps  and
     mitered linejoins instead of the round linecaps and linejoins normally used
     by [4mgrops[24m, use the following.
            .de XX
            ps: def
            /BPhook { 2 setlinecap 0 setlinejoin } def
            ..
            .devicem XX
     (Square  linecaps,  as opposed to butt linecaps (“[1m0 setlinecap[22m”), give true
     corners in boxed tables even though the lines are drawn unconnected.)

   [1mEncapsulated PostScript[0m
     [4mgrops[24m itself doesn't emit bounding box information.  The following  script,
     [4mgroff2eps[24m, produces an EPS file.

            #!/bin/sh
            groff -P-b16 "$1" > "$1".ps
            gs -dNOPAUSE -sDEVICE=bbox -- "$1".ps 2> "$1".bbox
            sed -e "/^%%Orientation/r $1.bbox" \
                -e "/^%!PS-Adobe-3.0/s/$/ EPSF-3.0/" "$1".ps > "$1".eps
            rm "$1".ps "$1".bbox

     You can then use “[1mgroff2eps foo[22m” to convert file [4mfoo[24m to [4mfoo.eps[24m.

   [1mTrueType and other font formats[0m
     To  use  TrueType fonts with [4mgrops[24m, convert them first to Type 42 format, a
     PostScript wrapper equivalent to the PFA format  described  in  ]8;;man:pfbtops(1)\[4mpfbtops[24m(1)]8;;\.
     Several  methods  exist to generate a Type 42 wrapper; some of them involve
     the use of a PostScript interpreter such as Ghostscript——see ]8;;man:gs(1)\[4mgs[24m(1)]8;;\.

     ]8;;https://fontforge.org/\FontForge]8;;\ converts most outline font formats.  Here's how we'd set  up  Ro‐
     boto Slab Serif for use with [4mgroff[24m.

         MAP=/usr/share/groff/1.24.0/font/devps/generate/text.map
         TTF=/usr/share/fonts/truetype/roboto/slab/RobotoSlab-Regular.ttf
         BASE=$(basename "$TTF")
         INT=${BASE%.ttf}
         PFA=$INT.pfa
         AFM=$INT.afm
         GFN=RSR
         DIR=$HOME/.local/groff/font
         mkdir -p "$DIR"/devps
         fontforge -lang=ff -c "Open(\"$TTF\");\
         Generate(\"$DIR/devps/$PFA\");"
         afmtodit "$DIR/devps/$AFM" "$MAP" "$DIR/devps/$GFN"
         printf "$BASE\t$PFA\n" >> "$DIR/devps/download"

     [4mfontforge[24m  and [4mafmtodit[24m may produce warnings depending on font file attrib‐
     utes.  Test the font as follows.

         printf ".ft RSR\nHello, world!\n" | groff -F "$DIR" > hello.ps

     Once you're satisfied that the font works, you may  want  to  generate  any
     available  related  styles  (for  instance,  Roboto  Slab  also has “Bold”,
     “Light”, and “Thin” styles) and set up [4mGROFF_FONT_PATH[24m in your  environment
     to  include the directory you keep the generated fonts in so that you don't
     have to use the [1m-F [22moption.

[1mFont installation[0m
     For your convenience, [4mgroff[24m offers [4minstall-font.bash[24m, a shell  script  that
     interactively assists the configuration of fonts for use with the GNU [4mtroff[0m
     formatter and the [4mgrops[24m output driver.  See section “Files” below.

     The following is a step-by-step font installation guide for [4mgrops.[0m

     •  Convert  your font to something [4mgroff[24m understands.  This is a PostScript
        Type 1 font in PFA format or a PostScript Type 42 font, together with an
        AFM file.  A PFA file begins as follows.
               %!PS-AdobeFont-1.0:
        A PFB file contains this string as well, preceded by  some  non-printing
        bytes.  If your font is in PFB format, use [4mgroff[24m's ]8;;man:pfbtops(1)\[4mpfbtops[24m(1)]8;;\ program to
        convert  it  to  PFA.  For TrueType and other font formats, we recommend
        [4mfontforge[24m, which can convert most outline font formats.  A Type 42  font
        file begins as follows.
               %!PS-TrueTypeFont
        This  is  a  wrapper format for TrueType fonts.  Old PostScript printers
        might not support them (that is, they might not have a built-in TrueType
        font interpreter).  In the following steps, we will consider the use  of
        CTAN's ]8;;https://ctan.org/tex-archive/fonts/brushscr\BrushScriptX-Italic]8;;\ font in PFA format.

     •  Convert  the  AFM  file  to  a  [4mgroff[24m  font  description  file  with the
        ]8;;man:afmtodit(1)\[4mafmtodit[24m(1)]8;;\ program.  For instance,
               $ [1mafmtodit BrushScriptX-Italic.afm text.map BSI[0m
        converts the Adobe Font Metric file [4mBrushScriptX-Italic.afm[24m to the [4mgroff[0m
        font description file [4mBSI[24m.

        If you have a font family which provides regular upright (roman),  bold,
        italic,  and  bold-italic  styles  (where  “italic”  may be “oblique” or
        “slanted”), we recommend using the letters [1mR[22m,  [1mB[22m,  [1mI[22m,  and  [1mBI[22m,  respec‐
        tively, as suffixes to the [4mgroff[24m font family name to enable [4mgroff[24m's font
        family  and  style  selection  features.  An example is [4mgroff[24m's built-in
        support for Times: the font family name is abbreviated  as  [1mT[22m,  and  the
        [4mgroff[24m  font  names  are  therefore [1mTR[22m, [1mTB[22m, [1mTI[22m, and [1mTBI[22m.  In our example,
        however, the BrushScriptX font is available  in  a  single  style  only,
        italic.

     •  Install  the  [4mgroff[24m  font description file(s) in a [4mdevps[24m subdirectory in
        the search path that [4mgroff[24m uses for device and font  file  descriptions.
        See  the  [4mGROFF_FONT_PATH[24m entry in section “Environment” of ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ for
        the current value of the font search path.  While [4mgroff[24m doesn't directly
        use AFM files, it is a good idea to store them alongside  its  font  de‐
        scription files.

     •  Register fonts in the [4mdevps/download[24m file so they can be located for em‐
        bedding  in  PostScript  files [4mgrops[24m generates.  Only the first [4mdownload[0m
        file encountered in the font search path is read.  If in doubt, copy the
        default [4mdownload[24m file (see section “Files” below) to the first directory
        in the font search path and add your fonts there.  The  PostScript  font
        name used by [4mgrops[24m is stored in the [1minternalname [22mfield in the [4mgroff[24m font
        description  file.   (This name does not necessarily resemble the font's
        file name.)  We add the following line to [4mdownload[24m.
               BrushScriptX-Italic→BrushScriptX-Italic.pfa
        A tab character, depicted as →, separates the fields.

     •  Test the selection and embedding of the new font.
               printf "\\f[BSI]Hello, world!\n" | groff -T ps >hello.ps
               see hello.pdf

[1mOld fonts[0m
     [4mgroff[24m versions 1.19.2 and earlier contained descriptions of a slightly dif‐
     ferent set of the base 35 PostScript level 2 fonts defined by  Adobe.   The
     older  set  has 314 glyphs and a larger set of kerning pairs; the newer one
     has only 229 glyphs, but includes the Euro sign.  For backward  compatibil‐
     ity,  these  old  font  descriptions  are also installed in the [4m/usr/share/[0m
     [4mgroff/1.24.0/oldfont/devps[24m directory.

     To use them, make sure that [4mgrops[24m finds the fonts before the default system
     fonts (with the same names): either give [4mgrops[24m the [1m-F [22mcommand-line option,
            $ [1mgroff -Tps -P-F -P/usr/share/groff/1.24.0/oldfont [22m...
     or add the directory to [4mgroff[24m's font and device description search path en‐
     vironment variable,
            $ [1mGROFF_FONT_PATH=/usr/share/groff/1.24.0/oldfont \[0m
                   [1mgroff -Tps [22m...
     when the command runs.

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

[1mEnvironment[0m
     [4mGROFF_FONT_PATH[0m
            A list of directories in which to seek the selected output  device's
            directory  of  device  and font description files.  See ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ and
            ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

     [4mGROPS_PROLOGUE[0m
            If this is set to [4mfoo[24m, then [4mgrops[24m uses the file  [4mfoo[24m  (in  the  font
            path)  instead of the default prologue file [4mprologue[24m.  The option [1m-P[0m
            overrides this environment variable.

     [4mSOURCE_DATE_EPOCH[0m
            A timestamp (expressed as seconds since the Unix epoch)  to  use  as
            the  output  creation  timestamp  in place of the current time.  The
            time  is  converted  to  human-readable  form  using  ]8;;man:gmtime(3)\[4mgmtime[24m(3)]8;;\  and
            ]8;;man:asctime(3)\[4masctime[24m(3)]8;;\, and recorded in a PostScript comment.

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

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

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

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

     [4m/usr/share/groff/1.24.0/font/devps/prologue[0m
            is the default PostScript prologue prefixed to every output file.

     [4m/usr/share/groff/1.24.0/font/devps/text.enc[0m
            describes the encoding scheme used by most PostScript Type 1  fonts;
            the  [1mencoding  [22mdirective of font description files for the [1mps [22mdevice
            refers to it.

     [4m/usr/share/groff/1.24.0/tmac/ps.tmac[0m
            defines macros for use with the [1mps [22moutput device.  It  is  automati‐
            cally loaded by [4mtroffrc[24m when the [1mps [22moutput device is selected.

     [4m/usr/share/groff/1.24.0/tmac/pspic.tmac[0m
            defines  the  [1mPSPIC  [22mmacro  for  embedding images in a document; see
            ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\.  It is automatically loaded by [4mtroffrc.[0m

     [4m/usr/share/groff/1.24.0/tmac/psold.tmac[0m
            provides replacement glyphs for text fonts that lack complete cover‐
            age of the ISO Latin-1 character set; using it,  [4mgroff[24m  can  produce
            glyphs  like eth (ð) and thorn (þ) that older PostScript printers do
            not natively support.

     [4m/usr/share/doc/groff-1.24.0/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.0                       2026-01-29                           [4mgrops[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mgrotty[24m(1)                    General Commands Manual                   [4mgrotty[24m(1)

[1mName[0m
     grotty - [4mgroff[24m output driver for typewriter-like (terminal) devices

[1mSynopsis[0m
     [1mgrotty [22m[[1m-dfhot[22m] [[1m-i[22m|[1m-r[22m] [[1m-F [4m[22mfont-directory[24m] [[4mfile[24m ...]

     [1mgrotty -c [22m[[1m-bBdfhouU[22m] [[1m-F [4m[22mfont-directory[24m] [[4mfile[24m ...]

     [1mgrotty --help[0m

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

[1mDescription[0m
     The  GNU  [4mroff[24m  TTY  (“Teletype”)  output  driver  translates the output of
     ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ into a form suitable for typewriter-like devices, including  video
     terminal  emulators.  Normally, [4mgrotty[24m is invoked by ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ when the lat‐
     ter is given one of the “[1m-T ascii[22m”, “[1m-T latin1[22m”, or “[1m-T utf8[22m” options.  (In
     this installation, [1mps [22mis the default output device.)  Use [4mgroff[24m's [1m-P [22moption
     to pass any options shown above to [4mgrotty[24m.  If no [4mfile[24m arguments are given,
     or if [4mfile[24m is “-”, [4mgrotty[24m reads the standard input stream.   It  writes  to
     the standard output stream.

     By  default,  [4mgrotty[24m  emits  SGR escape sequences (from ISO 6429, popularly
     called “ANSI escapes”) to change text attributes (bold, italic,  underline,
     reverse video [“negative image”] and colors).  Devices supporting SGR 30–37
     and  40–47  sequences  can  view [4mroff[24m documents using eight different back‐
     ground and foreground colors.  [4mgrotty[24m's [4mtty.tmac[24m  file  defines  the  eight
     color  names  of ISO 6429: black, white, red, green, blue, yellow, magenta,
     and cyan.  Unrecognized colors map to the default color, the value of which
     depends on the settings of the terminal.  Also see the [1m-t [22moption below.

     By default, [4mgrotty[24m produces OSC 8 hyperlinks on devices employing  SGR  es‐
     cape sequences.

     In  accord  with long-standing practice and terminals (emulators) that lack
     support for slanted (oblique or  italic)  faces,  [4mgrotty[24m  marks  italicized
     character  cells  with underlines instead by default——but see the [1m-i [22moption
     below.

   [1mSGR and OSC support in pagers[0m
     When paging [4mgrotty[24m's output with ]8;;man:less(1)\[4mless[24m(1)]8;;\, the latter program  must  be  in‐
     structed to pass SGR and OSC sequences through to the device; its [1m-R [22moption
     is one way to achieve this ([4mless[24m version 566 or later is required for OSC 8
     support).  Consequently, programs like ]8;;man:man(1)\[4mman[24m(1)]8;;\ that page [4mroff[24m documents with
     [4mless[24m must call it with an appropriate option.

   [1mLegacy output format[0m
     The  [1m-c  [22moption  tells [4mgrotty[24m to use an output format compatible with paper
     terminals, like the Teletype machines for which [4mroff[24m and [4mnroff[24m  were  first
     developed  but  which  are no longer in wide use.  SGR escape sequences are
     not emitted; bold, italic, and underlining character  attributes  are  thus
     not  manipulated.  Instead, [4mgrotty[24m overstrikes, representing a bold charac‐
     ter [4mc[24m with the sequence “[4mc[24m BACKSPACE [4mc[24m”, an italic character [4mc[24m with the se‐
     quence “[1m_ [22mBACKSPACE [4mc[24m”, and bold italics with “[1m_ [22mBACKSPACE [4mc[24m BACKSPACE  [4mc[24m”.
     This  rendering  is inherently ambiguous when the character [4mc[24m is itself the
     underscore.

     The legacy output format can be rendered on a video terminal (or  emulator)
     by  piping  [4mgrotty[24m's output through ]8;;man:ul(1)\[4mul[24m(1)]8;;\, which may render bold italics as
     reverse video.  Some implementations of ]8;;man:more(1)\[4mmore[24m(1)]8;;\ also are  able  to  display
     these  sequences; you may wish to experiment with that command's [1m-b [22moption.
     [4mless[24m renders legacy bold and italics without requiring  options.   In  con‐
     trast  to  the  terminal output drivers of some other [4mroff[24m implementations,
     [4mgrotty[24m never outputs reverse line feeds.  You need not  filter  its  output
     through ]8;;man:col(1)\[4mcol[24m(1)]8;;\ to remove them.

   [1mDevice extension commands[0m
     [4mgrotty[24m  recognizes a device extension command produced by the [4mgroff[24m request
     [1mdevice [22mor [4mroff[24m [1m\X [22mescape sequence.

     [1m\X'tty: link [22m[[4muri[24m [[4mkey[24m[1m=[4m[22mvalue[24m] ...][1m'[0m
            Embed a hyperlink using the OSC 8 terminal escape sequence.   Speci‐
            fying  [4muri[24m  starts hyperlinked text, and omitting it ends the hyper‐
            link.  When [4muri[24m is present, any number of additional key/value pairs
            can be specified; their interpretation is the responsibility of  the
            pager  or  terminal.  Spaces or tabs cannot appear literally in [4muri[24m,
            [4mkey[24m, or [4mvalue[24m; they must be represented in an alternate form.

   [1mDevice description files[0m
     If the [4mDESC[24m file for the character encoding contains the  “[1municode[22m”  direc‐
     tive,  [4mgrotty[24m  emits  Unicode  characters in UTF-8 encoding.  Otherwise, it
     emits characters in a single-byte encoding depending on  the  data  in  the
     font description files.  See ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

     A font description file may contain a directive “[1minternalname [4m[22mn[24m” where [4mn[24m is
     a  decimal  integer.   If the 01 bit in [4mn[24m is set, [4mgrotty[24m treats the font as
     slanted; if the 02 bit is set, [4mgrotty[24m treats the font as bold.

   [1mTypefaces[0m
     [4mgrotty[24m supports the standard four styles: [1mR [22m(roman), [1mI [22m([4mitalic[24m), [1mB  [22m([1mbold[22m),
     and  [1mBI  [22m([4m[1mbold-italic[24m[22m).   Because the output driver operates in [4mnroff[24m mode,
     attempts to set or change the font family or type size are ignored.

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

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

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

     [1m-b      [22mSuppress the use of overstriking for bold characters in legacy out‐
             put format.

     [1m-B      [22mUse  only  overstriking for bold-italic characters in legacy output
             format.

     [1m-c      [22mUse [4mgrotty[24m's legacy output format (see  subsection  “Legacy  output
             format” above).  SGR and OSC escape sequences are not emitted.

     [1m-d      [22mIgnore  all drawing commands in the input.  By default, [4mgrotty[24m ren‐
             ders “[1mD l[22m” commands that have at least one zero  argument  (and  so
             are  either horizontal or vertical) using Unicode box drawing char‐
             acters (for the [1mutf8 [22mdevice) or the [1m-[22m, [1m|[22m, and [1m+ [22mcharacters (for all
             other devices).  [4mgrotty[24m handles “[1mD p[22m”  commands  that  consist  en‐
             tirely   of   horizontal   and   vertical   lines  similarly.   See
             ]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\.

     [1m-f      [22mEmit a form feed at the end of each page having no  output  on  its
             last line.

     [1m-F [4m[22mdir[24m  Prepend  directory  dir[4m/dev[24mname to the search path for font and de‐
             vice description files; [4mname[24m describes the output device's  charac‐
             ter encoding, one of [1mascii[22m, [1mlatin1[22m, or [1mutf8[22m.

     [1m-h      [22mUse  literal horizontal tab characters in the output.  Tabs are as‐
             sumed to be set every 8 columns.

     [1m-i      [22mRender fonts marked as slanted with the SGR  attribute  for  italic
             text  rather  than  underlined  text.  Many terminals don't support
             this attribute; however, ]8;;man:xterm(1)\[4mxterm[24m(1)]8;;\, since patch  #314  (2014-12-28),
             does.  Ignored if [1m-c [22mis also specified.

     [1m-o      [22mSuppress  overstriking (other than for bold and/or underlined char‐
             acters when the legacy output format is in use; see options [1m-b  [22mand
             [1m-u[22m).

     [1m-r      [22mRender  fonts  marked as slanted with the SGR attribute for reverse
             video text rather than underlined text.  Ignored if  [1m-c  [22mor  [1m-i  [22mis
             also specified.

     [1m-t      [22mAssume  that  the  output  device supports SGR 38 and 48 escape se‐
             quences, which permit specification of  character  cell  foreground
             and  background colors in the RGB color space with 8 bits per chan‐
             nel.

     [1m-u      [22mSuppress the use of underlining for  italic  characters  in  legacy
             output format.

     [1m-U      [22mUse  only  underlining  for bold-italic characters in legacy output
             format.

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

[1mEnvironment[0m
     [4mGROFF_FONT_PATH[0m
            A  list of directories in which to seek the selected output device's
            directory of device and font description files.   See  ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\  and
            ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

     [4mGROFF_NO_SGR[0m
            If  set, [4mgrotty[24m's legacy output format is used just as if the [1m-c [22mop‐
            tion were specified; see subsection “Legacy output format” above.

[1mFiles[0m
     [4m/usr/share/groff/1.24.0/font/devascii/DESC[0m
            describes the [1mascii [22moutput device.

     [4m/usr/share/groff/1.24.0/font/devascii/[24mF
            describes the font known as [4mF[24m on device [1mascii[22m.

     [4m/usr/share/groff/1.24.0/font/devlatin1/DESC[0m
            describes the [1mlatin1 [22moutput device.

     [4m/usr/share/groff/1.24.0/font/devlatin1/[24mF
            describes the font known as [4mF[24m on device [1mlatin1[22m.

     [4m/usr/share/groff/1.24.0/font/devutf8/DESC[0m
            describes the [1mutf8 [22moutput device.

     [4m/usr/share/groff/1.24.0/font/devutf8/[24mF
            describes the font known as [4mF[24m on device [1mutf8[22m.

     [4m/usr/share/groff/1.24.0/tmac/tty.tmac[0m
            defines macros for use with the [1mascii[22m, [1mlatin1[22m, and [1mutf8  [22moutput  de‐
            vices.  It is automatically loaded by [4mtroffrc[24m when any of those out‐
            put devices is selected.

     [4m/usr/share/groff/1.24.0/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.0                       2026-02-01                          [4mgrotty[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mgxditview[24m(1)                 General Commands Manual                [4mgxditview[24m(1)

[1mName[0m
     gxditview - display [4mtroff[24m output in X11

[1mSynopsis[0m
     [1mgxditview [22m[[4mX-toolkit-option[24m ...] [[1m-backingStore [4m[22mbacking-store-type[24m]
               [[1m-filename [4m[22mfile[24m] [[1m-page [4m[22mpage-number[24m] [[1m-printCommand [4m[22mcommand[24m]
               [[1m-resolution [4m[22mresolution[24m] [4mfile[0m

     [1mgxditview -help[0m
     [1mgxditview --help[0m

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

[1mDescription[0m
     [4mgxditview[24m  renders  the output of GNU [4mtroff[24m to an X11 display.  It uses the
     standard X11 fonts, which are rendered by the X server.

     The output of ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ is in a  page  description  language  documented  in
     ]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\.   Normally,  users  do  not  observe  this output because the
     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ wrapper automatically runs  an  output  driver  to  interpret  it;
     [4mgroff[24m's  [1m-Z [22moption leaves it on the standard output stream instead.  It can
     be viewed by explicitly calling “[1mgxditview [4m[22mfile[24m”.  If the [4mfile[24m  operand  is
     “[1m-[22m”, [4mgxditview[24m will read the standard input stream; [4mfile[24m cannot be omitted.
     GNU [4mtroff[24m's page description language is device-independent but not device-
     agnostic.   [4mgxditview[24m can view it for all typesetter devices, but the qual‐
     ity is device-dependent.  [4mgxditview[24m will not display  output  for  terminal
     ([4mnroff[24m) devices.

     The best results are achieved with the [1mX[22m* devices for [4mtroff[24m's [1m-T [22moption, of
     which  there are four: [1m-TX75[22m, [1m-TX75-12[22m, [1m-TX100[22m, and [1m-TX100-12[22m.  They differ
     by the X resolution (75 or 100 dots per inch) and the base point  size  (10
     or 12 points).  They are especially built for [4mgxditview[24m.  When using one of
     these, [4mtroff[24m generates output for this device and calls [4mgxditview[24m automati‐
     cally for viewing.

     [1m-X  [22mproduces  good  results  only  with  [1m-Tps[22m, [1m-TX75[22m, [1m-TX75-12[22m, [1m-TX100[22m, and
     [1m-TX100-12[22m.  The default resolution for previewing  [1m-Tps  [22moutput  is  75dpi;
     this can be changed with the [1m-resolution [22moption.

     While  [4mgxditview[24m  is  running,  the left mouse button brings up a menu with
     several entries.

     [1mNext Page      [22mDisplay the next page.

     [1mPrevious Page  [22mDisplay the previous page.

     [1mSelect Page    [22mCollect a page number from a dialog box and render it.

     [1mPrint          [22mCollect a command from a dialog box  and  use  it  to  print
                    [4mtroff[24m  output.   The  default command initially displayed is
                    controlled by the [1mprintCommand [22mapplication resource, and  by
                    the [1m-printCommand [22moption.

     [1mOpen           [22mCollect  a  file  name from a dialog box and render it.  The
                    named file should contain [4mtroff[24m output.  If  the  file  name
                    starts with a bar or pipe symbol, “[1m|[22m” it will be interpreted
                    as a command from which to read.

     [1mQuit           [22mExit from [1mgxditview[22m.

     The  menu  entries  correspond  to  actions  with similar but not identical
     names, which can also be  accessed  with  keyboard  accelerators.   The  [4mn[24m,
     [4mSpace[24m,  [4mReturn[24m, and [4mNext[24m ([4mPgDn[24m) keys are bound to the [1mNextPage [22maction.  The
     [4mp[24m, [4mb[24m, [4mBackSpace[24m, [4mDelete[24m, and [4mPrior[24m ([4mPgUp[24m) keys are bound to  the  [1mPrevious‐[0m
     [1mPage [22maction.  The [4mp[24m key with any modifier (Shift, Control, Alt, or Meta) is
     bound  to  the  [1mPrint [22maction.  The [4mg[24m key is bound to the [1mSelectPage [22maction.
     The [4mo[24m key is bound to the [1mOpenFile [22maction.  The [4mq[24m key is bound to the  [1mQuit[0m
     action.   The [4mr[24m key is bound to a [1mRerasterize [22maction which rereads the cur‐
     rent file, and redisplays the current page; if the current file is  a  com‐
     mand, the command will be re-executed.  Vertical scrolling can be done with
     the  [4mk[24m  and [4mj[24m keys; horizontal scrolling is bound to the [4mh[24m and [4ml[24m keys.  The
     arrow keys ([4mup[24m, [4mdown[24m, [4mleft[24m, and  [4mright[24m)  are  also  bound  to  the  obvious
     scrolling actions.

     The [1mpaperlength [22mand [1mpaperwidth [22mcommands in the [4mDESC[24m file describing a [4mgroff[0m
     output  device  specify  the length and width in basic units of the virtual
     page displayed by [4mgxditview[24m; see ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

   [1mX defaults[0m
     This program uses the [4mDvi[24m widget from the X Toolkit.  It understands all of
     the core resource names and classes as well as:

     [1mwidth [22m(class [1mWidth[22m)
            Specifies the width of the window.

     [1mheight [22m(class [1mHeight[22m)
            Specifies the height of the window.

     [1mforeground [22m(class [1mForeground[22m)
            Specifies the default foreground color.

     [1mfont [22m(class [1mFont[22m)
            Specifies the font to be used for error messages.

     [1mfontMap [22m(class [1mFontMap[22m)
            Specifies the mapping from [4mgroff[24m font names to X font  names.   This
            must be a string containing a sequence of lines.  Each line contains
            two  whitespace-separated  fields: the [4mgroff[24m font name is first, and
            the XLFD (X Logical Font Description) second.  The default is  shown
            in subsection “Default font map” below.

   [1mDefault font map[0m
     XLFDs  are  long  and unwieldy, so some lines are shown broken and indented
     below.

     TR  -adobe-times-medium-r-normal--*-100-*-*-*-*-iso8859-1\n\
     TI  -adobe-times-medium-i-normal--*-100-*-*-*-*-iso8859-1\n\
     TB  -adobe-times-bold-r-normal--*-100-*-*-*-*-iso8859-1\n\
     TBI -adobe-times-bold-i-normal--*-100-*-*-*-*-iso8859-1\n\
     CR  -adobe-courier-medium-r-normal--*-100
             -*-*-*-*-iso8859-1\n\
     CI  -adobe-courier-medium-o-normal
             --*-100-*-*-*-*-iso8859-1\n\
     CB  -adobe-courier-bold-r-normal--*-100-*-*-*-*-iso8859-1\n\
     CBI -adobe-courier-bold-o-normal--*-100-*-*-*-*-iso8859-1\n\
     HR  -adobe-helvetica-medium-r-normal
             --*-100-*-*-*-*-iso8859-1\n\
     HI  -adobe-helvetica-medium-o-normal
             --*-100-*-*-*-*-iso8859-1\n\
     HB  -adobe-helvetica-bold-r-normal
             --*-100-*-*-*-*-iso8859-1\n\
     HBI -adobe-helvetica-bold-o-normal
             --*-100-*-*-*-*-iso8859-1\n\
     NR  -adobe-new century schoolbook-medium-r-normal--*-100
             -*-*-*-*-iso8859-1\n\
     NI  -adobe-new century schoolbook-medium-i-normal--*-100
             -*-*-*-*-iso8859-1\n\
     NB  -adobe-new century schoolbook-bold-r-normal--*-100
             -*-*-*-*-iso8859-1\n\
     NBI -adobe-new century schoolbook-bold-i-normal--*-100
             -*-*-*-*-iso8859-1\n\
     S   -adobe-symbol-medium-r-normal--*-100
             -*-*-*-*-adobe-fontspecific\n\
     SS  -adobe-symbol-medium-r-normal--*-100
             -*-*-*-*-adobe-fontspecific\n\

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

     [4mgxditview[24m accepts all of the standard X Toolkit command-line options  along
     with the additional options listed below.

     [1m-page  [22mThis  option  specifies  the  page number of the document to be dis‐
            played.

     [1m-backingStore [4m[22mbacking-store-type[0m
            Because redisplay of the rendered  [4mtroff[24m  output  can  take  a  per‐
            ceiptible  amount of time, this option causes the server to save the
            window contents so that when it is scrolled around the viewport, the
            window is painted from contents saved in  backing  store.   [4mbacking-[0m
            [4mstore-type[24m can be one of [1mAlways[22m, [1mWhenMapped [22mor [1mNotUseful[22m.

     [1m-printCommand [4m[22mcommand[0m
            The  default  command displayed in the dialog box for the [1mPrint [22mmenu
            entry will be [4mcommand[24m.

     [1m-resolution [4m[22mres[0m
            [4mtroff[24m output file will be displayed at a resolution of [4mres[24m dots  per
            inch, unless the [4mDESC[24m file contains the [1mX11 [22mdirective, in which case
            the  device  resolution  will  be used.  This corresponds to the [4mDvi[0m
            widget's [1mresolution [22mresource.  The default is [1m75[22m.

     [1m-filename [4m[22mstring[0m
            The default file name displayed in the dialog box for the [1mOpen  [22mmenu
            entry  will be [4mstring[24m.  This can be either a file name, or a command
            starting with “[1m|[22m”.

     The following standard X Toolkit command-line arguments are  commonly  used
     with [4mgxditview[24m.

     [1m-bg [4m[22mcolor[0m
            This  option  specifies  the  color to use for the background of the
            window.  The default is “[1mwhite[22m”.

     [1m-bd [4m[22mcolor[0m
            This option specifies the color to use for the border of the window.
            The default is “[1mblack[22m”.

     [1m-bw [4m[22mnumber[0m
            This option specifies the width in pixels of the border  surrounding
            the window.

     [1m-fg [4m[22mcolor[0m
            This option specifies the color to use for displaying text.  The de‐
            fault is “[1mblack[22m”.

     [1m-fn [4m[22mfont[0m
            This  option  specifies  the  font  to be used for displaying widget
            text.  The default is “[1mfixed[22m”.

     [1m-rv    [22mThis option indicates that reverse  video  should  be  simulated  by
            swapping the foreground and background colors.

     [1m-geometry [4m[22mgeometry[0m
            This option specifies the preferred size and position of the window.

     [1m-display [4m[22mhost[24m[1m:[4m[22mdisplay[0m
            This option specifies the X server to contact.

     [1m-xrm [4m[22mresourcestring[0m
            This option specifies a resource string to be used.

[1mExit status[0m
     [4mgxditview[24m  exits with status [1m0 [22mon successful operation, and status [1m2 [22mif the
     program cannot 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.  See ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ and
            ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

[1mFiles[0m
     [4m/etc/X11/app-defaults/GXditview[0m
     [4m/etc/X11/app-defaults/GXditview-color[0m
            define X application defaults for  [4mgxditview[24m.   Users  can  override
            these  values in the [4m.Xdefaults[24m file, normally located in the user's
            home directory.  See ]8;;man:appres(1)\[4mappres[24m(1)]8;;\ and ]8;;man:xrdb(1)\[4mxrdb[24m(1)]8;;\.

     [4m/usr/share/groff/1.24.0/font/devX100/DESC[0m
            describes the [1mX100 [22moutput device.

     [4m/usr/share/groff/1.24.0/font/devX100/[24mF
            describes the font known as [4mF[24m on device [1mX100[22m.

     [4m/usr/share/groff/1.24.0/font/devX100-12/DESC[0m
            describes the [1mX100-12 [22moutput device.

     [4m/usr/share/groff/1.24.0/font/devX100-12/[24mF
            describes the font known as [4mF[24m on device [1mX100-12[22m.

     [4m/usr/share/groff/1.24.0/font/devX75/DESC[0m
            describes the [1mX75 [22moutput device.

     [4m/usr/share/groff/1.24.0/font/devX75/[24mF
            describes the font known as [4mF[24m on device [1mX75[22m.

     [4m/usr/share/groff/1.24.0/font/devX75-12/DESC[0m
            describes the [1mX75-12 [22moutput device.

     [4m/usr/share/groff/1.24.0/font/devX75-12/[24mF
            describes the font known as [4mF[24m on device [1mX75-12[22m.

     [4m/usr/share/groff/1.24.0/tmac/X.tmac[0m
            defines macros for use with the [1mX100[22m, [1mX100-12[22m, [1mX75[22m, and [1mX75-12  [22mout‐
            put  devices.   It  is  automatically  loaded by [4mtroffrc[24m when any of
            those output devices is selected.

     [4m/usr/share/groff/1.24.0/tmac/Xps.tmac[0m
            sets up [4mtroff[24m to use [4mgxditview[24m as a previewer for device-independent
            output targeting the [1mps [22moutput device.  It is  automatically  loaded
            by [4mtroffrc[24m when [4mtroff[24m is given the options [1m-X [22mand [1m-Tps[22m.

[1mExamples[0m
     The following command views this man page with a base point size of 12.

            groff -TX100-12 -man gxditview.1

     The  quality of the result depends mainly on the chosen point size and dis‐
     play resolution; for rapid previewing, however, something like
            groff -X -P-resolution -P100 [4mdocument[0m
     yields acceptable results.

[1mAuthors[0m
     [4mgxditview[24m and its predecessor [4mxditview[24m were written by Keith Packard (MIT X
     Consortium), Richard L. Hyde (Purdue), David Slattengren  (Berkeley),  Mal‐
     colm  Slaney  (Schlumberger Palo Alto Research), Mark Moraes (University of
     Toronto), and James Clark.

     This program is derived from [4mxditview[24m; portions of [4mxditview[24m  originated  in
     [4mxtroff[24m, which was derived from [4msuntroff[24m.

[1mSee also[0m
     ]8;;https://www.x.org/releases/X11R7.6/doc/xorg-docs/specs/XLFD/xlfd.html\“X  Logical  Font  Description  Conventions”]8;;\,  by  Jim  Flowers and Stephen
     Gildea.

     ]8;;man:X(7)\[4mX[24m(7)]8;;\, ]8;;man:xrdb(1)\[4mxrdb[24m(1)]8;;\, ]8;;man:xditview(1)\[4mxditview[24m(1)]8;;\, ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, ]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\

groff 1.24.0                       2024-11-29                       [4mgxditview[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mhpftodit[24m(1)                  General Commands Manual                 [4mhpftodit[24m(1)

[1mName[0m
     hpftodit - create font description files for use with [4mgroff[24m and [4mgrolj4[0m

[1mSynopsis[0m
     [1mhpftodit [22m[[1m-aqs[22m] [[1m-i [4m[22mn[24m] [4mtfm-file[24m [4mmap-file[24m [4mfont-description[0m

     [1mhpftodit -d [4m[22mtfm-file[24m [[4mmap-file[24m]

     [1mhpftodit --help[0m

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

[1mDescription[0m
     [4mhpftodit[24m creates a font description file for  use  with  a  Hewlett-Packard
     LaserJet  4-series  (or  newer)  printer and the ]8;;man:grolj4(1)\[4mgrolj4[24m(1)]8;;\ output driver of
     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, using data from an HP tagged font metric (TFM) file.  [4mtfm-file[24m is
     the name of the font's TFM file; Intellifont and  TrueType  TFM  files  are
     supported, but symbol set TFM files are not.  [4mmap-file[24m is a file giving the
     [4mgroff[24m  special  character  identifiers  for  glyphs  in the font; this file
     should consist of a sequence of lines of the form
            [4mm[24m [4mu[24m [4mc1[24m [4mc2[24m ... [# [4mcomment[24m]
     where [4mm[24m is a decimal integer giving the glyph's MSL  (Master  Symbol  List)
     number,  [4mu[24m  is a hexadecimal integer giving its Unicode character code, and
     [4mc1[24m, [4mc2[24m, ...  are its [4mgroff[24m glyph names (see ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\ for a list).  The
     values can be separated by any number of spaces and/or tabs.   The  Unicode
     value  must  use  uppercase hexadecimal digits A–F, and must lack a leading
     “[1m0x[22m”, “[1mu[22m”, or “[1mU+[22m”.  Unicode values corresponding to composite  glyphs  are
     decomposed;  that is “[1mu00C0[22m” becomes “[1mu0041_0300[22m”.  A glyph without a [4mgroff[0m
     special character identifier may be named [1mu[4m[22mXXXX[24m if the glyph corresponds to
     a Unicode value, or as an unnamed glyph “[1m---[22m”.  If the given Unicode  value
     is  in the Private Use Area (PUA) (0xE000–0xF8FF), the glyph is included as
     an unnamed glyph.  Refer to ]8;;man:groff_diff(1)\[4mgroff_diff[24m(1)]8;;\ for additional information  about
     unnamed glyphs and how to access them.

     Blank  lines and lines beginning with “[1m#[22m” are ignored.  A “[1m#[22m” following one
     or more [4mgroff[24m names begins a comment.  Because “[1m#[22m” is a valid  [4mgroff[24m  name,
     it  must appear first in a list of [4mgroff[24m names if a comment is included, as
     in
            3   0023   #   # number sign
     or
            3   0023   # sh   # number sign
     whereas in
            3   0023   sh #   # number sign
     the first “[1m#[22m” is interpreted as the beginning of the comment.

     [4mhpftodit[24m writes output to [4mfont-description,[24m a file named for  the  intended
     [4mgroff[24m  font  name;  if this operand is “[1m-[22m”, [4mhpftodit[24m writes to the standard
     output stream.  The [1m-i [22moption directs [4mhpftodit[24m to automatically generate an
     italic correction, a left italic correction, and a subscript correction for
     each glyph.  See ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

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

     [1m-a     [22mInclude glyphs in the TFM file that are not included in [4mmap-file[24m.  A
            glyph with corresponding Unicode value is given the  name  u[4mXXXX[24m;  a
            glyph without a Unicode value is included as an unnamed glyph “---”.
            A glyph with a Unicode value in the Private Use Area (0xE000–0xF8FF)
            is also included as an unnamed glyph.

            This  option provides a simple means of adding Unicode-named and un‐
            named glyphs to a font without including them in the map  file,  but
            it  affords little control over which glyphs are placed in a regular
            font and which are placed in a special font.  The  presence  or  ab‐
            sence of the [1m-s [22moption has some effect on which glyphs are included:
            without  it,  only  the “text” symbol sets are searched for matching
            glyphs; with it, only the “mathematical” symbol sets  are  searched.
            Nonetheless,  restricting the symbol sets searched isn't very selec‐
            tive——many glyphs are placed in  both  regular  and  special  fonts.
            Normally, [1m-a [22mshould be used only as a last resort.

     [1m-d     [22mDump  information  about the TFM file to the standard output stream;
            use this to ensure that a TFM file is a proper match for a font, and
            that its contents are suitable.  The information includes the values
            of important TFM tags and a listing (by MSL number  for  Intellifont
            TFM  files or by Unicode value for TrueType TFM files) of the glyphs
            included in the TFM file.  The unit of measure “DU”  for  some  tags
            indicates  design  units; there are 8782 design units per em for In‐
            tellifont fonts, and 2048 design units per em  for  TrueType  fonts.
            Note that the accessibility of a glyph depends on its inclusion in a
            symbol  set;  some  TFM files list many glyphs but only a few symbol
            sets.

            The glyph listing includes the glyph index within the TFM file,  the
            MSL  or  Unicode  value,  and the symbol set and character code that
            will be used to print the glyph.  If [4mmap-file[24m is given, [4mgroff[24m  names
            are  given  for matching glyphs.  If only the glyph index and MSL or
            Unicode value are given, the glyph does not appear in any  supported
            symbol set and cannot be printed.

            With the [1m-d [22moption, [4mmap-file[24m is optional, and [4moutput-font[24m is ignored
            if given.

     [1m-i [4m[22mn[24m   Generate  an italic correction for each glyph so that its width plus
            its italic correction is equal to [4mn[24m thousandths of an  em  plus  the
            amount  by  which  the right edge of the glyphs's bounding box is to
            the right of its origin.  The minimum value [4mhpftodit[24m will  write  is
            zero.

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

            Also generate a left italic correction for each  glyph  equal  to  [4mn[0m
            thousandths  of  an em plus the amount by which the left edge of the
            glyphs's bounding box is to the left of its origin.  The left italic
            correction may be negative.

            This option normally is needed only with italic or oblique fonts;  a
            value of 50 (0.05 em) usually is a reasonable choice.

     [1m-q     [22mSuppress  warnings  about glyphs in the map file that were not found
            in the TFM file.  Warnings never are given for unnamed glyphs or  by
            glyphs  named  by  their Unicode values.  This option is useful when
            sending the output of [4mhpftodit[24m to the standard output stream.

     [1m-s     [22mAdd the [1mspecial [22mdirective to the font  description  file,  affecting
            the  order  in  which  HP  symbol  sets are searched for each glyph.
            Without this option, the “text” sets are searched before the “mathe‐
            matical” symbol sets.  With it, the search order is reversed.

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

[1mFiles[0m
     [4m/usr/share/groff/1.24.0/font/devlj4/DESC[0m
            describes the [1mlj4 [22moutput device.

     [4m/usr/share/groff/1.24.0/font/devlj4/[24mF
            describes the font known as [4mF[24m on device [1mlj4[22m.

     [4m/usr/share/groff/1.24.0/font/devlj4/generate/Makefile[0m
            is a ]8;;man:make(1)\[4mmake[24m(1)]8;;\ script that uses ]8;;man:hpftodit(1)\[4mhpftodit[24m(1)]8;;\ to prepare the [4mgroff[24m  font
            description files above from HP TFM data; it can be used to regener‐
            ate them in the event the TFM files are updated.

     [4m/usr/share/groff/1.24.0/font/devlj4/generate/special.awk[0m
            is  an ]8;;man:awk(1)\[4mawk[24m(1)]8;;\ script that corrects the Intellifont-based height met‐
            rics for several glyphs in the [1mS  [22m(special)  font  for  TrueType  CG
            Times used in the HP LaserJet 4000 and later.

     [4m/usr/share/groff/1.24.0/font/devlj4/generate/special.map[0m
     [4m/usr/share/groff/1.24.0/font/devlj4/generate/symbol.map[0m
     [4m/usr/share/groff/1.24.0/font/devlj4/generate/text.map[0m
     [4m/usr/share/groff/1.24.0/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.0                       2025-08-02                        [4mhpftodit[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mindxbib[24m(1)                   General Commands Manual                  [4mindxbib[24m(1)

[1mName[0m
     indxbib - make inverted index of bibliographic databases

[1mSynopsis[0m
     [1mindxbib [22m[[1m-w[22m] [[1m-c [4m[22mcommon-words-file[24m] [[1m-d [4m[22mdir[24m] [[1m-f [4m[22mlist-file[24m]
             [[1m-h [4m[22mmin-hash-table-size[24m] [[1m-i [4m[22mexcluded-fields[24m]
             [[1m-k [4m[22mmax-keys-per-record[24m] [[1m-l [4m[22mmin-key-length[24m] [[1m-n [4m[22mthreshold[24m]
             [[1m-o [4m[22mfile[24m] [[1m-t [4m[22mmax-key-length[24m] [[4mfile[24m ...]

     [1mindxbib --help[0m

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

[1mDescription[0m
     [4mindxbib[24m makes an inverted index of the bibliographic databases in each [4mfile[0m
     to speed their access by ]8;;man:refer(1)\[4mrefer[24m(1)]8;;\, ]8;;man:lookbib(1)\[4mlookbib[24m(1)]8;;\, and ]8;;man:lkbib(1)\[4mlkbib[24m(1)]8;;\.   The  program
     writes  to  a  temporary  file that it later renames to file[4m.i[24m.  If no [4mfile[0m
     operands are present and no [1m-o [22moption is given,  [4mindxbib[24m  names  the  index
     [4mInd.i[24m.

     Bibliographic  databases are divided into records by blank lines.  Within a
     record, each field starts with a [1m% [22mcharacter at the beginning  of  a  line.
     Fields have a one-letter name that follows the [1m% [22mcharacter.

     [4mindxbib[24m  stores the values set by the [1m-c[22m, [1m-l[22m, [1m-n[22m, and [1m-t [22moptions in the in‐
     dex: programs that search the index interpret them, discarding and truncat‐
     ing keys appropriately, and using the original  keys  to  verify  that  any
     record found using the index actually contains the keys.  This means that a
     user  of an index need not know whether these options were used in the cre‐
     ation of the index, provided that not all the keys to be searched for would
     have been discarded during indexing and that the user supplies at least the
     part of each key that would have remained after being truncated during  in‐
     dexing.   [4mindxbib[24m  also  stores the value set by the [1m-i [22moption in the index
     for use in verifying records found using it.

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

     [1m-c [4m[22mcommon-words-file[0m
             Read the list of common words  from  [4mcommon-words-file[24m  instead  of
             [4m/usr/share/groff/1.24.0/eign[24m.

     [1m-d [4m[22mdir[24m  Use [4mdir[24m as the name of the directory to store in the index, instead
             of  that  returned by ]8;;man:getcwd(2)\[4mgetcwd[24m(2)]8;;\.  Typically, [4mdir[24m will be a symbolic
             link whose target is the current working directory.

     [1m-f [4m[22mlist-file[0m
             Read the files to be indexed from [4mlist-file[24m.  If  [4mlist-file[24m  is  [1m-[22m,
             files  will  be read from the standard input stream.  The [1m-f [22moption
             can be given at most once.

     [1m-h [4m[22mmin-hash-table-size[0m
             Use the first prime number greater than or equal  to  the  argument
             for  the  size  of the hash table.  Larger values will usually make
             searching faster, but will make the index  file  larger  and  cause
             [4mindxbib[24m to use more memory.  The default hash table size is 997.

     [1m-i [4m[22mexcluded-fields[0m
             Don't  index  the  contents  of fields whose names are in [4mexcluded-[0m
             [4mfields[24m.  Field names are one character each.  If this option is not
             present, [4mindxbib[24m excludes fields [1mX[22m, [1mY[22m, and [1mZ[22m.

     [1m-k [4m[22mmax-keys-per-record[0m
             Use no more keys per input record than specified in  the  argument.
             If this option is not present, the maximum is 100.

     [1m-l [4m[22mmin-key-length[0m
             Discard  any  key  whose  length  in characters is shorter than the
             value of the argument.  If this option is not present, the  minimum
             key length is 3.

     [1m-n [4m[22mthreshold[0m
             Discard the [4mthreshold[24m most common words from the common words file.
             If  this  option is not present, the 100 most common words are dis‐
             carded.

     [1m-o [4m[22mbasename[0m
             Name the index basename[4m.i[24m.

     [1m-t [4m[22mmax-key-length[0m
             Truncate keys to [4mmax-key-length[24m in characters.  If this  option  is
             not present, keys are truncated to 6 characters.

     [1m-w      [22mIndex whole files.  Each file is a separate record.

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

[1mFiles[0m
     file[4m.i[0m
            index for [4mfile[0m

     [4mInd.i[24m  default index name

     [4m/usr/share/groff/1.24.0/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.0                       2025-05-01                         [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.0                       2024-12-09                           [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.0                       2024-10-18                         [4mlookbib[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mmmroff[24m(1)                    General Commands Manual                   [4mmmroff[24m(1)

[1mName[0m
     mmroff - reference- and PostScript inclusion-handling  front  end  for  GNU
     [4mroff[24m [4mmm[24m macro package

[1mSynopsis[0m
     [1mmmroff [22m[[1m-x[22m] [4mgroff-argument[24m ...

     [1mmmroff --help[0m

     [1mmmroff --version[0m

[1mDescription[0m
     [4mmmroff[24m is a simple wrapper for [4mgroff[24m, used to expand internal references in
     [4mmm[24m  documents;  see  ]8;;man:groff_mm(7)\[4mgroff_mm[24m(7)]8;;\.  It runs [4mgroff[24m with the [1m-mm [22moption twice,
     first with [1m-z [22mand [1m-rRef=1 [22mto populate reference and index files with  their
     corresponding  entries,  and then without to produce the document.  It also
     handles the inclusion of PostScript images with the [1mPIC  [22mmacro.   Documents
     that  do  not  use these features of [4mgroff[24m [4mmm[24m (the [1mINITI[22m, [1mIND[22m, [1mINDP[22m, [1mINITR[22m,
     [1mSETR[22m, [1mGETHN[22m, [1mGETPN[22m, [1mGETR[22m, [1mGETST[22m, and [1mPIC [22mmacros) do not require [4mmmroff[24m.

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

     [1m-x     [22mCreate or update the reference list file and exit.

[1mEnvironment[0m
     Normally, the path separator in environment variables ending with  [4mPATH[24m  is
     the  colon;  this may vary depending on the operating system.  For example,
     Windows uses a semicolon instead.

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

[1mExit status[0m
     [4mmmroff[24m exits with status [1m0 [22mif the [1m--help [22mor [1m--version [22moptions  were  speci‐
     fied,  or  if  [1m-x [22mwas specified and the program successfully created or up‐
     dated the reference list file.  It exits with status [1m1 [22mif it was unable  to
     create necessary files.  Otherwise, it exits with the status of [4mgroff[24m.

[1mAuthors[0m
     [4mmmroff[24m was written by ]8;;mailto:jh@axis.se\Jörgen Hägg]8;;\ of Lund, Sweden.

[1mSee also[0m
     ]8;;man:groff_mm(7)\[4mgroff_mm[24m(7)]8;;\, ]8;;man:groff_mmse(7)\[4mgroff_mmse[24m(7)]8;;\, ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\, ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\, ]8;;man:pic(1)\[4mpic[24m(1)]8;;\, ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\

groff 1.24.0                       2026-02-23                          [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.0                       2025-11-14                            [4mneqn[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mnroff[24m(1)                     General Commands Manual                    [4mnroff[24m(1)

[1mName[0m
     nroff - format documents with [4mgroff[24m for terminal (“TTY”) devices

[1mSynopsis[0m
     [1mnroff [22m[[1m-abcCEhikpRStUVzZ[22m] [[1m-d [4m[22mctext[24m] [[1m-d [4m[22mstring[24m[1m=[4m[22mtext[24m] [[1m-D [4m[22mfallback-input-[0m
           [4mencoding[24m] [[1m-I [4m[22minclusion-directory[24m] [[1m-K [4m[22minput-encoding[24m] [[1m-m [4m[22mmacro-[0m
           [4mpackage[24m] [[1m-M [4m[22mmacro-directory[24m] [[1m-n [4m[22mpage-number[24m] [[1m-o [4m[22mpage-list[24m]
           [[1m-P [4m[22mpostprocessor-argument[24m] [[1m-r [4m[22mcnumeric-expression[24m]
           [[1m-r [4m[22mregister[24m[1m=[4m[22mnumeric-expression[24m] [[1m-T [4m[22moutput-device[24m] [[1m-w [4m[22mwarning-[0m
           [4mcategory[24m] [[1m-W [4m[22mwarning-category[24m] [[4mfile[24m ...]

     [1mnroff --help[0m

     [1mnroff -v [22m[[4mother-nroff-option[24m ...]
     [1mnroff --version [22m[[4mother-nroff-option[24m ...]

[1mDescription[0m
     [4mnroff[24m formats documents written in the ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\  language  for  typewriter-
     like devices such as terminal emulators.  GNU [4mnroff[24m emulates the AT&T [4mnroff[0m
     command using ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\.  [4mnroff[24m generates output via ]8;;man:grotty(1)\[4mgrotty[24m(1)]8;;\, [4mgroff[24m's ter‐
     minal output driver, which needs to know the character encoding scheme used
     by  the  device.   Consequently,  acceptable arguments to the [1m-T [22moption are
     [1mascii[22m,  [1mlatin1[22m,  and  [1mutf8[22m;  any  others  are  ignored.   If  neither   the
     [4mGROFF_TYPESETTER[24m environment variable nor the [1m-T [22mcommand-line option (which
     overrides  the environment variable) specifies a (valid) device, [4mnroff[24m con‐
     sults the locale to select an appropriate output device.   It  first  tries
     the ]8;;man:locale(1)\[4mlocale[24m(1)]8;;\ program, then checks several locale-related environment vari‐
     ables;  see  section  “Environment”  below.   If all of the foregoing fail,
     [4mnroff[24m assumes “[1m-T ascii[22m”.

     The [1m-a[22m, [1m-b[22m, [1m-c[22m, [1m-C[22m, [1m-d[22m, [1m-E[22m, [1m-i[22m, [1m-I[22m, [1m-m[22m, [1m-M[22m, [1m-n[22m, [1m-o[22m, [1m-r[22m, [1m-U[22m, [1m-w[22m, [1m-W[22m, and  [1m-z[0m
     options  have  the  effects described in ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\.  [1m-c [22mand [1m-h [22mimply “[1m-P -c[22m”
     and “[1m-P -h[22m”, respectively; [1m-c [22mis also meaningful to [4mtroff[24m itself.  Further,
     GNU [4mnroff[24m ignores the AT&T [4mnroff[24m options [1m-e[22m, [1m-q[22m, and  [1m-s[22m.   ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\  docu‐
     ments  options  [1m-D[22m, [1m-k[22m, [1m-K[22m, [1m-p[22m, [1m-P[22m, [1m-R[22m, [1m-t[22m, [1m-S[22m, and [1m-Z[22m.  [1m-V [22mcauses [4mnroff[24m to
     display the constructed [4mgroff[24m command on the standard  output  stream,  but
     does not execute it.  [1m-v [22mand [1m--version [22mshow version information about [4mnroff[0m
     and  the  programs it runs, while [1m--help [22mdisplays a usage message; all exit
     afterward.

[1mExit status[0m
     [4mnroff[24m exits with status [1m2 [22mif there was a  problem  parsing  its  arguments,
     with status [1m0 [22mif any of the options [1m-V[22m, [1m-v[22m, [1m--version[22m, or [1m--help [22mwere spec‐
     ified, and with the status of [4mgroff[24m otherwise.

[1mEnvironment[0m
     Normally,  the  path separator in environment variables ending with [4mPATH[24m is
     the colon; this may vary depending on the operating system.   For  example,
     Windows uses a semicolon instead.

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

     [4mGROFF_TYPESETTER[0m
            specifies the default output device for [4mgroff[24m.

     [4mLC_ALL[0m
     [4mLC_CTYPE[0m
     [4mLANG[0m
     [4mLESSCHARSET[0m
            are  pattern-matched  in  this  order for contents matching standard
            character encodings supported by [4mgroff[24m in the event no [1m-T [22moption  is
            given and [4mGROFF_TYPESETTER[24m is unset, or the values specified are in‐
            valid.

[1mFiles[0m
     [4m/usr/share/groff/1.24.0/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.0                       2025-12-18                           [4mnroff[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mpdfmom[24m(1)                    General Commands Manual                   [4mpdfmom[24m(1)

[1mName[0m
     pdfmom - produce PDF documents using the [4mmom[24m macro package for [4mgroff[0m

[1mSynopsis[0m
     [1mpdfmom [22m[[1m--roff[22m] [[1m-Tpdf[22m] [[4mgroff-options[24m] [[4mfile[24m ...]

     [1mpdfmom [22m[[1m--roff[22m] [1m-Tps [22m[[4mpdfroff-options[24m] [[4mgroff-options[24m] [[4mfile[24m ...]

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

[1mDescription[0m
     [4mpdfmom[24m is a wrapper around ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ that facilitates the production of  PDF
     documents from files formatted with the [4mmom[24m macros.

     If  the  [1m--roff [22moption is used, the wrapper can be used with macro packages
     other than ]8;;man:groff_mom(7)\[4mgroff_mom[24m(7)]8;;\.  This is also true if the wrapper  is  renamed  or
     linked  as  a pseudonym; for example, creating a [4mpdfms[24m link pointing to the
     [4mpdfmom[24m executable makes a wrapper for producing PDFs with the [4mms[24m package.

     [4mpdfmom[24m prints to the standard output, so output must usually be  redirected
     to  a destination file.  The size of the final PDF can be reduced by piping
     the output through ]8;;man:ps2pdf(1)\[4mps2pdf[24m(1)]8;;\.

     If called with the [1m-Tpdf [22moption (which is the  default),  [4mpdfmom[24m  processes
     files  using  [4mgroff[24m's native PDF driver, ]8;;man:gropdf(1)\[4mgropdf[24m(1)]8;;\.  If [1m-Tps [22mis given, pro‐
     cessing is passed over to [4mpdfroff[24m, which uses  [4mgroff[24m's  PostScript  driver.
     In  either case, multiple runs of the source file are performed in order to
     satisfy any forward references in the document.

     [4mpdfmom[24m accepts all the same options as [4mgroff[24m.  If [1m-Tps [22mis  given,  the  op‐
     tions  associated  with  [4mpdfroff[24m  are  accepted as well.  When [4mpdfmom[24m calls
     [4mpdfroff[24m, the options “[1m-mpdfmark -mom  --no-toc[22m”  options  are  implied  and
     should  not  be given on the command line.  Equally, it is not necessary to
     supply the [1m-mom [22mor [1m-m mom [22moptions when [1m-Tps [22mis absent.

     PDF integration with the [4mmom[24m macros is discussed  in  full  in  the  manual
     “Producing PDFs with [4mgroff[24m and [4mmom[24m”, which was itself produced with [4mpdfmom[24m.

     If called with the [1m-v [22mor [1m--version [22moptions, [4mpdfmom[24m displays its version in‐
     formation  and exits.  Using the [1m--help [22moption displays a usage message and
     exits.

[1mAuthors[0m
     [4mpdfmom[24m was written by ]8;;mailto:deri@chuzzlewit.myzen.co.uk\Deri James]8;;\ and ]8;;mailto:peter@schaffter.ca\Peter Schaffter]8;;\, and is maintained  by
     James.

[1mSee also[0m
     [4m/usr/share/doc/groff-1.24.0/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.0                       2026-01-01                          [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.0                       2024-05-03                         [4mpfbtops[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mpic[24m(1)                       General Commands Manual                      [4mpic[24m(1)

[1mName[0m
     pic - compile pictures for [4mtroff[24m or TeX

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

     [1mpic -t [22m[[1m-cCSUz[22m] [[4mfile[24m ...]

     [1mpic --help[0m

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

[1mDescription[0m
     The GNU implementation of [4mpic[24m is part of the ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\  document  formatting
     system.  [4mpic[24m is a ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ preprocessor that translates descriptions of di‐
     agrammatic  pictures embedded in ]8;;man:roff(7)\[4mroff[24m(7)]8;;\ or TeX input into the language un‐
     derstood by TeX or [4mtroff[24m.  It copies each [4mfile[24m's contents to  the  standard
     output stream, translating each [4mpicture[24m between lines starting with [1m.PS [22mand
     any  of  [1m.PE[22m, [1m.PF[22m, or [1m.PY[22m.  End a [4mpic[24m picture with [1m.PE [22mto leave the drawing
     position at the bottom of the picture, and with [1m.PF [22mor [1m.PY [22mto leave  it  at
     the  top.   Normally, [4mpic[24m is not executed directly by the user, but invoked
     by specifying the [1m-p [22moption to ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\.  If no [4mfile[24m operands are  present,
     or if [4mfile[24m is “[1m-[22m”, [4mpic[24m reads the standard input stream.

     It  is  the user's responsibility to provide appropriate definitions of the
     [1mPS[22m, [1mPE[22m, and one or both of the [1mPF [22mand [1mPY [22mmacros.  When a macro package does
     not supply these, obtain simple definitions with the  [4mgroff[24m  option  [1m-mpic[22m;
     these horizontally center each picture.

     GNU  [4mpic[24m  supports [1mPY [22mas a synonym of [1mPF [22mto work around a name space colli‐
     sion with the [4mmm[24m macro package, which defines [1mPF [22mas a page  footer  manage‐
     ment macro.  Use [1mPF [22mpreferentially unless a similar problem faces your doc‐
     ument.

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

     [1m-c     [22mBe  more  compatible  with [4mtpic[24m; implies [1m-t[22m.  Lines beginning with [1m\[0m
            are not passed through transparently.  Lines beginning  with  [1m.  [22mare
            passed  through  with  the  initial [1m. [22mchanged to [1m\[22m.  GNU [4mpic[24m gives a
            line beginning with [1m.ps [22mspecial treatment: it takes an optional  in‐
            teger  argument  specifying  the line thickness (pen size) in milli‐
            inches, a missing argument restores the previous line thickness, and
            the default line thickness is 8  milliinches.   The  line  thickness
            thus  specified takes effect only when a non-negative line thickness
            has not been specified by use of the [1mthickness [22mattribute or by  set‐
            ting the [1mlinethick [22mvariable.

     [1m-C     [22mRecognize  [1m.PS[22m,  [1m.PE[22m, [1m.PF[22m, and [1m.PY [22meven when followed by a character
            other than space or newline.

     [1m-n     [22mDon't use [4mgroff[24m extensions to the [4mtroff[24m drawing  commands.   Specify
            this  option  if  a postprocessor you're using doesn't support these
            extensions, described in ]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\.  This option also causes  [4mpic[0m
            not to use zero-length lines to draw dots in [4mtroff[24m mode.

     [1m-S     [22mEnable  safer  mode  and  ignore any subsequent [1m-U [22moption.  In [4msafer[0m
            [4mmode,[24m [4mpic[24m ignores [1msh [22mcommands, which can be useful when operating on
            untrustworthy input.  [4mpic[24m operates in safer mode by default.

     [1m-t     [22mProduce TeX output.

     [1m-U     [22mOperate in [4munsafe[24m [4mmode;[24m [1msh [22mcommands are interpreted.

     [1m-z     [22mIn TeX mode, draw dots using zero-length lines.

     The following options supported by other versions of [4mpic[24m are ignored.

     [1m-D      [22mDraw all lines using the \D escape sequence.  GNU [4mpic[24m  always  does
             this.

     [1m-T [4m[22mdev[24m  Generate  output for the [4mtroff[24m device [4mdev[24m.  This option is unneces‐
             sary in GNU [4mpic[24m because the [4mtroff[24m it generates  is  device-indepen‐
             dent.

[1mUsage[0m
     This  section  primarily  discusses the differences between GNU [4mpic[24m and the
     Eighth Edition Unix version of AT&T [4mpic[24m (1985).  Many of these  differences
     also apply to later versions of AT&T [4mpic[24m.

   [1mTeX mode[0m
     TeX-compatible  output  is  produced  when the [1m-t [22moption is specified.  You
     must use a TeX driver that supports [4mtpic[24m version 2 specials.  ([4mtpic[24m  was  a
     fork  of  AT&T  [4mpic[24m by Tim Morgan of the University of California at Irvine
     that diverged from its source around 1984.  It  is  best  known  today  for
     lending its name to a group of [1m\special [22mcommands it produced for TeX.)

     Lines  beginning  with [1m\ [22mare passed through unaltered except for a [1m% [22msuffix
     to avoid unwanted spaces.  Use this feature to change fonts or the value of
     [1m\baselineskip[22m.  Other applications may produce undesirable results; use  at
     your own risk.  By default, lines beginning with a dot are not treated spe‐
     cially——but see the [1m-c [22moption.

     In  TeX  mode,  [4mpic[24m defines a vbox called [1m\graph [22mfor each picture.  Use GNU
     [4mpic[24m's [1mfigname [22mcommand to change the name of the vbox.  You must print  that
     vbox yourself using the command
            \centerline{\box\graph}
     for  instance.   Since  the  vbox  has a height of zero——it is defined with
     [1m\vtop[22m——this produces slightly more vertical space above  the  picture  than
     below it;
            \centerline{\raise 1em\box\graph}
     would  avoid  this.  To give the vbox a positive height and a depth of zero
     (as used by LaTeX's [4mgraphics.sty[24m, for example), define the following  macro
     in your document.
            \def\gpicbox#1{%
              \vbox{\unvbox\csname #1\endcsname\kern 0pt}}
     You can then simply say [1m\gpicbox{graph} [22minstead of [1m\box\graph[22m.

   [1mCommands[0m
     Several  commands new to GNU [4mpic[24m accept delimiters, shown in their synopses
     as braces [1m{ }[22m.  Nesting of braces is supported.  Any other characters  (ex‐
     cept  a  space,  tab, or newline) may be used as alternative delimiters, in
     which case the members of a given pair must be identical.  GNU  [4mpic[24m  recog‐
     nizes  double-quoted strings within delimiters of either kind; such strings
     may contain the delimiter character or unbalanced braces.

     [1mfor [4m[22mvariable[24m [1m= [4m[22mexpr1[24m [1mto [4m[22mexpr2[24m [[1mby [22m[[1m*[22m][4mexpr3[24m] [1mdo [4m[22mX[24m [4mbody[24m [4mX[0m
            Set [4mvariable[24m to [4mexpr1[24m.  While the value of [4mvariable[24m is less than  or
            equal  to  [4mexpr2[24m,  do [4mbody[24m and increment [4mvariable[24m by [4mexpr3[24m; if [1mby [22mis
            not given, increment [4mvariable[24m by 1.  [4mexpr3[24m can be negative, in which
            case [4mvariable[24m is then tested whether it is greater than or equal  to
            [4mexpr2[24m.  A [1m* [22mprefix on [4mvariable[24m multiplies it by [4mexpr3[24m (which must be
            greater  than  zero)  at each iteration rather than incrementing it.
            If the range constraint on [4mexpr3[24m isn't met, the loop does  not  exe‐
            cute.  [4mX[24m can be any character not in [4mbody[24m.

     [1mif [4m[22mexpr[24m [1mthen [4m[22mX[24m [4mif-true[24m [4mX[24m [[1melse [4m[22mY[24m [4mif-false[24m [4mY[24m]
            Evaluate  [4mexpr[24m;  if it is non-zero then do [4mif-true[24m, otherwise do [4mif-[0m
            [4mfalse[24m.  [4mX[24m can be any character not in [4mif-true[24m.  [4mY[24m can be any charac‐
            ter not in [4mif-false[24m.

     [1mprint [4m[22marg[24m ...
            Catenate and write arguments to the standard error  stream  followed
            by  a newline.  Each [4marg[24m must be an expression, a position, or text.
            This feature is useful for debugging.

     [1mcommand [4m[22marg[24m ...
            Catenate arguments and pass them as a line to [4mtroff[24m  or  TeX.   Each
            [4marg[24m  must be an expression, a position, or text.  [1mcommand [22mallows the
            values of [4mpic[24m variables to be passed to the formatter.  Thus,
                   .PS
                   x = 14
                   command ".ds string x is " x "."
                   .PE
                   \*[string]
            produces
                   x is 14.
            when formatted with [4mtroff[24m.

     [1msh [4m[22mX[24m [4mcommand[24m [4mX[0m
            Pass [4mcommand[24m to a shell via ]8;;man:system(3)\[4msystem[24m(3)]8;;\.  Ignored  if  [1m-U  [22moption  not
            specified.

     [1mcopy "[4m[22mfilename[24m[1m"[0m
            Include [4mfilename[24m at this point in the file.

     [1mcopy [22m[[1m"[4m[22mfilename[24m[1m"[22m] [1mthru [4m[22mX[24m [4mbody[24m [4mX[24m [[1muntil [22m"[4mword[24m[1m"[22m]
     [1mcopy [22m[[1m"[4m[22mfilename[24m[1m"[22m] [1mthru [4m[22mmacro[24m [[1muntil [22m"[4mword[24m[1m"[22m]
            This construct does [4mbody[24m once for each line of [4mfilename[24m; the line is
            split into blank-delimited words, and occurrences of [1m$[4m[22mi[24m in [4mbody[24m, for
            [4mi[24m  between  1  and 9, are replaced by the [4mi[24m-th word of the line.  If
            [4mfilename[24m is not given, lines are taken from the current input up  to
            [1m.PE[22m.   If an [1muntil [22mclause is specified, GNU [4mpic[24m reads lines only un‐
            til encountering one beginning with [4mword[24m; which it then discards.  [4mX[0m
            can be any character not in [4mbody[24m.  For example,
                   .PS
                   copy thru % circle at ($1,$2) % until "END"
                   1 2
                   3 4
                   5 6
                   END
                   box
                   .PE
            and
                   .PS
                   circle at (1,2)
                   circle at (3,4)
                   circle at (5,6)
                   box
                   .PE
            are equivalent.  The commands to be performed for each line can also
            be taken from a macro defined earlier by  giving  the  name  of  the
            macro as the argument to [1mthru[22m.  The argument after [1mthru [22mis looked up
            as a macro name first; if not defined, its first character is inter‐
            preted as a delimiter.

     [1mreset[0m
     [1mreset [4m[22mpvar1[24m[[1m,[22m] [4mpvar2[24m ...
            Reset predefined variables [4mpvar1[24m, [4mpvar2[24m ... to their default values;
            if  no  arguments are given, reset all predefined variables to their
            default values.  Variable names may be separated by commas,  spaces,
            or  both.   Assigning  a  value  to [1mscale [22malso causes all predefined
            variables that control dimensions to be reset to their default  val‐
            ues times the new value of [1mscale[22m.

     [1mplot [4m[22mexpr[24m ["[4mtext[24m"]
            Create a text object by using [4mtext[24m as a format string for ]8;;man:sprintf(3)\[4msprintf[24m(3)]8;;\
            with an argument of [4mexpr[24m.  If [4mtext[24m is omitted, [1m"%g" [22mis implied.  At‐
            tributes  can  be specified in the same way as for a normal text ob‐
            ject.  [4mCaution:[24m be very careful that you specify an appropriate for‐
            mat string in [4mtext;[24m [4mpic[24m's validation of it is limited.  [1mplot [22mis dep‐
            recated in favour of [1msprintf[22m.

     [4mvar[24m [1m:= [4m[22mexpr[0m
            Update an existing variable.  [4mvar[24m must already be defined, and  [4mexpr[0m
            is  assigned to [4mvar[24m without creating a variable local to the current
            block.  (By contrast, [1m= [22mdefines [4mvar[24m in the current block  if  it  is
            not already defined there, and then changes the value in the current
            block only.)  For example,
                   [1m.PS[0m
                   [1mx = 3[0m
                   [1my = 3[0m
                   [1m[[0m
                   [1mx := 5[0m
                   [1my = 5[0m
                   [1m][0m
                   [1mprint x   y[0m
                   [1m.PE[0m
            writes
                   5 3
            to the standard error stream.

   [1mExpressions[0m
     The syntax for expressions has been significantly extended.

     [4mx[24m [1m^ [4m[22my[24m (exponentiation)
     [1msin([4m[22mx[24m[1m)[0m
     [1mcos([4m[22mx[24m[1m)[0m
     [1matan2([4m[22my[24m[1m, [4m[22mx[24m[1m)[0m
     [1mlog([4m[22mx[24m[1m) [22m(base 10)
     [1mexp([4m[22mx[24m[1m) [22m(base 10, i.e. 10^[4mx[24m)
     [1msqrt([4m[22mx[24m[1m)[0m
     [1mint([4m[22mx[24m[1m)[0m
     [1mrand() [22m(return a random number between 0 and 1)
     [1mrand([4m[22mx[24m[1m) [22m(return a random number between 1 and [4mx[24m; deprecated)
     [1msrand([4m[22mx[24m[1m) [22m(set the random number seed)
     [1mmax([4m[22me1[24m[1m, [4m[22me2[24m[1m)[0m
     [1mmin([4m[22me1[24m[1m, [4m[22me2[24m[1m)[0m
     [1m![4m[22me[0m
     [4me1[24m [1m&& [4m[22me2[0m
     [4me1[24m [1m|| [4m[22me2[0m
     [4me1[24m [1m== [4m[22me2[0m
     [4me1[24m [1m!= [4m[22me2[0m
     [4me1[24m [1m>= [4m[22me2[0m
     [4me1[24m [1m> [4m[22me2[0m
     [4me1[24m [1m<= [4m[22me2[0m
     [4me1[24m [1m< [4m[22me2[0m
     [1m"[4m[22mstr1[24m[1m" == "[4m[22mstr2[24m[1m"[0m
     [1m"[4m[22mstr1[24m[1m" != "[4m[22mstr2[24m[1m"[0m

     String  comparison  expressions  must  be parenthesised in some contexts to
     avoid ambiguity.

   [1mOther changes[0m
     A bare expression, [4mexpr[24m, is acceptable as an attribute; it is equivalent to
     “[4mdir[24m [4mexpr[24m”, where [4mdir[24m is the current direction.   For  example,  “[1mline  2i[22m”
     draws  a  line  2  inches  long in the current direction.  The ‘i’ (or ‘I’)
     character is ignored; to use another measurement unit, set the [1mscale  [22mvari‐
     able to an appropriate value.

     The  maximum  width  and height of the picture are taken from the variables
     [1mmaxpswid [22mand [1mmaxpsht[22m.  Initially, these have values  8.5  and  11,  respec‐
     tively.

     Scientific notation is allowed for numbers, as with “[1mx = 5e-2[22m”.

     Text  attributes  can  be  compounded.  For example, “[1m"foo" above ljust[22m” is
     valid.

     There is no limit to the depth to which blocks can be nested.  For example,
            [A: [B: [C: box ]]] with .A.B.C.sw at 1,2
            circle at last [].A.B.C
     is acceptable.

     Arcs have compass points determined by the circle of which  the  arc  is  a
     part.

     Circles,  ellipses, and arcs can be dotted or dashed.  In TeX mode, splines
     can be dotted or dashed as well.

     Boxes can have rounded corners.  The [1mrad [22mattribute specifies the radius  of
     the  quarter-circles at each corner.  If no [1mrad [22mor [1mdiam [22mattribute is given,
     a radius of [1mboxrad [22mis used.  Initially, [1mboxrad [22mhas a value  of  0.   A  box
     with rounded corners can be dotted or dashed.

     Boxes  can  have slanted sides, generalizing them from rectangles to paral‐
     lelograms.  The [1mxslanted [22mand [1myslanted [22mattributes specify the [4mx[24m and  [4my[24m  off‐
     sets of the box's upper right corner from its default position.

     The  [1m.PS [22mline accepts a second argument specifying a maximum height for the
     picture.  If a width of zero is specified, it is ignored when computing the
     scaling factor for the picture.  GNU [4mpic[24m always scales  a  picture  by  the
     same  amount  vertically  and horizontally.  This differs from DWB 2.0 [4mpic[24m,
     which may change the picture's aspect ratio if a height is specified.

     Each text object has an associated invisible box that determines  its  com‐
     pass  points and implicit motion.  The dimensions of the box are taken from
     its width and height attributes.  If the width attribute is  not  supplied,
     the  value of [1mtextwid [22mis assumed.  If the height attribute is not supplied,
     the height defaults to the number of text strings associated with  the  ob‐
     ject times [1mtextht[22m.  Initially, [1mtextwid [22mand [1mtextht [22mhave values of 0.

     In  (almost  all) places where a quoted text string can be used, an expres‐
     sion of the form

            [1msprintf("[4m[22mformat[24m[1m", [4m[22marg[24m[1m, [22m...[1m)[0m

     can be used instead; it transforms its arguments per [4mformat[24m,  which  should
     be  a  string as described in ]8;;man:printf(3)\[4mprintf[24m(3)]8;;\, and appropriate to the quantity of
     arguments supplied.  GNU [4mpic[24m supports only the conversion specifiers [1me[22m,  [1mE[22m,
     [1mf[22m,  [1mg[22m, [1mG[22m, and [1m%[22m, modifiers “[1m#[22m”, “[1m-[22m”, “[1m+[22m”, and “ ” [space]), a minimum field
     width, and an optional precision.

     The thickness of the lines used  to  draw  objects  is  controlled  by  the
     [1mlinethick  [22mvariable,  which  is measured in points.  A negative value indi‐
     cates the default thickness.  In TeX output mode when the [1m-c [22moption is  not
     given, this means 8 milliinches.  In [4mtroff[24m and TeX [1m-c [22moutput modes, the de‐
     fault  thickness  corresponds to the type size.  (Thus, if the type size is
     10 points, a line is 10 points thick.)  A [1mlinethick [22mvalue of zero draws the
     thinnest  possible  line  supported  by  the  output  device.    Initially,
     [1mlinethick  [22mhas  a  value of -1.  A [1mthick[22m[[1mness[22m] attribute is also available.
     For example, “[1mcircle thickness 1.5[22m” draws a circle with a line thickness of
     1.5 points.  The thickness of lines is not affected by  the  value  of  the
     [1mscale [22mvariable, nor by the width or height given in the [1m.PS [22mline.

     Boxes (including boxes with rounded corners or slanted sides), circles, and
     ellipses can be filled by giving them an attribute of [1mfill[22m[[1med[22m], which takes
     an  optional  expression  argument with a value between 0 and 1; 0 fills it
     with white, 1 with black, and values in between with a proportionally  gray
     shade.   A value greater than 1 is interpreted as the shade of gray that is
     being used for text and lines.  Normally this is black, but output  devices
     may  provide a mechanism for changing this.  Without an argument, the value
     of the variable [1mfillval [22mis used.  Initially, [1mfillval [22mhas a  value  of  0.5.
     The [1minvisible [22mattribute does not affect the filling of objects.  Text asso‐
     ciated  with  a  filled object is added after the object is filled, so that
     the text is not obscured by the filling.

     Additional modifiers are available to draw colored objects: [1moutline[22m[[1md[22m] sets
     the color of the outline, [1mshaded [22mthe  fill  color,  and  [1mcolo[22m[[1mu[22m][1mr[22m[[1med[22m]  sets
     both.  All expect a subsequent string argument specifying the color.
            circle shaded "green" outline "black"
     Color  is  not  yet supported in TeX mode.  Device macro files like [4mps.tmac[0m
     declare color names; you can define additional ones with the  [1mdefcolor  [22mre‐
     quest  (see  ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\).   [4mpic[24m assumes at the beginning of each picture that
     the stroke and fill colors are set to the device defaults.

     To change the name of the vbox in TeX mode, set the pseudo-variable [1mfigname[0m
     (which is actually a specially parsed command) within a picture.  For exam‐
     ple,
            .PS
            figname = foobar;
            circle "dig here";
            .PE
     makes the picture available in the box [1m\foobar[22m.

     Arrow heads are drawn as solid triangles if the variable [1marrowhead [22mis  non-
     zero  and  either  TeX  mode is enabled or the [1m-n [22moption is not used.  Ini‐
     tially, [1marrowhead [22mhas a value of 1.  Solid arrow heads  are  always  filled
     with the current outline (stroke) color.

     The  [4mtroff[24m output of [4mpic[24m is device-independent.  The [1m-T [22moption is therefore
     redundant.  Except where noted, all measurements and dimensions use  inches
     implicitly; they are never interpreted as [4mtroff[24m basic units.

     Objects  can  have  an  [1maligned  [22mattribute, but it is supported only by the
     ]8;;man:grops(1)\[4mgrops[24m(1)]8;;\ and ]8;;man:gropdf(1)\[4mgropdf[24m(1)]8;;\ output drivers.  Any text associated with an [1maligned[0m
     object is rotated about the object's center such that it is oriented  along
     a  line  connecting the start and end points of the object.  [1maligned [22mhas no
     effect on objects whose start and end points are coincident.

     In places where [4mn[24m[1mth [22mis allowed, [1m`[4m[22mexpr[24m[1m'th [22mis also allowed.  “[1m'th[22m” is a  sin‐
     gle  token:  no space is allowed between the apostrophe and the “[1mth[22m”.  Con‐
     sider the following example.

            for i = 1 to 4 do {
               box
               move right 0.5
            }
            for i = 1 to 3 do {
               arrow from `i'th box.ne to `i+1'th box.sw
            }

     Arbitrary polygons can be drawn using the [1mpolygon [22mkeyword followed by a se‐
     ries of [4mn[24m-1 line segments, where [4mn[24m is the number of edges of  the  polygon.
     This  allows  GNU [4mtroff[24m to interpret the line segments as a complete object
     such that the [1mfilled [22mand [1mshaded [22mattributes may be  used.   The  last  user-
     specified  line segment determines the polygon's final drawing position and
     direction.  For example, draw and fill a triangle with the following.

            polygon up 1 then right 1 down 0.5 fill 0.5

     Two reference point suffixes permit the  positioning  of  drawing  elements
     relative to a polygon.  “[1m.vertex [4m[22mexpr[24m” locates the vertices, and “[1m.midpoint[0m
     [4mexpr[24m”  for  locating  the midpoints of edges.  GNU [1mpic [22mnumbers vertices and
     midpoints in drawing order starting from [1m1 .  [22mYou can abbreviate [1m.vertex [22mas
     [1m.v [22mor [1m.ver[22m, and [1m.midpoint [22mas [1m.mid[22m.

     For example,

            arrow down
            polygon up 0.5 right 1 \
            then down 0.5 right 1 \
            then down 0.5 left 1 \
            with .v2 at last line.end
            arrow down from last polygon.v4

     creates and correctly places a flowchart decision diamond.

     [1m.center [22m([1m.c[22m) is also available, but compass points do not work as  expected
     and should not be used with polygons.

   [1mConverting [4mpic[24m to other image formats[0m
     To  create  a  stand-alone graphics file from a [4mpic[24m file, first compose the
     picture.  Bracket your [4mpic[24m code with [1m.PS [22mand [1m.PE  [22mtokens.   [4mgroff[24m  requests
     that  don't  produce  formatted output may precede [1m.PS[22m, but format no text,
     not even any injected by a macro package, which may include a  page  number
     even  on  the  first page, as [4mmm[24m does by default.  Consider writing a “raw”
     [4mroff[24m document that uses no macro package.

     Next, convert the [4mroff[24m/[4mpic[24m input into the desired format.   [4mgroff[24m  distrib‐
     utes a simple utility, ]8;;man:pic2graph(1)\[4mpic2graph[24m(1)]8;;\, for this purpose.  Other possibilities
     exist,  particularly  if  you  first transform your picture into PostScript
     format with “[1mgroff -T ps[22m”.  However, such a PostScript file lacks  bounding
     box  information; [4mroff[24m formatters produce page-sized output.  Several tools
     with names beginning “psto” or “ps2” exist that can infer the bounding  box
     and  perform  a  format  conversion.  One of these is the PostScript inter‐
     preter  Ghostscript  ([4mgs[24m(1)),  which  exposes  format  converters  via  its
     [1m-sDEVICE= [22moption.  “[1mgs --help[22m” lists available devices.

     Alternatively,  produce  a  PDF  with “[1mgroff -T pdf[22m”; ]8;;man:gropdf(1)\[4mgropdf[24m(1)]8;;\'s [1m-p [22moption
     sets the MediaBox of the file.

     The Encapsulated PostScript File (EPS) format is still sometimes seen.  The
     aforementioned Ghostscript offers ]8;;man:ps2epsi(1)\[4mps2epsi[24m(1)]8;;\, and a standalone package  and
     command ]8;;man:ps2eps(1)\[4mps2eps[24m(1)]8;;\ is also available.

     For  raster image formats, use ]8;;man:pstopnm(1)\[4mpstopnm[24m(1)]8;;\; the resulting ]8;;man:pnm(5)\[4mpnm[24m(5)]8;;\ file can be
     then converted to virtually any image format using the [4mnetpbm[24m tools.

     GNU [4mplotutils[24m offers a ]8;;man:pic2plot(1)\[4mpic2plot[24m(1)]8;;\ utility for converting [4mpic[24m  input  to  a
     wide variety of other image formats, including SVG.

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

[1mFiles[0m
     [4m/usr/share/groff/1.24.0/tmac/pic.tmac[0m
            offers simple definitions of the [1mPS[22m, [1mPE[22m, [1mPF[22m, and [1mPY [22mmacros.  Load it
            with the [1mmso [22mrequest when eschewing a full-service macro package, or
            using one that doesn't supply its own definitions for them.

[1mCaveats[0m
     The  spacing of dots and dashes in broken lines scales with other graphics,
     and is configurable.  For example,

            line from 0,0 to 100,0 dotted 5

     spaces the dots in a dotted line 5 units apart.  The spacing of dashes  can
     be set the same way.  The [1mdashwid [22mvariable sets the length of dashes.

[1mBugs[0m
     Characters  that  are  invalid as input to GNU [4mtroff[24m (see the [4mgroff[24m Texinfo
     manual or ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\ for a list) are rejected even in TeX mode.

     Research Tenth Edition Unix [4mpic[24m's [1mfillval [22minterprets 0 as black  and  1  as
     white, incompatibly with GNU [4mpic[24m.

[1mSee also[0m
     [4m/usr/share/doc/groff-1.24.0/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.0                       2021-08-11                             [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.0                       2025-08-02                       [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.0                       2024-10-18                         [4mpreconv[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mrefer[24m(1)                     General Commands Manual                    [4mrefer[24m(1)

[1mName[0m
     refer - process bibliographic references for [4mgroff[0m

[1mSynopsis[0m
     [1mrefer [22m[[1m-bCenPRS[22m] [[1m-a [4m[22mn[24m] [[1m-B [4m[22mfield[24m[1m.[4m[22mmacro[24m] [[1m-c [4m[22mfields[24m] [[1m-f [4m[22mn[24m] [[1m-i [4m[22mfields[24m]
           [[1m-k [4m[22mfield[24m] [[1m-l [4m[22mrange-expression[24m] [[1m-p [4m[22mdatabase-file[24m] [[1m-s [4m[22mfields[24m]
           [[1m-t [4m[22mn[24m] [[4mfile[24m ...]

     [1mrefer --help[0m

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

[1mDescription[0m
     The GNU implementation of [4mrefer[24m is part of the ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ document formatting
     system.  [4mrefer[24m is a ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ preprocessor that prepares bibliographic cita‐
     tions by looking up keywords specified in a ]8;;man:roff(7)\[4mroff[24m(7)]8;;\ input document, obviat‐
     ing the need to type such annotations, and permitting the citation style in
     formatted output to be altered independently and systematically.  It copies
     the  contents  of  each [4mfile[24m to the standard output stream, looking up each
     [4mcitation[24m between lines starting with [1m.[ [22mand [1m.] [22mand replacing it with a bib‐
     liographic reference.  GNU [4mrefer[24m furthermore interprets lines between those
     starting with [1m.R1 [22mand [1m.R2 [22mas instructions directing how citations are to be
     processed.  [4mrefer[24m interprets and generates [4mroff[24m [1mlf [22mrequests  so  that  file
     names  and line numbers in messages produced by commands that read its out‐
     put correctly describe the source document.  Normally, [4mrefer[24m  is  not  exe‐
     cuted  directly  by  the  user,  but invoked by specifying the [1m-R [22moption to
     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\.  If no [4mfile[24m operands are present, or if [4mfile[24m is “[1m-[22m”, [4mrefer[24m  reads
     the standard input stream.

     A citation identifies a work by reference to a [4mbibliographic[24m [4mrecord[24m detail‐
     ing  it.  Select a work from a database of records by listing keywords that
     uniquely identify its entry.   Alternatively,  a  document  can  specify  a
     record  for  the work at the point its citation occurs.  A document can use
     either or both strategies as desired.

     For each citation, [4mrefer[24m produces a [4mmark[24m in the text, like a  superscripted
     footnote  number  or  “[Lesk1978a]”.   A  mark  consists of a [4mlabel[24m between
     [4mbrackets.[24m  The mark can be separated from surrounding text and  from  other
     labels  in various ways.  [4mrefer[24m produces [4mroff[24m language requests usable by a
     document or a macro package such as [4mme[24m, [4mmm[24m, [4mmom[24m, or [4mms[24m to produce a format‐
     ted reference for each citation.  A citation's reference can be output  im‐
     mediately  after  it  occurs (as with footnotes), or references may [4maccumu‐[0m
     [4mlate[24m, with corresponding output appearing later in the  document  (as  with
     endnotes).  When references accumulate, multiple citations of the same ref‐
     erence produce a single formatted entry.

     Interpretation of lines between [1m.R1 [22mand [1m.R2 [22mtokens as preprocessor commands
     is  a  GNU  [4mrefer[24m extension.  Documents employing this feature can still be
     processed by AT&T [4mrefer[24m by adding the lines
            .de R1
            .ig R2
            ..
     to the beginning of the document.  The foregoing input causes [4mtroff[24m to  ig‐
     nore  everything  between  [1m.R1 [22mand [1m.R2[22m.  The effects of some [4mrefer[24m commands
     can be achieved by command-line options; these are supported  for  compati‐
     bility with AT&T [4mrefer[24m.  It is usually more convenient to use commands.

   [1mBibliographic records[0m
     A  bibliographic  record  describes  a referenced work in sufficient detail
     that it may be cited to accepted standards of  scholarly  and  professional
     clarity.   The  record format permits annotation and extension that a docu‐
     ment may use or ignore.  A record is a plain text sequence of  [4mfields,[24m  one
     per  line,  each  consisting of a percent sign [1m%[22m, an alphanumeric character
     classifying it, one space, and its contents.  If  a  field's  contents  are
     empty, the field is ignored.

     Frequently,  such records are organized into a [4mbibliographic[24m [4mdatabase,[24m with
     each entry separated by blank lines or file boundaries.  This practice  re‐
     lieves  documents  of  the  need to maintain bibliographic data themselves.
     The programs ]8;;man:lookbib(1)\[4mlookbib[24m(1)]8;;\ and ]8;;man:lkbib(1)\[4mlkbib[24m(1)]8;;\ consult a bibliographic database,  and
     ]8;;man:indxbib(1)\[4mindxbib[24m(1)]8;;\  indexes  one to speed retrieval from it, reducing document pro‐
     cessing time.  Use of these tools is optional.

     The conventional uses of the bibliographic field entries  are  as  follows.
     Within  a  record, fields other than [1m%A [22mand [1m%E [22mreplace previous occurrences
     thereof.  The ordering of multiple [1m%A [22mand [1m%E [22mfields is significant.

     [1m%A     [22mnames an author.  If the name contains a suffix  such  as  “Jr.”  or
            “III”,  it should be separated from the surname by a comma.  We rec‐
            ommend always supplying an [1m%A [22mfield or a [1m%Q [22mfield.

     [1m%B     [22mrecords the title of the book within which a cited article  is  col‐
            lected.  See [1m%J [22mand [1m%T[22m.

     [1m%C     [22mnames the city or other place of publication.

     [1m%D     [22mindicates  the  date  of publication.  Specify the year in full.  If
            the month is specified, use its name rather than  its  number;  only
            the first three letters are required.  We recommend always supplying
            a  [1m%D  [22mfield; if the date is unknown, use “[1min press[22m” or “[1munknown[22m” as
            its contents.

     [1m%E     [22mnames an editor of the book within which a  cited  article  is  col‐
            lected.   Where  a work has editors but no authors, name the editors
            in [1m%A [22mfields and append “[1m, (ed.)[22m” or  “[1m,  (eds.)[22m”  to  the  last  of
            these.

     [1m%G     [22mrecords  the  U.S.  government  ordering number, ISBN, DOI, or other
            unique identifier.

     [1m%I     [22mnames the publisher (issuer).

     [1m%J     [22mrecords the name of the journal within which a cited article is col‐
            lected.  See [1m%B [22mand [1m%T[22m.

     [1m%K     [22mlists keywords intended to aid searches.

     [1m%L     [22mis a label; typically unused in database entries,  it  can  override
            the label format otherwise determined.

     [1m%N     [22mrecords the issue number of the journal within which a cited article
            is collected.

     [1m%O     [22mpresents  additional  (“other”) information, typically placed at the
            end of the reference.

     [1m%P     [22mlists the page numbers of a cited work that is part of a larger col‐
            lection.  Specify a range with [4mm[24m[1m-[4m[22mn[24m.

     [1m%Q     [22mnames an institutional author when no [1m%A [22mfields are  present.   Only
            one [1m%Q [22mfield is permitted.

     [1m%R     [22mis  an  identifier for a report, thesis, memorandum, or other unpub‐
            lished work.

     [1m%S     [22mrecords the title of a series to which the cited work belongs.

     [1m%T     [22mis the work's title.  See [1m%B [22mand [1m%J[22m.

     [1m%V     [22mis the volume number of the journal or  book  containing  the  cited
            work.

     [1m%X     [22mis  an annotation.  By convention, it is not formatted in the citing
            document.

     If the obsolescent “accent strings” feature of the [4mms[24m or [4mme[24m macro  packages
     is  used,  such  strings  should follow the character to be accented; an [4mms[0m
     document must call the [1mAM [22mmacro before using them.   Do  not  quote  accent
     strings:  use  one  [1m\  [22mrather than two.  See ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\ for a modern ap‐
     proach to the problem of diacritics.

   [1mCitations[0m
     Citations have a characteristic format.
            [1m.[[4m[22mopening-text[0m
            [4mflags[24m [4mkeyword[24m ...
            [4mfield[0m
            ...
            [1m.][4m[22mclosing-text[0m

     [4mopening-text[24m, [4mclosing-text[24m, and [4mflags[24m are optional, and only one [4mkeyword[24m or
     [4mfield[24m need be specified.  If keywords are present, [4mrefer[24m searches the  bib‐
     liographic  database(s)  for  a  unique  reference matching them.  Multiple
     matches are an error; add more keywords to disambiguate the reference.   In
     the  absence of keywords, [4mfields[24m constitute the bibliographic record.  Oth‐
     erwise, [4mfields[24m specify additional data to replace or  supplement  those  in
     the  reference.  When references are accumulating and keywords are present,
     specify additional [4mfields[24m at most on the first  citation  of  a  particular
     reference; they apply to all further citations thereof.

     [4mopening-text[24m  and  [4mclosing-text[24m  are  [4mroff[24m input used to bracket the label,
     overriding the [1mbracket-label [22mcommand.  Leading and trailing spaces are sig‐
     nificant.  If either of these is non-empty, the corresponding  argument  to
     the [1mbracket-label [22mcommand is not used; alter this behavior with the [1m[ [22mand [1m][0m
     [4mflags.[0m

     [4mflags[24m  is  a list of non-alphanumeric characters each of which modifies the
     treatment of the particular citation.  AT&T [4mrefer[24m ignores them  since  they
     are non-alphanumeric.  They direct GNU [4mrefer[24m as follows.

     [1m#      [22mUse  the  label specified by the [1mshort-label [22mcommand, if any.  [4mrefer[0m
            otherwise uses the normal label.  Typically, a  short  label  imple‐
            ments  author-date citation styles consisting of a name, a year, and
            a disambiguating letter if necessary.  “[1m#[22m” is meant to suggest  such
            a (quasi-)numeric label.

     [1m[      [22mPrecede   [4mopening-text[24m   with   the  first  argument  given  to  the
            [1mbracket-label [22mcommand.

     [1m]      [22mFollow  [4mclosing-text[24m  with  the  second  argument   given   to   the
            [1mbracket-label [22mcommand.

     An advantage of the [1m[ [22mand [1m] [22mflags over use of [4mopening-text[24m and [4mclosing-text[0m
     is  that  you can update the document's bracketing style in one place using
     the [1mbracket-label [22mcommand.  Another is that sorting and  merging  of  cita‐
     tions is not necessarily inhibited if the flags are used.

     [4mrefer[24m  appends  any  label resulting from a citation to the [4mroff[24m input line
     preceding the [1m.[ [22mtoken.  If there is no such line, [4mrefer[24m issues  a  warning
     diagnostic.

     There is no special notation for citing multiple references in series.  Use
     a sequence of citations, one for each reference, with nothing between them.
     [4mrefer[24m  attaches all of their labels to the line preceding the first.  These
     labels may be sorted or merged.  See the description of the  [1m<>  [22mlabel  ex‐
     pression,  and of the [1msort-adjacent-labels [22mand [1mabbreviate-label-ranges [22mcom‐
     mands.  A label is not merged if its citation has a non-empty  [4mopening-text[0m
     or  [4mclosing-text[24m.  However, the labels for two adjacent citations, the for‐
     mer using the [1m] [22mflag and without any [4mclosing-text,[24m and the latter using the
     [1m[ [22mflag and without any [4mopening-text,[24m may be sorted and merged even  if  the
     former's  [4mopening-text[24m or the latter's [4mclosing-text[24m is non-empty.  (To pre‐
     vent these operations, use the dummy character escape sequence  [1m\&  [22mas  the
     former's [4mclosing-text[24m.)

   [1mCommands[0m
     Commands are contained between lines starting with [1m.R1 [22mand [1m.R2[22m.  The [1m-R [22mop‐
     tion  prevents  recognition  of  these  lines.  When [4mrefer[24m encounters a [1m.R1[0m
     line, it flushes any accumulated references.  Neither [1m.R1  [22mnor  [1m.R2  [22mlines,
     nor anything between them, is output.

     Commands are separated by newlines or semicolons.  A number sign ([1m#[22m) intro‐
     duces  a  comment that extends to the end of the line, but does not conceal
     the newline.  Each command is broken up into words.  Words are separated by
     spaces or tabs.  A word that begins with a (neutral) double quote  ([1m"[22m)  ex‐
     tends  to  the  next  double  quote  that is not followed by another double
     quote.  If there is no such double quote, the word extends to  the  end  of
     the  line.   Pairs of double quotes in a word beginning with a double quote
     collapse to one double quote.  Neither a number sign  nor  a  semicolon  is
     recognized inside double quotes.  A line can be continued by ending it with
     a backslash “[1m\[22m”; this works everywhere except after a number sign.

     Each  command [4mname[24m that is marked with * has an associated negative command
     [1mno-[4m[22mname[24m that undoes the effect of [4mname[24m.  For example, the  [1mno-sort  [22mcommand
     specifies that references should not be sorted.  The negative commands take
     no arguments.

     In  the following description each argument must be a single word; [4mfield[24m is
     used for a single upper or lower case letter naming a field; [4mfields[24m is used
     for a sequence of such letters; [4mm[24m and [4mn[24m are used for  a  non-negative  num‐
     bers;  [4mstring[24m is used for an arbitrary string; [4mfile[24m is used for the name of
     a file.

     [1mabbreviate[22m* [4mfields[24m [4mstring1[24m [4mstring2[24m [4mstring3[24m [4mstring4[0m
            Abbreviate the first names of [4mfields[24m.  An  initial  letter  will  be
            separated  from  another initial letter by [4mstring1[24m, from the surname
            by [4mstring2[24m, and from anything  else  (such  as  “von”  or  “de”)  by
            [4mstring3[24m.   These  default to a period followed by a space.  In a hy‐
            phenated first name, the initial of the first part of the name  will
            be  separated from the hyphen by [4mstring4[24m; this defaults to a period.
            No attempt is made to handle any ambiguities that might result  from
            abbreviation.  Names are abbreviated before sorting and before label
            construction.

     [1mabbreviate-label-ranges[22m* [4mstring[0m
            Three  or  more adjacent labels that refer to consecutive references
            will be abbreviated to a label consisting of the first  label,  fol‐
            lowed  by [4mstring[24m, followed by the last label.  This is mainly useful
            with numeric labels.  If [4mstring[24m is omitted, it defaults to “[1m-[22m”.

     [1maccumulate[22m*
            Accumulate references instead of writing out each reference as it is
            encountered.  Accumulated references will be written out whenever  a
            reference of the form
                   [1m.[[0m
                   [1m$LIST$[0m
                   [1m.][0m
            is encountered, after all input files have been processed, and when‐
            ever a [1m.R1 [22mline is recognized.

     [1mannotate[22m* [4mfield[24m [4mstring[0m
            [4mfield[24m  is  an  annotation; print it at the end of the reference as a
            paragraph preceded by the line

                   [1m.[4m[22mstring[0m

            If [4mstring[24m is omitted, it will default to [1mAP[22m; if [4mfield[24m is also  omit‐
            ted it will default to [1mX[22m.  Only one field can be an annotation.

     [1marticles [4m[22mstring[24m ...
            Each  [4mstring[24m  is a definite or indefinite article, and should be ig‐
            nored at the beginning of [1mT [22mfields when  sorting.   Initially,  “a”,
            “an”, and “the” are recognized as articles.

     [1mbibliography [4m[22mfile[24m ...
            Write  out  all the references contained in each bibliographic data‐
            base [4mfile[24m.  This command should come last in an [1m.R1[22m/[1m.R2 [22mblock.

     [1mbracket-label [4m[22mstring1[24m [4mstring2[24m [4mstring3[0m
            In the text, bracket each label with [4mstring1[24m and [4mstring2[24m.  An occur‐
            rence of [4mstring2[24m immediately followed by [4mstring1[24m will be turned into
            [4mstring3[24m.  The default behavior is as follows.
                   bracket-label \*([. \*(.] ", "

     [1mcapitalize [4m[22mfields[0m
            Convert [4mfields[24m to caps and small caps.

     [1mcompatible[22m*
            Recognize [1m.R1 [22mand [1m.R2 [22meven when followed by a character  other  than
            space or newline.

     [1mdatabase [4m[22mfile[24m ...
            Search each bibliographic database [4mfile[24m.  For each [4mfile[24m, if an index
            file[4m.i[24m  created  by  ]8;;man:indxbib(1)\[4mindxbib[24m(1)]8;;\ exists, then it will be searched in‐
            stead; each index can cover multiple databases.

     [1mdate-as-label[22m* [4mstring[0m
            [4mstring[24m is a label expression that specifies a string with  which  to
            replace  the  [1mD  [22mfield after constructing the label.  See subsection
            “Label expressions” below for a description  of  label  expressions.
            This  command  is  useful  if you do not want explicit labels in the
            reference list, but instead want to handle any necessary disambigua‐
            tion by qualifying the date in some way.  The label used in the text
            would typically be some combination of the author and date.  In most
            cases you should also use the  [1mno-label-in-reference  [22mcommand.   For
            example,
                   date-as-label D.+yD.y%a*D.-y
            would attach a disambiguating letter to the year part of the [1mD [22mfield
            in the reference.

     [1mdefault-database[22m*
            The default database should be searched.  This is the default behav‐
            ior,  so the negative version of this command is more useful.  [4mrefer[0m
            determines whether the default database should be  searched  on  the
            first   occasion   that   it   needs   to   do  a  search.   Thus  a
            [1mno-default-database [22mcommand must be given before then, in  order  to
            be effective.

     [1mdiscard[22m* [4mfields[0m
            When  the  reference  is read, [4mfields[24m should be discarded; no string
            definitions for [4mfields[24m will be output.  Initially, [4mfields[24m are [1mXYZ[22m.

     [1met-al[22m* [4mstring[24m [4mm[24m [4mn[0m
            Configure use of “[1met al[22m” in the evaluation of [1m@ [22mexpressions in label
            expressions.  If [4mu[24m is the number of authors needed to make  the  au‐
            thor sequence unambiguous and the total number of authors is [4mt,[24m then
            the last [4mt[24m-[4mu[24m authors will be replaced by [4mstring[24m provided that [4mt[24m-[4mu[24m is
            not  less  than [4mm[24m and [4mt[24m is not less than [4mn[24m.  The default behavior is
            as follows.
                   et-al " et al" 2 3
            Note the absence of a dot from the end of the abbreviation, which is
            arguably not correct.  ([4mEt[24m [4mal[24m[.]  is short for [4met[24m [4malli[24m, as  [4metc.[24m  is
            short for [4met[24m [4mcetera[24m.)

     [1minclude [4m[22mfile[0m
            Include [4mfile[24m and interpret the contents as commands.

     [1mjoin-authors [4m[22mstring1[24m [4mstring2[24m [4mstring3[0m
            Join multiple authors together with [4mstring[24ms.  When there are exactly
            two  authors, they will be joined with [4mstring1[24m.  When there are more
            than two authors, all but the last two will be joined with  [4mstring2[24m,
            and the last two authors will be joined with [4mstring3[24m.  If [4mstring3[24m is
            omitted,  it  will default to [4mstring1[24m; if [4mstring2[24m is also omitted it
            will also default to [4mstring1[24m.  For example,
                   join-authors " and " ", " ", and "
            will restore the default method for joining authors.

     [1mlabel-in-reference[22m*
            When outputting the reference, define the string [1m[F [22mto be the refer‐
            ence's label.  This is the default behavior, so the negative version
            of this command is more useful.

     [1mlabel-in-text[22m*
            For each reference output a label in the text.  The  label  will  be
            separated   from   the   surrounding   text   as  described  in  the
            [1mbracket-label [22mcommand.  This is the default behavior, so  the  nega‐
            tive version of this command is more useful.

     [1mlabel [4m[22mstring[0m
            [4mstring[24m is a label expression describing how to label each reference.

     [1mseparate-label-second-parts [4m[22mstring[0m
            When merging two-part labels, separate the second part of the second
            label  from the first label with [4mstring[24m.  See the description of the
            [1m<> [22mlabel expression.

     [1mmove-punctuation[22m*
            In the text, move any punctuation at the end of line past the label.
            We recommend employing this command  unless  you  are  using  super‐
            scripted numbers as labels.

     [1mreverse[22m* [4mstring[0m
            Reverse  the  fields whose names are in [4mstring[24m.  An optional integer
            after a field name limits the number of such  fields  to  the  given
            count; no integer means no limit.

     [1msearch-ignore[22m* [4mfields[0m
            While searching for keys in databases for which no index exists, ig‐
            nore the contents of [4mfields[24m.  Initially, fields [1mXYZ [22mare ignored.

     [1msearch-truncate[22m* [4mn[0m
            Only  require the first [4mn[24m characters of keys to be given.  In effect
            when searching for a given key words in the database  are  truncated
            to the maximum of [4mn[24m and the length of the key.  Initially, [4mn[24m is 6.

     [1mshort-label[22m* [4mstring[0m
            [4mstring[24m  is a label expression that specifies an alternative (usually
            shorter) style of label.  This is used when the [1m# [22mflag is  given  in
            the  citation.  When using author-date style labels, the identity of
            the author or authors is sometimes clear from the context, and so it
            may be desirable to omit the author or authors from the label.   The
            [1mshort-label  [22mcommand  will typically be used to specify a label con‐
            taining just a date and possibly a disambiguating letter.

     [1msort[22m* [4mstring[0m
            Sort references according to [4mstring[24m.  References will  automatically
            be  accumulated.   [4mstring[24m should be a list of field names, each fol‐
            lowed by a number, indicating how many fields with the  name  should
            be  used  for  sorting.   “[1m+[22m”  can  be used to indicate that all the
            fields with the name should be used.  Also [1m. [22mcan be used to indicate
            the references should be sorted using the (tentative) label.   (Sub‐
            section  “Label expressions” below describes the concept of a tenta‐
            tive label.)

     [1msort-adjacent-labels[22m*
            Sort labels that are adjacent in the text according to  their  posi‐
            tion in the reference list.  This command should usually be given if
            the  [1mabbreviate-label-ranges [22mcommand has been given, or if the label
            expression contains a [1m<> [22mexpression.  This has no effect unless ref‐
            erences are being accumulated.

   [1mLabel expressions[0m
     Label expressions can be evaluated both normally and tentatively.  The  re‐
     sult  of  normal  evaluation  is  used for output.  The result of tentative
     evaluation, called the [4mtentative[24m [4mlabel[24m, is used to gather  the  information
     that  normal evaluation needs to disambiguate the label.  Label expressions
     specified by the [1mdate-as-label [22mand [1mshort-label [22mcommands are  not  evaluated
     tentatively.  Normal and tentative evaluation are the same for all types of
     expression  other  than [1m@[22m, [1m*[22m, and [1m% [22mexpressions.  The description below ap‐
     plies to normal evaluation, except where otherwise specified.

     [4mfield[24m [[4mn[24m]
             is the [4mn[24mth part of [4mfield[24m.  If [4mn[24m is omitted, it defaults to 1.

     [1m'[4m[22mstring[24m[1m'[0m
             The characters in [4mstring[24m literally.

     [1m@       [22mAll authors joined as specified by the [1mjoin-authors  [22mcommand.   The
             whole  of  each  author's name is used.  However, if the references
             are sorted by author (that is, the sort specification  starts  with
             “[1mA+[22m”),  then  authors' surnames will be used instead, provided that
             this does not introduce ambiguity, and also an initial  subsequence
             of  the  authors may be used instead of all the authors, again pro‐
             vided that this does not introduce ambiguity.  Given any two refer‐
             enced works with [4mn[24m authors, the use of only the surname for the [4mn[24mth
             author of a reference is regarded as ambiguous if the other  refer‐
             ence  shares  the first [4mn[24m-1 authors, the [4mn[24mth authors of each refer‐
             ence are not identical, but the [4mn[24mth authors' surnames [4mare[24m the same.
             A proper initial subsequence of the sequence of  authors  for  some
             reference  is  considered  to  be ambiguous if there is a reference
             with some other sequence of authors which also has that subsequence
             as a proper initial subsequence.  When an  initial  subsequence  of
             authors  is  used, the remaining authors are replaced by the string
             specified by the [1met-al [22mcommand; this command may also specify addi‐
             tional requirements that must be met before an initial  subsequence
             can be used.  [1m@ [22mtentatively evaluates to a canonical representation
             of  the authors, such that authors that compare equally for sorting
             purposes have the same representation.

     [1m%[4m[22mn[0m
     [1m%a[0m
     [1m%A[0m
     [1m%i[0m
     [1m%I      [22mThe serial number of the reference formatted according to the char‐
             acter following the [1m%[22m.  The serial number of a reference is 1  plus
             the  number of earlier references with same tentative label as this
             reference.  These expressions  tentatively  evaluate  to  an  empty
             string.

     [4mexpr[24m[1m*   [22mIf there is another reference with the same tentative label as this
             reference,  then  [4mexpr[24m,  otherwise an empty string.  It tentatively
             evaluates to an empty string.

     [4mexpr[24m[1m+[4m[22mn[0m
     [4mexpr[24m[1m-[4m[22mn[24m  The first ([1m+[22m) or last ([1m-[22m) [4mn[24m upper or lower case letters  or  digits
             of  [4mexpr[24m.  [4mroff[24m special characters (such as [1m\('a[22m) count as a single
             letter.  Accent strings are retained but do not  count  toward  the
             total.

     [4mexpr[24m[1m.l  [4m[22mexpr[24m converted to lowercase.

     [4mexpr[24m[1m.u  [4m[22mexpr[24m converted to uppercase.

     [4mexpr[24m[1m.c  [4m[22mexpr[24m converted to caps and small caps.

     [4mexpr[24m[1m.r  [4m[22mexpr[24m reversed so that the surname is first.

     [4mexpr[24m[1m.a  [4m[22mexpr[24m  with  first  names  abbreviated.   Fields  specified  in  the
             [1mabbreviate [22mcommand are abbreviated before any labels are evaluated.
             Thus [1m.a [22mis useful only when you want a field to be abbreviated in a
             label but not in a reference.

     [4mexpr[24m[1m.y  [22mThe year part of [4mexpr[24m.

     [4mexpr[24m[1m.+y[0m
             The part of [4mexpr[24m before the year, or the whole of [4mexpr[24m if  it  does
             not contain a year.

     [4mexpr[24m[1m.-y[0m
             The  part  of  [4mexpr[24m after the year, or an empty string if [4mexpr[24m does
             not contain a year.

     [4mexpr[24m[1m.n  [22mThe surname part of [4mexpr[24m.

     [4mexpr1[24m[1m~[4m[22mexpr2[0m
             [4mexpr1[24m except that if the last character of [4mexpr1[24m is [1m- [22mthen it  will
             be replaced by [4mexpr2[24m.

     [4mexpr1[24m [4mexpr2[0m
             The catenation of [4mexpr1[24m and [4mexpr2[24m.

     [4mexpr1[24m[1m|[4m[22mexpr2[0m
             If [4mexpr1[24m is non-empty then [4mexpr1[24m otherwise [4mexpr2[24m.

     [4mexpr1[24m[1m&[4m[22mexpr2[0m
             If [4mexpr1[24m is non-empty then [4mexpr2[24m otherwise an empty string.

     [4mexpr1[24m[1m?[4m[22mexpr2[24m[1m:[4m[22mexpr3[0m
             If [4mexpr1[24m is non-empty then [4mexpr2[24m otherwise [4mexpr3[24m.

     [1m<[4m[22mexpr[24m[1m>  [22mThe  label is in two parts, which are separated by [4mexpr[24m.  Two adja‐
             cent two-part labels which have the same first part will be  merged
             by appending the second part of the second label onto the first la‐
             bel     separated     by    the    string    specified    in    the
             [1mseparate-label-second-parts [22mcommand (initially, a comma followed by
             a space); the resulting label will also be a  two-part  label  with
             the same first part as before merging, and so additional labels can
             be  merged  into  it.   It  is permissible for the first part to be
             empty;  this  may  be  desirable  for  expressions  used   in   the
             [1mshort-label [22mcommand.

     [1m([4m[22mexpr[24m[1m)  [22mThe same as [4mexpr[24m.  Used for grouping.

     The  above expressions are listed in order of precedence (highest first); [1m&[0m
     and [1m| [22mhave the same precedence.

   [1mMacro interface[0m
     Each reference starts with a call to the macro [1m]-[22m.  The string [1m[F  [22mwill  be
     defined    to    be    the   label   for   this   reference,   unless   the
     [1mno-label-in-reference [22mcommand has been given.  There then follows a  series
     of  string  definitions, one for each field: string [1m[[4m[22mX[24m corresponds to field
     [4mX[24m.  The register [1m[P [22mis set to 1 if the [1mP [22mfield contains a range  of  pages.
     The [1m[T[22m, [1m[A [22mand [1m[O [22mregisters are set to 1 according as the [1mT[22m, [1mA [22mand [1mO [22mfields
     end  with  any of [1m.?! [22m(an end-of-sentence character).  The [1m[E [22mregister will
     be set to 1 if the [1m[E [22mstring contains more than one name.  The reference is
     followed by a call to the [1m][ [22mmacro.  The first argument to this macro gives
     a number representing the type of the reference.  If a reference contains a
     [1mJ [22mfield, it will be classified as type 1, otherwise  if  it  contains  a  [1mB[0m
     field,  it  will be type 3, otherwise if it contains a [1mG [22mor [1mR [22mfield it will
     be type 4, otherwise if it contains an [1mI [22mfield it will be type 2, otherwise
     it will be type 0.  The second argument is a symbolic name  for  the  type:
     [1mother[22m,  [1mjournal-article[22m,  [1mbook[22m, [1marticle-in-book[22m, or [1mtech-report[22m.  Groups of
     references that have been accumulated or are produced by  the  [1mbibliography[0m
     command  are  preceded  by a call to the [1m]< [22mmacro and followed by a call to
     the [1m]> [22mmacro.

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

     [1m-R     [22mDon't recognize lines beginning with [1m.R1[22m/[1m.R2[22m.

     Other options are equivalent to [4mrefer[24m commands.

     [1m-a [4m[22mn[24m            [1mreverse A[4m[22mn[0m

     [1m-b              no-label-in-text; no-label-in-reference[0m

     [1m-B              [22mSee below.

     [1m-c [4m[22mfields[24m       [1mcapitalize [4m[22mfields[0m

     [1m-C              compatible[0m

     [1m-e              accumulate[0m

     [1m-f [4m[22mn[24m            [1mlabel %[4m[22mn[0m

     [1m-i [4m[22mfields[24m       [1msearch-ignore [4m[22mfields[0m

     [1m-k              label L~%a[0m

     [1m-k [4m[22mfield[24m        [1mlabel [4m[22mfield[24m[1m~%a[0m

     [1m-l              label A.nD.y%a[0m

     [1m-l [4m[22mm[24m            [1mlabel A.n+[4m[22mm[24m[1mD.y%a[0m

     [1m-l ,[4m[22mn[24m           [1mlabel A.nD.y-[4m[22mn[24m[1m%a[0m

     [1m-l [4m[22mm[24m[1m,[4m[22mn[24m          [1mlabel A.n+[4m[22mm[24m[1mD.y-[4m[22mn[24m[1m%a[0m

     [1m-n              no-default-database[0m

     [1m-p [4m[22mdb-file[24m      [1mdatabase [4m[22mdb-file[0m

     [1m-P              move-punctuation[0m

     [1m-s [4m[22mspec[24m         [1msort [4m[22mspec[0m

     [1m-S              label "(A.n|Q) ', ' (D.y|D)"; bracket-label " (" ) "; "[0m

     [1m-t [4m[22mn[24m            [1msearch-truncate [4m[22mn[0m

     The [1mB [22moption has command equivalents with the addition that the file  names
     specified  on  the  command line are processed as if they were arguments to
     the [1mbibliography [22mcommand instead of in the normal way.

     [1m-B              annotate X AP; no-label-in-reference[0m

     [1m-B [4m[22mfield[24m[1m.[4m[22mmacro[24m  [1mannotate [4m[22mfield[24m [4mmacro[24m[1m; no-label-in-reference[0m

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

[1mEnvironment[0m
     [4mREFER[24m    Assign this variable a file name to override the default database.

[1mFiles[0m
     [4m/usr/dict/papers/Ind[0m
            Default database.

     file[4m.i[0m
            Index files.

     [4m/usr/share/groff/1.24.0/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.0                       2025-11-10                           [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.0                       2025-06-22                          [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 sarting 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.0                       2026-02-07                             [4mtbl[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mtfmtodit[24m(1)                  General Commands Manual                 [4mtfmtodit[24m(1)

[1mName[0m
     tfmtodit - adapt TeX Font Metrics files for use with [4mgroff[24m and [4mgrodvi[0m

[1mSynopsis[0m
     [1mtfmtodit [22m[[1m-s[22m] [[1m-g [4m[22mgf-file[24m] [[1m-k [4m[22mskew-char[24m] [4mtfm-file[24m [4mmap-file[24m [4mfont-[0m
              [4mdescription[0m

     [1mtfmtodit --help[0m

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

[1mDescription[0m
     [4mtfmtodit[24m creates a font description file for use with ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\'s [1mdvi [22moutput
     device.  [4mtfm-file[24m is the name of the TeX font metric  file  for  the  font.
     [4mmap-file[24m  assigns  [4mgroff[24m ordinary or special character identifiers to glyph
     indices in the font; it should consist of a sequence of lines of the form
            [4mi[24m [4mc1[24m ... [4mcn[0m
     where [4mi[24m is a position of the glyph in the font in decimal, and  [4mc1[24m  through
     [4mcn[24m are glyph identifiers in the form used by [4mgroff[24m font descriptions.  If a
     glyph  has  no  [4mgroff[24m  names but exists in [4mtfm-file,[24m it is put in the [4mgroff[0m
     font  description  file  as  an  unnamed  glyph.   Output  is  written   in
     ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\  format  to  [4mfont-description,[24m  a file named for the intended
     [4mgroff[24m font name.

     If the font is “special”, meaning that [4mgroff[24m should search  it  whenever  a
     glyph is not found in the current font, use the [1m-s [22moption and name [4mfont-de‐[0m
     [4mscription[24m in the [1mfonts [22mdirective in the output device's [4mDESC[24m file.

     To  do  a good job of math typesetting, [4mgroff[24m requires font metric informa‐
     tion not present in [4mtfm-file.[24m  This is because TeX has separate math italic
     fonts, whereas [4mgroff[24m uses normal italic fonts for math.  The additional in‐
     formation required by [4mgroff[24m is given by the two arguments to  the  [1mmath_fit[0m
     macro  in  the  Metafont programs for the Computer Modern fonts.  In a text
     font (a font for which [1mmath_fit [22mis false), Metafont normally ignores  these
     two  arguments.   Metafont  can be made to put this information into the GF
     (“generic font”) files it produces by loading the following definition  af‐
     ter [1mcmbase [22mwhen creating [4mcm.base[24m.
            def ignore_math_fit(expr left_adjustment,right_adjustment) =
                special "adjustment";
                numspecial left_adjustment*16/designsize;
                numspecial right_adjustment*16/designsize;
                enddef;
     For  the  EC  font family, load the following definition after [1mexbase[22m; con‐
     sider patching [4mexbase.mf[24m locally.
            def ignore_math_fit(expr left_adjustment,right_adjustment) =
                ori_special "adjustment";
                ori_numspecial left_adjustment*16/designsize;
                ori_numspecial right_adjustment*16/designsize;
                enddef;
     The only difference from the previous example is the “ori_” prefix to “spe‐
     cial” and “numspecial”.  The GF file created using this modified [4mcm.base[24m or
     [4mexbase.mf[24m should be specified with the [1m-g [22moption, which should [4mnot[24m be given
     for a font for which [1mmath_fit [22mis true.

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

     [1m-g [4m[22mgf-file[0m
            Use the [4mgf-file[24m produced by Metafont containing “[1mspecial[22m” and  “[1mnum‐[0m
            [1mspecial[22m” commands to obtain additional font metric information.

     [1m-k [4m[22mskew-char[0m
            The skew character of this font is at position [4mskew-char.[24m  [4mskew-char[0m
            should  be  an integer; it may be given in decimal, with a leading 0
            in octal, or with a leading 0x in hexadecimal.  Any kerns whose sec‐
            ond component is [4mskew-char[24m are ignored.

     [1m-s     [22mAdd the [1mspecial [22mdirective to the font description file.

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

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

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

     [4m/usr/share/groff/1.24.0/font/devdvi/generate/ec.map[0m
     [4m/usr/share/groff/1.24.0/font/devdvi/generate/msam.map[0m
     [4m/usr/share/groff/1.24.0/font/devdvi/generate/msbm.map[0m
     [4m/usr/share/groff/1.24.0/font/devdvi/generate/tc.map[0m
     [4m/usr/share/groff/1.24.0/font/devdvi/generate/texb.map[0m
     [4m/usr/share/groff/1.24.0/font/devdvi/generate/texex.map[0m
     [4m/usr/share/groff/1.24.0/font/devdvi/generate/texi.map[0m
     [4m/usr/share/groff/1.24.0/font/devdvi/generate/texitt.map[0m
     [4m/usr/share/groff/1.24.0/font/devdvi/generate/texmi.map[0m
     [4m/usr/share/groff/1.24.0/font/devdvi/generate/texr.map[0m
     [4m/usr/share/groff/1.24.0/font/devdvi/generate/texsy.map[0m
     [4m/usr/share/groff/1.24.0/font/devdvi/generate/textex.map[0m
     [4m/usr/share/groff/1.24.0/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.0                       2024-10-18                        [4mtfmtodit[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mtroff[24m(1)                     General Commands Manual                    [4mtroff[24m(1)

[1mName[0m
     troff - GNU [4mroff[24m typesetter and document formatter

[1mSynopsis[0m
     [1mtroff [22m[[1m-abcCEiRSUz[22m] [[1m-d [4m[22mctext[24m] [[1m-d [4m[22mstring[24m[1m=[4m[22mtext[24m] [[1m-f [4m[22mfont-family[24m] [[1m-F [4m[22mfont-[0m
           [4mdirectory[24m] [[1m-I [4m[22minclusion-directory[24m] [[1m-m [4m[22mmacro-package[24m] [[1m-M [4m[22mmacro-[0m
           [4mdirectory[24m] [[1m-n [4m[22mpage-number[24m] [[1m-o [4m[22mpage-list[24m] [[1m-r [4m[22mcnumeric-expression[24m]
           [[1m-r [4m[22mregister[24m[1m=[4m[22mnumeric-expression[24m] [[1m-T [4m[22moutput-device[24m] [[1m-w [4m[22mwarning-[0m
           [4mcategory[24m] [[1m-W [4m[22mwarning-category[24m] [[4mfile[24m ...]

     [1mtroff --help[0m

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

[1mDescription[0m
     GNU  [4mtroff[24m  transforms  ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\ language input into the device-independent
     page description language detailed in ]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\; [4mtroff[24m is thus the heart
     of the GNU [4mroff[24m document  formatting  system.   If  no  [4mfile[24m  operands  are
     present, or if [4mfile[24m is “[1m-[22m”, [4mtroff[24m reads the standard input stream.

     GNU  [4mtroff[24m  is  functionally  compatible with the AT&T [4mtroff[24m typesetter and
     features numerous extensions.  Many people prefer to use the ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\  com‐
     mand,  a  front end which also runs preprocessors and output drivers in the
     appropriate order and with appropriate options.

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

     [1m-a       [22mGenerate  a  plain  text approximation of the typeset output.  The
              read-only register [1m.A [22mis set to 1.  This option produces a sort of
              abstract preview of the formatted output.

              •  Page breaks are marked by a phrase in angle brackets; for exam‐
                 ple, “<beginning of page>”.

              •  Lines are broken where they would be in formatted output.

              •  Vertical motion, apart from that implied by  a  break,  is  not
                 represented.

              •  A  horizontal  motion  of any size is represented as one space.
                 Adjacent horizontal motions are not combined.  Supplemental in‐
                 ter-sentence space (configured by the second  argument  to  the
                 [1m.ss [22mrequest) is not represented.

              •  A special character is rendered as its identifier between angle
                 brackets; for example, a hyphen appears as “<hy>”.

              The  above  description  should not be considered a specification;
              the details of [1m-a [22moutput are subject to change.

     [1m-b       [22mWrite a backtrace reporting the state of [4mtroff[24m's input  parser  to
              the  standard error stream with each diagnostic message.  The line
              numbers given in the backtrace might not always  be  correct,  be‐
              cause  [4mtroff[24m's  idea  of  line numbers can be confused by requests
              that append to macros.

     [1m-c       [22mDisable multi-color output and “[1mcolor[22m” request's ability to enable
              it.

     [1m-C       [22mEnable  AT&T  [4mtroff[24m   compatibility   mode;   implies   [1m-c[22m.    See
              ]8;;man:groff_diff(7)\[4mgroff_diff[24m(7)]8;;\.

     [1m-d [4m[22mctext[0m
     [1m-d [4m[22mstring[24m[1m=[4m[22mtext[0m
              Define [4mroff[24m string [4mc[24m or [4mstring[24m as [4mtext.[24m  [4mc[24m must be a one-character
              identifier;  [4mstring[24m  can be of arbitrary length.  Such assignments
              happen before any macro file  is  loaded,  including  the  startup
              file.   Due to ]8;;man:getopt_long(3)\[4mgetopt_long[24m(3)]8;;\ limitations, [4mc[24m cannot be, and [4mstring[0m
              cannot contain, an equals sign, even though that is a valid  char‐
              acter in a [4mroff[24m identifier.

     [1m-E       [22mInhibit  [4mtroff[24m  error messages; implies [1m-Ww[22m.  This option does [4mnot[0m
              suppress messages sent to the standard error stream  by  documents
              or macro packages using [1mtm [22mor related requests.

     [1m-f [4m[22mfam[24m   Use [4mfam[24m as the default font family.

     [1m-F [4m[22mdir[24m   Search in directory [4mdir[24m for the selected output device's directory
              of  device  and  font  description  files.  See the description of
              [4mGROFF_FONT_PATH[24m in section “Environment”  below  for  the  default
              search locations and ordering.

     [1m-i       [22mRead  the  standard  input stream after all named input files have
              been processed.

     [1m-I [4m[22mdir[24m   Search the directory [4mdir[24m for files (those  named  on  the  command
              line;  in [1mpsbb[22m, [1mso[22m, and [1msoquiet [22mrequests; and in “[1m\X'ps: import'[22m”,
              “[1m\X'ps: file'[22m”, and “[1m\X'pdf: pdfpic'[22m” device extension escape  se‐
              quences).   [1m-I  [22mmay  be  specified  more  than  once;  each [4mdir[24m is
              searched in the given order.  To search the current working direc‐
              tory before others, add “[1m-I .[22m” at the desired place; it is  other‐
              wise  searched last.  [1m-I [22mworks similarly to, and is named for, the
              “include” option of Unix C compilers.

     [1m-m [4m[22mmac[24m   Search for the macro package mac[4m.tmac[24m and read it prior to any in‐
              put.  If not found, [4mtmac.[24mmac is attempted.  See the description of
              [4mGROFF_TMAC_PATH[24m in section “Environment”  below  for  the  default
              search locations and ordering.

     [1m-M [4m[22mdir[24m   Search  directory  [4mdir[24m  for  macro  files.  See the description of
              [4mGROFF_TMAC_PATH[24m in section “Environment”  below  for  the  default
              search locations and ordering.

     [1m-n [4m[22mnum[24m   Begin numbering pages at [4mnum.[24m  The default is [1m1[22m.

     [1m-o [4m[22mlist[24m  Output  only pages in [4mlist,[24m which is a comma-separated list of in‐
              clusive page ranges; [4mn[24m means page [4mn,[24m  [4mm[24m[1m-[4m[22mn[24m  means  every  page  be‐
              tween  [4mm[24m  and  [4mn[24m,  [1m-[4m[22mn[24m means every page up to [4mn[24m, and [4mn[24m[1m- [22mmeans every
              page from [4mn[24m on.  [4mtroff[24m stops processing and exits after formatting
              the last page enumerated in [4mlist.[0m

     [1m-r [4m[22mcnumeric-expression[0m
     [1m-r [4m[22mregister[24m[1m=[4m[22mnumeric-expression[0m
              Define [4mroff[24m register [4mc[24m or [4mregister[24m as [4mnumeric-expression.[24m  [4mc[24m  must
              be  a  one-character  identifier;  [4mregister[24m  can  be  of arbitrary
              length.  Such assignments happen before any macro file is  loaded,
              including  the  startup  file.  Due to ]8;;man:getopt_long(3)\[4mgetopt_long[24m(3)]8;;\ limitations,
              [4mc[24m cannot be, and [4mregister[24m cannot contain,  an  equals  sign,  even
              though that is a valid character in a [4mroff[24m identifier.

     [1m-R       [22mPrevent  loading  of  [4mtroffrc[24m  and [4mtroffrc-end[24m; this option can be
              useful for troubleshooting.

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

     [1m-T [4m[22mdev[24m   Prepare output for device [4mdev.[24m  The default is [1mps[22m; see ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\.

     [1m-U       [22mOperate in [4munsafe[24m [4mmode,[24m enabling the [1mcf[22m, [1mopen[22m, [1mopena[22m, [1mpi[22m, [1mpso[22m, and
              [1msy [22mrequests, which are disabled by default because they  allow  an
              untrusted  input document to run arbitrary commands, put arbitrary
              content into [4mtroff[24m output, or write to arbitrary file names.  (GNU
              [4mtroff[24m does not, however, accept  newlines  (line  feeds)  in  file
              names  supplied  as arguments to requests.)  This option also adds
              the current directory to the macro package search path; see the [1m-m[0m
              and [1m-M [22moptions above.

     [1m-w [4m[22mcat[0m
     [1m-W [4m[22mcat[24m   Enable and inhibit, respectively, warnings in category  [4mcat.[24m   See
              section “Warnings” below.

     [1m-z       [22mSuppress formatted output.

[1mWarnings[0m
     GNU  [4mtroff[24m divides its warning diagnostics into named, numbered categories.
     The [1m-w [22mand [1m-W [22moptions use the associated names.  A power of two  character‐
     izes  each  category;  the [1mwarn [22mrequest and the [1m.warn [22mregister respectively
     set and report the sum of enabled category codes.  Warnings of  each  cate‐
     gory are produced under the following circumstances.

                ┌───────────────────────┬──────────────────────────┐
                │ Bit   Code   Category │ Bit    Code     Category │
                ├───────────────────────┼──────────────────────────┤
                │   0      [4m1[24m   [1mchar     [22m│  10      [4m1024[24m   [1mreg      [22m│
                │   1      [4m2[24m   [4munused[24m   │  11      [4m2048[24m   [1mtab      [22m│
                │   2      [4m4[24m   [1mbreak    [22m│  12      [4m4096[24m   [4munused[24m   │
                │   3      [4m8[24m   [1mdelim    [22m│  13      [4m8192[24m   [1mmissing  [22m│
                │   4     [4m16[24m   [4munused[24m   │  14     [4m16384[24m   [1minput    [22m│
                │   5     [4m32[24m   [1mscale    [22m│  15     [4m32768[24m   [1mescape   [22m│
                │   6     [4m64[24m   [1mrange    [22m│  16     [4m65536[24m   [1mspace    [22m│
                │   7    [4m128[24m   [1msyntax   [22m│  17    [4m131072[24m   [1mfont     [22m│
                │   8    [4m256[24m   [1mdi       [22m│  18    [4m262144[24m   [1mig       [22m│
                │   9    [4m512[24m   [1mmac      [22m│  19    [4m524288[24m   [1mcolor    [22m│
                │                       │  20   [4m1048576[24m   [1mfile     [22m│
                └───────────────────────┴──────────────────────────┘

     [1mbreak           [22m4   A  filled output line could not be broken such that its
                         length was less than or equal to, or adjusted such that
                         its length was exactly equal to, the output line length
                         “[1m\n[.l][22m”.  GNU [4mtroff[24m reports the amount of  overset  or
                         underset   in   the  scaling  unit  configured  by  the
                         [1mwarnscale [22mrequest in [1mtroff [22mmode, and in ens (‘[1mn[22m’; char‐
                         acter cells) in [1mnroff [22mmode.  This category  is  enabled
                         by default.

     [1mchar            [22m1   No  user-defined character of the requested name or in‐
                         dex exists and no mounted font defines a glyph for  it,
                         or  input  could  not be encoded for device-independent
                         output.  This category is enabled by default.

     [1mcolor      [22m524288   An undefined color name was selected,  an  attempt  was
                         made  to  define  a  color  using an unrecognized color
                         space, an invalid channel value in a  color  definition
                         was  encountered,  or an attempt was made to redefine a
                         default color.

     [1mdelim           [22m8   The selected delimiter character was ambiguous  because
                         it  is also meaningful when beginning a numeric expres‐
                         sion, or the closing delimiter in  an  escape  sequence
                         was missing or mismatched.

                         A future [4mgroff[24m release may reject ambiguous delimiters.
                         In  compatibility  mode,  ambiguous  delimiters are ac‐
                         cepted without warning.

     [1mdi            [22m256   A [1mdi[22m, [1mda[22m, [1mbox[22m, or [1mboxa [22mrequest was invoked  without  an
                         argument when there was no current diversion.

     [1mescape      [22m32768   An unsupported escape sequence was encountered.

     [1mfile      [22m1048576   An attempt was made to read a file that does not exist.
                         or a stream remained open at formatter exit.  This cat‐
                         egory is enabled by default.

     [1mfont       [22m131072   A non-existent font was selected.  This category is en‐
                         abled by default.

     [1mig         [22m262144   An  invalid  escape  sequence occurred in input ignored
                         using the [1mig [22mrequest.  This warning category  diagnoses
                         a  condition that is an error when it occurs in non-ig‐
                         nored input.

     [1minput       [22m16384   An invalid character occurred on the input stream.

     [1mmac           [22m512   An undefined string,  macro,  or  diversion  was  used.
                         When  such  an  object is dereferenced, an empty one of
                         that name is automatically created.  So, unless  it  is
                         later  deleted,  [4mtroff[24m  issues  at most one warning for
                         each.

                         [4mtroff[24m also uses this category to warn of an attempt  to
                         move  an  unplanted trap macro.  In such cases, the un‐
                         planted macro is [4mnot[24m dereferenced, so it is not created
                         if it does not exist.

     [1mmissing      [22m8192   A request was invoked with a mandatory argument absent.

     [1mrange          [22m64   A numeric expression was out of range for its context.

     [1mreg          [22m1024   An undefined register was used.  When an undefined reg‐
                         ister is dereferenced, the formatter automatically  de‐
                         fines  it  with  a  value of 0.  So, unless it is later
                         deleted, GNU [4mtroff[24m issues at most one warning for each.

     [1mscale          [22m32   A scaling unit inappropriate to its context was used in
                         a numeric expression.

     [1mspace       [22m65536   A space was missing between a request or macro and  its
                         argument.   This  warning is produced when an undefined
                         name longer than two characters is encountered and  the
                         first  two  characters of the name constitute a defined
                         name.  No request is invoked, no macro called,  and  an
                         empty  macro  is not defined.  This category is enabled
                         by default.  It never occurs in compatibility mode.

     [1msyntax        [22m128   A  self-contradictory  hyphenation  mode  or  character
                         flags  were  requested;  an empty or incomplete numeric
                         expression was encountered; an operand to a numeric op‐
                         erator was missing; an attempt was made to format char‐
                         acters or spaces on an input line after an output  line
                         continuation  escape sequence; a recognized but inappo‐
                         site escape sequence or unprintable character code  was
                         used in a device extension command; an attempt was made
                         to  define a recursive, empty, or nonsensical character
                         class; or a [4mgroff[24m extension escape sequence  or  condi‐
                         tional  expression  operator was used while in compati‐
                         bility mode.

     [1mtab          [22m2048   A tab character appeared in a parameterized escape  se‐
                         quence,  in  an unquoted macro argument, or where a re‐
                         quest expected a numeric expression argument.

     Two warning names group other warning categories for convenience.

     [1mall    [22mAll warning categories except [1mdi[22m, [1mmac[22m, and [1mreg[22m.  This  shorthand  is
            intended to produce all warnings that are useful with macro packages
            and documents written for AT&T [4mtroff[24m and its descendants, which have
            less fastidious diagnostics than GNU [4mtroff[24m.

     [1mw      [22mAll  warning  categories.   Authors  of documents and macro packages
            targeting [4mgroff[24m are encouraged to use this setting.

[1mExit status[0m
     [4mtroff[24m exits with status [1m0 [22mon successful operation, status [1m2 [22mif the  program
     cannot  interpret its command-line arguments, and status [1m1 [22mif it encounters
     a fatal error during operation, or is directed to abort by the input.

[1mEnvironment[0m
     [4mGROFF_FONT_PATH[24m and [4mGROFF_TMAC_PATH[24m each accept a search path  of  directo‐
     ries;  that  is,  a  list of directory names separated by the system's path
     component separator character.  On Unix systems, this character is a  colon
     (:); on Windows systems, it is a semicolon (;).

     [4mGROFF_FONT_PATH[0m
            A  list of directories in which to seek the selected output device's
            directory of device and font description files.  [4mtroff[24m will scan di‐
            rectories given as arguments to  any  specified  [1m-F  [22moptions  before
            these,   then   in   a  site-specific  directory  ([4m/usr/share/groff/[0m
            [4msite-font[24m), a standard location ([4m/usr/share/groff/1.24.0/font[24m),  and
            a compatibility directory ([4m/usr/lib/font[24m) after them.

     [4mGROFF_TMAC_PATH[0m
            A  list  of  directories  in which to search for macro files.  [4mtroff[0m
            will scan directories given as arguments to any specified [1m-M [22moptions
            before these, then the current directory (only if in  unsafe  mode),
            the  user's  home  directory, a site-specific directory ([4m/usr/share/[0m
            [4mgroff/site-tmac[24m), and a standard location  ([4m/usr/share/groff/1.24.0/[0m
            [4mtmac[24m) after them.

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

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

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

[1mFiles[0m
     [4m/usr/share/groff/1.24.0/tmac/troffrc[0m
            is an initialization macro file loaded  before  any  macro  packages
            specified with [1m-m [22moptions.

     [4m/usr/share/groff/1.24.0/tmac/troffrc-end[0m
            is  an  initialization  macro  file  loaded after all macro packages
            specified with [1m-m [22moptions.

     [4m/usr/share/groff/1.24.0/tmac/[24mname[4m.tmac[0m
            are macro files distributed with [4mgroff[24m.

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

     [4m/usr/share/groff/1.24.0/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.0                       2026-02-10                           [4mtroff[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mxtotroff[24m(1)                  General Commands Manual                 [4mxtotroff[24m(1)

[1mName[0m
     xtotroff - convert X font metrics into [4mgroff[24m font metrics

[1mSynopsis[0m
     [1mxtotroff [22m[[1m-d [4m[22mdestination-directory[24m] [[1m-r [4m[22mresolution[24m] [[1m-s [4m[22mtype-size[24m] [4mfont-map[0m

     [1mxtotroff --help[0m

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

[1mDescription[0m
     [4mxtotroff[24m  uses  [4mfont-map[24m to create ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\ font description files from X11
     fonts.  Each line in [4mfont-map[24m pairs a [4mgroff[24m font name with an X  font  name
     as  an  X  Logical Font Description (XLFD) pattern.  The pair's members are
     separated by spaces and/or tabs.  For example, an input [4mfont-map[24m file  con‐
     sisting of the line
            TB -adobe-times-bold-r-normal--*-*-*-*-p-*-iso8859-1
     maps the XLFD on the right to the [4mgroff[24m font name [1mTB[22m, conventionally “Times
     bold”.

     [4mxtotroff[24m opens a connection to the running X server to query its font cata‐
     log, and aborts if it cannot.  If necessary, the wildcards in the XLFD pat‐
     terns are populated with the arguments to the [1m-r [22mand [1m-s [22moptions.  If a font
     name  is  still  ambiguous,  [4mxtotroff[24m aborts.  For each successful mapping,
     [4mxtotroff[24m creates a [4mgroff[24m font description file in the current  working  di‐
     rectory (or that specified by the [1m-d [22moption) named for each [4mgroff[24m font, and
     reports the mapping to the standard output stream.

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

     [1m-d [4m[22mdestination-directory[0m
            Write  font  descriptions  to  [4mdestination-directory[24m rather than the
            current working directory.

     [1m-r [4m[22mresolution[0m
            Set the resolution for all font patterns in [4mfont-map[24m.  The value  is
            used  for  both  the  horizontal and vertical motion quanta.  If not
            specified, a resolution of 75dpi is assumed.

     [1m-s [4m[22mtype-size[0m
            Set the type size in points for all font patterns in  [4mfont-map[24m.   If
            not specified, a size of 10 points is assumed.

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

[1mFiles[0m
     [4m/usr/share/groff/1.24.0/font/FontMap-X11[0m
            is  the font mapping file used to produce the pre-generated font de‐
            scription files, supplied with [4mgroff[24m, of X11 core fonts  correspond‐
            ing to the 13 base Type 1 fonts for PostScript level 1.

[1mBugs[0m
     The only supported font encodings are “iso8859-1” and “adobe-fontspecific”.

[1mSee also[0m
     ]8;;https://www.x.org/releases/X11R7.6/doc/xorg-docs/specs/XLFD/xlfd.html\“X  Logical  Font  Description  Conventions”]8;;\,  by  Jim  Flowers and Stephen
     Gildea.

     ]8;;man:X(7)\[4mX[24m(7)]8;;\, ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, ]8;;man:gxditview(1)\[4mgxditview[24m(1)]8;;\, ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\, ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\

groff 1.24.0                       2024-10-18                        [4mxtotroff[24m(1)
────────────────────────────────────────────────────────────────────────────────
[4mgroff_font[24m(5)                  File Formats Manual                 [4mgroff_font[24m(5)

[1mName[0m
     groff_font - GNU [4mroff[24m device and font description files

[1mDescription[0m
     The [4mgroff[24m font and output device description formats are slight  extensions
     of those used by AT&T device-independent [4mtroff[24m.  In distinction to the AT&T
     implementation,  [4mgroff[24m  lacks  a  binary  format; all files are text files.
     (Plan 9 [4mtroff[24m has also abandoned the binary format.)  The device  and  font
     description files for a device [4mname[24m are stored in a [4mdev[24mname directory.  The
     device description file is called [4mDESC[24m, and, for each font supported by the
     device, a font description file is called [4mf,[24m where [4mf[24m is usually an abbrevi‐
     ation  of a font's name and/or style.  For example, the [1mps [22m(PostScript) de‐
     vice has [4mgroff[24m font  description  files  for  Times  roman  ([1mTR[22m)  and  Zapf
     Chancery  Medium  italic  ([1mZCMI[22m),  among many others, while the [1mutf8 [22mdevice
     (for terminals) has font descriptions for  the  roman,  italic,  bold,  and
     bold-italic styles ([1mR[22m, [1mI[22m, [1mB[22m, and [1mBI[22m, respectively).

     Device  and font description files are read by the formatter, [4mtroff[24m, and by
     output drivers.  The programs typically delegate these files' processing to
     an internal library, [4mlibgroff[24m, ensuring their consistent interpretation.

[4m[1mDESC[24m file format[0m
     The [4mDESC[24m file contains a series of directives; each begins a  line.   Their
     order  is  not  important,  with two exceptions: (1) the [1mres [22mdirective must
     precede any [1mpapersize [22mdirective; and (2) the [1mcharset  [22mdirective  must  come
     last  (if  at  all).  If a directive name is repeated, later entries in the
     file override previous ones (except that the paper dimensions are  computed
     based  on  the  [1mres  [22mdirective  last  seen  when [1mpapersize [22mis encountered).
     Spaces and/or tabs separate words and are ignored at line boundaries.  Com‐
     ments start with the “[1m#[22m” character and extend to the end of a line.   Empty
     lines are ignored.

     [1mfamily [4m[22mfam[0m
             The default font family is [4mfam[24m.

     [1mfonts [4m[22mn[24m [4mF1[24m ... [4mFn[0m
             Fonts [4mF1[24m, ..., [4mFn[24m are mounted at font positions [4mm[24m+1, ..., [4mm[24m+[4mn[24m where
             [4mm[24m  is  the number of [1mstyles [22m(see below).  This directive may extend
             over more than one line.  A font name of [1m0 [22mcauses  no  font  to  be
             mounted at the corresponding position.

     [1mhor [4m[22mn[24m   The  horizontal  motion  quantum is [4mn[24m basic units.  Horizontal mea‐
             surements round to multiples of [4mn.[0m

     [1mimage_generator [4m[22mprogram[0m
             Use [4mprogram[24m to generate PNG images from  PostScript  input.   Under
             GNU/Linux,  this is usually ]8;;man:gs(1)\[4mgs[24m(1)]8;;\, but under other systems (notably
             Cygwin) it might be set to another  name.   The  ]8;;man:grohtml(1)\[4mgrohtml[24m(1)]8;;\  driver
             uses this directive.

     [1mpaperlength [4m[22mn[0m
             The  vertical dimension of the output medium is [4mn[24m basic units (dep‐
             recated: use [1mpapersize [22minstead).

     [1mpapersize [4m[22mformat-or-dimension-pair-or-file-name[24m ...
             The dimensions of the output medium are as according to  the  argu‐
             ment,  which  is  either  a standard paper format, a pair of dimen‐
             sions, or the name of a plain text file containing  either  of  the
             foregoing.   Recognized  paper  formats are the ISO and DIN formats
             [1mA0[22m–[1mA7[22m, [1mB0[22m–[1mB7[22m, [1mC0[22m–[1mC7[22m, and [1mD0[22m–[1mD7[22m; the  U.S.  formats  [1mletter[22m,  [1mlegal[22m,
             [1mtabloid[22m, [1mledger[22m, [1mstatement[22m, and [1mexecutive[22m; and the envelope formats
             [1mcom10[22m,  [1mmonarch[22m,  and [1mDL[22m.  Matching is performed without regard for
             lettercase.

             Alternatively,  the  argument  can  be  a   custom   paper   format
             [4mlength[24m[1m,[4m[22mwidth[24m  (with  no  spaces  before  or after the comma).  Both
             [4mlength[24m and [4mwidth[24m must have a unit appended; valid units are “[1mi[22m” for
             inches, “[1mc[22m” for centimeters, “[1mp[22m” for points,  and  “[1mP[22m”  for  picas.
             Example:  “[1m12c,235p[22m”.   An argument that starts with a digit is al‐
             ways treated as a custom paper format.

             Finally, the argument can be a file name (e.g., [4m/etc/papersize[24m); if
             the file can be opened, the first line is  read  and  a  match  at‐
             tempted against each other form.  No comment syntax is supported.

             More  than  one  argument can be specified; each is scanned in turn
             and the first valid paper specification used.

     [1mpaperwidth [4m[22mn[0m
             The horizontal dimension of the output  medium  is  [4mn[24m  basic  units
             (deprecated: use [1mpapersize [22minstead).

     [1mpass_filenames[0m
             Direct  [4mtroff[24m  to emit the name of the source file being processed.
             This is achieved with the intermediate output command “[1mx F[22m”,  which
             [4mgrohtml[24m interprets.

     [1mpostpro [4m[22mprogram[0m
             Use [4mprogram[24m as the postprocessor.

     [1mprepro [4m[22mprogram[0m
             Use  [4mprogram[24m  as a preprocessor.  The [1mhtml [22mand [1mxhtml [22moutput devices
             use this directive.

     [1mprint [4m[22mprogram[0m
             Use [4mprogram[24m as the print spooler.  If omitted, [4mgroff[24m's  [1m-l  [22mand  [1m-L[0m
             options are ignored.

     [1mres [4m[22mn[24m   The device resolution is [4mn[24m basic units per inch.

     [1msizes [4m[22ms1[24m ... [4msn[24m [1m0[0m
             The device has fonts at [4ms1[24m, ..., [4msn[24m scaled points (see below).  The
             list  of  sizes  must  be terminated by a [1m0[22m.  Each [4msi[24m can also be a
             range of sizes [4mm[24m–[4mn[24m.  The list can extend over more than one line.

     [1msizescale [4m[22mn[0m
             A typographical point is subdivided into [4mn[24m scaled points.  The  de‐
             fault is [1m1[22m.

     [1mstyles [4m[22mS1[24m ... [4mSm[0m
             The  first [4mm[24m font mounting positions are associated with styles [4mS1[24m,
             ..., [4mSm[24m.

     [1mtcommand[0m
             The postprocessor can handle the [1mt [22mand [1mu [22mintermediate  output  com‐
             mands.

     [1municode[0m
             The  output  device supports the complete Unicode repertoire.  This
             directive is useful only for devices which produce character  enti‐
             ties instead of glyphs.

             If  [1municode  [22mis present, no [1mcharset [22msection is required in the font
             description files since the Unicode handling built  into  [4mgroff[24m  is
             used.   However,  if there are entries in a font description file's
             [1mcharset [22msection, they either  override  the  default  mappings  for
             those  particular characters or add new mappings (normally for com‐
             posite characters).

             The [1mutf8[22m, [1mhtml[22m, and [1mxhtml [22moutput devices use this directive.

     [1munitwidth [4m[22mn[0m
             Arbitrary basis with respect to which font metrics are  proportion‐
             ally scaled when rendering glyphs at a type size of one point.

     [1munscaled_charwidths[0m
             Make  the font handling module always return unscaled glyph widths.
             The [4mgrohtml[24m driver uses this directive.

     [1muse_charnames_in_special[0m
             [4mtroff[24m should encode special characters in arguments to  device  ex‐
             tension commands.  The [4mgrohtml[24m driver uses this directive.

     [1mvert [4m[22mn[24m  The  vertical  motion  quantum is [4mn[24m basic units.  Vertical measure‐
             ments round to multiples of [4mn.[0m

     [1mcharset[0m
             This directive and the rest of the file are ignored.  It is  recog‐
             nized  for  compatibility with other [4mtroff[24m implementations.  In GNU
             [4mtroff[24m, character set repertoire is described on a per-font basis.

     [4mtroff[24m recognizes but ignores the directives [1mspare1[22m,  [1mspare2[22m,  and  [1mbiggest‐[0m
     [1mfont[22m.

     The  [1mres[22m,  [1munitwidth[22m, [1mfonts[22m, and [1msizes [22mlines are mandatory.  Directives not
     listed above are ignored by [4mtroff[24m but may be used by postprocessors to  ob‐
     tain further information about the device.

[1mFont description file format[0m
     On typesetting output devices, each font is typically available at multiple
     sizes.   While paper measurements in the device description file are in ab‐
     solute units, measurements applicable to fonts must be proportional to  the
     type  size.   The font's [4munit[24m [4mwidth[24m establishes a numerical basis that per‐
     mits all of its metrics to be expressed as  integers  if  rendered  at  one
     point.   When  the  formatter configures a type size, it scales the metrics
     linearly relative to that basis.  The unit width has no inherent  relation‐
     ship  to  the device resolution, and the same division procedure applies to
     all font metrics.  Observe that whatever unit might one select for the unit
     width, the division operation implied by scaling cancels it out, leaving  a
     dimensionless quantity.

     For  instance,  [4mgroff[24m's [1mlbp [22mdevice uses a [1munitwidth [22mdirective with an argu‐
     ment of 800.  Its Times roman font [1mTR [22mhas a [1mspacewidth [22mof 833; this is also
     the width of its comma, period, centered period, and mathematical asterisk,
     while its “[1mM[22m” has a width of 2,963.  Thus, an “[1mM[22m”  on  the  [1mlbp  [22mdevice  is
     2,963  ÷ 800 times the unit width, or approximately 3.7.  At a type size of
     10 points, a Times roman “[1mM[22m” is therefore 37 units wide.

     A font description file has two sections.  The first is a sequence  of  di‐
     rectives, and is parsed similarly to the [4mDESC[24m file described above.  Except
     for  the  directive  names that begin the second section, their ordering is
     immaterial.  Later directives of  the  same  name  override  earlier  ones,
     spaces and tabs are handled in the same way, and the same comment syntax is
     supported.  Empty lines are ignored throughout.

     [1mname [4m[22mF[24m  The name of the font is [4mF[24m.  “[1mDESC[22m” is an invalid font name.  Simple
             integers  are valid, but their use is discouraged.  ([4mgroff[24m requests
             and escape sequences interpret non-negative  integers  as  mounting
             positions  instead.   Further, a font named “[1m0[22m” cannot be automati‐
             cally mounted by the [1mfonts [22mdirective of a [4mDESC[24m file.)

     [1mspacewidth [4m[22mn[0m
             The width of an unadjusted inter-word space is [4mn[24m, relative  to  the
             device's unit width.

     The  directives above must appear in the first section; those below are op‐
     tional.

     [1mslant [4m[22mn[0m
            The font's glyphs have a slant of [4mn[24m degrees; a positive [4mn[24m slants  in
            the direction of text flow.

     [1mligatures [4m[22mlig1[24m ... [4mlign[24m [[1m0[22m]
            Glyphs [4mlig1[24m, ..., [4mlign[24m are ligatures; possible ligatures are [1mff[22m, [1mfi[22m,
            [1mfl[22m,  [1mffi[22m,  and  [1mffl[22m.  For compatibility with other [4mtroff[24m implementa‐
            tions, the list of ligatures may be terminated with a [1m0[22m.   The  list
            of ligatures must not extend over more than one line.

     [1mspecial[0m
            The  font  is  [4mspecial[24m: when the document attempts to format a glyph
            that is not present in the formatter's currently selected font,  the
            glyph  is  sought in any mounted fonts that bear this property.  Of‐
            ten, such fonts are [4munstyled[24m, having  no  heavy  (bold)  or  slanted
            (italic or oblique) variants.

     Other  directives in this section are ignored by GNU [4mtroff[24m, but may be used
     by postprocessors to obtain further information about the font.

     The second section contains one to three subsections, which can  appear  in
     any  order, and any of which starts the second section.  Each starts with a
     directive on a line by itself.  A [1mcharset [22msubsection  is  mandatory  unless
     the  associated  [4mDESC[24m file contains the [1municode [22mdirective.  Another subsec‐
     tion, [1mkernpairs[22m, is optional.

     The directive [1mcharset [22mstarts the character set  subsection.   (On  typeset‐
     ters,  this  directive  is  misnamed  since it starts a list of glyphs, not
     characters.)  It precedes a series of glyph  descriptions,  one  per  line.
     Each  such  glyph description comprises a set of fields separated by spaces
     or tabs and organized as follows.

            [4mname[24m [4mmetrics[24m [4mtype[24m [4mindex[24m [[4mentity-name[24m] [[1m-- [4m[22mcomment[24m]

     [4mname[24m identifies the glyph: a printable character [4mc[24m corresponds to the [4mtroff[0m
     ordinary character [4mc[24m, and a multi-character sequence not beginning with  [1m\[22m,
     corresponds  to  the GNU [4mtroff[24m special character escape sequence “[1m\[[4m[22mname[24m[1m][22m”.
     A name consisting of three minus signs, “[1m---[22m”, indicates that the glyph  is
     unnamed:  such  glyphs  can  be  accessed only by the [1m\N [22mescape sequence in
     [4mtroff[24m.  A special character named “[1m---[22m” can still be  defined  using  [1m.char[0m
     and  similar  requests.   The  [4mname[24m “[1m\-[22m” defines the minus sign glyph.  Fi‐
     nally, [4mname[24m can be the  horizontal  motion  escape  sequences,  [1m\|  [22mand  [1m\^[0m
     (“thin” and “hair” spaces, respectively), in which case only the width met‐
     ric  described  below  is  applied; a font can thus customize the widths of
     these spaces.

     The form of the [4mmetrics[24m field is as follows (on one line; it may be  broken
     here for readability).

            [4mwidth[24m[[1m,[22m[[4mheight[24m[[1m,[22m[[4mdepth[24m[[1m,[22m[[4mitalic-correction[24m[[1m,[22m[
            [4mleft-italic-correction[24m[[1m,[22m[[4msubscript-correction[24m]]]]]]]]]]

     Spaces,  tabs,  and  newlines are prohibited between these [4msubfields,[24m which
     are expressed as decimal integers.  The unit of measure is that established
     by the [1munitwidth [22mdirective and scaled to the type size.   Unspecified  sub‐
     fields  default  to  0.   Since there is no associated binary format, these
     values are not required to fit into the C language data type [4mchar[24m  as  they
     are in AT&T device-independent [4mtroff[24m.

     The [4mwidth[24m subfield gives the width of the glyph.  The [4mheight[24m subfield gives
     the  height  of  the glyph (upward is positive); if a glyph does not extend
     above the baseline, give it a zero height,  not  a  negative  height.   The
     [4mdepth[24m  subfield  gives  the depth of the glyph——that is, the distance below
     the baseline to which the glyph extends (downward is positive); if a  glyph
     does  not  extend  below the baseline, give it a zero depth, not a negative
     depth.  Italic corrections  apply  when  upright  and  slanted  (italic  or
     oblique)  styles  are  typeset  adjacently.   The  [4mitalic-correction[24m is the
     amount of space to add after a slanted glyph to be followed immediately  by
     an upright glyph.  The [4mleft-italic-correction[24m is the amount of space to add
     before a slanted glyph to be preceded immediately by an upright glyph.  The
     [4msubscript-correction[24m is the amount of space to add after a slanted glyph to
     be followed by a subscript; it should be less than the italic correction.

     For  fonts  used with typesetters, the [4mtype[24m field gives a featural descrip‐
     tion of the glyph: it is a bit mask recording whether the glyph is  an  as‐
     cender, descender, both, or neither.  When a [1m\w [22mescape sequence is interpo‐
     lated, these values are bitwise or-ed together for each glyph and stored in
     the [1mct [22mregister.  In font descriptions for terminals, all glyphs might have
     a type of zero, regardless of their appearance.

     0      means  the glyph lies entirely between the baseline and a horizontal
            line at the “x-height” of the font, as with “a”, “c”, and “x”;

     1      means the glyph descends below the baseline, like “p”;

     2      means the glyph ascends above the font's x-height, like “A” or “b”);
            and

     3      means the glyph is both an ascender and a descender——this is true of
            parentheses in some fonts.

     The [4mindex[24m field is an integer that uniquely identifies a glyph  within  the
     font;  any  integer is accepted as input, (that is, any integer parsable by
     the C standard library's ]8;;man:strtol(3)\[4mstrtol[24m(3)]8;;\ function) but no practical font  employs
     all  possible  values.   An [4mindex[24m is limited to the range of the system's C
     language data type [4mint[24m.  In a [4mtroff[24m document, use the indexed character es‐
     cape sequence [1m\N [22mto specify a glyph by index.

     The [4mentity-name[24m field defines an identifier for the glyph  that  the  post‐
     processor  uses  to print the [4mtroff[24m glyph [4mname[24m.  This field is optional; it
     was introduced so that the [4mgrohtml[24m output driver could encode its character
     set.  For example, the glyph [1m\[Po] [22mis represented by “[1m&pound;[22m” in HTML 4.0.
     For efficiency, these data are now compiled directly into  [4mgrohtml[24m.   [4mgrops[0m
     uses the field to build sub-encoding arrays for PostScript fonts containing
     more than 256 glyphs.

     Anything  on the line after the [4mentity-name[24m field or “[1m--[22m” is ignored.  When
     [4mafmtodit[24m generates font description files for ]8;;man:gropdf(1)\[4mgropdf[24m(1)]8;;\  and  ]8;;man:grops(1)\[4mgrops[24m(1)]8;;\,  it
     writes the UTF-16 code for the character to the comment field.

     A line in the [1mcharset [22msection can also have the form
            [4mname[24m [1m"[0m
     identifying  [4mname[24m  as another name for the glyph mentioned in the preceding
     line.  Such aliases can be chained.

     A [1mcharset-range [22msubsection works like the [1mcharset [22mdirective except that the
     glyph descriptions use a [4mname[24m of the form [1mu[4m[22mAAAA[24m[1m..u[4m[22mFFFF[24m, where [4mAAAA[24m and [4mFFFF[0m
     are hexadecimal digit sequences; the specified metrics then  apply  identi‐
     cally to all glyphs in the designated range.

     The  directive [1mkernpairs [22mstarts a list of kerning adjustments to be made to
     adjacent glyph pairs from this font.  It contains a sequence of lines  for‐
     matted as follows.
            [4mg1[24m [4mg2[24m [4mn[0m
     The  foregoing  means  that when glyph [4mg1[24m is typeset immediately before [4mg2[24m,
     the space between them should be increased by [4mn[24m.  The unit  of  measure  is
     that  established  by  the [1munitwidth [22mdirective and scaled to the type size.
     Most kerning pairs should have a negative value for [4mn[24m.

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

     [4m/usr/share/groff/1.24.0/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.0                       2025-12-19                      [4mgroff_font[24m(5)
────────────────────────────────────────────────────────────────────────────────
[4mgroff_out[24m(5)                   File Formats Manual                  [4mgroff_out[24m(5)

[1mName[0m
     groff_out - GNU [4mroff[24m device-independent page description language

[1mDescription[0m
     The fundamental operation of the GNU  [4mtroff[24m  formatter,  ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\,  is  the
     translation  of  the  ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\ input language into a series of instructions
     concerned primarily with placing glyphs or geometric  objects  at  specific
     positions  on  a  rectangular  page.  In the following discussion, the term
     [4mcommand[24m refers to this device-independent output  language,  never  to  the
     language  intended  for use by document authors.  Device-independent output
     commands comprise several categories: glyph output; font, color,  and  text
     size  selection;  motion of the drawing position; page advancement; drawing
     of geometric primitives; and device extension  commands,  a  catch-all  for
     other  operations.   The last includes directives to start and stop output,
     identify the intended output device, and embed URL hyperlinks in  supported
     output formats.

   [1mBackground[0m
     As  ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\  is a wrapper program around GNU [4mtroff[24m and automatically calls
     an output driver, users seldom encounter this format under  normal  circum‐
     stances.   [4mgroff[24m  offers  the option [1m-Z [22mto inhibit postprocessing such that
     GNU [4mtroff[24m's output is sent to the standard output stream just as it is when
     running GNU [4mtroff[24m directly.

     The purpose of device-independent output is to facilitate  the  development
     of  postprocessors  by providing a common programming interface for all de‐
     vices.  It is a distinct, and much simpler, language from that of the  for‐
     matter,  [4mtroff[24m.  The device-independent output can be thought of as a “page
     description language”.

     In the following discussion, the term [4mtroff[24m [4moutput[24m describes what is output
     by GNU [4mtroff[24m, while [4mpage[24m [4mdescription[24m denotes the language accepted  by  the
     parser  that  interprets  this  output for the output drivers.  This parser
     handles whitespace more flexibly than AT&T [4mtroff[24m's  implementation,  recog‐
     nizes a GNU extension to the language, and supports a legacy compressed en‐
     coding  of  a  subset of commands for compatibility; otherwise, the formats
     are the same.  (The parser for device-independent output can  be  found  in
     the [4mgroff[24m sources at [4msrc/libs/libdriver/input.cpp[24m.)

     When Brian Kernighan designed AT&T [4mtroff[24m's device-independent page descrip‐
     tion language circa 1980, he had to balance readability and maintainability
     against  severe constraints on file size and transmission speed to the out‐
     put device.  A decade later, when  James  Clark  wrote  [4mgroff[24m,  these  con‐
     straints were no longer as tight.

   [1mSyntax[0m
     [4mroff[24m's  page  description  language  is a sequence of [4mtokens:[24m single-letter
     commands or their arguments.  Some commands accept a subcommand as a  first
     argument, followed by one or more further arguments.

     AT&T device-independent [4mtroff[24m used whitespace minimally when producing out‐
     put.   GNU [4mtroff[24m, in contrast, attempts to make its output more human-read‐
     able.  The whitespace characters——tab, space, and newline——are always mean‐
     ingful.  They are never used to represent spacing in the document; that  is
     done  with horizontal ([1mh[22m, [1mH[22m) and vertical ([1mv[22m, [1mV[22m) positioning commands.  Any
     sequence of space and/or tab characters is equivalent to  a  single  space,
     separating commands from arguments and arguments from each other.  Space is
     required  only where omitting it would cause ambiguity.  A line break sepa‐
     rates commands.  The comment character is a pound/hash sign ([1m#[22m), and  marks
     the  remainder of the line as a comment.  A line comprising only whitespace
     after comment removal does nothing but separate input tokens.

     For example, the relative horizontal motion command ([1mh[22m) and the command  to
     write one glyph ([1mc[22m), each take a single argument; the former a signed inte‐
     ger,  and  the  latter  a printable ISO 646/“ASCII” character.  A series of
     such commands could validly occur without spaces on an input line, but  GNU
     [4mtroff[24m follows each with a newline.

     Some  commands  have a more complex syntax; the GNU [4mtroff[24m extension command
     for writing glyph sequences ([1mt[22m) accepts a  variable  number  of  arguments.
     Those that draw geometric objects ([1mD[22m) or control the device ([1mx[22m) furthermore
     recognize  subcommand  arguments.   Such commands thus must end with a new‐
     line.  In GNU [4mtroff,[24m the device extension (sub)command “[1mx X[22m” uniquely  sup‐
     ports a line continuation syntax; a single input line contains any other.

   [1mArgument units[0m
     Some commands accept integer arguments that represent measurements, but the
     scaling  units  of  the formatter's language are never used.  Most commands
     assume a scaling unit of “[1mu[22m” (basic units),  and  others  use  “[1ms[22m”  (scaled
     points).   These  are  defined  by the parameters specified in the device's
     [4mDESC[24m file; see ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\ and, for more on scaling units,  ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\  and
     [4mGroff:[24m  [4mThe[24m  [4mGNU[24m [4mImplementation[24m [4mof[24m [4mtroff[24m, the [4mgroff[24m Texinfo manual.  Color-
     related commands use dimensionless integers.

     Note that single characters can have the eighth bit set, as can  the  names
     of fonts and special characters (this is, glyphs).  The names of glyphs and
     fonts  can  be of arbitrary length.  A glyph that is to be printed will al‐
     ways be in the current font.

     A string argument is always terminated by  the  next  whitespace  character
     (space,  tab,  or  newline); an embedded [1m# [22mcharacter is regarded as part of
     the argument, not as the beginning of a comment command.  An integer  argu‐
     ment  is  already terminated by the next non-digit character, which then is
     regarded as the first character of the next argument or command.

   [1mOutput structure[0m
     Device-independent [4mtroff[24m output is organized into three parts: a header,  a
     body, and a trailer.

     The  task  of  the  header  is to set general device parameters.  GNU [4mtroff[0m
     guarantees that its header consists of the following three lines:

            [1mx T [4m[22mdevice[0m
            [1mx res [4m[22mn[24m [4mh[24m [4mv[0m
            [1mx init[0m

     with the parameters [4mn[24m, [4mh[24m, and [4mv[24m set as outlined in subsection “Device  Con‐
     trol  Commands” below.  The parser for the device-independent page descrip‐
     tion language format is able to interpret additional  whitespace  and  com‐
     ments as well even in the header.

     The  body  contains  the document's visible content.  Once an output driver
     interprets “[1mx init[22m”, it prepares to handle commands in general.  Processing
     terminates when a “[1mx stop[22m” command is encountered; the last line of any GNU
     [4mtroff[24m page description output always contains such a command.

     Semantically, the body is page-oriented.  The [1mp [22mcommand starts a new  page.
     Positioning,  writing, and drawing commands are performed within a page, so
     they cannot occur before the first [1mp [22mcommand.  The  output  driver  reckons
     absolute  positioning (by the [1mH [22mand [1mV [22mcommands) with respect to the current
     page's origin at the top left corner, and all other positioning relative to
     the drawing position on the page.

     The trailer advances the drawing position to the bottom of the page and in‐
     forms the device that the document (or “job”) has ended.

[1mCommand reference[0m
     This section describes all page description output commands, both from AT&T
     [4mtroff[24m as well as extension commands issued by GNU [4mtroff.[0m

   [1mComment command[0m
     [1m#[4m[22manything[24m⟨line-break⟩
            Apply comment annotation.  Ignore any characters from the [1m#  [22mcharac‐
            ter  up  to the next newline.  Each comment can be preceded by arbi‐
            trary syntactical space, and every command can be  terminated  by  a
            comment.

   [1mSimple commands[0m
     The  commands in this subsection have a command code consisting of a single
     character, taking a fixed number of arguments.  Most of them  are  commands
     for  positioning  and  text writing.  These commands are smart about white‐
     space.  Optionally, [4msyntactical[24m [4mspace[24m can be inserted  before,  after,  and
     between  the  command  letter and its arguments.  All of these commands are
     stackable, i.e., they can be preceded by other simple commands or  followed
     by  arbitrary  other  commands  on the same line.  A separating [4msyntactical[0m
     [4mspace[24m is necessary only when two integer arguments would clash  or  if  the
     preceding argument ends with a string argument.

     [1mC [4m[22mid[24m⟨white-space⟩
            Typeset the glyph of the special character [4mid[24m.  Trailing syntactical
            space  is  necessary  to  allow special character names of arbitrary
            length.  The drawing position is not advanced.

     [1mc [4m[22mc[24m    Typeset the glyph of the ordinary character [4mc[24m.  The drawing position
            is not advanced.

     [1mf [4m[22mn[24m    Select the font mounted at position [4mn[24m.  [4mn[24m cannot be negative.

     [1mH [4m[22mn[24m    Horizontally move the drawing position to [4mn[24m  basic  units  from  the
            left edge of the page.  [4mn[24m cannot be negative.

     [1mh [4m[22mn[24m    Move  the  drawing position right [4mn[24m basic units.  AT&T [4mtroff[24m allowed
            negative [4mn;[24m GNU [4mtroff[24m does not produce such values, but [4mgroff[24m's out‐
            put driver library handles them.

     [1mm [4m[22mscheme[24m [[4mcomponent[24m ...]
            Select the stroke color using the  [4mcomponent[24ms  in  the  color  space
            [4mscheme[24m.   Each  [4mcomponent[24m  is  an  integer between 0 and 65536.  The
            quantity of components and their meanings  vary  with  each  [4mscheme[24m.
            This command is a [4mgroff[24m extension.

            [1mmc [4m[22mcyan[24m [4mmagenta[24m [4myellow[0m
                   Use  the  CMY color scheme with components cyan, magenta, and
                   yellow.

            [1mmd     [22mUse the default color (no components; black in most cases).

            [1mmg [4m[22mgray[0m
                   Use a grayscale color scheme with a component ranging between
                   0 (black) and 65536 (white).

            [1mmk [4m[22mcyan[24m [4mmagenta[24m [4myellow[24m [4mblack[0m
                   Use the CMYK color scheme with components cyan, magenta, yel‐
                   low, and black.

            [1mmr [4m[22mred[24m [4mgreen[24m [4mblue[0m
                   Use the RGB color scheme  with  components  red,  green,  and
                   blue.

     [1mN [4m[22mn[24m    Typeset the glyph with index [4mn[24m in the current font.  [4mn[24m is normally a
            non-negative  integer.   The  drawing position is not advanced.  The
            [1mhtml [22mand [1mxhtml [22mdevices use this command with negative [4mn[24m  to  produce
            unbreakable  space; the absolute value of [4mn[24m is taken and interpreted
            in basic units.

     [1mn [4m[22mb[24m [4ma[24m  Indicate a break.  No action is performed; the command is present to
            make the output more easily parsed.  The integers [4mb[24m and  [4ma[24m  describe
            the vertical space amounts before and after the break, respectively.
            GNU  [4mtroff[24m issues this command but [4mgroff[24m's output driver library ig‐
            nores it.  See [1mv [22mand [1mV[22m.

     [1mp [4m[22mn[24m    Begin a new page, setting its number to [4mn[24m.  Each  page  is  indepen‐
            dent,  even  from those using the same number.  The vertical drawing
            position is set to 0.  All positioning, writing,  and  drawing  com‐
            mands  are interpreted in the context of a page, so a [1mp [22mcommand must
            precede them.

     [1ms [4m[22mn[24m    Set type size to [4mn[24m scaled points (unit [1mz [22min GNU [4mtroff[24m).  AT&T  [4mtroff[0m
            used unscaled points ([1mp[22m) instead; see section “Compatibility” below.

     [1mt [4m[22mxyz[24m...⟨white-space⟩
     [1mt [4m[22mxyz[24m... [4mdummy-arg[24m⟨white-space⟩
            Typeset  word  [4mxyz[24m; that is, set a sequence of ordinary glyphs named
            [4mx[24m, [4my[24m, [4mz[24m, ..., terminated by a space or newline; an  optional  second
            integer  argument  is ignored (this allows the formatter to generate
            an even number of arguments).  Each glyph  is  set  at  the  current
            drawing  position, and the position is then advanced horizontally by
            the glyph's width.  A glyph's width is read from its metrics in  the
            font  description file, scaled to the current type size, and rounded
            to a multiple of the horizontal motion quantum.  Use the  [1mC  [22mcommand
            to  emplace  glyphs of special characters.  The [1mt [22mcommand is a [4mgroff[0m
            extension and is output only for devices whose  [4mDESC[24m  file  contains
            the [1mtcommand [22mdirective; see ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

     [1mu [4m[22mn[24m [4mxyz[24m...
     [1mu [4m[22mxyz[24m... [4mdummy-arg[24m⟨white-space⟩
            Typeset  word  [4mxyz[24m with track kerning.  As [1mt[22m, but after placing each
            glyph, the drawing position is further advanced  horizontally  by  [4mn[0m
            basic  units.  The [1mu [22mcommand is a [4mgroff[24m extension and is output only
            for devices whose [4mDESC[24m file contains  the  [1mtcommand  [22mdirective;  see
            ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

     [1mV [4m[22mn[24m    Vertically  move  the drawing position to [4mn[24m basic units from the top
            edge of the page.  [4mn[24m cannot be negative.

     [1mv [4m[22mn[24m    Move the drawing position down [4mn[24m basic units.   AT&T  [4mtroff[24m  allowed
            negative [4mn;[24m GNU [4mtroff[24m does not produce such values, but [4mgroff[24m's out‐
            put driver library handles them.

     [1mw      [22mIndicate  an  inter-word space.  No action is performed; the command
            is present to make the output more easily parsed.   Only  inter-word
            spaces  on  an  output  line (be they breakable or not) are thus de‐
            scribed; those resulting from horizontal motion escape sequences are
            not.  GNU [4mtroff[24m issues this command but [4mgroff[24m's  output  driver  li‐
            brary ignores it.  See [1mh [22mand [1mH[22m.

   [1mGraphics commands[0m
     Each  graphics  or  drawing command in the page description language starts
     with the letter “[1mD[22m”, followed by one or two characters that specify a  sub‐
     command;  this  is  followed by a fixed or variable number of integer argu‐
     ments that are separated by a single space character.  A “[1mD[22m”,  command  may
     not be followed by another command on the same line (apart from a comment),
     so each “[1mD[22m” command is terminated by a syntactical line break.

     GNU  [4mtroff[24m output follows AT&T [4mtroff[24m's output conventions (no space between
     command and subcommand, all arguments are preceded by a single space  char‐
     acter),  but  [4mgroff[24m's parser allows optional space between the command let‐
     ters and makes the space before the first  argument  optional.   As  usual,
     each space can be any sequence of tab and space characters.

     Some  graphics  commands  can take a variable number of arguments.  In this
     case, they are integers representing a size measured in basic units [1mu[22m.  The
     [4mh[24m arguments stand for horizontal distances where positive means right, neg‐
     ative left.  The [4mv[24m arguments stand for vertical  distances  where  positive
     means  down,  negative up.  All these distances are offsets relative to the
     current location.

     Each graphics command directly corresponds to a [4mtroff[24m [1m\D  [22mescape  sequence.
     See subsection “Drawing commands” of ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\.

     Unless indicated otherwise, each graphics command directly corresponds to a
     similar [4mgroff[24m [1m\D [22mescape sequence; see ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\.

     Unknown  [1mD  [22mcommands  are assumed to be device-specific.  Its arguments are
     parsed as strings; the whole information is then sent to the postprocessor.

     In the following command reference, the syntax element [4m⟨line-break⟩[24m means a
     [4msyntactical[24m [4mline[24m [4mbreak[24m as defined in subsection “Separation” above.

     [1mD~ [4m[22mh1[24m [4mv1[24m [4mh2[24m [4mv2[24m ... [4mhn[24m [4mvn[24m⟨line-break⟩
            Draw B-spline from current position to offset ([4mh1[24m, [4mv1[24m), then to off‐
            set ([4mh2[24m, [4mv2[24m) if given, etc., up to ([4mhn[24m, [4mvn[24m). This  command  takes  a
            variable  number of argument pairs; the current position is moved to
            the terminal point of the drawn curve.

     [1mDa [4m[22mh1[24m [4mv1[24m [4mh2[24m [4mv2[24m⟨line-break⟩
            Draw arc from current position to ([4mh1[24m, [4mv1[24m)+([4mh2[24m, [4mv2[24m) with  center  at
            ([4mh1[24m, [4mv1[24m);  then  move the current position to the final point of the
            arc.

     [1mDC [4m[22md[24m⟨line-break⟩
     [1mDC [4m[22md[24m [4mdummy-arg[24m⟨line-break⟩
            Draw a solid circle using the current fill  color  with  diameter  [4md[0m
            (integer  in basic units [1mu[22m) with leftmost point at the current posi‐
            tion; then move the current position to the rightmost point  of  the
            circle.  An optional second integer argument is ignored (this allows
            the  formatter  to generate an even number of arguments).  This com‐
            mand is a GNU extension.

     [1mDc [4m[22md[24m⟨line-break⟩
            Draw circle line with diameter [4md[24m (integer in  basic  units  [1mu[22m)  with
            leftmost  point at the current position; then move the current posi‐
            tion to the rightmost point of the circle.

     [1mDE [4m[22mh[24m [4mv[24m⟨line-break⟩
            Draw a solid ellipse in the current fill color with a horizontal di‐
            ameter of [4mh[24m and a vertical diameter of [4mv[24m  (both  integers  in  basic
            units  [1mu[22m) with the leftmost point at the current position; then move
            to the rightmost point of the ellipse.  This command is a GNU exten‐
            sion.

     [1mDe [4m[22mh[24m [4mv[24m⟨line-break⟩
            Draw an outlined ellipse with a horizontal diameter of [4mh[24m and a  ver‐
            tical  diameter of [4mv[24m (both integers in basic units [1mu[22m) with the left‐
            most point at current position; then move to the rightmost point  of
            the ellipse.

     [1mDF [4m[22mcolor-scheme[24m [[4mcomponent[24m ...]⟨line-break⟩
            Set  fill  color  for  solid  drawing  objects using different color
            schemes; the analogous command for setting the color of  text,  line
            graphics, and the outline of graphic objects is [1mm[22m.  The color compo‐
            nents  are  specified as integer arguments between 0 and 65536.  The
            number of color components and their meaning vary for the  different
            color  schemes.   These commands are generated by GNU [4mtroff[24m's escape
            sequences “[1m\D'F [22m...[1m'[22m” [1m\M [22m(with no other corresponding graphics  com‐
            mands).  No position changing.  This command is a GNU extension.

            [1mDFc [4m[22mcyan[24m [4mmagenta[24m [4myellow[24m⟨line-break⟩
                   Set  fill color for solid drawing objects using the CMY color
                   scheme, having the 3 color components cyan, magenta, and yel‐
                   low.

            [1mDFd [22m⟨line-break⟩
                   Set fill color for solid drawing objects to the default  fill
                   color value (black in most cases).  No component arguments.

            [1mDFg [4m[22mgray[24m⟨line-break⟩
                   Set fill color for solid drawing objects to the shade of gray
                   given by the argument, an integer between 0 (black) and 65536
                   (white).

            [1mDFk [4m[22mcyan[24m [4mmagenta[24m [4myellow[24m [4mblack[24m⟨line-break⟩
                   Set fill color for solid drawing objects using the CMYK color
                   scheme,  having the 4 color components cyan, magenta, yellow,
                   and black.

            [1mDFr [4m[22mred[24m [4mgreen[24m [4mblue[24m⟨line-break⟩
                   Set fill color for solid drawing objects using the RGB  color
                   scheme, having the 3 color components red, green, and blue.

     [1mDf [4m[22mn[24m⟨line-break⟩
            The argument [4mn[24m must be an integer in the range -32767 to 32767.

            0≤[4mn[24m≤1000
                   Set the color for filling solid drawing objects to a shade of
                   gray,  where 0 corresponds to solid white, 1000 (the default)
                   to solid black, and values in between to intermediate  shades
                   of gray; this command is superseded by “[1mDFg[22m”.

            [4mn[24m<0 or [4mn[24m>1000
                   Set  the  filling  color to the color that is currently being
                   used for the text and the outline, see command [1mm[22m.  For  exam‐
                   ple, the command sequence

                          mg 0 0 65536
                          Df -1

                   sets all colors to blue.

            This command is a GNU extension.

     [1mDl [4m[22mh[24m [4mv[24m⟨line-break⟩
            Draw  line from current position to offset ([4mh[24m, [4mv[24m) (integers in basic
            units [1mu[22m); then set current position to the end of the drawn line.

     [1mDp [4m[22mh1[24m [4mv1[24m [4mh2[24m [4mv2[24m ... [4mhn[24m [4mvn[24m⟨line-break⟩
            Draw a polygon line from current position to offset  ([4mh1[24m, [4mv1[24m),  from
            there  to  offset  ([4mh2[24m, [4mv2[24m),  etc.,  up to offset ([4mhn[24m, [4mvn[24m), and from
            there back to the starting position.  For  historical  reasons,  the
            position  is changed by adding the sum of all arguments with odd in‐
            dex to the current horizontal position and the even ones to the ver‐
            tical position.  Although this doesn't make sense  it  is  kept  for
            compatibility.  This command is a [4mgroff[24m extension.

     [1mDP [4m[22mh1[24m [4mv1[24m [4mh2[24m [4mv2[24m ... [4mhn[24m [4mvn[24m⟨line-break⟩
            The  same  macro as the corresponding [1mDp [22mcommand with the same argu‐
            ments, but draws a solid polygon in the current  fill  color  rather
            than  an  outlined polygon.  The position is changed in the same way
            as with [1mDp[22m.  This command is a GNU extension.

     [1mDt [4m[22mn[24m⟨line-break⟩
            Set the current line thickness to [4mn[24m (an integer in basic units [1mu[22m) if
            [4mn[24m>0; if [4mn[24m=0 select the smallest available line thickness; otherwise,
            the line thickness is made proportional to the type size,  which  is
            the  default.   For  historical  reasons, the horizontal position is
            changed by adding the argument to the current  horizontal  position,
            while  the  vertical position is not changed.  Although this doesn't
            make sense, it is kept for compatibility.  This command is a GNU ex‐
            tension.

   [1mDevice control commands[0m
     Each device control command starts with the letter “[1mx[22m”, followed by a space
     character (optional or arbitrary space or tab in GNU [4mtroff[24m) and  a  subcom‐
     mand letter or word; each argument (if any) must be preceded by a syntacti‐
     cal  space.   All “[1mx[22m”, commands are terminated by a syntactical line break;
     no device control command can be followed by another command  on  the  same
     line (except a comment).

     The  subcommand  is basically a single letter, but to increase readability,
     it can be written as a word, i.e., an arbitrary sequence of characters ter‐
     minated by the next tab, space, or newline character.   All  characters  of
     the  subcommand  word  but  the first are simply ignored.  For example, GNU
     [4mtroff[24m outputs the initialization command “[1mx i[22m” as “[1mx init[22m” and the  resolu‐
     tion command “[1mx r[22m” as “[1mx res[22m”.

     In  the following, the syntax element [4m⟨line-break⟩[24m means a [4msyntactical[24m [4mline[0m
     [4mbreak[24m as defined in subsection “Separation” above.

     [1mxF [4m[22mname[24m⟨line-break⟩
            ([4mFilename[24m control command)
            Use [4mname[24m as the intended name for the current file in error reports.
            This is useful for remembering the original  file  name  when  [4mgroff[0m
            uses  its  internal piping mechanism.  The input file is not changed
            by this command.  This command is a GNU extension.

     [1mxf [4m[22mn[24m [4ms[24m⟨line-break⟩
            ([4mfont[24m control command)
            Mount font position [4mn[24m (a non-negative integer) with font named [4ms[24m  (a
            text word); see ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.

     [1mxH [4m[22mn[24m⟨line-break⟩
            ([4mHeight[24m control command)
            Set  character  height to [4mn[24m (a positive integer in scaled points [1mz[22m).
            [4mClassical[24m [4mtroff[24m used the unit points ([1mp[22m) instead; see section  “Com‐
            patibility” below.

     [1mxi [22m⟨line-break⟩
            ([4minit[24m control command)
            Initialize device.  This is the third command of the header.

     [1mxp [22m⟨line-break⟩
            ([4mpause[24m control command)
            Parsed but ignored.  The classical documentation reads [4mpause[24m [4mdevice,[0m
            [4mcan[24m [4mbe[24m [4mrestarted[24m.

     [1mxr [4m[22mn[24m [4mh[24m [4mv[24m⟨line-break⟩
            ([4mresolution[24m control command)
            Resolution is [4mn[24m, while [4mh[24m is the minimal horizontal motion, and [4mv[24m the
            minimal vertical motion possible with this device; all arguments are
            positive  integers  in  basic  units [1mu [22mper inch.  This is the second
            command of the header.

     [1mxS [4m[22mn[24m⟨line-break⟩
            ([4mSlant[24m control command)
            Set slant to [4mn[24m degrees (an integer in basic units [1mu[22m).

     [1mxs [22m⟨line-break⟩
            ([4mstop[24m control command)
            Terminates the processing of the current file; issued  as  the  last
            command of device-independent [4mtroff[24m output.

     [1mxt [22m⟨line-break⟩
            ([4mtrailer[24m control command)
            Generate  trailer  information, if any.  In [1mgroff[22m, this is currently
            ignored.

     [1mxT [4m[22mxxx[24m⟨line-break⟩
            ([4mTypesetter[24m control command)
            Set the name of the output driver to [4mxxx[24m, a sequence  of  non-white‐
            space  characters terminated by whitespace.  The possible names cor‐
            respond to those of [4mgroff[24m's [1m-T [22moption.  This is the first command of
            the header.

     [1mxu [4m[22mn[24m⟨line-break⟩
            ([4munderline[24m control command)
            Configure underlining of spaces.  If [4mn[24m is 1,  start  underlining  of
            spaces;  if  [4mn[24m is 0, stop underlining of spaces.  This is needed for
            the [1mcu [22mrequest in [1mnroff [22mmode and is ignored otherwise.  This command
            is a GNU extension.

     [1mxX [4m[22manything[24m⟨line-break⟩
            ([4mX-escape[24m control command)
            Send string [4manything[24m uninterpreted to the device.  If the line  fol‐
            lowing  this  command  starts with a [1m+ [22mcharacter this line is inter‐
            preted as a continuation line in the following sense.  The [1m+ [22mis  ig‐
            nored,  but  a  newline character is sent instead to the device, the
            rest of the line is sent uninterpreted.  The  same  applies  to  all
            following lines until the first character of a line is not a [1m+ [22mchar‐
            acter.   This  command is generated by the [4mgroff[24m escape sequence [1m\X[22m.
            Line continuation is a GNU extension.

   [1mLegacy compressed encoding[0m
     AT&T [4mtroff[24m primarily emitted glyphs by writing two digits (a  motion)  fol‐
     lowed  by a single character corresponding to a glyph.  This syntax is less
     a command itself than a compressed encoding of the [1mc [22mand [1mh [22mcommands.

     [4mddc[24m    Move right [4mdd[24m (exactly two decimal digits) basic units [1mu[22m, then print
            glyph with single-letter name [4mc[24m.

            In [4mgroff[24m, arbitrary [4msyntactical[24m [4mspace[24m around and within this command
            is allowed to be added.  Only when a preceding command on  the  same
            line  ends with an argument of variable length a separating space is
            obligatory.  In [4mclassical[24m [4mtroff[24m, large clusters of these  and  other
            commands were used, mostly without spaces; this made such output al‐
            most unreadable.

     For modern high-resolution devices, this command is impractical because the
     widths of the glyphs have a greater magnitude in basic units than two deci‐
     mal digits can represent.  In [4mgroff[24m, it is used only for output to the [1mX75[22m,
     [1mX75-12[22m,  [1mX100[22m,  and [1mX100-12 [22mdevices.  For others, the commands [1mt [22mand [1mu [22mpro‐
     vide greater functionality and superior troubleshooting capacity.

[1mCompatibility[0m
     The page description language of AT&T [4mtroff[24m  was  first  documented  in  “A
     Typesetter-independent  TROFF”,  by  Brian  Kernighan, and by 1992 the AT&T
     [4mtroff[24m manual was updated to incorporate a description of it.

     [4mgroff[24m's page description language is compatible with this specification ex‐
     cept in the following aspects.

     •  AT&T device-independent [4mtroff[24m's quasi-device independence is not yet im‐
        plemented.

     •  The printing hardware of the early 1980s differed from today's.  [4mgroff[24m's
        output device names also differ from those of AT&T  [4mtroff[24m  For  example,
        the  PostScript  device  in  AT&T [4mtroff,[24m [1mpost [22m(implemented by the driver
        command [4mdpost[24m), has a resolution of only 720 units  per  inch,  suitable
        for  printers  of  decades  past.  [4mgroff[24m's [1mps [22mdevice has a resolution of
        72000 units per inch.  In principle, by implementing a rescaling  mecha‐
        nism, [4mgroff[24m could come to emulate AT&T's [1mpost [22mdevice.

     •  While  the  B-spline  command [1mD~ [22mis reliably interpreted by [4mgroff[24m's page
        description language parser, some output drivers don't implement drawing
        routines for it.

     •  In GNU [4mtroff,[24m the argument to the commands [1ms [22mand [1mx H  [22muses  an  implicit
        unit  of scaled points [1mz [22mwhereas AT&T [4mtroff[24m uses spacing points [1mp[22m.  This
        isn't an incompatibility, but a compatible extension, for both units co‐
        incide for any device without a [1msizescale [22mdirective in  its  [4mDESC[24m  file,
        including all postprocessors from AT&T and [4mgroff[24m's text ([4mnroff[24m-mode) de‐
        vices.   [4mgroff[24m  devices  that use [1msizescale [22meither do not exist for AT&T
        [4mtroff[24m have a different name, or seem to have a different resolution.  So
        conflicts are very unlikely.

     •  The drawing position after  the  commands  “[1mDp[22m”,  “[1mDP[22m”,  and  “[1mDt[22m”,  are
        processed  is illogical.  Since old versions of GNU [4mtroff[24m had this wart,
        we've retained it for compatibility, but may change it  in  the  future.
        Wrap these drawing commands with the [1m\Z [22mescape sequence to both overcome
        the  illogical  positioning and keep your input working consistently re‐
        gardless of the wart's presence in the implementation.

     The differences  between  [4mgroff[24m  and  [4mclassical[24m  [4mtroff[24m  are  documented  in
     ]8;;man:groff_diff(7)\[4mgroff_diff[24m(7)]8;;\.

[1mFiles[0m
     [4m/usr/share/groff/1.24.0/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.0                       2026-01-31                       [4mgroff_out[24m(5)
────────────────────────────────────────────────────────────────────────────────
[4mgroff_tmac[24m(5)                  File Formats Manual                 [4mgroff_tmac[24m(5)

[1mName[0m
     groff_tmac - macro files in the GNU [4mroff[24m typesetting system

[1mDescription[0m
     Definitions of macros, strings, and registers for use in a ]8;;man:roff(7)\[4mroff[24m(7)]8;;\ document
     can be collected into [4mmacro[24m [4mfiles[24m, [4mroff[24m input files designed to produce  no
     output themselves but instead ease the preparation of other [4mroff[24m documents.
     There  is no syntactical difference between a macro file and any other [4mroff[0m
     document; only its purpose distinguishes it.  When  a  macro  file  is  in‐
     stalled  at  a  standard location, named according to a certain convention,
     and suitable for use by a general audience, it is termed a  [4mmacro[24m  [4mpackage[24m.
     The  “tmac”  name  originated  in  early Unix culture as an abbreviation of
     “[4mtroff[24m macros”.

     Macro packages can be loaded by supplying the [1m-m [22moption to  ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\  or  a
     [4mgroff[24m  front  end.   A  macro  file's name must have the form name[4m.tmac[24m (or
     [4mtmac.[24mname) and be placed in a “[4mtmac[24m directory” to be loadable with the  “[1m-m[0m
     [4mname[24m”  option.   Section “Environment” of ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ lists these directories.
     Alternatively, a [4mgroff[24m document requiring a macro file can load it with the
     [1mmso [22m(“macro source”) request.

     Macro files are named for their most noteworthy application,  but  a  macro
     file need not define any macros.  It can restrict itself to defining regis‐
     ters and strings or invoking other [4mgroff[24m requests.  It can even be empty.

     Encode  macro files in ISO 646:1991 IRV (US-ASCII) or ISO Latin-1 (8859-1).
     To prepare for a future [4mgroff[24m  release  supporting  UTF-8  input,  restrict
     files  to  ISO  646  codes.  ]8;;man:soelim(1)\[4msoelim[24m(1)]8;;\ by design does not interpret [1mmso [22mre‐
     quests, and the encodings used by documents  employing  a  macro  file  can
     vary.

[1mMacro packages[0m
     Some  macro  packages (“major” or “full-service”) assume responsibility for
     page layout and other critical functions; others (“supplemental” or “auxil‐
     iary”) do not.  GNU [4mroff[24m provides most major macro packages found  in  AT&T
     and  BSD Unix systems, an additional full-service package, and many supple‐
     mental packages.  Multiple full-service macro packages cannot  be  used  by
     the same document.  Auxiliary packages can, in general, be freely combined,
     though attention to their use of the [4mgroff[24m language name spaces for identi‐
     fiers  (particularly  registers, macros, strings, and diversions) should be
     paid.  Name space management challenged AT&T [4mtroff[24m users; GNU [4mtroff[24m's  sup‐
     port  for  arbitrarily long identifiers affords few excuses for name colli‐
     sions, apart from attempts at compatibility with the demands of  historical
     documents.

   [1mMan pages[0m
     Two  full-service macro packages are specialized for formatting Unix refer‐
     ence manuals; they do not  support  features  like  footnotes  or  multiple
     columnation.

     [4man[24m       constructs  man  pages  in  a format introduced by Seventh Edition
              Unix (1979).  Its macro interface is small, and the package widely
              used; see ]8;;man:groff_man(7)\[4mgroff_man[24m(7)]8;;\.

     [4mdoc[24m      constructs man pages in a format introduced by 4.3BSD-Reno (1990).
              It provides many more features than [4man[24m, but is also  larger,  more
              complex, and not as widely adopted; see ]8;;man:groff_mdoc(7)\[4mgroff_mdoc[24m(7)]8;;\.

     Because  readers of man pages often do not know in advance which macros are
     used to format a given document, a wrapper is available.

     [4mandoc[24m    recognizes a document's use of [4man[24m or [4mdoc[24m and loads the correspond‐
              ing macro package.  Multiple man pages, in either format,  can  be
              handled; [4mandoc[24m reloads each macro package as necessary.

   [1mGeneral full-service packages[0m
     The  following  packages each support composition of documents of any kind,
     from single-page memos to lengthy monographs.  They are  similar  in  func‐
     tionality; select one that suits your taste.

     [4mme[24m     originates in 2BSD (1978); see ]8;;man:groff_me(7)\[4mgroff_me[24m(7)]8;;\.

     [4mmm[24m     originates  in  Programmer's  Workbench  (PWB)  Unix 1.0 (1977); see
            ]8;;man:groff_mm(7)\[4mgroff_mm[24m(7)]8;;\.

     [4mmom[24m    was contributed to [4mgroff[24m in 2002, and freely exercises its many  ex‐
            tended features.  See ]8;;man:groff_mom(7)\[4mgroff_mom[24m(7)]8;;\.

     [4mms[24m     originates in Sixth Edition Unix (1975); see ]8;;man:groff_ms(7)\[4mgroff_ms[24m(7)]8;;\.

   [1mLocalization packages[0m
     For  Western  languages, an auxiliary package for localization sets the hy‐
     phenation mode and loads hyphenation patterns and exceptions.  Localization
     files can also adjust the date format and provide translations  of  strings
     used  by  some of the full-service macro packages; alter the input encoding
     (see the next section); and change the amount  of  supplemental  inter-sen‐
     tence  space.  For Eastern languages, the localization file defines charac‐
     ter classes and sets flags on them.  By default, [4mtroffrc[24m loads  the  local‐
     ization file for English.

     [4mtrans[24m  loads  localized  strings used by various macro packages after their
            localized forms have been prepared by a localization macro file.

     [4mgroff[24m provides the following localization files.

     [4mcs[24m     Czech; localizes [4mman[24m, [4mme[24m, [4mmm[24m, [4mmom[24m, and [4mms[24m.  Sets the input  encoding
            to Latin-2 by loading [4mlatin2.tmac[24m.

     [4mde[0m
     [4mden[24m    German; localizes [4mman[24m, [4mme[24m, [4mmm[24m, [4mmom[24m, and [4mms[24m.  Sets the input encoding
            to Latin-1 by loading [4mlatin1.tmac[24m.

            [4mde.tmac[24m  selects  hyphenation  patterns for traditional orthography,
            and [4mden.tmac[24m does the same for the new  orthography  (“Rechtschreib‐
            reform”).

     [4men[24m     English.  Sets the input encoding to Latin-1 by loading [4mlatin1.tmac[24m.

     [4mes[24m     Spanish;  localizes [4mman[24m, [4mme[24m, [4mmm[24m, [4mmom[24m, and [4mms[24m.  Sets the input encod‐
            ing to Latin-9 by loading [4mlatin9.tmac[24m.

     [4mfr[24m     French; localizes [4mman[24m, [4mme[24m, [4mmm[24m, [4mmom[24m, and [4mms[24m.  Sets the input encoding
            to Latin-9 by loading [4mlatin9.tmac[24m.

     [4mit[24m     Italian; localizes [4mman[24m, [4mme[24m, [4mmm[24m, [4mmom[24m, and [4mms[24m.  Sets the input  encod‐
            ing to Latin-1 by loading [4mlatin1.tmac[24m.

     [4mja[24m     Japanese.

     [4mpl[24m     Polish; localizes [4mman[24m, [4mme[24m, [4mmm[24m, [4mmom[24m, and [4mms[24m.  Sets the input encoding
            to Latin-2 by loading [4mlatin2.tmac[24m.

     [4mru[24m     Russian;  localizes [4mman[24m, [4mme[24m, [4mmm[24m, [4mmom[24m, and [4mms[24m.  Sets the input encod‐
            ing to KOI8-R by loading [4mkoi8-r.tmac[24m.

     [4msv[24m     Swedish; localizes [4mman[24m, [4mme[24m, [4mmm[24m, [4mmom[24m, and [4mms[24m.  Sets the input  encod‐
            ing  to Latin-1 by loading [4mlatin1.tmac[24m.  Some of the localization of
            the [4mmm[24m package is handled separately; see ]8;;man:groff_mmse(7)\[4mgroff_mmse[24m(7)]8;;\.

     [4mzh[24m     Chinese.

   [1mInput encodings[0m
     Localization influences automatic hyphenation in two distinct  but  related
     respects.   A  macro  file  specific to a character coding identifies which
     character codes correspond to letters expected in  the  language's  hyphen‐
     ation  pattern  files  and  sets up case equivalences for those letters.  A
     language's macro file determines which of these letters are  equivalent  to
     other letters for hyphenation purposes.

     For  example,  in  English,  the  letter  “ñ”  occurs  in  loan words.  The
     [4mlatin1.tmac[24m and [4mlatin9.tmac[24m macro files define a hyphenation code  for  “ñ”
     and  make “Ñ” equivalent to it.  The English localization file [4men.tmac[24m fur‐
     thermore makes “ñ” equivalent to “n”.  In Spanish ([4mes.tmac[24m),  however,  “ñ”
     and “n” are [4mnot[24m equivalent.  The language localization file loads an appro‐
     priate encoding localization file; a document need not do so directly.

     [4mlatin1[0m
     [4mlatin2[0m
     [4mlatin5[0m
     [4mlatin9[24m  support  the  ISO  Latin-1, Latin-2, Latin-5, and Latin-9 encodings
             (8859-1, 8859-2, 8859-9, and 8859-15, respectively).

     [4mkoi8-r[24m  supports the KOI8-R encoding.  KOI8-R  code  points  in  the  range
             0x80–0x9F  are  not  valid input to GNU [4mtroff[24m; see section “Identi‐
             fiers” in ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\.  This should be no impediment to practical doc‐
             uments, as these KOI8-R code points do not encode letters, but box-
             drawing symbols and characters that are better obtained via special
             character escape sequences; see ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\.

   [1mGeneral auxiliary packages[0m
     The macro packages in this section are not intended  for  stand-alone  use,
     but  can  add  functionality to any other macro package or to plain (“raw”)
     [4mgroff[24m documents.

     [4m62bit[24m      provides macros for addition, multiplication,  and  division  of
                62-bit  integers  (allowing safe multiplication of signed 31-bit
                integers, for example).

     [4mhdtbl[24m      allows the generation of tables using a syntax  similar  to  the
                HTML  table model.  This Heidelberger table macro package is not
                a preprocessor, which can be useful if the contents of table en‐
                tries are determined by macro calls  or  string  interpolations.
                Compare to ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\.  It works only with the [1mps [22mand [1mpdf [22moutput de‐
                vices.  See ]8;;man:groff_hdtbl(7)\[4mgroff_hdtbl[24m(7)]8;;\.

     [4mpapersize[24m  enables  the paper format to be set on the command line with the
                “[1m-d paper=[4m[22mfmt[24m” option to [4mtroff[24m.  Valid [4mfmt[24ms are the ISO and  DIN
                formats “[1mA0[22m–[1mA6[22m”, “[1mB0[22m–[1mB6[22m”, “[1mC0[22m–[1mC6[22m”, and “[1mD0[22m–[1mD6[22m”; the U.S. formats
                “[1mletter[22m”,   “[1mlegal[22m”,   “[1mtabloid[22m”,   “[1mledger[22m”,  “[1mstatement[22m”,  and
                “[1mexecutive[22m”; and the envelope formats  “[1mcom10[22m”,  “[1mmonarch[22m”,  and
                “[1mDL[22m”.   All  formats,  even those for envelopes, are in portrait
                orientation: the longer measurement is vertical.  Appending  “l”
                (ell)  to  any  of  these denotes landscape orientation instead.
                This macro file assumes one-inch horizontal  margins,  and  sets
                registers  recognized  by  the  [4mgroff[24m [4mman[24m, [4mmdoc[24m, [4mmm[24m, [4mmom[24m, and [4mms[0m
                packages to configure them accordingly.  If you  want  different
                margins,  you  will  need  to use those packages' facilities, or
                [4mtroff[24m [1mll [22mand/or [1mpo [22mrequests, to adjust them.  An  output  device
                typically  requires  command-line  options [1m-p [22mand [1m-l [22mto override
                the paper dimensions and orientation, respectively,  defined  in
                its  [4mDESC[24m file; see subsection “Paper format” of ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\.  This
                macro file is normally loaded at startup  by  the  [4mtroffrc[24m  file
                when formatting for a typesetter (but not a terminal).

     [4mpdfpic[24m     provides a single macro, [1mPDFPIC[22m, that operates in two modes.  If
                it is not used with [4mgropdf[24m, the given [4mfile[24m must be a PDF; [1mPDFPIC[0m
                then  relies  on  the external program ]8;;man:pdftops(1)\[4mpdftops[24m(1)]8;;\ to convert the
                PDF to an encapsulated PostScript (EPS) file and calls the [1mPSPIC[0m
                macro with which it shares an interface.  If output is to a  PDF
                document, [1mPDFPIC [22muses the “[1mpdf: pdfpic[22m” device extension command
                (see ]8;;man:gropdf(1)\[4mgropdf[24m(1)]8;;\); the given [4mfile[24m can then be a PDF or any graphic
                file format supported by [4mgropdf[24m.

                Since [1mPDFPIC [22mneeds to discover the width and height of the image
                (to check if sufficient room exists to place it on the page), it
                has dependencies on external programs as shown below.

                        ┌───────┬────────────┬─────────┬─────────────┐
                        │       │ [4mpdfinfo[24m(1) │ [4mfile[24m(1) │ [4midentify[24m(1) │
                        ├───────┼────────────┼─────────┼─────────────┤
                        │ [4m.pdf[24m  │     ✓      │    ✓    │      ✓      │
                        ├───────┼────────────┼─────────┼─────────────┤
                        │ [4m.jpg[24m  │     ✗      │    ✓    │      ✓      │
                        ├───────┼────────────┼─────────┼─────────────┤
                        │ [4m.jp2[24m  │     ✗      │    ✗    │      ✓      │
                        ├───────┼────────────┼─────────┼─────────────┤
                        │ other │     ✗      │    ✗    │      ✓      │
                        └───────┴────────────┴─────────┴─────────────┘

                To  include  image formats such as PNG, PAM, and GIF, [4mgropdf[24m re‐
                lies upon PerlMagick modules to embed the graphic.  They are not
                needed for the types listed in the table above.

                If the required programs are not available, [4mfile[24m is treated as a
                PDF; failure is likely if it is not one.

     [4mpic[24m        supplies definitions of the macros [1mPS[22m, [1mPE[22m, [1mPF[22m, and [1mPY[22m, used with
                the ]8;;man:pic(1)\[4mpic[24m(1)]8;;\ preprocessor.  They center each picture.  Use  it  if
                your document does not use a full-service macro package, or that
                package  does  not supply working [4mpic[24m macro definitions.  Except
                for [4mman[24m and [4mmdoc[24m, those provided with [4mgroff[24m already do  so  (ex‐
                ception: [4mmm[24m employs the name [1mPF [22mfor a different purpose).

     [4mpspic[24m      provides a macro, [1mPSPIC[22m, that includes a PostScript graphic in a
                document.   The  [1mps[22m, [1mdvi[22m, [1mhtml[22m, and [1mxhtml [22moutput devices support
                such inclusions; for all other drivers, the  image  is  replaced
                with  a  rectangular  border  of  the  same size.  [4mpspic.tmac[24m is
                loaded at startup by the [4mtroffrc[24m file.

                Its syntax is as follows.

                       [1m.PSPIC [22m[[1m-L[22m|[1m-R[22m|[1m-C[22m|[1m-I [4m[22mn[24m] [4mfile[24m [[4mwidth[24m [[4mheight[24m]]

                [4mfile[24m is the name of the PostScript file; [4mwidth[24m and  [4mheight[24m  give
                the  desired  width and height of the image.  If neither a [4mwidth[0m
                nor a [4mheight[24m argument is specified, the  image's  natural  width
                (as given in the file's bounding box) or the current line length
                is used as the width, whatever is smaller.  The [4mwidth[24m and [4mheight[0m
                arguments  may  have scaling units attached; the default scaling
                unit is [1mi[22m.  [1mPSPIC [22mscales the graphic uniformly in the horizontal
                and vertical directions so that it is no more  than  [4mwidth[24m  wide
                and  [4mheight[24m  high.   Option [1m-C [22mcenters the graphic horizontally;
                this is the default.   [1m-L  [22mand  [1m-R  [22mleft-  and  right-align  the
                graphic,  respectively.  [1m-I [22mindents the graphic by [4mn[24m (with a de‐
                fault scaling unit of [1mm[22m).

                To use [1mPSPIC [22mwithin a diversion, we recommend extending it  with
                the  following  code,  assuring  that the diversion's width com‐
                pletely covers the image's width.

                       .am PSPIC
                       .  vpt 0
                       \h'(\\n[ps-offset]u + \\n[ps-deswid]u)'
                       .  sp -1
                       .  vpt 1
                       ..

                Failure to load [1mPSPIC[22m's image argument is not  an  error.   (The
                [1mpsbb  [22mrequest  does  issue an error diagnostic.)  To make such a
                failure fatal, append to the [1mpspic*error-hook [22mmacro.

                       .am pspic*error-hook
                       .  ab
                       ..

     [4mptx[24m        provides a macro, [1mxx[22m, to format permuted index entries  as  pro‐
                duced  by the GNU ]8;;man:ptx(1)\[4mptx[24m(1)]8;;\ program.  If your formatting needs dif‐
                fer, copy the macro into your document and adapt it.

     [4mrfc1345[24m    defines special character escape sequences named for  the  glyph
                mnemonics specified in RFC 1345 and the digraph table of the Vim
                text editor.  See ]8;;man:groff_rfc1345(7)\[4mgroff_rfc1345[24m(7)]8;;\.

     [4msboxes[24m     offers  an  interface  to the “[1mpdf: background[22m” device extension
                command supported by ]8;;man:gropdf(1)\[4mgropdf[24m(1)]8;;\.  Using this  package,  [4mgroff[24m  [4mms[0m
                documents can draw colored rectangles beneath any output.

                [1m.BOXSTART SHADED [4m[22mcolor[24m [1mOUTLINED [4m[22mcolor[24m [1mINDENT [4m[22msize[24m [1mWEIGHT [4m[22msize[0m
                       begins  a  box, where the argument after [1mSHADED [22mgives the
                       fill color and that  after  [1mOUTLINED  [22mthe  border  color.
                       Omit  the  former  to get a borderless filled box and the
                       latter for a border with no fill.  The  specified  [1mWEIGHT[0m
                       is used if the box is [1mOUTLINED[22m.

                       [1mINDENT  [22mprecedes  a  value  that leaves a gap between the
                       border and the contents inside the box.

                       Each [4mcolor[24m must be a defined [4mgroff[24m color name,  and  each
                       [4msize[24m a valid [4mgroff[24m numeric expression.  The keyword/value
                       pairs can be specified in any order.

                Boxes can be stacked, so you can start a box within another box;
                usually  the  later  boxes  would be smaller than the containing
                box, but this is not enforced.  When using  [1mBOXSTART[22m,  the  left
                position  is the current indent minus the [1mINDENT [22min the command,
                and the right position is the left position  (calculated  above)
                plus the current line length and twice the indent.

                [1m.BOXSTOP[0m
                       takes no parameters.  It closes the most recently started
                       box  at  the  current  vertical position after adding its
                       [1mINDENT [22mspacing.

                Your [4mgroff[24m  documents  can  conditionally  exercise  the  [4msboxes[0m
                macros.  The register [1mGSBOX [22mis defined if the package is loaded,
                and  interpolates  a  true  value if the [1mpdf [22moutput device is in
                use.

                [4msboxes[24m furthermore hooks into the ]8;;man:groff_ms(7)\[4mgroff_ms[24m(7)]8;;\ package to receive
                notifications when footnotes are growing, so that it  can  close
                boxes  on a page before footnotes are printed.  When that condi‐
                tion obtains, [4msboxes[24m will close open boxes two points above  the
                footnote  separator  and  re-open  them on the next page.  (This
                amount probably will not match the box's [1mINDENT[22m.)

                See ]8;;file:///usr/share/doc/groff-1.24.0/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.0                       2026-02-03                      [4mgroff_tmac[24m(5)
────────────────────────────────────────────────────────────────────────────────
[4mgroff[24m(7)                Miscellaneous Information Manual                [4mgroff[24m(7)

[1mName[0m
     groff - GNU [4mroff[24m language reference

[1mDescription[0m
     [4mgroff[24m is short for GNU [4mroff[24m, a free reimplementation of the AT&T device-in‐
     dependent  [4mtroff[24m typesetting system.  See ]8;;man:roff(7)\[4mroff[24m(7)]8;;\ for a survey of and back‐
     ground on [4mroff[24m systems.

     This document is intended as a reference.  The primary [4mgroff[24m manual, [4mGroff:[0m
     [4mThe[24m [4mGNU[24m [4mImplementation[24m [4mof[24m [4mtroff[24m, by Trent A. Fisher and Werner Lemberg,  is
     a  better  resource for learners, containing many examples and much discus‐
     sion.  It is written in Texinfo; you can browse it interactively with “info
     groff”.  Additional formats, including plain text, HTML, TeX DVI, and  PDF,
     may be available in [4m/usr/share/doc/groff-1.24.0[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.  We say
     “the formatter” when speaking of behavior that is generally true  of  [4mtroff[0m
     and [4mnroff[24m programs.

     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.

[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 [1m\B [22mescape sequence tests its argument for validity as a numeric expres‐
     sion.

     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 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; use the no-break control character
     to  prevent  the  break.  Break suppression is its sole behavioral distinc‐
     tion.  Employing the no-break control character  to  invoke  requests  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
                occurence  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 “Gtroff Inter‐
     nals” 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.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 intelligble 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 identifer.  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  according
     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 interpreation 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‐
     pets  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.0                       2026-02-08                           [4mgroff[24m(7)
────────────────────────────────────────────────────────────────────────────────
[4mgroff_char[24m(7)           Miscellaneous Information Manual           [4mgroff_char[24m(7)

[1mName[0m
     groff_char - GNU [4mroff[24m special character and glyph repertoire

[1mDescription[0m
     The  GNU  [4mroff[24m typesetting system has a large glyph repertoire suitable for
     production of varied literary, professional,  technical,  and  mathematical
     documents.   [4mgroff[24m  works with [4mcharacters;[24m an output device renders [4mglyphs.[0m
     [4mgroff[24m’s  input  character  set  is  restricted  to  that  defined  by   the
     ISO  Latin‐1  (ISO  8859‐1)  standard.  For ease of document maintenance in
     UTF‐8 environments, it is advisable to use only  the  Unicode  basic  Latin
     code  points;  these correspond to ISO 646:1991 IRV (US‐ASCII), a subset of
     all of the foregoing which has only 94 visible, printable code points.   In
     [4mgroff,[24m  these are termed [4mordinary[24m [4mcharacters.[24m  Often, many more are desired
     in output.

     AT&T [4mtroff[24m in the 1970s faced a similar problem: the available typesetter’s
     glyph repertoire differed from that of the computers  that  controlled  it.
     [4mtroff[24m’s solution was a form of escape sequence known as a [4mspecial[24m [4mcharacter[0m
     to  access  several dozen additional glyphs available in the fonts prepared
     for mounting in the phototypesetter.  These glyphs were mapped onto a  two‐
     character name space for a degree of mnemonic convenience; for example, the
     escape sequence [1m\(aa [22mencoded an acute accent and [1m\(sc [22ma section sign.

     [4mgroff[24m  has  lifted  historical  [4mroff[24m  limitations on special character name
     lengths, but recognizes  and  retains  compatibility  with  the  historical
     names.   [4mgroff[24m  expands the lexicon of glyphs available by name and permits
     users to define their own special character escape sequences with the  [1mchar[0m
     request.  Special character names are [4mgroff[24m identifiers; see section “Iden‐
     tifiers” in ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\.  Our discussion uses the terms “glyph name” and “spe‐
     cial  character  name” interchangeably; we assume no character translations
     or redefinitions.

     This document lists all of the glyph names predefined by [4mgroff[24m’s  font  de‐
     scription  files  and  presents the systematic notation by which it enables
     access to arbitrary Unicode  code  points  and  construction  of  composite
     glyphs.   Glyphs  listed may be unavailable, or may vary in appearance, de‐
     pending on the output device and font chosen when the page  was  formatted.
     This page was rendered for device [1mutf8 [22mprimarily using font [1mR[22m.

     A  few  escape sequences that are not [4mgroff[24m special characters also produce
     glyphs; these exist for syntactical or historical reasons.  [1m\'[22m, [1m\`[22m, [1m\-[22m, and
     [1m\_ [22mare translated on input to the special character escape sequences [1m\[aa][22m,
     [1m\[ga][22m, [1m\[-][22m, and [1m\[ul][22m, respectively.  Others include  [1m\\[22m,  [1m\.  [22m(backslash‐
     dot), and [1m\e[22m; see ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\.  A small number of special characters represent
     glyphs  that are not encoded in Unicode; examples include the baseline rule
     [1m\[ru] [22mand the Bell System logo [1m\[bs].[0m

     In [4mgroff[24m, test support for any character (ordinary  or  special)  with  the
     conditional expression operator “[1mc[22m”.
            .ie c \[bs] \{Welcome to the \[bs] Bell System;
            did you get the Wehrmacht helmet or the Death Star?\}
            .el No Bell System logo.

     While  [4mgroff[24m  accepts eight‐bit encoded input, not all such code points are
     valid as input.  Character codes 0, 11, 13–31,  and  128–159  are  invalid.
     (This  is  all  C0  and C1 controls except for SOH through LF [Control+A to
     Control+J], and FF [Control+L].)  Some of these code  points  are  used  by
     [4mgroff[24m  for internal purposes, which is one reason it does not support UTF‐8
     natively.

   [1mFundamental character set[0m
     The ordinary characters catalogued above, plus the space, tab, newline, and
     leader (Control+A), form the fundamental character  set  for  [4mgroff[24m  input;
     anything in the language, even over one million code points in Unicode, can
     be  expressed  using it.  Code points in the range 33–126 comprise a common
     set of printable glyphs in all of the aforementioned ISO character encoding
     standards.  It is this character set and (with some noteworthy  exceptions)
     the corresponding glyph repertoire for which AT&T [4mtroff[24m was implemented.

     All of the following characters map to glyphs as you would expect.
           ┌───────────────────────────────────────────────────────────┐
           │ ! # $ % & ( ) * + , . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ? @ │
           │ A B C D E F G H I J K L M N O P Q R S T U V W X Y Z [ ] _ │
           │ a b c d e f g h i j k l m n o p q r s t u v w x y z { | } │
           └───────────────────────────────────────────────────────────┘
     The remaining ordinary characters surprise computing professionals and oth‐
     ers  intimately  familiar with the ISO character encodings.  The developers
     of AT&T [4mtroff[24m chose mappings for them that would be useful for  typesetting
     technical  literature in a broad range of scientific disciplines: Bell Labs
     used the system to prepare AT&T’s patent filings with the U.S.  government.
     Further,   the   prevailing  character  encoding  standard  in  the  1970s,
     USAS X3.4‐1968 (ASCII), deliberately supported semantic ambiguity  at  some
     code  points,  and outright substitution at several others, to suit the lo‐
     calization demands of various national standards bodies.

     The table below presents the seven exceptional code points with their typi‐
     cal keycap engravings, their glyph mappings and semantics in [4mroff[24m  systems,
     and  the  escape sequences producing the Unicode basic Latin character they
     replace.  The first, the neutral double quote, is a partial  exception  be‐
     cause it does represent itself, but since the [4mroff[24m language also uses it to
     quote  macro  arguments, [4mgroff[24m supports a special character escape sequence
     as an alternative form so that the glyph can be easily  included  in  macro
     arguments  without requiring the user to master the quoting rules that AT&T
     [4mtroff[24m required in that context.  (Some requests, like [1mds[22m, also treat [1m" [22mnon‐
     literally at the beginning of an argument.)  Furthermore, not  all  of  the
     special  character  escape  sequences are portable to AT&T [4mtroff[24m and all of
     its descendants; these [4mgroff[24m extensions are  presented  using  its  special
     character form [1m\[][22m, whereas portable special character escape sequences are
     shown  in  the  traditional  [1m\(  [22mform.  [1m\- [22mand [1m\e [22mare portable to all known
     [4mtroff[24ms.  [1m\e [22mmeans “the glyph of the current escape character”; it therefore
     can produce unexpected output if the [1mec [22mrequest is used.  On devices with a
     limited glyph repertoire, glyphs in the “keycap” and  “appearance”  columns
     on  the  same  row  of the table may look identical; except for the neutral
     double quote, this will [4mnot[24m be the case on  more‐capable  devices.   Review
     your document using as many different output devices as possible.

       ┌───────────────────────────────────────────────────────────────────┐
       │ Keycap   Appearance and meaning   Special character and meaning   │
       ├───────────────────────────────────────────────────────────────────┤
       │ "        " neutral double quote   \[dq] neutral double quote      │
       │ '        ’ closing single quote   \[aq] neutral apostrophe        │
       │ -        ‐ hyphen                 \- or \[-] minus sign/Unix dash │
       │ \        (escape character)       \e or \[rs] reverse solidus     │
       │ ^        ˆ modifier circumflex    \[ha] circumflex/caret/“hat”    │
       │ `        ‘ opening single quote   \(ga grave accent               │
       │ ~        ˜ modifier tilde         \[ti] tilde                     │
       └───────────────────────────────────────────────────────────────────┘

     The  hyphen‐minus  is  a particularly unfortunate case of overloading.  Its
     awkward name in ISO 8859 and later standards reflects the many distinguish‐
     able purposes to which it had already been put by the  1980s,  including  a
     hyphen,  a  minus  sign,  and  (alone  or  in repetition) dashes of varying
     widths.  For best results in [4mroff[24m systems, use the “[1m-[22m” character  in  input
     outside  an  escape sequence [4monly[24m to mean a hyphen, as in the phrase “long‐
     term”.  For a minus sign in running text or a Unix file  name  or  command‐
     line option dash, use [1m\- [22m(or [1m\[-] [22min [4mgroff[24m if you find it helps the clarity
     of  the source document).  (Another minus sign, for use in mathematical ex‐
     pressions, is available as [1m\(mi[22m.)  AT&T [4mtroff[24m supported em‐dashes as  [1m\(em[22m,
     as does [4mgroff[24m.

     The  special character escape sequence for the apostrophe as a neutral sin‐
     gle quote is typically needed only in technical content; typing words  like
     “can’t” and “Anne’s” in a natural way will render correctly, because in or‐
     dinary  prose an apostrophe is typeset either as a closing single quotation
     mark or as a neutral single quote, depending on  the  capabilities  of  the
     output  device.   By contrast, special character escape sequences should be
     used for quotation marks unless portability to limited or historical  [4mtroff[0m
     implementations  is necessary; on those systems, the input convention is to
     pair the grave accent with the apostrophe for single quotes, and to  double
     both  characters  for double quotes.  AT&T [4mtroff[24m defined no special charac‐
     ters for  quotation  marks  or  the  apostrophe.   Repeated  single  quotes
     (‘‘thus’’)  will be visually distinguishable from double quotes (“thus”) on
     terminal devices, and perhaps on others (depending on the font selected and
     its kerning configuration).
        ┌─────────────────────────────────────────────────────────────────┐
        │ AT&T [4mtroff[24m input          recommended [4mgroff[24m input               │
        ├─────────────────────────────────────────────────────────────────┤
        │ A Winter's Tale           A Winter's Tale                       │
        │ `U.K. outer quotes'       \[oq]U.K. outer quotes\[cq]           │
        │ `U.K. ``inner'' quotes'   \[oq]U.K. \[lq]inner\[rq] quotes\[cq] │
        │ ``U.S. outer quotes''     \[lq]U.S. outer quotes\[rq]           │
        │ ``U.S. `inner' quotes''   \[lq]U.S. \[oq]inner\[cq] quotes\[rq] │
        └─────────────────────────────────────────────────────────────────┘
     If you frequently require quotation marks in  your  document,  see  if  the
     macro  package you’re using supplies strings or macros to facilitate quota‐
     tion, or define them yourself (except in man pages).

     Using Unicode basic Latin characters to compose boxes and lines is  ill‐ad‐
     vised.   [4mroff[24m  systems  have  dedicated features for drawing horizontal and
     vertical lines, the [1m\l[22m, [1m\L[22m, and [1m\D [22mescape sequences.  Also  see  subsection
     “Rules  and  lines” below.  Preprocessors like ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\ and ]8;;man:pic(1)\[4mpic[24m(1)]8;;\ draw boxes
     and will produce the best possible output for the device, falling  back  to
     basic Latin glyphs only when necessary.

   [1mEight‐bit encodings and Latin‐1 supplement[0m
     ISO  646  is a seven‐bit code encoding 128 code points; eight‐bit codes are
     twice the size.  ISO Latin‐1 (8859‐1) allocated  the  additional  space  to
     what Unicode calls “C1 controls” (control characters) and the “Latin‐1 sup‐
     plement”.   The  C1  controls are neither printable nor usable as GNU [4mtroff[0m
     input.

     GNU [4mtroff[24m handles two Latin‐1 supplement characters  specially,  and  never
     produces them as output.

     NBSP   encodes a no‐break space; it maps to [1m\~[22m, the adjustable non‐breaking
            space escape sequence.

     SHY    encodes a soft hyphen; it maps to [1m\%[22m, the hyphenation control escape
            sequence.

     The  remaining  characters  in the Latin‐1 supplement represent themselves.
     Although they can be specified directly with the keyboard on  systems  con‐
     figured to use Latin‐1 as the character encoding, it is more portable, both
     to other [4mroff[24m systems and to UTF‐8 environments, to use their special char‐
     acter  escape  sequences,  shown  below.  The glyph descriptions we use are
     non‐standard in some cases, for brevity.

     ¡  \[r!] inverted exclamation mark     Ñ  \[~N] N tilde
     ¢  \[ct] cent sign                     Ò  \[`O] O grave
     £  \[Po] pound sign                    Ó  \['O] O acute
     ¤  \[Cs] currency sign                 Ô  \[^O] O circumflex
     ¥  \[Ye] yen sign                      Õ  \[~O] O tilde
     ¦  \[bb] broken bar                    Ö  \[:O] O dieresis
     §  \[sc] section sign                  ×  \[mu] multiplication sign
     ¨  \[ad] dieresis accent               Ø  \[/O] O slash
     ©  \[co] copyright sign                Ù  \[`U] U grave
     ª  \[Of] feminine ordinal indicator    Ú  \['U] U acute
     «  \[Fo] left double chevron           Û  \[^U] U circumflex
     ¬  \[no] logical not                   Ü  \[:U] U dieresis
     ®  \[rg] registered sign               Ý  \['Y] Y acute
     ¯  \[a-] macron accent                 Þ  \[TP] uppercase thorn
     °  \[de] degree sign                   ß  \[ss] lowercase sharp s
     ±  \[+-] plus‐minus                    à  \[`a] a grave
     ²  \[S2] superscript two               á  \['a] a acute
     ³  \[S3] superscript three             â  \[^a] a circumflex
     ´  \[aa] acute accent                  ã  \[~a] a tilde
     µ  \[mc] micro sign                    ä  \[:a] a dieresis
     ¶  \[ps] pilcrow sign                  å  \[oa] a ring
     ·  \[pc] centered period               æ  \[ae] ae ligature
     ¸  \[ac] cedilla accent                ç  \[,c] c cedilla
     ¹  \[S1] superscript one               è  \[`e] e grave
     º  \[Om] masculine ordinal indicator   é  \['e] e acute
     »  \[Fc] right double chevron          ê  \[^e] e circumflex
     ¼  \[14] one quarter symbol            ë  \[:e] e dieresis
     ½  \[12] one half symbol               ì  \[`i] i grave
     ¾  \[34] three quarters symbol         í  \['i] e acute
     ¿  \[r?] inverted question mark        î  \[^i] i circumflex
     À  \[`A] A grave                       ï  \[:i] i dieresis
     Á  \['A] A acute                       ð  \[Sd] lowercase eth
     Â  \[^A] A circumflex                  ñ  \[~n] n tilde
     Ã  \[~A] A tilde                       ò  \[`o] o grave
     Ä  \[:A] A dieresis                    ó  \['o] o acute
     Å  \[oA] A ring                        ô  \[^o] o circumflex
     Æ  \[AE] AE ligature                   õ  \[~o] o tilde
     Ç  \[,C] C cedilla                     ö  \[:o] o dieresis
     È  \[`E] E grave                       ÷  \[di] division sign
     É  \['E] E acute                       ø  \[/o] o slash
     Ê  \[^E] E circumflex                  ù  \[`u] u grave
     Ë  \[:E] E dieresis                    ú  \['u] u acute
     Ì  \[`I] I grave                       û  \[^u] u circumflex
     Í  \['I] I acute                       ü  \[:u] u dieresis
     Î  \[^I] I circumflex                  ý  \['y] y acute
     Ï  \[:I] I dieresis                    þ  \[Tp] lowercase thorn
     Ð  \[-D] uppercase eth                 ÿ  \[:y] y dieresis

   [1mSpecial character escape forms[0m
     Glyphs that lack a character code in the basic Latin repertoire to directly
     represent them are entered by  one  of  several  special  character  escape
     forms.  Such glyphs can be simple or composite, and accessed either by name
     or numerically by code point.  Code points and combining properties are de‐
     termined  by character encoding standards, whereas glyph names as used here
     originated in AT&T [4mtroff[24m special character  escape  sequences.   Predefined
     glyph names use only characters in the basic Latin repertoire.

     [1m\([4m[22mgl[24m   is  a  special character escape sequence for the glyph with the two‐
            character name [4mgl[24m.  This is the original syntax  form  supported  by
            AT&T [4mtroff[24m.  The acute accent, [1m\(aa[22m, is an example.

     [1m\C'[4m[22mglyph‐name[24m[1m'[0m
            is  a special character escape sequence for [4mglyph‐name[24m, which can be
            of arbitrary length.  The delimiter, shown here as a  neutral  apos‐
            trophe, can be any character not occurring in [4mglyph‐name[24m.  This syn‐
            tax form was introduced in later versions of AT&T device‐independent
            [4mtroff[24m.   The  foregoing  acute  accent  example  can be expressed as
            [1m\C'aa'[22m.

     [1m\[[4m[22mglyph‐name[24m[1m][0m
            is a special character escape sequence for [4mglyph‐name[24m, which can  be
            of  arbitrary  length  but must not contain a closing square bracket
            “[1m][22m”.  (No glyph names predefined by [4mgroff[24m employ “[1m][22m”.)  The  forego‐
            ing acute accent example can be expressed in in GNU [4mtroff[24m as [1m\[aa][22m.

     [1m\C'[4m[22mc[24m[1m' [22mand [1m\[[4m[22mc[24m[1m] [22mare not synonyms for the ordinary character “[4mc[24m”, but request
     the  special  character  named  “[1m\[4m[22mc[24m”.   For example, “[1m\[a][22m” is not “a”, but
     rather a special character with the internal glyph name (used in  font  de‐
     scription  files and diagnostic messages) [1m\a[22m, which is typically undefined.
     The only such glyph name [4mgroff[24m predefines is  the  minus  sign,  which  can
     therefore be accessed as [1m\C'-' [22mor [1m\[-][22m.

     [1m\[[4m[22mbase‐char[24m [4mcomposite‐1[24m [4mcomposite‐2[24m ... [4mcomposite‐n[24m[1m][0m
            is a composite glyph.  Glyphs like a lowercase “e” with an acute ac‐
            cent, as in the word “café”, can be expressed as [1m\[e aa][22m.

     Normally,  the formatter advances the drawing position after setting a spe‐
     cial character, as it does for ordinary ones.   [4mgroff[24m’s  [1mcomposite  [22mrequest
     designates a special character as combining, suppressing advancement.

     You can obtain a report of mappings defined by the [1mcomposite [22mrequest on the
     standard  error  stream  with  the  [1mpcomposite [22mrequest.  The [4mcomposite.tmac[0m
     macro file, loaded automatically by the default [4mtroffrc[24m, maps certain  spe‐
     cial  characters  to  combining characters as shown in subsection “Accents”
     below.

     Unicode encodes far more characters than [4mgroff[24m has names for; special char‐
     acter escape forms based on numerical code points enable access to  any  of
     them.   Frequently  used  glyphs  or  glyph  combinations  can be stored in
     strings, and new glyph names can be created [4mad[24m [4mhoc[24m with the  [1mchar  [22mrequest;
     see ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\.

     [1m\[u[4m[22mnnnn[24m[[4mn[24m[[4mn[24m]][1m][0m
            is a Unicode numeric special character escape sequence.  Any Unicode
            code point can be accessed with four to six hexadecimal digits, with
            hexadecimal letters accepted in uppercase form only.  Thus, [1m\[u02DA][0m
            accesses the (spacing) ring accent, producing “˚”.

     Unicode  code  points can be composed as well; when they are, GNU [4mtroff[24m re‐
     quires NFD (Normalization Form D), where all Unicode glyphs  are  maximally
     decomposed.   (Exception:  precomposed characters in the Latin‐1 supplement
     described above are also accepted.  Do not count on this exception  remain‐
     ing  in  a  future GNU [4mtroff[24m that accepts UTF‐8 input directly.)  Thus, GNU
     [4mtroff[24m accepts “caf[1m\['e][22m”, “caf[1m\[e aa][22m”, and “caf[1m\[u0065_0301][22m”, as ways  to
     input  “café”.  (Due to its legacy 8‐bit encoding compatibility, at present
     it also accepts “caf[1m\[u00E9][22m” on ISO Latin‐1 systems.)

     [1m\[u[4m[22mbase‐char[24m[[1m_[4m[22mcombining‐component[24m]...]
            constructs a composite glyph from Unicode numeric special  character
            escape sequences.  The code points of the base glyph and the combin‐
            ing components are each expressed in hexadecimal, with an underscore
            ([1m_[22m) separating each component.  Thus, [1m\[u006E_0303] [22mproduces “ñ”.

     [1m\[char[4m[22mnnn[24m[1m][0m
            expresses an eight‐bit code point where [4mnnn[24m is the code point of the
            character,  a  decimal  number between 0 and 255 without leading ze‐
            roes.  This legacy numeric special character escape sequence is used
            to map characters onto glyphs via the [1mtrin [22mrequest  in  macro  files
            loaded by ]8;;man:grotty(1)\[4mgrotty[24m(1)]8;;\.

[1mGlyph tables[0m
     In  this  section,  [4mgroff[24m’s  glyph  name repertoire is presented in tabular
     form.  The meanings of the columns are as follows.

     [1mOutput   [22mshows the glyph as it appears on the device used  to  render  this
              document;  although it can have a notably different shape on other
              devices (and is subject to user‐directed translation and  replace‐
              ment),  [4mgroff[24m  attempts  reasonable  equivalency on all output de‐
              vices.

     [1mInput    [22mshows the [4mgroff[24m character (ordinary or special) that normally pro‐
              duces the glyph.  Some code points have multiple glyph names.

     [1mUnicode  [22mis the code point notation for the glyph or  combining  glyph  se‐
              quence as described in subsection “Special character escape forms”
              above.   It corresponds to the standard notation for Unicode short
              identifiers such that [4mgroff[24m’s [1mu[4m[22mnnnn[24m  is  equivalent  to  Unicode’s
              U+[4mnnnn[24m.

     [1mNotes    [22mdescribes  the  glyph, elucidating the mnemonic value of the glyph
              name where possible.

              A plus sign “+” indicates that the glyph name appears in the  AT&T
              [4mtroff[24m  user’s  manual,  CSTR  #54 (1992 revision).  When using the
              AT&T special character syntax [1m\([4m[22mxx[24m, widespread portability can  be
              expected from such names.

              Entries marked with “***” denote glyphs used for mathematical pur‐
              poses.   On  typesetting  devices, such glyphs are typically drawn
              from a [4mspecial[24m font (see ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\).  Often, such glyphs  lack
              bold  or  italic style forms or have metrics that look incongruous
              in ordinary prose.  A few that are not uncommon  in  running  text
              have  “text  variants”,  which should work better in that context.
              Conversely, a handful of glyphs that are  normally  drawn  from  a
              text  font may be required in mathematical expressions.  Both sets
              of exceptions are noted in the tables where they appear  (“Logical
              symbols” and “Mathematical symbols”).

   [1mBasic Latin[0m
     Apart  from basic Latin characters with special mappings, described in sub‐
     section “Fundamental character set” above, a few others in that range  have
     special  character  glyph  names.   These were defined for ease of input on
     non‐U.S. keyboards lacking keycaps for them, or  for  symmetry  with  other
     special character glyph names serving a similar purpose.

     The  vertical  bar  is overloaded; the [1m\[ba] [22mand [1m\[or] [22mescape sequences may
     render differently.  See subsection “Mathematical symbols”  below  for  un‐
     styled  variants  of  the plus, minus, and equals signs normally drawn from
     this range.

     Output   Input   Unicode   Notes
     ───────────────────────────────────────────────────────────────────────────
     "        \[dq]   u0022     neutral double quote
     #        \[sh]   u0023     number sign
     $        \[Do]   u0024     dollar sign
     '        \[aq]   u0027     apostrophe, neutral single quote
     /        \[sl]   u002F     slash, solidus +
     @        \[at]   u0040     at sign
     [        \[lB]   u005B     left square bracket
     \        \[rs]   u005C     reverse solidus
     ]        \[rB]   u005D     right square bracket
     ^        \[ha]   u005E     circumflex, caret, “hat”
     {        \[lC]   u007B     left brace
     |        |       u007C     bar +
     |        \[ba]   u007C     bar
     |        \[or]   u007C     bitwise or +
     }        \[rC]   u007D     right brace
     ~        \[ti]   u007E     tilde

   [1mSupplementary Latin letters[0m
     Historically, [1m\[ss] [22mdeveloped from a ligature of “sz”.  An  uppercase  form
     is  available  as [1m\[u1E9E][22m, but in the German language it is of specialized
     use; ß does [4mnot[24m normally uppercase‐transform to it,  but  rather  to  “SS”.
     “Lowercase  f  with hook” is also used as a function symbol; see subsection
     “Mathematical symbols” below.

     Output   Input   Unicode   Notes
     ───────────────────────────────────────────────────────────────────────────
     Ð        \[-D]   u00D0     uppercase eth
     ð        \[Sd]   u00F0     lowercase eth
     Þ        \[TP]   u00DE     uppercase thorn
     þ        \[Tp]   u00FE     lowercase thorn
     ß        \[ss]   u00DF     lowercase sharp s
     ı        \[.i]   u0131     i without tittle
     ȷ        \[.j]   u0237     j without tittle
     ƒ        \[Fn]   u0192     lowercase f with hook, function
     Ł        \[/L]   u0141     L with stroke
     ł        \[/l]   u0142     l with stroke
     Ø        \[/O]   u00D8     O with stroke
     ø        \[/o]   u00F8     o with stroke

   [1mLigatures and digraphs[0m
     Output   Input   Unicode           Notes
     ───────────────────────────────────────────────────────────────────────────
     ff       \[ff]   u0066_0066        ff ligature +
     fi       \[fi]   u0066_0069        fi ligature +
     fl       \[fl]   u0066_006C        fl ligature +
     ffi      \[Fi]   u0066_0066_0069   ffi ligature +
     ffl      \[Fl]   u0066_0066_006C   ffl ligature +
     Æ        \[AE]   u00C6             AE ligature
     æ        \[ae]   u00E6             ae ligature
     Œ        \[OE]   u0152             OE ligature
     œ        \[oe]   u0153             oe ligature
     Ĳ        \[IJ]   u0132             IJ digraph
     ĳ        \[ij]   u0133             ij digraph

   [1mAccents[0m
     The non‐combining code point in parentheses is used when the special  char‐
     acter occurs in isolation (compare “[1mcaf\[e aa][22m” and “[1mcaf\[aa]e[22m”).

     Output   Input   Unicode         Notes
     ───────────────────────────────────────────────────────────────────────────
     ˝        \[a"]   u030B (u02DD)   double acute accent
     ¯        \[a-]   u0304 (u00AF)   macron accent
     ˙        \[a.]   u0307 (u02D9)   dot accent
     ^        \[a^]   u0302 (u005E)   circumflex accent
     ´        \[aa]   u0301 (u00B4)   acute accent +
     `        \[ga]   u0300 (u0060)   grave accent +
     ˘        \[ab]   u0306 (u02D8)   breve accent
     ¸        \[ac]   u0327 (u00B8)   cedilla accent
     ¨        \[ad]   u0308 (u00A8)   dieresis accent
     ˇ        \[ah]   u030C (u02C7)   caron accent
     ˚        \[ao]   u030A (u02DA)   ring accent
     ~        \[a~]   u0303 (u007E)   tilde accent
     ˛        \[ho]   u0328 (u02DB)   hook accent

   [1mAccented characters[0m
     All  of  these  glyphs  can  be composed using combining glyph names as de‐
     scribed in subsection “Special character escape forms” above; the names be‐
     low are short aliases for convenience.

     Output   Input   Unicode      Notes
     ───────────────────────────────────────────────────────────────────────────
     Á        \['A]   u0041_0301   A acute
     Ć        \['C]   u0043_0301   C acute
     É        \['E]   u0045_0301   E acute
     Í        \['I]   u0049_0301   I acute
     Ó        \['O]   u004F_0301   O acute
     Ú        \['U]   u0055_0301   U acute
     Ý        \['Y]   u0059_0301   Y acute
     á        \['a]   u0061_0301   a acute
     ć        \['c]   u0063_0301   c acute
     é        \['e]   u0065_0301   e acute
     í        \['i]   u0069_0301   i acute
     ó        \['o]   u006F_0301   o acute
     ú        \['u]   u0075_0301   u acute
     ý        \['y]   u0079_0301   y acute

     Ä        \[:A]   u0041_0308   A dieresis
     Ë        \[:E]   u0045_0308   E dieresis
     Ï        \[:I]   u0049_0308   I dieresis
     Ö        \[:O]   u004F_0308   O dieresis
     Ü        \[:U]   u0055_0308   U dieresis
     Ÿ        \[:Y]   u0059_0308   Y dieresis
     ä        \[:a]   u0061_0308   a dieresis
     ë        \[:e]   u0065_0308   e dieresis
     ï        \[:i]   u0069_0308   i dieresis
     ö        \[:o]   u006F_0308   o dieresis
     ü        \[:u]   u0075_0308   u dieresis
     ÿ        \[:y]   u0079_0308   y dieresis

     Â        \[^A]   u0041_0302   A circumflex
     Ê        \[^E]   u0045_0302   E circumflex
     Î        \[^I]   u0049_0302   I circumflex
     Ô        \[^O]   u004F_0302   O circumflex
     Û        \[^U]   u0055_0302   U circumflex
     â        \[^a]   u0061_0302   a circumflex
     ê        \[^e]   u0065_0302   e circumflex
     î        \[^i]   u0069_0302   i circumflex
     ô        \[^o]   u006F_0302   o circumflex
     û        \[^u]   u0075_0302   u circumflex

     À        \[`A]   u0041_0300   A grave
     È        \[`E]   u0045_0300   E grave
     Ì        \[`I]   u0049_0300   I grave
     Ò        \[`O]   u004F_0300   O grave
     Ù        \[`U]   u0055_0300   U grave
     à        \[`a]   u0061_0300   a grave
     è        \[`e]   u0065_0300   e grave
     ì        \[`i]   u0069_0300   i grave
     ò        \[`o]   u006F_0300   o grave
     ù        \[`u]   u0075_0300   u grave

     Ã        \[~A]   u0041_0303   A tilde
     Ñ        \[~N]   u004E_0303   N tilde
     Õ        \[~O]   u004F_0303   O tilde
     ã        \[~a]   u0061_0303   a tilde
     ñ        \[~n]   u006E_0303   n tilde
     õ        \[~o]   u006F_0303   o tilde

     Š        \[vS]   u0053_030C   S caron
     š        \[vs]   u0073_030C   s caron
     Ž        \[vZ]   u005A_030C   Z caron
     ž        \[vz]   u007A_030C   z caron

     Ç        \[,C]   u0043_0327   C cedilla
     ç        \[,c]   u0063_0327   c cedilla

     Å        \[oA]   u0041_030A   A ring
     å        \[oa]   u0061_030A   a ring

   [1mQuotation marks[0m
     The neutral double quote, useful in documenting programming  languages,  is
     also available as a special character for convenient embedding in macro ar‐
     guments; see subsection “Fundamental character set” above.

     Output   Input   Unicode   Notes
     ───────────────────────────────────────────────────────────────────────────
     „        \[Bq]   u201E     low double comma quote
     ‚        \[bq]   u201A     low single comma quote
     “        \[lq]   u201C     left double quote
     ”        \[rq]   u201D     right double quote
     ‘        \[oq]   u2018     single opening (left) quote
     ’        \[cq]   u2019     single closing (right) quote
     '        \[aq]   u0027     apostrophe, neutral single quote
     "        "       u0022     neutral double quote
     "        \[dq]   u0022     neutral double quote
     «        \[Fo]   u00AB     left double chevron
     »        \[Fc]   u00BB     right double chevron
     ‹        \[fo]   u2039     left single chevron
     ›        \[fc]   u203A     right single chevron

   [1mPunctuation[0m
     The Unicode name for U+00B7 is “middle dot”, which is unfortunately confus‐
     able with the [4mgroff[24m mnemonic for the visually similar but semantically dis‐
     tinct multiplication dot; see subsection “Mathematical symbols” below.

     Output   Input   Unicode   Notes
     ───────────────────────────────────────────────────────────────────────────
     ¡        \[r!]   u00A1     inverted exclamation mark
     ¿        \[r?]   u00BF     inverted question mark
     ·        \[pc]   u00B7     centered period
     ——       \[em]   u2014     em‐dash +
     –        \[en]   u2013     en‐dash
     ‐        -       u2010     hyphen +
     ‐        \[hy]   u2010     hyphen +

   [1mBrackets[0m
     On  typesetting  devices, the bracket extensions are font‐invariant glyphs;
     that is, they are rendered the same way regardless of font (with a  drawing
     escape  sequence).   On  terminals, they are [4mnot[24m font‐invariant; [4mgroff[24m maps
     them arbitrarily to U+23AA (“curly bracket  extension”).   In  AT&T  [4mtroff[24m,
     only  one  glyph  was  available to vertically extend brackets, braces, and
     parentheses: [1m\(bv[22m.

     Not all devices supply bracket pieces that can be piled up with [1m\b  [22mdue  to
     the  restrictions of the formatter’s piling algorithm.  The following macro
     offers a more general bracket‐building solution.
            .\" Make a pile centered vertically 0.5em above the baseline.
            .\" The first argument is placed at the top.
            .\" The pile is returned in string 'pile'.
            .eo
            .de pile-make
            .  nr pile-wd 0
            .  nr pile-ht 0
            .  ds pile-args
            .
            .  nr pile-# \n[.$]
            .  while \n[pile-#] \{\
            .    nr pile-wd (\n[pile-wd] >? \w'\$[\n[pile-#]]')
            .    nr pile-ht +(\n[rst] - \n[rsb])
            .    as pile-args \v'\n[rsb]u'\"
            .    as pile-args \Z'\$[\n[pile-#]]'\"
            .    as pile-args \v'-\n[rst]u'\"
            .    nr pile-# -1
            .  \}
            .
            .  ds pile \v'(-0.5m + (\n[pile-ht]u / 2u))'\"
            .  as pile \*[pile-args]\"
            .  as pile \v'((\n[pile-ht]u / 2u) + 0.5m)'\"
            .  as pile \h'\n[pile-wd]u'\"
            ..
            .ec

     Further complicating matters  is  that  some  glyphs  representing  bracket
     pieces  in  AT&T  [4mtroff[24m can be used for other mathematical symbols as well;
     for example, [1m\(lf [22mand [1m\(rf [22mprovide the floor  operator.   Some  output  de‐
     vices,  such  as [1mdvi[22m, don’t unify such glyphs.  For this reason, the glyphs
     [1m\[lf][22m, [1m\[rf][22m, [1m\[lc][22m, and [1m\[rc] [22mare not unified with similar‐looking bracket
     pieces.  In [4mgroff[24m, only glyphs with long names are guaranteed  to  pile  up
     correctly for all devices——provided those glyphs are available.

     Output   Input               Unicode   Notes
     ───────────────────────────────────────────────────────────────────────────
     [        [                   u005B     left square bracket
     [        \[lB]               u005B     left square bracket
     ]        ]                   u005D     right square bracket
     ]        \[rB]               u005D     right square bracket
     {        {                   u007B     left brace
     {        \[lC]               u007B     left brace
     }        }                   u007D     right brace
     }        \[rC]               u007D     right brace
     ⟨        \[la]               u27E8     left angle bracket
     ⟩        \[ra]               u27E9     right angle bracket
     ⎪        \[bv]               u23AA     brace vertical extension + ***
     ⎪        \[braceex]          u23AA     brace vertical extension

     ⎡        \[bracketlefttp]    u23A1     left square bracket top
     ⎢        \[bracketleftex]    u23A2     left square bracket extension
     ⎣        \[bracketleftbt]    u23A3     left square bracket bottom

     ⎤        \[bracketrighttp]   u23A4     right square bracket top
     ⎥        \[bracketrightex]   u23A5     right square bracket extension
     ⎦        \[bracketrightbt]   u23A6     right square bracket bottom

     ⎧        \[lt]               u23A7     left brace top +
     ⎨        \[lk]               u23A8     left brace middle +
     ⎩        \[lb]               u23A9     left brace bottom +
     ⎧        \[bracelefttp]      u23A7     left brace top
     ⎨        \[braceleftmid]     u23A8     left brace middle
     ⎩        \[braceleftbt]      u23A9     left brace bottom
     ⎪        \[braceleftex]      u23AA     left brace extension

     ⎫        \[rt]               u23AB     right brace top +
     ⎬        \[rk]               u23AC     right brace middle +
     ⎭        \[rb]               u23AD     right brace bottom +
     ⎫        \[bracerighttp]     u23AB     right brace top
     ⎬        \[bracerightmid]    u23AC     right brace middle
     ⎭        \[bracerightbt]     u23AD     right brace bottom
     ⎪        \[bracerightex]     u23AA     right brace extension

     ⎛        \[parenlefttp]      u239B     left parenthesis top
     ⎜        \[parenleftex]      u239C     left parenthesis extension
     ⎝        \[parenleftbt]      u239D     left parenthesis bottom
     ⎞        \[parenrighttp]     u239E     right parenthesis top
     ⎟        \[parenrightex]     u239F     right parenthesis extension
     ⎠        \[parenrightbt]     u23A0     right parenthesis bottom

   [1mArrows[0m
     Output   Input   Unicode   Notes
     ───────────────────────────────────────────────────────────────────────────
     ←        \[<-]   u2190     horizontal arrow left +
     →        \[->]   u2192     horizontal arrow right +
     ↔        \[<>]   u2194     bidirectional horizontal arrow
     ↓        \[da]   u2193     vertical arrow down +
     ↑        \[ua]   u2191     vertical arrow up +
     ↕        \[va]   u2195     bidirectional vertical arrow
     ⇐        \[lA]   u21D0     horizontal double arrow left
     ⇒        \[rA]   u21D2     horizontal double arrow right
     ⇔        \[hA]   u21D4     bidirectional horizontal double arrow
     ⇓        \[dA]   u21D3     vertical double arrow down
     ⇑        \[uA]   u21D1     vertical double arrow up
     ⇕        \[vA]   u21D5     bidirectional vertical double arrow
     ⎯        \[an]   u23AF     horizontal arrow extension

   [1mRules and lines[0m
     On  typesetting  devices, the font‐invariant glyphs (see subsection “Brack‐
     ets” above) [1m\[br][22m, [1m\[ul][22m, and [1m\[rn] [22mform corners when adjacent; they can be
     used to build boxes.  On terminal devices, they are mapped as shown in  the
     table.  The Unicode‐derived names of these three glyphs are approximations.

     The ordinary character [1m_ [22maccesses the underscore glyph in a font; [1m\[ul][22m, by
     contrast, may be font‐invariant on typesetting devices.

     The  baseline  rule  [1m\[ru] [22mis a font‐invariant glyph, namely a rule of one‐
     half em.

     In AT&T [4mtroff[24m, [1m\[rn] [22malso served as a one en extension of the  square  root
     symbol.  [4mgroff[24m favors [1m\[radicalex] [22mfor this purpose; see subsection “Mathe‐
     matical symbols” below.

     Output   Input   Unicode   Notes
     ───────────────────────────────────────────────────────────────────────────
     |        |       u007C     bar
     |        \[ba]   u007C     bar
     │        \[br]   u2502     box rule +
     _        _       u005F     underscore, low line +
     _        \[ul]   ‐‐‐       underrule +
     ‾        \[rn]   u203E     overline +
     _        \[ru]   ‐‐‐       baseline rule +
     ¦        \[bb]   u00A6     broken bar
     /        /       u002F     slash, solidus +
     /        \[sl]   u002F     slash, solidus +
     \        \[rs]   u005C     reverse solidus

   [1mText markers[0m
     Output   Input   Unicode   Notes
     ───────────────────────────────────────────────────────────────────────────
     ○        \[ci]   u25CB     circle +
     •        \[bu]   u2022     bullet +
     †        \[dg]   u2020     dagger +
     ‡        \[dd]   u2021     double dagger +
     ◊        \[lz]   u25CA     lozenge, diamond
     □        \[sq]   u25A1     square +
     ¶        \[ps]   u00B6     pilcrow sign
     §        \[sc]   u00A7     section sign +
     ☜        \[lh]   u261C     hand pointing left +
     ☞        \[rh]   u261E     hand pointing right +
     @        @       u0040     at sign
     @        \[at]   u0040     at sign
     #        #       u0023     number sign
     #        \[sh]   u0023     number sign
     ↵        \[CR]   u21B5     carriage return
     ✓        \[OK]   u2713     check mark

   [1mLegal symbols[0m
     The Bell System logo is not supported in [4mgroff[24m.

     Output   Input   Unicode   Notes
     ───────────────────────────────────────────────────────────────────────────
     ©        \[co]   u00A9     copyright sign +
     ®        \[rg]   u00AE     registered sign +
     ™        \[tm]   u2122     trade mark sign
              \[bs]   ‐‐‐       Bell System logo +

   [1mCurrency symbols[0m
     Output   Input   Unicode   Notes
     ───────────────────────────────────────────────────────────────────────────
     $        $       u0024     dollar sign
     $        \[Do]   u0024     dollar sign
     ¢        \[ct]   u00A2     cent sign +
     €        \[eu]   u20AC     Euro sign
     €        \[Eu]   u20AC     variant Euro sign
     ¥        \[Ye]   u00A5     yen sign
     £        \[Po]   u00A3     pound sign
     ¤        \[Cs]   u00A4     currency sign

   [1mUnits[0m
     Output   Input   Unicode   Notes
     ───────────────────────────────────────────────────────────────────────────
     °        \[de]   u00B0     degree sign +
     ‰        \[%0]   u2030     per thousand, per mille sign
     ′        \[fm]   u2032     arc minute sign, foot mark +
     ″        \[sd]   u2033     arc second sign
     µ        \[mc]   u00B5     micro sign
     ª        \[Of]   u00AA     feminine ordinal indicator
     º        \[Om]   u00BA     masculine ordinal indicator

   [1mLogical symbols[0m
     The  variants of the not sign may differ in appearance or spacing depending
     on the device and font selected.  Unicode does not encode a discrete  “bit‐
     wise  or”  sign:  on typesetting devices, it is drawn shorter than the bar,
     about the same height as a capital letter.  Terminal  devices  unify  [1m\[ba][0m
     and [1m\[or][22m.

     Output   Input    Unicode   Notes
     ───────────────────────────────────────────────────────────────────────────
     ∧        \[AN]    u2227     logical and
     ∨        \[OR]    u2228     logical or
     ¬        \[no]    u00AC     logical not + ***
     ¬        \[tno]   u00AC     text variant of [1m\[no][0m
     ∃        \[te]    u2203     there exists
     ∀        \[fa]    u2200     for all
     ∋        \[st]    u220B     such that
     ∴        \[3d]    u2234     therefore
     ∴        \[tf]    u2234     therefore
     |        |        u007C     bar +
     |        \[or]    u007C     bitwise or +

   [1mMathematical symbols[0m
     [1m\[Fn]  [22malso appears in subsection “Supplementary Latin letters” above.  The
     plus‐minus, multiplication, and division signs, [1m\[+-][22m,  [1m\[mu][22m,  and  [1m\[di][22m,
     are normally drawn from the special font, but have text font variants.  The
     plus,  minus, and equals signs are normally drawn from text fonts, but have
     special font variants.  Variants may differ in appearance  or  spacing  de‐
     pending on the device and font selected.

     In AT&T [4mtroff[24m, [1m\(rn [22m(“root en extender”) served as the horizontal extension
     of  the  radical  (square  root)  sign,  [1m\(sr[22m, and was drawn at the maximum
     height of the typeface’s bounding box, enabling it to double as an overline
     (see subsection “Rules and lines” above).  A  contemporary  font’s  radical
     sign  might  not  ascend to such an extreme.  In [4mgroff[24m, you can instead use
     [1m\[radicalex] [22mto continue the radical sign [1m\[sr][22m; these  special  characters
     are  intended for use with text fonts.  [1m\[sqrt] [22mand [1m\[sqrtex] [22mare their un‐
     styled counterparts.

     Output   Input          Unicode      Notes
     ───────────────────────────────────────────────────────────────────────────
     ½        \[12]          u00BD        one half symbol +
     ¼        \[14]          u00BC        one quarter symbol +
     ¾        \[34]          u00BE        three quarters symbol +
     ⅛        \[18]          u215B        one eighth symbol
     ⅜        \[38]          u215C        three eighths symbol
     ⅝        \[58]          u215D        five eighths symbol
     ⅞        \[78]          u215E        seven eighths symbol
     ¹        \[S1]          u00B9        superscript one
     ²        \[S2]          u00B2        superscript two
     ³        \[S3]          u00B3        superscript three

     +        +              u002B        plus
     +        \[pl]          u002B        special variant of plus + ***
     -        \[-]           u002D        minus
     −        \[mi]          u2212        special variant of minus + ***
     ∓        \[-+]          u2213        minus‐plus
     ±        \[+-]          u00B1        plus‐minus + ***
     ±        \[t+-]         u00B1        text variant of [1m\[+-][0m
     ⋅        \[md]          u22C5        multiplication dot
     ×        \[mu]          u00D7        multiplication sign + ***
     ×        \[tmu]         u00D7        text variant of [1m\[mu][0m
     ⊗        \[c*]          u2297        circled times
     ⊕        \[c+]          u2295        circled plus
     ÷        \[di]          u00F7        division sign, obelus + ***
     ÷        \[tdi]         u00F7        text variant of [1m\[di][0m
     ⁄        \[f/]          u2044        fraction slash
     *        *              u002A        asterisk
     ∗        \[**]          u2217        mathematical asterisk +

     ≤        \[<=]          u2264        less than or equal to +
     ≥        \[>=]          u2265        greater than or equal to +
     ≪        \[<<]          u226A        much less than
     ≫        \[>>]          u226B        much greater than
     =        =              u003D        equals
     =        \[eq]          u003D        special variant of equals + ***
     ≠        \[!=]          u003D_0338   not equals +
     ≡        \[==]          u2261        equivalent +
     ≢        \[ne]          u2261_0338   not equivalent
     ≅        \[=~]          u2245        approximately equal to
     ≃        \[|=]          u2243        asymptotically equal to +
     ~        \[ti]          u007E        tilde +
     ∼        \[ap]          u223C        similar to, tilde operator +
     ≈        \[~~]          u2248        almost equal to
     ≈        \[~=]          u2248        almost equal to
     ∝        \[pt]          u221D        proportional to +

     ∅        \[es]          u2205        empty set +
     ∈        \[mo]          u2208        element of a set +
     ∉        \[nm]          u2208_0338   not element of set
     ⊂        \[sb]          u2282        proper subset +
     ⊄        \[nb]          u2282_0338   not subset
     ⊃        \[sp]          u2283        proper superset +
     ⊅        \[nc]          u2283_0338   not superset
     ⊆        \[ib]          u2286        subset or equal +
     ⊇        \[ip]          u2287        superset or equal +
     ∩        \[ca]          u2229        intersection, cap +
     ∪        \[cu]          u222A        union, cup +

     ∠        \[/_]          u2220        angle
     ⊥        \[pp]          u22A5        perpendicular
     ∫        \[is]          u222B        integral +
     ∫        \[integral]    u222B        integral ***
     ∑        \[sum]         u2211        summation ***
     ∏        \[product]     u220F        product ***
     ∐        \[coproduct]   u2210        coproduct ***
     ∇        \[gr]          u2207        gradient +
     √        \[sr]          u221A        radical sign, square root +
     ‾        \[rn]          u203E        overline +
     ‾        \[radicalex]   ‐‐‐          radical extension
     √        \[sqrt]        u221A        radical sign, square root ***
     ‾        \[sqrtex]      ‐‐‐          radical extension ***

     ⌈        \[lc]          u2308        left ceiling +
     ⌉        \[rc]          u2309        right ceiling +
     ⌊        \[lf]          u230A        left floor +
     ⌋        \[rf]          u230B        right floor +

     ∞        \[if]          u221E        infinity +
     ℵ        \[Ah]          u2135        aleph symbol
     ƒ        \[Fn]          u0192        lowercase f with hook, function
     ℑ        \[Im]          u2111        blackletter I, imaginary part
     ℜ        \[Re]          u211C        blackletter R, real part
     ℘        \[wp]          u2118        Weierstrass p
     ∂        \[pd]          u2202        partial differential
     ℏ        \[-h]          u210F        h bar
     ℏ        \[hbar]        u210F        h bar

   [1mGreek glyphs[0m
     These glyphs are intended for technical use, not for typesetting Greek lan‐
     guage text; normally, the uppercase letters have  upright  shape,  and  the
     lowercase  ones are slanted.  For the latter, we include in parentheses un‐
     der “Unicode” more appropriate code points from the  Mathematical  Alphanu‐
     meric Symbols block of the Supplementary Multilingual Plane.

     Output   Input   Unicode          Notes
     ───────────────────────────────────────────────────────────────────────────
     Α        \[*A]   u0391            uppercase alpha +
     Β        \[*B]   u0392            uppercase beta +
     Γ        \[*G]   u0393            uppercase gamma +
     Δ        \[*D]   u0394            uppercase delta +
     Ε        \[*E]   u0395            uppercase epsilon +
     Ζ        \[*Z]   u0396            uppercase zeta +
     Η        \[*Y]   u0397            uppercase eta +
     Θ        \[*H]   u0398            uppercase theta +
     Ι        \[*I]   u0399            uppercase iota +
     Κ        \[*K]   u039A            uppercase kappa +
     Λ        \[*L]   u039B            uppercase lambda +
     Μ        \[*M]   u039C            uppercase mu +
     Ν        \[*N]   u039D            uppercase nu +
     Ξ        \[*C]   u039E            uppercase xi +
     Ο        \[*O]   u039F            uppercase omicron +
     Π        \[*P]   u03A0            uppercase pi +
     Ρ        \[*R]   u03A1            uppercase rho +
     Σ        \[*S]   u03A3            uppercase sigma +
     Τ        \[*T]   u03A4            uppercase tau +
     Υ        \[*U]   u03A5            uppercase upsilon +
     Φ        \[*F]   u03A6            uppercase phi +
     Χ        \[*X]   u03A7            uppercase chi +
     Ψ        \[*Q]   u03A8            uppercase psi +
     Ω        \[*W]   u03A9            uppercase omega +

     α        \[*a]   u03B1 (u1D6FC)   lowercase alpha +
     β        \[*b]   u03B2 (u1D6FD)   lowercase beta +
     γ        \[*g]   u03B3 (u1D6FE)   lowercase gamma +
     δ        \[*d]   u03B4 (u1D6FF)   lowercase delta +
     ε        \[*e]   u03B5 (u1D700)   lowercase epsilon +
     ζ        \[*z]   u03B6 (u1D701)   lowercase zeta +
     η        \[*y]   u03B7 (u1D702)   lowercase eta +
     θ        \[*h]   u03B8 (u1D703)   lowercase theta +
     ι        \[*i]   u03B9 (u1D704)   lowercase iota +
     κ        \[*k]   u03BA (u1D705)   lowercase kappa +
     λ        \[*l]   u03BB (u1D706)   lowercase lambda +
     μ        \[*m]   u03BC (u1D707)   lowercase mu +
     ν        \[*n]   u03BD (u1D708)   lowercase nu +
     ξ        \[*c]   u03BE (u1D709)   lowercase xi +
     ο        \[*o]   u03BF (u1D70A)   lowercase omicron +
     π        \[*p]   u03C0 (u1D70B)   lowercase pi +
     ρ        \[*r]   u03C1 (u1D70C)   lowercase rho +
     σ        \[*s]   u03C3 (u1D70E)   lowercase sigma +
     τ        \[*t]   u03C4 (u1D70F)   lowercase tau +
     υ        \[*u]   u03C5 (u1D710)   lowercase upsilon +
     ϕ        \[*f]   u03D5 (u1D717)   lowercase phi +
     χ        \[*x]   u03C7 (u1D712)   lowercase chi +
     ψ        \[*q]   u03C8 (u1D713)   lowercase psi +
     ω        \[*w]   u03C9 (u1D714)   lowercase omega +

     ϵ        \[+e]   u03F5 (u1D716)   variant epsilon (lunate)
     ϑ        \[+h]   u03D1 (u1D717)   variant theta (cursive form)
     ϖ        \[+p]   u03D6 (u1D717)   variant pi (similar to omega)
     φ        \[+f]   u03C6 (u1D71B)   variant phi (curly shape)
     ς        \[ts]   u03C2 (u1D70D)   terminal lowercase sigma +

   [1mPlaying card symbols[0m
     Output   Input   Unicode   Notes
     ───────────────────────────────────────────────────────────────────────────
     ♣        \[CL]   u2663     solid club suit
     ♠        \[SP]   u2660     solid spade suit
     ♥        \[HE]   u2665     solid heart suit
     ♦        \[DI]   u2666     solid diamond suit

[1mHistory[0m
     A  consideration  of  the  typefaces originally available to AT&T [4mnroff[24m and
     [4mtroff[24m illuminates many conventions that one might regard  as  idiosyncratic
     fifty  years  afterward.   (See  section “History” of ]8;;man:roff(7)\[4mroff[24m(7)]8;;\ for more con‐
     text.)  The face used by the Teletype Model 37 terminals of the Murray Hill
     Unix Room was based on ASCII, but assigned  multiple  meanings  to  several
     code  points,  as  suggested  by that standard.  Decimal 34 ([1m"[22m) served as a
     dieresis accent and neutral double quotation mark; decimal  39  ([1m'[22m)  as  an
     acute  accent, apostrophe, and closing (right) single quotation mark; deci‐
     mal 45 ([1m-[22m) as a hyphen and a minus sign; decimal 94 ([1m^[22m) as a circumflex ac‐
     cent and caret; decimal 96 ([1m`[22m) as a grave accent and opening (left)  single
     quotation mark; and decimal 126 ([1m~[22m) as a tilde accent and (with a half‐line
     motion)  swung  dash.  The Model 37 bore an optional extended character set
     offering upright Greek letters and several mathematical symbols; these were
     documented as early as the [4mkbd[24m(VII) man page of the  (First  Edition)  [4mUnix[0m
     [4mProgrammer’s[24m [4mManual.[0m

     At  the  time  Graphic Systems delivered the C/A/T phototypesetter to AT&T,
     the ASCII character set was not considered a standard  basis  for  a  glyph
     repertoire  by traditional typographers.  In the stock Times roman, italic,
     and bold styles available, several ASCII characters  were  not  present  at
     all,  nor  was most of the Teletype’s extended character set.  AT&T commis‐
     sioned a “special” font to retain their accustomed repertoire.

     A representation of the coverage of the C/A/T’s text  fonts  follows.   The
     glyph  resembling  an  underscore is a baseline rule, and that resembling a
     vertical line is a box rule.  In italics, the box rule was not slanted.  We
     also observe that the hyphen and minus sign were  already  “de‐unified”  by
     the fonts provided; a decision whither to map an input “-” therefore had to
     be taken.

              ┌─────────────────────────────────────────────────────┐
              │ A B C D E F G H I J K L M N O P Q R S T U V W X Y Z │
              │ a b c d e f g h i j k l m n o p q r s t u v w x y z │
              │ 0 1 2 3 4 5 6 7 8 9 fi fl ffi ffl                   │
              │ ! $ % & ( ) ‘ ’ * + - . , / : ; = ? [ ] │           │
              │ • □ —— ‐ _ ¼ ½ ¾ ° † ′ ¢ ® ©                        │
              └─────────────────────────────────────────────────────┘

     The  special  font supplied the missing ASCII and Teletype extended glyphs,
     among several others.  The plus, minus, and equals signs  appeared  in  the
     special font despite availability in text fonts “to insulate the appearance
     of  equations  from  the choice of standard [read: text] fonts”——a priority
     since [4mtroff[24m was turned to the task of mathematical typesetting as  soon  as
     it was developed.

     We  note  that  AT&T  took the opportunity to de‐unify the apostrophe/right
     single quotation mark from the acute accent (a choice ISO later  duplicated
     in  its 8859 series of standards).  A slash intended to be mirror‐symmetric
     with the backslash was also included, as was the Bell System  logo;  we  do
     not attempt to depict the latter.

           ┌───────────────────────────────────────────────────────────┐
           │ [4mα[24m [4mβ[24m [4mγ[24m [4mδ[24m [4mε[24m [4mζ[24m [4mη[24m [4mθ[24m [4mι[24m [4mκ[24m [4mλ[24m [4mμ[24m [4mν[24m [4mξ[24m [4mο[24m [4mπ[24m [4mρ[24m [4mσ[24m [4mς[24m [4mτ[24m [4mυ[24m [4mϕ[24m [4mχ[24m [4mψ[24m [4mω[24m         │
           │ Γ Δ Θ Λ Ξ Π Σ Υ Φ Ψ Ω                                     │
           │ " ´ \ ^ _ ` ~ / < > { } # @ + − = ∗                       │
           │ ≥ ≤ ≡ ≈ ∼ ≠ ↑ ↓ ← → × ÷ ± ∞ ∂ ∇ ¬ ∫ ∝ √ ‾ ∪ ∩ ⊂ ⊃ ⊆ ⊇ ∅ ∈ │
           │ § ‡ ☜ ☞ | ○ ⎧ ⎩ ⎫ ⎭ ⎨ ⎬ ⎪ ⌊ ⌋ ⌈ ⌉                         │
           └───────────────────────────────────────────────────────────┘

     One  ASCII  character as rendered by the Model 37 was apparently abandoned.
     That device printed decimal 124 (|) as a broken vertical line, like Unicode
     U+00A6 (¦).  No equivalent was available on the C/A/T; the box rule  [1m\[br][22m,
     brace  vertical  extension [1m\[bv][22m, and “or” operator [1m\[or] [22mwere used as con‐
     textually appropriate.

     Devices supported by AT&T device‐independent [4mtroff[24m exhibited  some  differ‐
     ences  in  glyph detail.  For example, on the Autologic APS‐5 phototypeset‐
     ter, the square [1m\(sq [22mbecame filled in the Times bold face.

[1mFiles[0m
     The files below are loaded automatically by the default [4mtroffrc[24m.

     [4m/usr/share/groff/1.24.0/tmac/composite.tmac[0m
            assigns alternate mappings for identifiers after the first in a com‐
            posite special character escape sequence.  See subsection  “Accents”
            above.

     [4m/usr/share/groff/1.24.0/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.0                       2025‐12‐19                      [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.  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
     of  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 in‐
     tepreted 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 “Gtroff In‐
             ternals” in [4mGroff:[24m [4mThe[24m [4mGNU[24m [4mImplementation[24m [4mof[24m [4mtroff[24m, the [4mgroff[24m  Tex‐
             info  manual);  disabling compatibility mode and setting the escape
             character to to [1m\ [22mwhile interpreting  [4mcontents.[24m   Any  emboldening,
             constant  spacing,  or  track kerning applies to this object rather
             than to individual glyphs resulting from  the  formatting  of  [4mcon‐[0m
             [4mtents.[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 “Gtroff Internals”
             in [4mGroff:[24m [4mThe[24m [4mGNU[24m [4mImplementation[24m [4mof[24m [4mtroff[24m, the [4mgroff[24m  Texinfo  man‐
             ual, 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 the categories, or “types”, of reported warnings.  [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 cate‐
             gories 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 1[22m” disables all warnings except those about missing  glyphs.
             If no argument is given, all warning categories are enabled.

     [1m.warnscale [4m[22mscaling‐unit[0m
             Select scaling unit used in certain warnings (one of [1mu[22m, [1mi[22m, [1mc[22m, [1mp[22m, or
             [1mP[22m;  default:  [1mi[22m).   Ignored on [4mnroff[24m‐mode output devices, for which
             these diagnostics report the vertical page location in  lines,  and
             the horizontal page location in ens.

     [1m.while [4m[22mcond‐expr[24m [4minput[0m
             Evaluate  the conditional expression [4mcond‐expr[24m, and repeatedly exe‐
             cute [4minput[24m unless and  until  [4mcond‐expr[24m  evaluates  false.   [4minput,[0m
             which  is  often a conditional block, is referred to as the “[1mwhile[22m”
             request’s [4mbody.[0m

             GNU [4mtroff[24m treats the body of a “[1mwhile[22m” request similarly to that of
             a [1mde [22mrequest (albeit one not read in copy mode), but stores it  un‐
             der  an  internal  name and deletes it when the loop finishes.  The
             operation of a macro containing a “[1mwhile[22m” request can slow signifi‐
             cantly if its body is large.  Each time GNU [4mtroff[24m interpolates  the
             macro,  it parses and stores the “[1mwhile[22m” body again.  An often bet‐
             ter solution——and one that  is  more  portable,  since  AT&T  [4mtroff[0m
             lacked  the “[1mwhile[22m” request——is to instead write a recursive macro,
             which is parsed only once (unless you redefine it).  To prevent in‐
             finite loops, GNU [4mtroff[24m limits the default number of available  re‐
             cursion levels to 1,000 or somewhat less (because things other than
             macro  calls can be on the input stack).  You can disable this pro‐
             tective measure, or alter the limit, by setting the  [1mslimit  [22mregis‐
             ter.  See section “Debugging” below.

             If  a  “[1mwhile[22m”  body  begins  with a conditional block, its closing
             brace must end an input line.

             The “[1mbreak[22m” and “[1mcontinue[22m” requests alter a “[1mwhile[22m” loop’s flow  of
             control.

     [1m.write [4m[22mstream[24m [[[1m"[22m][4mcharacter‐sequence[24m]
             Write   [4mcharacter‐sequence[24m,  a  sequence  of  ordinary  characters,
             spaces, or tabs read in copy mode, to [4mstream[24m, which must previously
             have been the subject of an “[1mopen[22m” (or [1mopena[22m) request, followed  by
             a newline.  GNU [4mtroff[24m flushes the stream after writing to it.

     [1m.writec [4m[22mstream[24m [[[1m"[22m][4mcharacter‐sequence[24m]
             As “[1mwrite[22m”, but does not append a newline to [4mcontents[24m.

     [1m.writem [4m[22mstream[24m [4mname[0m
             Write  the  contents  of  the macro or string [4mname[24m to [4mstream[24m, which
             must previously have been the subject of an “[1mopen[22m” (or  [1mopena[22m)  re‐
             quest.  GNU [4mtroff[24m reads the contents of [4mname[24m in copy mode.

   [1mAltered registers[0m
     GNU  [4mtroff[24m alters the semantics of two AT&T [4mtroff[24m registers and imparts se‐
     mantics to two others that CSTR #54 documented as “reserved”.

     [1m\n[.R][0m
            Because GNU [4mtroff[24m dynamically manages register  storage,  it  repur‐
            poses  the  [1m.R  [22mregister  to  interpolate the maximum integer repre‐
            sentable in the formatter.  Favor its use over numeric literals with
            many zeroes or nines to indicate an arbitrary large quantity.

     [1m\n[.s][0m
            In GNU [4mtroff[24m, the [1m.s [22mregister is string‐valued; it interpolates  the
            type  size  in  typographical  points, which can be represented as a
            decimal fraction.

     [1m\n[.x][0m
            Interpolate major version number of  the  running  [4mtroff[24m  formatter.
            For  example,  if  the  version  number  is 1.23.0, then [1m\n[.x] [22mcon‐
            tains 1.

     [1m\n[.y][0m
            Interpolate minor version number of  the  running  [4mtroff[24m  formatter.
            For  example,  if  the  version  number  is 1.23.0, then [1m\n[.y] [22mcon‐
            tains 23.  Also see [1m\n[.Y] [22mbelow.

   [1mNew registers[0m
     GNU [4mtroff[24m exposes more formatter state via many  new  read‐only  registers.
     Their names often correspond to the requests that affect them.

     [1m\n[.br]       [22mWithin  a  macro  definition,  interpolate  1 if the macro is
                   called with the “normal” control character (“.” by  default),
                   and  0  otherwise.  This facility allows requests to be reli‐
                   ably wrapped by a macro.  Interpolating the [1m.br [22mregister out‐
                   side of a macro definition makes no sense.

     [1m\n[.C]        [22mInterpolate 1 if AT&T [4mtroff[24m compatibility mode is in  effect,
                   0 otherwise.  See [1mcp[22m.

     [1m\n[.cdp]      [22mInterpolate depth of last glyph added to the environment.  It
                   is positive if the glyph extends below the baseline.

     [1m\n[.ce]       [22mInterpolate  count of input lines remaining to be centered in
                   the environment.

     [1m\n[.cht]      [22mInterpolate height of last glyph added  to  the  environment.
                   It is positive if the glyph extends above the baseline.

     [1m\n[.color]    [22mInterpolate 1 if color output is enabled, 0 otherwise.

     [1m\n[.cp]       [22mWithin a “[1mdo[22m” request, interpolate the saved value of compat‐
                   ibility mode (see [1m\n[.C] [22mabove).

     [1m\n[.csk]      [22mInterpolate skew of last glyph added to the environment.  The
                   [4mskew[24m  of  a  glyph is how far to the right of the center of a
                   glyph the center of an  accent  over  that  glyph  is  to  be
                   placed.

     [1m\n[.ev]       [22mInterpolate  name  of current environment.  This is a string‐
                   valued register.

     [1m\n[.fam]      [22mInterpolate name of the environment’s  default  font  family.
                   This is a string‐valued register.

     [1m\n[.fn]       [22mInterpolate  resolved  name of the font selected in the envi‐
                   ronment.  This is a string‐valued register.

     [1m\n[.fp]       [22mInterpolate next free non‐zero font mounting position.

     [1m\n[.g]        [22mInterpolate 1.  Test with “[1mif[22m” or [1mie  [22mto  check  whether  GNU
                   [4mtroff[24m is the formatter.

     [1m\n[.height]   [22mInterpolate the rescaled height of the environment’s selected
                   font, in scaled points.  It is zero if the font height is not
                   rescaled.  See [1m\H[22m.

     [1m\n[.hla]      [22mInterpolate hyphenation language of the environment.  This is
                   a string‐valued register.

     [1m\n[.hlc]      [22mInterpolate  count  of  immediately preceding consecutive hy‐
                   phenated lines in the environment.

     [1m\n[.hlm]      [22mInterpolate maximum number of  consecutive  hyphenated  lines
                   allowed in the environment.

     [1m\n[.hy]       [22mInterpolate automatic hyphenation mode of the environment.

     [1m\n[.hydefault][0m
                   Interpolate hyphenation mode default of the environment.

     [1m\n[.hym]      [22mInteprolate hyphenation margin of the environment.

     [1m\n[.hys]      [22mInterpolate hyphenation space adjustment threshold of the en‐
                   vironment.

     [1m\n[.in]       [22mInterpolate  indentation amount applicable to the output line
                   pending in the environment.

     [1m\n[.int]      [22mInterpolate 1 if the text most recently formatted in the  en‐
                   vironment  was  “interrupted”  or continued with [1m\c[22m, 0 other‐
                   wise.

     [1m\n[.it]       [22mInterpolate count of input lines remaining  in  the  environ‐
                   ment’s pending input trap.

     [1m\n[.itc]      [22mInterpolate  1 if the environment’s pending input trap honors
                   the output line continuation escape sequence ([1m\c[22m),  0  other‐
                   wise.

     [1m\n[.itm]      [22mInterpolate  the  name of the macro associated with the envi‐
                   ronment’s pending input trap.  This is a string‐valued regis‐
                   ter.

     [1m\n[.kern]     [22mInterpolate 1 if pairwise kerning is enabled, 0 otherwise.

     [1m\n[.lg]       [22mInterpolate ligature mode.

     [1m\n[.linetabs][0m
                   Interpolate 1 if line‐tabs mode is enabled  in  the  environ‐
                   ment, 0 otherwise.

     [1m\n[.ll]       [22mInterpolate line length applicable to the environment’s pend‐
                   ing output line.

     [1m\n[.lt]       [22mInterpolate the environment’s title line length.

     [1m\n[.m]        [22mInterpolate  name of the environment’s selected stroke color.
                   This is a string‐valued register.

     [1m\n[.M]        [22mInterpolate name of the environment’s  selected  fill  color.
                   This is a string‐valued register.

     [1m\n[.ne]       [22mInterpolate  amount  of  space demanded by the most recent [1mne[0m
                   request that sprang a page location trap.  See [1m\n[.trunc][22m.

     [1m\n[.nm]       [22mInterpolate 1 if output line numbering is enabled in the  en‐
                   vironment (even if temporarily suppressed), 0 otherwise.

     [1m\n[.nn]       [22mInterpolate  count  of lines remaining in the environment for
                   which numbering is suppressed while output line numbering  is
                   enabled.

     [1m\n[.ns]       [22mInterpolate 1 if no‐space mode is enabled, 0 otherwise.

     [1m\n[.O]        [22mInterpolate output suppression level.  See [1m\O[22m.

     [1m\n[.P]        [22mInterpolate  1  if  the  current page is selected for output,
                   0 otherwise.  See [1m-o [22mcommand‐line option to ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\.

     [1m\n[.pe]       [22mInterpolate 1 during page ejection, 0 otherwise.

     [1m\n[.pn]       [22mInterpolate next page number (either that set by [1mpn[22m, or  that
                   of the current page plus 1).

     [1m\n[.ps]       [22mInterpolate the environment’s type size in scaled points.

     [1m\n[.psr]      [22mInterpolate  the  environment’s  most recently requested type
                   size in scaled points.

     [1m\n[.pvs]      [22mInterpolate  the  environment’s  post‐vertical  line  spacing
                   amount.

     [1m\n[.rj]       [22mInterpolate  count  of  input  lines  remaining  to be right‐
                   aligned in the environment.

     [1m\n[.slant]    [22mInterpolate slant in degrees of  the  environment’s  selected
                   font.  See [1m\S[22m.

     [1m\n[.sr]       [22mInterpolate  the  environment’s  most recently requested type
                   size in typographical points.  This is a string‐valued regis‐
                   ter.

     [1m\n[.ss][0m
     [1m\n[.sss]      [22mInterpolate values of the  environment’s  minimum  inter‐word
                   space and supplemental inter‐sentence space, respectively, in
                   twelfths of the space width of the selected font.

     [1m\n[.sty]      [22mInterpolate  the  environment’s selected abstract font style,
                   if any.  This is a string‐valued register.

     [1m\n[.tabs]     [22mInterpolate the environment’s tab stop settings (if any) in a
                   form suitable for passage to  the  [1mta  [22mrequest.   This  is  a
                   string‐valued register.

     [1m\n[.trap]     [22mInterpolate the name of the next vertical position trap after
                   the  vertical drawing position.  This is a string‐valued reg‐
                   ister.

     [1m\n[.trunc]    [22mInterpolate amount of vertical space truncated  by  the  most
                   recently  sprung  page  location  trap,  or,  if the trap was
                   sprung by an [1mne [22mrequest, minus the amount of vertical  motion
                   produced  by  the [1mne [22mrequest.  In other words, at the point a
                   trap is sprung, [1m\n[.trunc] [22mrepresents the difference of  what
                   the  vertical  position would have been but for the trap, and
                   what the vertical position actually is.  See [1m\n[.ne][22m.

     [1m\n[.U]        [22mInterpolate 1 if in unsafe mode, 0 otherwise.   See  [1m-U  [22mcom‐
                   mand‐line option to ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\.

     [1m\n[.vpt]      [22mInterpolate  1 if vertical position traps are enabled, 0 oth‐
                   erwise.

     [1m\n[.warn]     [22mInterpolate  warning  mask.   See   section   “Warnings”   of
                   ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\.

     [1m\n[.Y]        [22mInterpolate  revision  number of the running [4mtroff[24m formatter.
                   For example, if the version number  is  1.23.0,  then  [1m\n[.Y][0m
                   contains 0.  Also see [1m\n[.x] [22mand [1m\n[.y] [22mabove.

     [1m\n[.zoom]     [22mInterpolate magnification of the environment’s selected font,
                   in thousandths, or 0 if magnification unused.  See [1mfzoom[22m.

     The following (writable) registers are set by the [1mpsbb [22mrequest.

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

     The following (writable) registers are set by the [1m\w [22mescape sequence.

     [1m\n[rst][0m
     [1m\n[rsb]  [22mLike  [1m\n[st]  [22mand  [1m\n[sb][22m,  but  taking account of the heights and
              depths of glyphs.  In other words, these registers store the high‐
              est and lowest vertical positions attained by the argument format‐
              ted by the [1m\w [22mescape sequence, doing what  AT&T  [4mtroff[24m  documented
              [1m\n[st] [22mand [1m\n[sb] [22mas doing.

     [1m\n[ssc]  [22mThe  amount  of (possibly negative) horizontal space to add to the
              last glyph before a subscript.

     [1m\n[skw]  [22mHow far to right of the center of the last glyph in the  [1m\w  [22margu‐
              ment, to place the center of an accent from a roman font over that
              glyph.

     Other  writable  registers are as follows.  Those relating to date and time
     are initialized using ]8;;man:localtime(3)\[4mlocaltime[24m(3)]8;;\ at formatter startup.

     [1m\n[c.]      [22mInterpolate input line number.  [1m\n[.c] [22mis a read‐only alias  of
                 this register.

     [1m\n[hours]   [22mInterpolate number of hours elapsed since midnight.

     [1m\n[hp]      [22mInterpolate  horizontal  position relative to that at the start
                 of the input line.

     [1m\n[lsn][0m
     [1m\n[lss]     [22mInterpolate count of leading spaces on input line and amount of
                 corresponding horizontal motion, respectively.

     [1m\n[minutes][0m
                 Interpolate number of minutes elapsed in the hour.

     [1m\n[seconds][0m
                 Interpolate number of seconds elapsed in the minute.

     [1m\n[systat]  [22mInterpolate return value of ]8;;man:system(3)\[4msystem[24m(3)]8;;\ function executed by most
                 recent [1msy [22mrequest.

     [1m\n[slimit]  [22mInterpolates maximum quantity of objects  on  [4mtroff[24m’s  internal
                 input  stack  (default:  1000).   If  non‐positive, there is no
                 limit: recursion can  continue  until  program  memory  is  ex‐
                 hausted.

     [1m\n[year]    [22mInterpolate  Gregorian  year.  AT&T [4mtroff[24m’s [1m\n[yr] [22minterpolates
                 the Gregorian year minus 1900.

   [1mDelimiters[0m
     AT&T [4mtroff[24m recognized slightly varying sets of  delimiters  when  expecting
     numerical  expressions (as with the [1m\h [22mescape sequence), string expressions
     (as with the [1m\w [22mescape sequence and [1mtl [22mrequest), and output comparisons (as
     in “[1m.if #foo#bar# .tm match[22m”).  GNU [4mtroff[24m, when not in compatibility  mode,
     recognizes  a single consistent set of delimiters.  Compatibility mode emu‐
     lates AT&T [4mtroff[24m only up to a point.  GNU [4mtroff[24m accepts leaders and tabs as
     delimiters, as well as Control+D (EOT or EOF), Control+H (BS or backspace),
     and Control+L (FF or form feed), all of which,  when  used  as  delimiters,
     cause AT&T [4mtroff[24m to behave in ways difficult to predict.

   [1mMiscellaneous[0m
     A font not listed in the output device’s [4mDESC[24m file’s [1mfonts [22mdirective is au‐
     tomatically  mounted  at  the  next  available font position when it is se‐
     lected.  If you mount a font explicitly with the [1mfp [22mrequest, you should  do
     so on the first unused position, which can be found in the [1m.fp [22mregister.

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

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

     GNU  [4mtroff[24m  keeps  track of the nesting depth of escape sequence interpola‐
     tions and other uses of delimiters, as in the [1mtl  [22mrequest  and  the  output
     comparison operator (that is, input like [1m'foo'bar' [22mas a conditional expres‐
     sion),  so  the  only  characters you need to avoid using as delimiters are
     those that appear in the arguments you input, not any that result from  in‐
     terpolation.   Typically,  [1m'  [22mworks fine.  Use visible characters as delim‐
     iters in GNU [4mtroff[24m, not US‐ASCII controls like BEL (Control+G).  The imple‐
     mentation of [1m\$@ [22mensures that the double quotes surrounding an argument ap‐
     pear at an interpolation depth different from that of the  arguments  them‐
     selves.  Similarly, in bracket‐form escape sequences like [1m\f[ZCMI], [22ma right
     bracket [1m] [22mdoes not end the sequence unless it occurs at the same interpola‐
     tion  depth  as the opening [1m[[22m.  In compatibility mode, no attention is paid
     to the interpolation depth.

     In GNU [4mtroff[24m, the [1mtr [22mrequest can map characters to  the  unbreakable  space
     escape  sequence [1m\~ [22mas a special case ([1mtr [22mnormally operates only on [4mcharac‐[0m
     [4mters[24m).  This feature replaces the odd‐parity [1mtr [22mmapping trick used in  AT&T
     [4mtroff[24m documents, where a character, often [1m~[22m, was “sacrificed” by mapping it
     to  “nothing”,  drafting it into use as an unadjustable, unbreakable space.
     (This feature was gratuitous even in early AT&T [4mtroff,[24m which supported  the
     [1m\[4m[22mspace[24m  escape  sequence  by  1976.)  Often, it makes more sense to use GNU
     [4mtroff[24m’s [1m\~ [22mescape sequence instead, which has been adopted by  every  other
     active  [4mtroff[24m implementation except that of Illumos, as well as by the non[4m‐[0m
     [4mtroff[24m [4mmandoc[24m.  Translation of a character to [1m\~ [22mis  generally  unnecessary,
     but  might be employed to obtain an unbreakable space when the escape char‐
     acter will subsequently be disabled.

     GNU [4mtroff[24m permits tabs and spaces after the first dot  on  a  control  line
     that ends a macro definition.

[1mFormatter output[0m
     The  page  description  language  output by GNU [4mtroff[24m is modeled after that
     used by AT&T [4mtroff[24m once the latter adopted a device‐independent approach in
     the early 1980s.  Only the differences are documented here.  For  a  fuller
     discussion, see ]8;;man:groff_out(5)\[4mgroff_out[24m(5)]8;;\.

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

   [1mUnits[0m
     The argument to the [1ms [22mcommand is in scaled points (units of points/[4mn[24m, where
     [4mn[24m is the argument to the [1msizescale [22mcommand in the [4mDESC[24m file).  The argument
     to the “[1mx H[22m” command is also in scaled points.

   [1mSimple commands[0m
     If the [1mtcommand [22mdirective is present in the output device’s [4mDESC[24m file,  GNU
     [4mtroff[24m employs the following two commands.

     [1mt [4m[22mxyz[24m...
            Typeset  word  [4mxyz[24m; that is, set a sequence of ordinary glyphs named
            [4mx[24m, [4my[24m, [4mz[24m, ..., terminated by a space or newline; an  optional  second
            integer  argument  is ignored (this allows the formatter to generate
            an even number of arguments).  Each glyph  is  set  at  the  current
            drawing  position, and the position is then advanced horizontally by
            the glyph’s width.  A glyph’s width is read from its metrics in  the
            font  description file, scaled to the current type size, and rounded
            to a multiple of the horizontal motion quantum.  Use the  [1mC  [22mcommand
            to emplace glyphs of special characters.

     [1mu [4m[22mn[24m [4mxyz[24m...
            Typeset  word  [4mxyz[24m with track kerning.  As [1mt[22m, but after placing each
            glyph, the drawing position is further advanced  horizontally  by  [4mn[0m
            basic units.

     New commands implement color support.

     [1mmc [4m[22mcyan[24m [4mmagenta[24m [4myellow[0m
     [1mmd[0m
     [1mmg [4m[22mgray[0m
     [1mmk [4m[22mcyan[24m [4mmagenta[24m [4myellow[24m [4mblack[0m
     [1mmr [4m[22mred[24m [4mgreen[24m [4mblue[0m
            Set the components of the stroke color with respect to various color
            spaces.  [1mmd [22mresets the stroke color to the default value.  The argu‐
            ments are integers in the range 0 to 65535.

     A new device control subcommand is available.

     [1mx u [4m[22mn[24m  If [4mn[24m is 1, start underlining of spaces.  If [4mn[24m is 0, stop underlining
            of spaces.  This facility is needed for the [1mcu [22mrequest in [4mnroff[24m mode
            and is ignored otherwise.

   [1mExtended drawing commands[0m
     GNU  [4mpic[24m does not produce [4mtroff[24m escape sequences employing these extensions
     if its [1m-n [22moption is given.

     [1mDf [4m[22mn[24m    Set the shade of gray used to fill geometric objects  to  [4mn[24m,  which
             must  be  an integer.  0 corresponds to white and 1000 to black.  A
             grayscale ramp spans the two.  A value outside this range uses  the
             stroke  color  as  the fill color.  The fill color is opaque.  Nor‐
             mally the default is black, but some drivers may provide a  way  of
             changing this.  [1mDf [22mis obsolete since 2002, superseded by [1mDFg [22mbelow.

             The corresponding [1m\D'f' [22mescape sequence should not be used: its ar‐
             gument  is  rounded to an integer multiple of the horizontal motion
             quantum, which can limit the precision of [4mn[24m.

     [1mDC [4m[22md[24m    Draw a filled circle of diameter [4md[24m with its leftmost point  at  the
             drawing position.

     [1mDE [4m[22mh[24m [4mv[24m  Draw  a  filled  ellipse, of horizontal axis [4mh[24m and vertical axis [4mv[24m,
             with its leftmost point at the drawing position.

     [1mDp [4m[22mdx[24m1[4mdy[24m1...[4mdxndyn[0m
             Draw a polygon with, for [4mi[24m=1,...,[4mn[24m+1, its [4mi[24mth vertex at the drawing
             position +[4mij[24m−=Σ11([4mdxj[24m,[4mdyj[24m).  [4mgroff[24m output drivers  automatically  close
             polygons,  drawing  a  line  from ([4mdxn[24m,[4mdyn[24m) back to ([4mdx[24m1,[4mdy[24m1).  The
             drawing position is left at the last [4mspecified[24m vertex, but this may
             change in a future version of GNU [4mtroff[24m.  Heirloom Doctools  [4mtroff[24m,
             like  DWB  [4mtroff[24m,  by  default  does not close the polygon.  In its
             [4mgroff[24m compatibility mode, Heirloom closes the  polygon  but  leaves
             the  drawing  position [4munchanged[24m——that is, at the polygon’s [4minitial[0m
             drawing position.

     [1mDP [4m[22mdx[24m1[4mdy[24m1...[4mdxndyn[0m
             As [1mDp[22m, but draw a filled rather than a stroked polygon.

     [1mDt [4m[22mn[24m    Set the line thickness to [4mn[24m basic units.  AT&T [4mtroff[24m output drivers
             use a thickness proportional to the type  size;  this  is  the  GNU
             [4mtroff[24m  default.   A  negative  [4mn[24m requests this explicitly.  An [4mn[24m of
             zero selects the smallest available line thickness.

     A difficulty arises in how the drawing position should be changed after the
     execution of these commands.  This has little  importance  to  most  users,
     since the output of GNU [4mgrn[24m and [4mpic[24m does not depend on it.  Given a drawing
     command  of  the  form  [1mD[4m[22mz[24m  [4mx[24m1[4my[24m1...[4mxnyn[24m,  where [4mz[24m is not [1mc [22mor [1me[22m, AT&T [4mtroff[0m
     treats each [4mxi[24m as a horizontal motion, each  [4myi[24m  as  a  vertical  one,  and
     therefore  assumes  that  the  width  of the drawn object is [4min[24m=Σ1[4mxi[24m, and its
     height is [4min[24m=Σ1[4myi[24m.  (Verify its assumption about height by examining  the  [1mst[0m
     and  [1msb  [22mregisters  after  using  such a drawing command in a [1m\w [22mescape se‐
     quence).  Thus after executing a [1mD [22mcommand of the form [1mD[4m[22mz[24m [4mx[24m1[4my[24m1...[4mxnyn[24m,  the
     drawing  position  increases by ([4min[24m=Σ1[4mxi[24m,[4min[24m=Σ1[4myi[24m).  For the sake of compatibil‐
     ity, GNU [4mtroff[24m follows this rule, even though it frustrates  extensions  to
     the  [1mD  [22mcommand  that set drawing parameters rather than rendering objects,
     producing ugly results in the case of [1mDt [22mand [1mDf[22m, or otherwise don’t parame‐
     terize objects as a series of vertices, as with GNU [4mtroff[24m’s filled ellipse,
     [1mDE[22m.  In a future release, GNU [4mtroff[24m and its output drivers may abandon  the
     application of this assumption to drawing commands not explicitly specified
     in  the  AT&T  “Troff User’s Manual”.  You can ensure predictable output by
     enclosing drawing commands in the zero‐motion escape sequence [1m\Z[22m.

     GNU [4mtroff[24m implements fill color selection with another set of extensions.

     [1mDFc [4m[22mcyan[24m [4mmagenta[24m [4myellow[0m
     [1mDFd[0m
     [1mDFg [4m[22mgray[0m
     [1mDFk [4m[22mcyan[24m [4mmagenta[24m [4myellow[24m [4mblack[0m
     [1mDFr [4m[22mred[24m [4mgreen[24m [4mblue[0m
            Set the components of the fill color as described under the  [1m\M  [22mes‐
            cape  sequence above.  [1mDFd [22mrestores the device’s default fill color.
            The drawing position is not updated, in contrast to [1mDf[22m.

   [1mDevice control syntax extension[0m
     GNU [4mtroff[24m introduces a line continuation convention, permitting  the  argu‐
     ment  to  the  [1mx  X [22mcommand to contain newlines.  A newline in the input is
     transformed to the sequence “[4mnewline[24m[1m+[22m”.  When interpreting an [1mx X  [22mcommand,
     a  postprocessor  should therefore be prepared for a plus sign after a new‐
     line; if it occurs, preserve the newline, discard the plus sign,  and  con‐
     tinue to collect the input into the argument of the [1mx X [22mcommand.  A newline
     [4mnot[24m  followed by a plus sign terminates the [1mx X [22mcommand.  An application of
     this feature is the embedding of PostScript or PDF language command streams
     into [4mtroff[24m output.

     GNU [4mtroff[24m guarantees that the first three output commands it emits  are  as
     follows.

            x T [4mdevice[0m
            x res [4mn[24m [4mh[24m [4mv[0m
            x init

[1mDebugging[0m
     In  addition to AT&T [4mtroff[24m’s debugging features, GNU [4mtroff[24m emits more error
     diagnostics when syntactical or semantic nonsense is encountered  and  sup‐
     ports  several warning categories; the output of these can be selected with
     “[1mwarn[22m”.  Also see the [1m-E[22m, [1m-w[22m, and [1m-W [22moptions of ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\.

     A trace of the formatter’s input processing stack can be emitted  when  er‐
     rors  or warnings occur by means of GNU [4mtroff[24m [1m-b [22moption, or produced on de‐
     mand with the [1mbacktrace [22mrequest.

     [4mgroff[24m also adds more flexible diagnostic output  requests  ([1mtmc  [22mand  [1mtm1[22m).
     Examine  the  state  of the formatter with requests that write lists of de‐
     fined colors ([1mpcolor[22m), composite character mappings ([1mpcomposite[22m),  environ‐
     ments  ([1mpev[22m), font translations ([1mpftr[22m), automatic hyphenation codes ([1mpchar[22m)
     and exceptions ([1mphw[22m), registers ([1mpnr[22m), open streams ([1mpstream[22m), and page lo‐
     cation traps ([1mpwh[22m).  Requests can  also  disclose  to  the  standard  error
     stream  the  internal  properties  and  representations  of  characters and
     classes ([1mpchar[22m), macros (and strings and diversions) ([1mpm[22m), and the list  of
     output nodes corresponding to the pending input line ([1mpline[22m).

[1mCompatibility mode[0m
     Some syntactical and behavioral differences between AT&T and GNU [4mtroff[24ms are
     thought  too  important  to  neglect; GNU [4mtroff[24m therefore makes available a
     [4mcompatibility[24m [4mmode[24m in an effort to keep documents prepared for  AT&T  [4mtroff[0m
     rendering well.

     Identifiers of arbitrary length may be GNU [4mtroff[24m’s most obvious innovation.
     AT&T  [4mtroff[24m  interprets  “[1m.dsabcd[22m”  as defining a string “[1mab[22m” with contents
     “[1mcd[22m”.  Normally, GNU [4mtroff[24m interprets this input as calling a  macro  named
     “[1mdsabcd[22m”.  AT&T [4mtroff[24m also interprets [1m\*[ [22mand [1m\n[ [22mas interpolating a string
     or  register, respectively, named “[1m[[22m”.  GNU [4mtroff[24m, however, normally inter‐
     prets “[1m[[22m” as bracketing a long name (with “[1m][22m” at the distal end).  In  com‐
     patibility  mode,  GNU  [4mtroff[24m interprets names in the traditional way, they
     thus can be two characters long at most.  See the  [1m-C  [22moption  in  ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\
     and, above, the [1m.C [22mand [1m.cp [22mregisters, and [1mcp [22mand “[1mdo[22m” requests, for more on
     compatibility mode.

     The  register  [1m\n[.cp] [22mis specialized and may require a statement of ratio‐
     nale.  When writing macro packages or documents that use GNU [4mtroff[24m features
     and which may be mixed with other packages or documents that do not——common
     scenarios include serial processing of man pages or use of the “[1mso[22m” or  [1mmso[0m
     requests——you may desire correct operation regardless of compatibility mode
     enablement in the surrounding context.  It may occur to you to save the ex‐
     isting  value  of  [1m\n(.C [22minto a register, say, [1m_C[22m, at the beginning of your
     file, turn compatibility mode off with “[1m.cp 0[22m”, then restore it  from  that
     register  at  the end with “[1m.cp \n(_C[22m”.  At the same time, a modular design
     of a document or macro package may lead you to multiple  layers  of  inclu‐
     sion.   You cannot use the same register name everywhere lest you “clobber”
     the value from a preceding or enclosing context.  The two‐character  regis‐
     ter  name  space of AT&T [4mtroff[24m is confining, but employing GNU [4mtroff[24m’s more
     capacious one, as with “[1m.nr _my_saved_C \n(.C[22m” does not work in compatibil‐
     ity mode; the register name is too long.  Employing the “[1mdo[22m” request is  no
     help: “[1m.do nr _my_saved_C \n(.C[22m” always saves zero to the register, because
     “[1mdo[22m” turns compatibility mode [4moff[24m while it interprets its argument list.

     GNU  [4mtroff[24m normally tracks the interpolation depth of escape sequence para‐
     meters and other delimited structures, but not in compatibility mode.   See
     section “Miscellaneous” above.

     The escape sequences [1m\f[22m, [1m\H[22m, [1m\m[22m, [1m\M[22m, [1m\R[22m, [1m\s[22m, and [1m\S [22mare transparent to con‐
     trol  character recognition at the beginning of an input line, or after the
     conditional expression of an “[1mif[22m” or  [1mie  [22mrequest,  only  in  compatibility
     mode.  That is, upon interpreting them, GNU [4mtroff[24m normally no longer recog‐
     nizes  a control character on the input line; but in compatibility mode, it
     does, just like AT&T [4mtroff.[0m

     Normally, the syntax form [1m\s[4m[22mn[24m accepts only a single character (a digit) for
     [4mn[24m, consistently with other forms that originated in AT&T  [4mtroff[24m,  like  [1m\*[22m,
     [1m\$[22m,  [1m\f[22m, [1m\g[22m, [1m\k[22m, [1m\n[22m, and [1m\z[22m.  In compatibility mode only, a non‐zero [4mn[24m must
     be in the range 4–39.  Legacy documents relying upon this quirk of  parsing
     should  migrate to another [1m\s [22mform.  [Background: The Graphic Systems C/A/T
     phototypesetter (the original device target for AT&T [4mtroff[24m) supported  only
     a  few discrete type sizes in the range 6–36 points, so Ossanna contrived a
     special case in the parser to do what the user must have meant.   Kernighan
     warned  of this in the 1992 revision of CSTR #54 (§2.3), and more recently,
     McIlroy referred to it as a “living fossil”.]

[1mOther differences[0m
     GNU [4mtroff[24m does not emit output if it has nothing to format.   For  example,
     it  treats  an  input  document  consisting solely of [1mnr [22mand [1mtm [22mrequests as
     empty, and produces nothing on its  standard  output  stream.   AT&T  [4mtroff[0m
     does, creating a blank page.

     Use  of  C0  control  characters  in  identifiers is not portable; Solaris,
     Plan 9, and Heirloom Doctools  [4mtroff[24ms  accept  Control+B,  Control+C,  Con‐
     trol+E, Control+F, and Control+G (only); DWB 3.3 [4mtroff[24m does not.  GNU [4mtroff[0m
     rejects C0 controls in identifiers with an error diagnostic.

     Formatters  that  don’t implement GNU [4mtroff[24m extension request names tend to
     ignore them, and if they don’t support a GNU  [4mtroff[24m  extension  escape  se‐
     quence,  they are liable to format its function selector character as text.
     For example, the adjustable, non‐breaking space escape sequence [1m\~ [22mis  also
     supported  by Heirloom Doctools [4mtroff[24m 050915 (September 2005), [4mmandoc[24m 1.9.5
     (2009‐09‐21), [4mneatroff[24m (commit 1c6ab0f6e, 2016‐09‐13), and Plan 9 from User
     Space [4mtroff[24m (commit 93f8143600, 2022‐08‐12), but not by  Solaris  or  Docu‐
     menter’s  Workbench [4mtroff[24ms, which both render it as “[1m~[22m”.  The [1m\A [22mescape se‐
     quence (see subsection “Escape sequences” above) may be helpful in avoiding
     their use.

     AT&T [4mtroff[24m discards trailing spaces from input lines, like GNU  [4mtroff[24m,  but
     when it does so, AT&T [4mtroff[24m also cancels end‐of‐sentence detection.  Use of
     the dummy character escape sequence [1m\& [22mis more portable.

     When  adjusting  output  lines to both margins, AT&T [4mtroff[24m at first adjusts
     spaces starting from the right; GNU [4mtroff[24m begins from the left.   Both  im‐
     plementations  adjust spaces from opposite ends on alternating output lines
     in this adjustment mode to prevent “rivers” in the text.

     GNU [4mtroff[24m does not always hyphenate words as AT&T [4mtroff[24m does.  The AT&T im‐
     plementation uses a set of hard‐coded rules specific to U.S. English, while
     GNU [4mtroff[24m uses language‐specific hyphenation  pattern  files  derived  from
     TeX.  Some versions of [4mtroff[24m reserved meager storage for hyphenation excep‐
     tion  words  (arguments  to the [1mhw [22mrequest); GNU [4mtroff[24m has no such restric‐
     tion.  When the [1mhy [22mrequest is invoked without an argument, GNU  [4mtroff[24m  sets
     the automatic hyphenation mode to the value of the [1m.hydefault [22mregister; the
     AT&T  implementation sets it to “[1m1[22m”, which is not suitable in GNU [4mtroff[24m for
     some languages, including English.

     Unlike GNU [4mtroff[24m, AT&T [4mtroff[24m does not recognize an occurrence of [1m\% [22mat  the
     beginning of a word as suppressing its hyphenation; instead, it (uselessly)
     marks  the  start  of the word as a potential hyphenation point, permitting
     output lines to end with hyphens that are not interior to a word.

     GNU [4mtroff[24m handles the dummy character [1m\& [22mdifferently from AT&T  [4mtroff[24m  when
     it  is followed by the hyphenation control escape sequence [1m\% [22mat the begin‐
     ning of a word.  GNU [4mtroff[24m does not regard the dummy character  as  “start‐
     ing”  the word; AT&T [4mtroff[24m does.  Further, Heirloom Doctools [4mtroff[24m does not
     honor an explicit hyphenation point marked with  [1m\%  [22mafter  a  word‐initial
     one.

     GNU  [4mtroff[24m  interprets request arguments representing file names and system
     commands in the same way it does the [4mcontents[24m argument to the [1mds  [22mand  “[1mas[22m”
     requests:  it  removes a leading neutral double quote ‘[1m"[22m’ from the argument
     to the [1mcf[22m, [1mnx[22m, [1mpi[22m, “[1mso[22m”, and [1msy  [22mrequests,  and  the  second  argument  (if
     present)  to  the [1mlf [22mrequest, permitting initial embedded spaces in it, and
     reads it to the end of the input line in copy mode.  This  difference  per‐
     mits the formatter to handle files with spaces in their names, but requires
     more care with trailing comments, and doubling of an initial neutral double
     quote “[1m"[22m” if the file name has one.

     The  existence  of  the [1m.T [22mstring is a common feature of device‐independent
     [4mtroff[24ms——DWB 3.3, Solaris, Heirloom Doctools, and Plan 9 [4mtroff[24m  all  support
     it——but valid values are specific to each implementation.

     The  (read‐only) register [1m.T [22minterpolates 1 if GNU [4mtroff[24m is run with the [1m-T[0m
     option, and 0 otherwise.  In contrast, AT&T [4mtroff[24m interpolated  1  only  if
     [4mnroff[24m was the formatter and was run with [1m-T[22m.

     AT&T [4mtroff[24m ignored attempts to remove read‐only registers; GNU [4mtroff[24m honors
     such requests.

     The [1mlf [22mrequest sets the number of the [4mcurrent[24m input line in AT&T [4mtroff[24m, and
     the [4mnext[24m in GNU [4mtroff[24m.

     AT&T  [4mtroff[24m  had  only environments named “[1m0[22m”, “[1m1[22m”, and “[1m2[22m”.  In GNU [4mtroff[24m,
     any number of environments may exist, using any valid identifiers for their
     names.

     As noted above in “Fractional type  sizes  and  new  scaling  units”,  AT&T
     [4mtroff[24m’s  [1mps  [22mrequest ignores scaling units and thus “[1m.ps 10u[22m” sets the type
     size to 10 points, whereas in GNU [4mtroff[24m it sets the type size to 10  [4mscaled[0m
     points,  possibly  a  much smaller measurement.  AT&T’s behavior also means
     that “[1m.ps 10p[22m” and “[1m.ps 10z[22m” are portable.

     The [1mab [22mrequest differs from AT&T [4mtroff[24m: GNU [4mtroff[24m writes no message to  the
     standard  error stream if no arguments are given, and it exits with a fail‐
     ure status instead of a successful one.

     The [1mbp [22mrequest differs from AT&T [4mtroff[24m: GNU [4mtroff[24m does not accept a scaling
     unit on the argument, a page number; the former does (uselessly).

     In AT&T [4mtroff[24m the [1mpm [22mrequest reports macro, string, and diversion sizes  in
     units  of  128‐byte  blocks, and an argument reduces the report to a sum of
     the above in the same units.  GNU [4mtroff[24m reports their lengths in characters
     or nodes if given no arguments, and otherwise dumps the JSON‐encoded  name,
     contents, and other properties of each named argument.

     AT&T  [4mtroff[24m  ignores the [1mss [22mrequest if the output is a terminal device; GNU
     [4mtroff[24m rounds down the values of minimum inter‐word  and  additional  inter‐
     sentence space each to the nearest multiple of 12.

     GNU  [4mtroff[24m  distinguishes  characters from glyphs.  Characters can be ordi‐
     nary, special, or indexed, and populate strings and macros.  Characters [4mper[0m
     [4mse[24m have not (yet) been formatted.  Glyphs represent graphemes (supplied  by
     the output device) and populate diversions.  Formatting converts characters
     into (sequences of) glyphs.  GNU [4mtroff[24m stores properties of the environment
     that affect how a glyph is rendered with the glyph node’s data.  Thus, sub‐
     sequent  formatting operations do not affect it, including [1mbd[22m, [1mcs[22m, [1mtkf[22m, [1mtr[22m,
     and [1mfp [22mrequests.  Normally, a macro or string contains only a list of char‐
     acters and a diversion contains only a list of  nodes.   However,  applying
     the  [1masciify [22mor [1munformat [22mrequests to a diversion converts some of its nodes
     back into characters.  Where the formatter  cannot  recover  the  character
     representation  of a node, it stores a null character in the character list
     corresponding to a single node in the node  list.   Consequently,  a  glyph
     node  does  not  behave as a character does in macro interpolation: it does
     not inherit special properties that the character from which  it  was  con‐
     structed might have had.

     One  way  to format a backslash in most documents is with the [1m\e [22mescape se‐
     quence; this formats the glyph of the current escape character,  regardless
     of  whether  it is used in a diversion; it also works in both GNU [4mtroff[24m and
     AT&T [4mtroff[24m.  (Naturally, if you’ve changed the escape character,  you  need
     to  prefix  the  “[1me[22m”  with  whatever it is——and you’ll likely get something
     other than a backslash in the output.)

     The other correct way, appropriate in contexts  independent  of  the  back‐
     slash’s  common  use  as  a [4mroff[24m escape character——perhaps in discussion of
     character sets or other programming languages——is the special character es‐
     cape sequence [1m\(rs [22mor [1m\[rs][22m, for “reverse solidus”, from its  name  in  the
     ECMA‐6  and ISO 10646 standards.  [AT&T [4mtroff[24m [4m’s[24m font description files did
     not define the [1mrs [22mspecial character, but those of its  descendant  Heirloom
     Doctools [4mtroff[24m do, as of its 060716 release (July 2006).]

     To store an escape sequence in a diversion that is interpreted when the di‐
     version  is  interpolated, either use the traditional [1m\! [22mtransparent output
     facility, or, if this is unsuitable, the new [1m\? [22mescape sequence.  See  sub‐
     section  “Escape sequences” above and sections “Diversions” and “Gtroff In‐
     ternals” in [4mGroff:[24m [4mThe[24m [4mGNU[24m [4mImplementation[24m [4mof[24m [4mtroff[24m, the [4mgroff[24m Texinfo  man‐
     ual.

     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.0                       2026‐01‐19                      [4mgroff_diff[24m(7)
────────────────────────────────────────────────────────────────────────────────
[4mgroff_hdtbl[24m(7)          Miscellaneous Information Manual          [4mgroff_hdtbl[24m(7)

[1mName[0m
     groff_hdtbl - Heidelberger table macros for GNU [4mroff[0m

[1mDescription[0m
     The [4mhdtbl[24m macros consist of four base and three optional macros, controlled
     by  about  twenty  arguments.  The syntax is simple and similar to the HTML
     table model and nearly as flexible:  you  can  write  sequences  of  tokens
     (macro  calls  with  their arguments and content data), separated by blanks
     and beginning with a macro call, into the same  line  to  get  compact  and
     cleanly  arranged input.  An advantage of [4mhdtbl[24m is that the tables are con‐
     structed without calling a preprocessor; this means  that  ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\’s  full
     macro capabilities are available.  On the other hand, table processing with
     [4mhdtbl[24m  is much slower than using the ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\ preprocessor.  A further advan‐
     tage is that the HTML‐like syntax of [4mhdtbl[24m  will  be  easily  converted  to
     HTML; this is not implemented yet.

[1mUsage[0m
     In  this and the next section, we present examples to help users understand
     the basic workflow of [4mhdtbl[24m.  First of all, you must  load  the  [4mhdtbl.tmac[0m
     file.   As with nearly all other [4mgroff[24m macro packages, there are two possi‐
     bilities to do so: Either add the line

            .mso hdtbl.tmac

     to your [4mroff[24m file before using any macros of the [4mhdtbl[24m package, or add  the
     option

            -m hdtbl

     to the command line of groff (before the document file which contains [4mhdtbl[0m
     macros).   Then  you  can include on or more tables in your document, where
     each one must be started and ended with the .TBL and .ETB  macros,  respec‐
     tively.

     In  this  man  page,  we approximate the result of each example as terminal
     output to be as generic as possible since [4mhdtbl[24m currently only supports the
     [1mps [22mand [1mpdf [22moutput drivers.

     The simplest well‐formed table consists of just single calls  to  the  four
     base  table macros in the right order.  Here we construct a table with only
     one cell.

            .TBL
            .TR
            .TD
            [4mcontents[24m [4mof[24m [4mthe[24m [4mtable[24m [4mcell[0m
            .ETB

     A terminal representation is

            +------------------------------------------------------+
            | [4mcontents-of-the-table-cell[24m                           |
            +------------------------------------------------------+

     Equivalent to the above is the following notation.

            .TBL .TR .TD "[4mcontents[24m [4mof[24m [4mthe[24m [4mtable[24m [4mcell[24m" .ETB

     By default, the formatted table is inserted into the  surrounding  text  at
     the place of its definition.  If the vertical space isn’t sufficient, it is
     placed  at  the  top of the next page.  Tables can also be stored for later
     insertion.

     Using ‘[4mrow‐number[24m*[4mcolumn‐number[24m’ as the data for the table cells,  a  table
     with two rows and two columns can be written as

            .TBL cols=2
            .  TR .TD 1*1 .TD 1*2
            .  TR .TD 2*1 .TD 2*2
            .ETB

     A terminal representation is

            +--------------------------+---------------------------+
            | 1*1                      | 1*2                       |
            +--------------------------+---------------------------+
            | 2*1                      | 2*2                       |
            +--------------------------+---------------------------+

     Here  we  see  a difference from HTML tables: The number of columns must be
     explicitly specified using the ‘cols=[4mm[24m’ argument  (or  indirectly  via  the
     ‘width’ argument, see below).

     The  contents  of a table cell is arbitrary; for example, it can be another
     table, without restriction to the nesting depth.  A given table layout  can
     be  either constructed with suitably nested tables or with proper arguments
     to .TD and .TH, controlling column and row spanning.  Note,  however,  that
     this table

            .TBL
            .  TR
            .    TD
            .      nop 1*1 1*2
            .  TR
            .    TD
            .      TBL cols=2 border=
            .        TR
            .          TD
            .            nop 2*1
            .          TD
            .            nop 2*2
            .      ETB
            .ETB

     and this table

            .TBL cols=2
            .  TR
            .    TD colspan=2
            .      nop 1*1 1*2
            .  TR
            .    TD
            .      nop 2*1
            .    TD
            .      nop 2*2
            .ETB

     are  similar  but  not identical (the use of .nop is purely cosmetic to get
     proper indentation).

     The first table looks like

            +------------------------------------------------------+
            | 1*1 1*2                                              |
            +------------------------------------------------------+
            |                                                      |
            | 2*1                         2*2                      |
            |                                                      |
            +------------------------------------------------------+

     and the second one like

            +------------------------------------------------------+
            | 1*1 1*2                                              |
            +---------------------------+--------------------------+
            | 2*1                       | 2*2                      |
            +---------------------------+--------------------------+

     Here is the latter table in a more compact form.

            .TBL cols=2 .TR ".TD colspan=2" 1*1 1*2
            .            TR .TD 2*1 .TD 2*2 .ETB

     If a macro has one or more arguments (see below), and it is not starting  a
     line, everything belonging to this macro including the macro itself must be
     enclosed in double quotes.

[1mMacros and arguments[0m
     The  order  of macro calls and other tokens follows the HTML model.  In the
     following list, valid predecessors and successors of all [4mhdtbl[24m  macros  are
     given, together with the possible arguments.

     Macro  arguments  are separated by blanks.  The order of arguments is arbi‐
     trary; they are of the form

            key=[4mvalue[0m

     or

            key='[4mvalue1[24m [[4mvalue2[24m [...]]'

     with the only exception of the optional argument of the macro  .ETB,  which
     is the string ‘hold’.  Another possible form is

            "key=[4mvalue1[24m [[4mvalue2[24m [...]]"

     However,  this  is  limited to the case where the macro is the first one in
     the line and not already enclosed in double quotes.

     Argument values specified below as [4mc[24m are colors predefined by [4mgroff[24m or col‐
     ors defined by the user with the .defcolor request.  Argument values [4md[24m  are
     decimal  numbers with or without decimal point.  Argument values [4mm[24m are nat‐
     ural numbers.  Argument values [4mn[24m are numerical values with the usual  [4mgroff[0m
     scaling  indicators.   Some  of  the  arguments  are specific to one or two
     macros, but most of them can be specified with .TBL,  .TR,  .TD,  and  .TH.
     These common arguments are explained in the next subsection.

     Most  of  the argument default values can be changed by the user by setting
     corresponding default registers or strings, as listed below.

     [1m.TBL [22m[[4margs[24m]
            Begin a new table.

            [1mpredecessor: [22m.TD, .TH, .ETB, cell contents
            [1msuccessor: [22m.CPTN, .TR
            [1marguments:[0m

                   border=[[4mn[24m]
                          Thickness of the surrounding  box  border.   ‘border=’
                          (no  value) means neither a surrounding box border nor
                          any horizontal or vertical separator lines between the
                          table rows and cells.  ‘border=0’ suppresses the  sur‐
                          rounding  box border, but still allows separator lines
                          between cells and rows.
                          [1mDefault: [22m‘border=.1n’ (register ‘t*b’).

                   bc=[4mc[24m   Border color.
                          [1mDefault: [22m‘bc=red4’ (string ‘t*bc’).

                   cols=[4mm[0m
                          Number of table columns.  This argument  is  necessary
                          if more than one column is in the table and no ‘width’
                          arguments are present.
                          [1mDefault: [22m‘cols=1’ (register ‘t*cols’).

                   cpd=[4mn[24m  Cell  padding,  i.e., the extra space between the cell
                          space border and the cell contents.
                          [1mDefault: [22m‘cpd=.5n’ (register ‘t*cpd’).

                   csp=[4mn[24m  Cell spacing, i.e., the extra space between the  table
                          border  or  vertical or horizontal lines between cells
                          and the cellspace.
                          [1mDefault: [22m‘csp=.5n’ (register ‘t*csp’).

                   tal=l|c|r
                          Horizontal alignment of the table, if  it  is  smaller
                          than   the   line  width.   ‘tal=l’:  left  alignment.
                          ‘tal=c’: centered alignment.   ‘tal=r’:  right  align‐
                          ment.
                          [1mDefault: [22m‘tal=l’ (register ‘t*tal’).

                   width='[4mw1[24m [[4mw2[24m [...]]'
                          Widths of table cells.  [4mw1[24m, [4mw2[24m, ... are either numbers
                          of  type  [4mn[24m or natural numbers with the pseudo‐scaling
                          indicator ‘%’, with the meaning “percent of the actual
                          line length (or column length for  inner  tables,  re‐
                          spectively)”.  If there are less width values than ta‐
                          ble  columns, the last width value is used for the re‐
                          maining cells.  The argument

                                 width='1.5i 10%'

                          for  example  indicates  that  the  first  column   is
                          1.5  inches  wide;  the remaining columns take 1/10 of
                          the column length each.
                          [1mDefault: [22mThe table width equals the outer line  length
                          or column length; the columns have equal widths.

                   height=[4mn[0m
                          Height  of  the table.  If the table with its contents
                          is lower than [4mn[24m, the last row  is  stretched  to  this
                          value.

     [1m.CPTN [22m[[4margs[24m]
            Text of caption.

            The (optionally numbered) table caption.  .CPTN is optional.

            [1mpredecessor: [22m.TBL
            [1msuccessor: [22m.TR
            [1marguments:[0m

                   val=t|b
                          Vertical alignment of the table caption.  ‘val=t’: The
                          caption  is placed above the table.  ‘val=b’: The cap‐
                          tion is placed below the table.
                          [1mDefault: [22m‘val=t’ (string ‘t*cptn’).

     [1m.TR [22m[[4margs[24m]
            Begin a new table row.

            [1mpredecessor: [22m.TBL, .CPTN, .TD, .TH, .ETB, cell contents
            [1msuccessor: [22m.TD, .TH
            [1marguments:[0m

                   height=[4mn[0m
                          The height of the row.  If a cell in the row is higher
                          than [4mn[24m, this  value  is  ignored;  otherwise  the  row
                          height is stretched to [4mn[24m.

     [1m.TD [22m[[4margs[24m [[4mcell[24m [4mcontents[24m]]
            Begin a table data cell.
     [1m.TH [22m[[4margs[24m [[4mcell[24m [4mcontents[24m]]
            Begin a table header cell.

            Arguments  and cell contents can be mixed.  The macro .TH is not re‐
            ally necessary and differs from .TD only in three default  settings,
            similar to the <TH> and <TD> HTML tags: The contents of .TH is hori‐
            zontally and vertically centered and typeset in boldface.

            [1mpredecessor: [22m.TR, .TD, .TH, .ETB, cell contents
            [1msuccessor: [22m.TD, .TH, .TR, .ETB, cell contents
            [1marguments:[0m

                   colspan=[4mm[0m
                          The  width  of  this  cell is the sum of the widths of
                          the [4mm[24m cells above and below this row.

                   rowspan=[4mm[0m
                          The height of this cell is the sum of the  heights  of
                          the [4mm[24m cells left and right of this column.

                          [1mRemark:  [22mOverlapping of column and row spanning, as in
                          the following table fragment (the overlapping  happens
                          in  the second cell in the second row), is invalid and
                          causes incorrect results.

                                 .TR .TD 1*1 ".TD 1*2 rowspan=2" .TD 1*3
                                 .TR ".TD 2*1 colspan=2"         .TD 2*3

                   A working example for headers and cells with [1mcolspan [22mis

                          .TBL cols=3
                          .  TR ".TH colspan=2" header1+2 .TH header3
                          .  TR .TD 1*1 .TD 1*2 .TD 1*3
                          .  TR .TD 2*1 ".TD colspan=2" 2*2+3
                          .ETB

                   This looks like

                          +------------------------------+---------------+
                          |          header1+2           |    header3    |
                          +--------------+---------------+---------------+
                          | 1*1          | 1*2           | 1*3           |
                          +--------------+---------------+---------------+
                          | 2*1          | 2*2+3                         |
                          +--------------+-------------------------------+

                   A working example with [1mrowspan [22mis

                          .TBL cols=3
                          .  TR
                          .  TD 1*1
                          .  TD rowspan=2 1+2*2
                          .  TD 1*3
                          .
                          .  TR
                          .  TD 2*1
                          .  TD 2*3
                          .ETB

                   which looks like

                          +--------------+---------------+---------------+
                          | 1*1          | 1+2*2         | 1*3           |
                          +--------------+               +---------------+
                          | 2*1          |               | 2*3           |
                          +--------------+---------------+---------------+

     [1m.ETB [22m[[1mhold[22m]
            End of the table.

            This macro finishes a table.  It causes one  of  the  following  ac‐
            tions.

            •  If  the  argument  ‘hold’ is given, the table is held until it is
               freed by calling the macro .t*free, which in turn prints the  ta‐
               ble  immediately, either at the current position or at the top of
               the next page if its height is larger than the remaining space on
               the page.

            •  Otherwise, if the table is higher than the remaining space on the
               page, it is printed at the top of the next page.

            •  If neither of the  two  above  constraints  hold,  the  table  is
               printed immediately at the place of its definition.

            [1mpredecessor: [22m.TD, .TH, .ETB, cell contents
            [1msuccessor: [22m.TBL, .TR, .TD, .TH, .ETB, cell contents
            [1marguments:[0m

                   hold   Prevent the table from being printed until it is freed
                          by  calling  the  macro .t*free.  This argument is ig‐
                          nored for inner (nested) tables.

     [1m.t*free [22m[[4mn[24m]
            Free the next held table or [4mn[24m held tables.  Call this utility  macro
            to  print  tables which are held by using the ‘hold’ argument of the
            .ETB macro.

   [1mArguments common to .TBL, .TR, .TD, and .TH[0m
     The arguments described in this section can be specified with the .TBL  and
     .TR macros, but they are eventually passed on to the table cells.  If omit‐
     ted, the defaults take place, which the user can change by setting the cor‐
     responding  default  registers or strings, as documented below.  Setting an
     argument with the .TBL macro has the same effect as setting it for all rows
     in the table.  Setting an argument with a .TR macro has the same effect  as
     setting it for all the .TH or .TD macro in this row.

     bgc=[[4mc[24m]
            The  background  color  of  the table cells.  This includes the area
            specified with the ‘csp’ argument.  The argument ‘bgc=’  (no  value)
            suppresses  a  background color; this makes the background transpar‐
            ent.
            [1mDefault: [22m‘bgc=bisque’ (string ‘t*bgc’).

     fgc=[4mc[24m  The foreground color of the cell contents.
            [1mDefault: [22m‘fgc=red4’ (string ‘t*fgc’).

     ff=[4mname[0m
            The font family for the table.  [4mname[24m is a [4mgroff[24m font family  identi‐
            fier, such as A for Avant Garde or HN for Helvetica Narrow.
            [1mDefault: [22mThe font family found before the table (string ‘t*ff’).

     fst=[4mstyle[0m
            The  font  style  for  the  table.  One of R, B, I, or BI for roman,
            [1mbold[22m, [4mitalic[24m, or [4m[1mbold[24m [4mitalic[24m[22m, respectively.  As with [4mroff[24m’s [1m.ft  [22mre‐
            quest, the ‘fst’ argument can be used to specify the font family and
            font  style  together, for example ‘fst=HNBI’ instead of ‘ff=HN’ and
            ‘fst=BI’.
            [1mDefault: [22mThe font style  in  use  right  before  the  table  (string
            ‘t*fst’).

     fsz='[4md1[24m [[4md2[24m]'
            A  decimal  or fractional factor [4md1[24m, by which the point size for the
            table is changed, and [4md2[24m, by which  the  vertical  line  spacing  is
            changed.  If [4md2[24m is omitted, value [4md1[24m is taken for both.
            [1mDefault: [22m‘fsz='1.0 1.0'’ (string ‘t*fsz’).

     hal=l|c|b|r
            Horizontal  alignment  of  the cell contents in the table.  ‘hal=l’:
            left alignment.  ‘hal=c’: centered alignment.  ‘hal=b’:  both  (left
            and right) alignment.  ‘hal=r’: right alignment.
            [1mDefault: [22m‘hal=b’ (string ‘t*hal’).

     val=t|m|b
            Vertical alignment of the cell contents in the table for cells lower
            than the current row.  ‘val=t’: alignment below the top of the cell.
            ‘val=m’:  alignment  in  the middle of the cell.  ‘val=b’: alignment
            above the cell bottom.
            [1mDefault: [22m‘val=t’ (string ‘t*val’).

     hl=[s|d]
            Horizontal line between the rows.  If specified with .TD or .TH this
            is a separator line to the cell below.  ‘hl=’ (no value): no separa‐
            tor line.   ‘hl=s’:  a  single  separator  line  between  the  rows.
            ‘hl=d’: a double separator line.

            The  thickness  of  the  separator  lines  is the half of the border
            thickness, but at least 0.1 inches.  The distance between the double
            lines is equal to the line thickness.

            [1mRemark: [22mTogether with ‘border=0’ for proper formatting the value  of
            ‘csp’  must  be  at  least .05 inches for single separator lines and
            .15 inches for double separator lines.
            [1mDefault: [22m‘hl=s’ (string ‘t*hl’).

     vl=[s|d]
            Vertical separator line between the cells.  If specified with .TD or
            .TH this is a separator line to the cell on the  right.   ‘vl=s’:  a
            single separator line between the cells.  ‘vl=d’: a double separator
            line.  ‘vl=’ (no value): no vertical cell separator lines.  For more
            information see the documentation of the ‘hl’ argument above.
            [1mDefault: [22m‘vl=s’ (string ‘t*vl’).

[4m[1mhdtbl[24m customization[0m
     Before  creating  the  first  table, you should configure default values to
     minimize the markup needed in each table.  The following  example  sets  up
     defaults suitable for typical papers:

            .ds t*bgc white\" background color
            .ds t*fgc black\" foreground color
            .ds t*bc black\"  border color
            .nr t*cpd 0.1n\"  cell padding

     The  file  [4m/usr/share/doc/groff-1.24.0/examples/hdtbl/common.roff[24m  provides
     another example setup in the “minimal Page setup” section.

     A table which does not fit on a partially filled page is printed  automati‐
     cally  on  the  top of the next page if you append the little utility macro
     t*hm to the page header macro of your document’s main macro  package.   For
     example, say

            .am pg@top
            .  t*hm
            ..

     if you use the [4mms[24m macro package.

     The  macro  t*EM checks for held or kept tables, and for missing ETB macros
     (table not closed).  You can call this macro by appending it the to end‐of‐
     input macro of the main, or “full‐service”,  macro  package  your  document
     uses.  For example, try
            .am pg@end-text
            .  t*EM
            ..
     if you use the [4mms[24m package.

[1mBugs and suggestions[0m
     Please  send your comments to the ]8;;mailto:groff@gnu.org\[4mgroff[24m mailing list]8;;\ or directly to the au‐
     thor.

[1mAuthors[0m
     The [4mhdtbl[24m macro package was written by ]8;;mailto:Joachim.Walsdorff@urz.uni-heidelberg.de\Joachim Walsdorff]8;;\.

[1mSee also[0m
     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\
            provides an overview of GNU [4mroff[24m and details how to invoke [4mgroff[24m  at
            the command line.

     ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\
            summarizes the [4mroff[24m language and GNU extensions to it.

     ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\
            describes the traditional [4mroff[24m preprocessor for tables.

groff 1.24.0                       2026‐02‐17                     [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 and font style to de‐
     faults, and restore the configured hyphenation mode.

     [1m.P[0m
     [1m.LP[0m
     [1m.PP    [22mBegin a new paragraph; these macros are synonymous.  Any indentation
            from use of [1mIP[22m, [1mTP[22m, or [1mHP [22mis cleared.  The inset amount, as affected
            by [1mRS [22mand [1mRE[22m, is not.

     [1m.HP [22m[[4mindentation[24m]
            Set a paragraph with a hanging indentation.  Text  on  output  lines
            after the first is indented by [4mindentation,[24m if specified, and by the
            amount of the [1mIN [22mregister otherwise.

            [4mCaution:[24m  A  hanging  indentation  cannot  be expressed naturally in
            (pure) HTML, a hanging paragraph is not distinguishable from an  or‐
            dinary one if it formats on only one output line, and non‐[4mroff[24m‐based
            man  page interpreters may treat [1mHP [22mas an ordinary paragraph anyway.
            Thus, information or distinctions you mean to express with  indenta‐
            tion may be lost.

     [1m.TP [22m[[4mindentation[24m]
            Set  an indented paragraph with a leading unindented tag.  The macro
            plants a one‐line input trap that honors  the  [1m\c  [22mescape  sequence;
            text  on  the  next  line  becomes the tag, set without indentation.
            Text on subsequent lines is indented by [4mindentation,[24m  if  specified,
            and  by  the  amount of the [1mIN [22mregister otherwise.  If the tag, plus
            the “tag spacing” stored in the [1mTS [22mregister (see  section  “Options”
            below)  is  wider  than the indentation, the package breaks the line
            after the tag.

     [1m.TQ    [22mSet an additional tag for a paragraph tagged  with  [1mTP[22m,  planting  a
            one‐line input trap as with [1mTP[22m.

            [1mTQ  [22mis  a  GNU extension supported by Heirloom Doctools [4mtroff[24m (since
            Git snapshot 151218) and [4mmandoc[24m  (since  1.14.5)  but  not  by  DWB,
            Plan 9, or Solaris [4mtroff[24ms.

     [1m.IP [22m[[4mmark[24m [[4mindentation[24m]]
            Set  an  indented  paragraph  with  an optional mark.  Arguments, if
            present, are handled as with [1mTP[22m, except that the [4mmark[24m argument to [1mIP[0m
            cannot include a macro call, and the tag separation amount stored in
            the [1mTS [22mregister is not enforced.

   [1mSynopsis macros[0m
     Use [1mSY [22mand [1mYS [22mto summarize syntax using familiar Unix  conventions.   Heir‐
     loom  Doctools  [4mtroff[24m (since Git snapshot 151218) and [4mmandoc[24m (since 1.14.5)
     support these GNU extensions; DWB, Plan 9, and Solaris [4mtroff[24ms do not.

     [1m.SY [4m[22mkeyword[24m [[4msuffix[24m]
            Begin synopsis.  Adjustment and automatic hyphenation are  disabled.
            If [1mSY [22mhas already been called without a corresponding [1mYS[22m, a break is
            performed.   [4mkeyword[24m and any [4msuffix[24m are set in bold.  When [4msuffix[24m is
            present, the package sets the next word after it without intervening
            space.  If a break is required in subsequent text  (up  to  a  para‐
            graphing,  sectioning,  or [1mYS [22mmacro call), lines after the first are
            indented.  Unless the previous synopsis’s indentation is reused (see
            [1mYS [22mbelow), output lines after the first indent by the width  of  the
            pending  output  line up to the end of [4mkeyword[24m plus a space, if [4mkey‐[0m
            [4mword[24m is the only argument, and up to the end of [4msuffix[24m otherwise.

     [1m.YS [22m[[4mreuse‐indentation[24m]
            End synopsis, breaking the line and restoring  indentation,  adjust‐
            ment,  and  hyphenation to their previous states.  If an argument is
            given, the indentation corresponding to  the  previous  [1mSY  [22mcall  is
            reused by the next [1mSY [22mcall instead of being computed.

   [1mHyperlink macros[0m
     Man page cross references are best presented with [1mMR[22m.  Mark email addresses
     with [1mMT[22m/[1mME [22mand other sorts of URI with [1mUR[22m/[1mUE[22m.  To hyperlink text, terminals
     and  pager  programs  must  support  ECMA‐48  OSC  8  escape sequences (see
     ]8;;man:grotty(1)\[4mgrotty[24m(1)]8;;\).  When device support is unavailable or disabled with the [1mU [22mreg‐
     ister (see section “Options” below), [4mgroff[24m [4mman[24m renders these  URIs  between
     angle brackets ([1m⟨ ⟩[22m) after the linked text.

     [1mMT[22m,  [1mME[22m, [1mUR[22m, and [1mUE [22mare GNU extensions supported by Heirloom Doctools [4mtroff[0m
     (since Git snapshot 151218) and [4mmandoc[24m ([1mUR[22m/[1mUE  [22msince  1.12.3;  [1mMT[22m/[1mME  [22msince
     1.14.2)  but not by DWB, Plan 9 (original), or Solaris [4mtroff[24ms.  Plan 9 from
     User Space’s [4mtroff[24m implements [1mMR[22m.

     Prepare arguments to [1mMR[22m, [1mMT[22m, and [1mUR [22mfor typesetting; they can appear in the
     output.  Use special character escape sequences  to  encode  Unicode  basic
     Latin characters where necessary, particularly the hyphen‐minus.

     [1m.MR [4m[22mtopic[24m [[4mmanual‐section[24m [[4mtrailing‐text[24m]]
            [4m(since[24m  groff [4m1.23)[24m Set a man page cross reference as “[4mtopic[24m[1m([4m[22mmanual‐[0m
            [4msection[24m[1m)[22m”.  If [4mmanual‐section[24m is absent, the package omits the  sur‐
            rounding  parentheses.   If [4mtrailing‐text[24m (typically punctuation) is
            specified, it follows the closing  parenthesis  without  intervening
            space.   Hyphenation  is  disabled while the cross reference is set.
            [4mtopic[24m is set in the font specified by the [1mMF [22mstring.  If [4mmanual‐sec‐[0m
            [4mtion[24m is present, the cross reference hyperlinks to a URI of the form
            “[1mman:[4m[22mtopic[24m([4mmanual‐section[24m)”.

     [1m.MT [4m[22maddress[0m
     [1m.ME [22m[[4mtrailing‐text[24m]
            Identify [4maddress[24m as an RFC 6068 [4maddr‐spec[24m for a “mailto:”  URI  with
            the  text between the two macro calls as the link text.  An argument
            to [1mME [22mis placed after the link text without intervening space.   [4mad‐[0m
            [4mdress[24m  may not be visible in the rendered document if hyperlinks are
            enabled and supported by the output driver.  If they  are  not,  [4mad‐[0m
            [4mdress[24m is set in angle brackets after the link text and before [4mtrail‐[0m
            [4ming‐text.[24m  If hyperlinking is enabled but there is no link text, [4mad‐[0m
            [4mdress[24m  is  formatted  and hyperlinked [4mwithout[24m angle brackets, except
            when [4maddress[24m appears as a [1mTP [22mparagraph tag.

     [1m.UR [4m[22muri[0m
     [1m.UE [22m[[4mtrailing‐text[24m]
            Identify [4muri[24m as an RFC 3986 URI hyperlink with the text between  the
            two macro calls as the link text.  An argument to [1mUE [22mis placed after
            the  link text without intervening space.  [4muri[24m may not be visible in
            the rendered document if hyperlinks are enabled and supported by the
            output driver.  If they are not, [4muri[24m is set in angle brackets  after
            the  link text and before [4mtrailing‐text.[24m  If hyperlinking is enabled
            but there is no link text, [4muri[24m is formatted and hyperlinked  [4mwithout[0m
            angle brackets, except when [4muri[24m appears as a [1mTP [22mparagraph tag.

     If  a  [1mUR[22m/[1mUE  [22mor [1mMT[22m/[1mME [22mpair occurs in a [1mTP [22mtag and hyperlinking is unavail‐
     able, [4mgroff[24m [4mman[24m sets the link target at the beginning of the indented para‐
     graph, not as part of the tag, unless there is no link text.

   [1mFont style macros[0m
     The [4mman[24m macro package is limited in its font styling options, offering only
     [1mbold [22m([1mB[22m), [4mitalic[24m ([1mI[22m), and roman.  Italic text  may  instead  render  under‐
     scored  on  terminals.   [1mSM [22msets text at a smaller type size, which differs
     visually from regular‐sized text only on typesetters.  The macros  [1mBI[22m,  [1mBR[22m,
     [1mIB[22m,  [1mIR[22m,  [1mRB[22m,  and [1mRI [22mset their odd‐ and even‐numbered arguments as text in
     the alternating styles their names indicate, with no space separating them.

     The default type size and family for typesetters is 10‐point Times,  except
     on  the  [1mX75-12  [22mand [1mX100-12 [22mdevices where the type size is 12 points.  The
     default style is roman.

     [1m.B [22m[[4mtext[24m]
            Set [4mtext[24m in bold.  Given no argument,  [1mB  [22mplants  a  one‐line  input
            trap;  text  on the next line, which can be further formatted with a
            macro, is set in bold.

     [1m.I [22m[[4mtext[24m]
            Set [4mtext[24m in an italic or oblique face.  Given no argument, [1mI  [22mplants
            a  one‐line  input trap; text on the next line, which can be further
            formatted with a macro, is set in an italic or oblique face.

     [1m.SM [22m[[4mtext[24m]
            Set [4mtext[24m one point smaller than the default type  size  on  typeset‐
            ters.   Given  no argument, [1mSM [22mplants a one‐line input trap; text on
            the next line, which can be further formatted with a macro,  is  set
            smaller.

     Unlike the above font style macros, the font style alternation macros below
     set  no input traps; they must be given arguments to have effect.  They ap‐
     ply italic corrections as appropriate.

     [1m.BI [4m[22mbold‐text[24m [4mitalic‐text[24m ...
            Set each argument in bold and italics, alternately.

     [1m.BR [4m[22mbold‐text[24m [4mroman‐text[24m ...
            Set each argument in bold and roman, alternately.

     [1m.IB [4m[22mitalic‐text[24m [4mbold‐text[24m ...
            Set each argument in italics and bold, alternately.

     [1m.IR [4m[22mitalic‐text[24m [4mroman‐text[24m ...
            Set each argument in italics and roman, alternately.

     [1m.RB [4m[22mroman‐text[24m [4mbold‐text[24m ...
            Set each argument in roman and bold, alternately.

     [1m.RI [4m[22mroman‐text[24m [4mitalic‐text[24m ...
            Set each argument in roman and italics, alternately.

   [1mHorizontal and vertical spacing[0m
     The package sets all text inboard of the left edge of the output medium  by
     the  amount of the [4mpage[24m [4moffset;[24m see register [1mPO [22min section “Options” below.
     Headers, footers (both set with [1mTH[22m), and section headings ([1mSH[22m) lie  at  the
     page  offset.   [4mgroff[24m [4mman[24m indents subsection headings ([1mSS[22m) by the amount in
     the [1mSN [22mregister.

     Ordinary paragraphs not within an [1mRS[22m/[1mRE  [22minset  region  are  inset  by  the
     amount stored in the [1mBP [22mregister; see section “Options” below.  The [1mIN [22mreg‐
     ister  configures  the default indentation amount used by [1mRS [22m(as the [4minset‐[0m
     [4mamount[24m), [1mIP[22m, [1mTP[22m, and [1mHP[22m; an overriding argument is a  number  plus  an  op‐
     tional  scaling unit.  If no scaling unit is given, the [4mman[24m package assumes
     “n”.  An indentation specified in a call to [1mIP[22m, [1mTP[22m, or  [1mHP  [22mpersists  until
     (1)  another of these macros is called with an [4mindentation[24m argument, or (2)
     [1mSH[22m, [1mSS[22m, or [1mP [22mor its synonyms is called; these  clear  the  indentation  en‐
     tirely.

     Several macros insert vertical space: [1mSH[22m, [1mSS[22m, [1mTP[22m, [1mP [22m(and its synonyms), [1mIP[22m,
     and  [1mHP[22m.  They then enable [4mno‐space[24m [4mmode;[24m see ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\.  The default inter‐
     section and inter‐paragraph spacing is 1v for terminals and 0.4v for  type‐
     setters.  (The deprecated macro [1mPD [22mcan change this vertical spacing, but we
     discourage  its use.)  Between [1mEX [22mand [1mEE [22mcalls, the inter‐paragraph spacing
     is 1v regardless of output device.

   [1mRegisters[0m
     Registers are described in section “Options” below.  They can  be  set  not
     only  on  the command line but in the site [4mman.local[24m file as well; see sec‐
     tion “Files” below.

   [1mStrings[0m
     The following strings are defined for use in man pages.  None of  these  is
     necessary  in  a  contemporary man page; see ]8;;man:groff_man_style(7)\[4mgroff_man_style[24m(7)]8;;\.  [4mgroff[24m [4mman[0m
     supports others for configuration of rendering parameters; see section “Op‐
     tions” below.

     [1m\*R     [22minterpolates a special character escape sequence  for  the  “regis‐
             tered sign” glyph, [1m\(rg[22m, if available, and “(Reg.)” otherwise.

     [1m\*S     [22minterpolates  an escape sequence setting the type size to the docu‐
             ment default.

     [1m\*(lq[0m
     [1m\*(rq   [22minterpolate special character escape sequences for left  and  right
             double‐quotation marks, [1m\(lq [22mand [1m\(rq[22m, respectively.

     [1m\*(Tm   [22minterpolates  a  special  character  escape sequence for the “trade
             mark sign” glyph, [1m\(tm[22m, if available, and “(TM)” otherwise.

   [1mHooks[0m
     Two macros, both GNU extensions, are called internally  by  the  [4mgroff[24m  [4mman[0m
     package  to format page headers and footers and can be redefined by the ad‐
     ministrator in a site’s [4mman.local[24m file (see section  “Files”  below).   The
     presentation  of  [1mTH  [22mabove describes the default headers and footers.  Be‐
     cause these macros are hooks for [4mgroff[24m [4mman[24m internals,  man  pages  have  no
     reason  to  call them.  Such hook definitions typically consist of “sp” and
     “tl” requests.  [1mPT [22mfurthermore has the responsibility  of  emitting  a  PDF
     bookmark  after  writing  the first page header in a document.  Consult the
     existing implementations in [4man.tmac[24m when drafting replacements.

     [1m.BT    [22mSet the page footer text (“bottom trap”).

     [1m.PT    [22mSet the page header text (“page trap”).

     To remove a page header or footer entirely, define the appropriate macro as
     empty rather than deleting it.

   [1mDeprecated features[0m
     Use of the following in man pages for public distribution is discouraged.

     [1m.AT [22m[[4msystem[24m [[4mrelease[24m]]
            Alter the footer for use with legacy AT&T man pages, overriding  any
            definition  of  the [4mfooter‐inside[24m argument to [1mTH[22m.  This macro exists
            only to render man pages from historical systems.

            The inside footer is populated per the value of [4msystem.[0m

                   3      7th edition [4m(default)[0m

                   4      System III

                   5      System V

            The optional [4mrelease[24m argument specifies the release  number,  as  in
            “System V Release 3”.

     [1m.DT    [22mReset tab stops to the default (every 0.5i).

            Use  of  this  presentation‐oriented macro is deprecated.  It trans‐
            lates poorly to HTML, under which exact space control and tabulation
            are not readily available.  Thus, information or  distinctions  that
            you  use  tab  stops  to express are likely to be lost.  If you feel
            tempted to change the tab stops such that calling this  macro  later
            to  restore  them  is  desirable,  consider  composing a table using
            ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\ instead.

     [1m.OP [4m[22moption‐name[24m [[4moption‐argument[24m]
            Indicate an optional command parameter called [4moption‐name[24m, which  is
            set  in bold.  If the option takes an argument, specify [4moption‐argu‐[0m
            [4mment[24m using a noun, abbreviation,  or  hyphenated  noun  phrase.   If
            present,  [4moption‐argument[24m is preceded by a space and set in italics.
            Square brackets in roman surround both arguments.

            Use of this quasi‐semantic macro, an extension whose name originated
            in DWB [4mtroff[24m, is deprecated; [4mgroff[24m’s interface differs.  Neither can
            easily be used to annotate options that take optional  arguments  or
            options  whose  arguments have internal structure (such as a mixture
            of literal and variable components).  One could  work  around  these
            limitations with font selection escape sequences, but font style al‐
            ternation  macros are preferable; they are more flexible and perform
            italic corrections on typesetters.

     [1m.PD [22m[[4mvertical‐space[24m]
            Configure  the  amount  of  vertical  space  between  paragraphs  or
            (sub)sections.   The  optional argument [4mvertical‐space[24m specifies the
            amount; the default scaling unit is “v”.  Without an  argument,  in‐
            ter‐paragraph  spacing  resets  to its default value; see subsection
            “Horizontal and vertical spacing” above.

            Use of this presentation‐oriented macro is  deprecated.   It  trans‐
            lates  poorly  to HTML, under which exact control of inter‐paragraph
            spacing is not readily available.  Thus, information or distinctions
            that you use [1mPD [22mto express are likely to be lost.

     [1m.SB [22m[[4mtext[24m]
            Set [4mtext[24m in bold and (on typesetters) one point smaller than the de‐
            fault type size.  Given no argument,  [1mSB  [22mplants  a  one‐line  input
            trap;  text  on the next line, which can be further formatted with a
            macro, is set smaller and in bold.  Use of this macro, an  extension
            originating  in SunOS 4.0 [4mtroff[24m, is deprecated.  [1mSM [22mwithout an argu‐
            ment, followed immediately by “[1mB [4m[22mtext[24m”,  produces  the  same  output
            more  portably.  The macros’ order is interchangeable; put [4mtext[24m with
            the latter.

     [1m.UC [22m[[4mversion[24m]
            Alter the footer for use with legacy BSD man pages,  overriding  any
            definition  of  the [4mfooter‐inside[24m argument to [1mTH[22m.  This macro exists
            only to render man pages from historical systems.

            The inside footer is populated per the value of [4mversion.[0m

                   3      3rd Berkeley Distribution [4m(default)[0m

                   4      4th Berkeley Distribution

                   5      4.2 Berkeley Distribution

                   6      4.3 Berkeley Distribution

                   7      4.4 Berkeley Distribution

   [1mHistory[0m
     ]8;;mailto:m.douglas.mcilroy@dartmouth.edu\M. Douglas McIlroy]8;;\ designed,  implemented,  and  documented  the  AT&T  [4mman[0m
     macros  for Unix Version 7 (1979) and employed them to edit Volume 1 of its
     [4mProgrammer’s[24m [4mManual[24m, a compilation of all man pages supplied by the system.
     The package supported the macros listed in this page not described  as  ex‐
     tensions,  except  [1mP [22mand the deprecated [1mAT [22mand [1mUC[22m.  It documented no regis‐
     ters and defined only [1mR [22mand [1mS [22mstrings.

     [1mUC [22mappeared in 3BSD (1980).  Unix System III (1980) introduced  [1mP  [22mand  ex‐
     posed  the  registers [1mIN [22mand [1mLL[22m, which had been internal to Seventh Edition
     Unix [4mman[24m.  PWB/Unix 2.0 (1980) added the [1mTm [22mstring.  4BSD (1980)  added  [1mlq[0m
     and  [1mrq  [22mstrings.   SunOS  2.0  (1985) recognized [1mC[22m, [1mD[22m, [1mP[22m, and [1mX [22mregisters.
     4.3BSD (1986) added [1mAT [22mand [1mP[22m.  Ninth Edition Unix (1986) introduced [1mEX  [22mand
     [1mEE[22m.   SunOS  4.0 (1988) added [1mSB[22m.  Unix System V (1988) incorporated the [1mlq[0m
     and [1mrq [22mstrings.

     Except for [1mEX[22m/[1mEE[22m, James Clark implemented the foregoing features  in  early
     versions  of  [4mgroff.[24m  Later, [4mgroff[24m 1.20 (2009) resurrected [1mEX[22m/[1mEE [22mand origi‐
     nated [1mSY[22m/[1mYS[22m, [1mTQ[22m, [1mMT[22m/[1mME[22m, and [1mUR[22m/[1mUE[22m.  Plan 9 from User Space’s  [4mtroff[24m  intro‐
     duced [1mMR [22min 2020, and incorporated the [1mlq [22mand [1mrq [22mstrings in 2025.

[1mOptions[0m
     The  following  [4mgroff[24m options set registers (with [1m-r[22m) and strings (with [1m-d[22m)
     recognized and used by the [4mman[24m macro package.  To ensure rendering  consis‐
     tent  with  output  device  capabilities  and reader preferences, man pages
     should never manipulate them.

     [1m-dAD=[4m[22madjustment‐mode[0m
              Set line adjustment to [4madjustment‐mode,[24m which is typically “[1mb[22m” for
              adjustment to both margins (the default), or “[1ml[22m” for  left  align‐
              ment  (ragged  right  margin).  Any valid argument to [4mgroff[24m’s “ad”
              request may be used.  See ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\ for less‐common choices.

     [1m-rBP=[4m[22mbase‐paragraph‐inset[0m
              Set the inset amount for ordinary paragraphs not within  an  [1mRS[22m/[1mRE[0m
              inset.  The default is 5n.

     [1m-rcR=1   [22mEnable  continuous  rendering.   Output is not paginated; instead,
              one (potentially very long) page is produced.  This is the default
              for terminal and HTML devices.  Use [1m-rcR=0 [22mto disable it on termi‐
              nals; on HTML devices, it cannot be disabled.

     [1m-rC1     [22mNumber output pages  consecutively,  in  strictly  increasing  se‐
              quence,  rather  than resetting the page number to 1 (or the value
              of register [1mP[22m) with each new [4mman[24m document.

     [1m-rCHECKSTYLE=[4m[22mn[0m
              Report problems with usage of this macro package exhibited by  the
              input  at  verbosity  level  [4mn[24m, where [4mn[24m is an integer in the range
              0–3, inclusive; [1m0 [22mdisables the messages and is the default.   This
              feature  is a development and debugging aid for man page maintain‐
              ers; the problems diagnosed, and range and meanings  of  the  sup‐
              ported levels, are subject to change.

     [1m-rCS=1   [22mSet  section  headings  (the  argument(s) to [1mSH[22m) in full capitals.
              This transformation is off by default because it discards  letter‐
              case distinctions.

     [1m-rCT=1   [22mSet  the  man  page  identifier (the first argument to [1mTH[22m) in full
              capitals in headers and footers.  This transformation  is  off  by
              default because it discards lettercase distinctions.

     [1m-rD1     [22mEnable  double‐sided  layout,  formatting footers for even and odd
              pages differently; see the description of [1mTH [22min subsection  “Docu‐
              ment structure macros” above.

     [1m-rFT=[4m[22mfooter‐distance[0m
              Set  distance  of the footer relative to the bottom of the page to
              [4mfooter‐distance;[24m this amount is always negative.  At one half‐inch
              above this location, the page text is broken  before  writing  the
              footer.   Ignored if continuous rendering is enabled.  The default
              is “-0.5i - 1v”.

     [1m-dHF=[4m[22mheading‐font[0m
              Select the font used for section and subsection headings; the  de‐
              fault  is “[1mB[22m” (bold style of the default family).  Any valid argu‐
              ment to [4mgroff[24m’s “ft” request may be used.  See ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\.

     [1m-rHY=0   [22mDisable automatic hyphenation.  Normally, it is enabled (1).   The
              hyphenation  mode  is  determined by the [4mgroff[24m locale; see section
              “Localization“ of ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\.

     [1m-rIN=[4m[22mstandard‐indentation[0m
              Set the default indentation amount used by [1mIP[22m, [1mTP[22m, and [1mHP[22m, and the
              inset amount used by [1mRS[22m.  The default is 7n on terminals and  7.2n
              on  typesetters.  Use only integer multiples of unit “n” on termi‐
              nals for consistent indentation.

     [1m-rLL=[4m[22mline‐length[0m
              Set line length; the default is 80n on terminals and 6.5i on type‐
              setters.

     [1m-rLT=[4m[22mtitle‐length[0m
              Set the line length for titles.  By default, it is set to the line
              length (see [1m-rLL [22mabove).

     [1m-dMF=[4m[22mman‐page‐topic‐font[0m
              Select the font used for man page identifiers in [1mTH [22mcalls and top‐
              ics named in [1mMR [22mcalls; the default is “[1mI[22m” (italic style of the de‐
              fault family).  Any valid argument to [4mgroff[24m’s “ft” request may  be
              used.   If the [1mMF [22mstring ends in “I”, the package assumes it to be
              an oblique typeface, and applies italic corrections before and af‐
              ter man page topics and identifiers.

     [1m-rP[4m[22mn[24m     Start enumeration of pages at [4mn[24m.  The default is 1.

     [1m-rPO=[4m[22mpage‐offset[0m
              Set page offset; the default is 0 on terminals and 1i on  typeset‐
              ters.

     [1m-rS[4m[22mtype‐size[0m
              Use  [4mtype‐size[24m for the document’s body text; acceptable values are
              10, 11, or 12 points.  See subsection “Font  style  macros”  above
              for the default.

     [1m-rSN=[4m[22msubsection‐indentation[0m
              Set  indentation of subsection headings to [4msubsection‐indentation.[0m
              The default is 3n.

     [1m-rTS=[4m[22mseparation[0m
              Require the given [4mseparation[24m between a [1mTP [22mparagraph’s tag and  its
              body.  The default is 2n.

     [1m-rU0     [22mDisable  generation of URI hyperlinks in output drivers capable of
              them, making the arguments to [1mMT [22mand [1mUR [22mcalls visible as formatted
              text.  ]8;;man:grohtml(1)\[4mgrohtml[24m(1)]8;;\, ]8;;man:gropdf(1)\[4mgropdf[24m(1)]8;;\, and ]8;;man:grotty(1)\[4mgrotty[24m(1)]8;;\ enable  hyperlinks  by
              default (the last only if not in its legacy output mode).

     [1m-rX[4m[22mp[24m     Number successors of page [4mp[24m as [4mp[24ma, [4mp[24mb, [4mp[24mc, and so forth.  The reg‐
              ister  tracking  the suffixed page letter uses format “a” (see the
              “af” request in ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\).

[1mFiles[0m
     [4m/usr/share/groff/1.24.0/tmac/an.tmac[0m
            Most [4mman[24m macros are defined in this file.  It also loads  extensions
            from [4man-ext.tmac[24m (see below).

     [4m/usr/share/groff/1.24.0/tmac/andoc.tmac[0m
            This brief [4mgroff[24m program detects whether the [4mman[24m or [4mmdoc[24m macro pack‐
            age  is  used by a document and loads the correct macro definitions,
            taking advantage of the fact that pages using them must call  [1mTH  [22mor
            [1mDd[22m,  respectively, before any other macros.  A [4mman[24m program or a user
            typing, for example, “[1mgroff -mandoc page.1[22m”,  need  not  know  which
            package the file [4mpage.1[24m uses.  Multiple man pages, in either format,
            can  be  handled;  [4mandoc[24m  reloads  each  macro package as necessary.
            Page‐local redefinitions of names used by the [4mman[24m or  [4mmdoc[24m  packages
            prior  to  [1mTH  [22mor [1mDd [22mcalls are “clobbered” by the reloading process.
            If you want to provide your own definition of an extension macro  to
            ensure its availability, the [4man-ext.tmac[24m entry below offers advice.

     [4m/usr/share/groff/1.24.0/tmac/an-ext.tmac[0m
            Definitions  of macros described above as extensions (and not depre‐
            cated) are contained in this file; in some cases, they  are  simpler
            versions of definitions appearing in [4man.tmac[24m, and are ignored if the
            formatter is GNU [4mtroff[24m.  They are written to be compatible with AT&T
            [4mtroff[24m and permissively licensed——not copylefted.  To reduce the risk
            of  name space collisions, string and register names begin only with
            “[1mm[22m”.  We encourage man page authors who are concerned  about  porta‐
            bility  to  legacy Unix systems to copy these definitions into their
            pages, and maintainers of [4mtroff[24m implementations or  work‐alike  sys‐
            tems  that format man pages to re‐use them.  To ensure reliable ren‐
            dering, define them after your page calls [1mTH[22m; see the discussion  of
            [4mandoc.tmac[24m  above.   Further,  it  is wise to define such page‐local
            macros (if at all) after the “Name”  section  to  accommodate  timid
            ]8;;man:makewhatis(8)\[4mmakewhatis[24m(8)]8;;\  or ]8;;man:mandb(8)\[4mmandb[24m(8)]8;;\ implementations that easily give up scan‐
            ning for indexing material.

     [4m/usr/share/groff/1.24.0/tmac/man.tmac[0m
            is a wrapper enabling the package to be loaded with the  option  “[1m-m[0m
            [1mman[22m”.

     [4m/usr/share/groff/1.24.0/tmac/mandoc.tmac[0m
            is  a  wrapper  enabling [4mandoc.tmac[24m to be loaded with the option “[1m-m[0m
            [1mmandoc[22m”.

     [4m/usr/share/groff/site-tmac/man.local[0m
            Put site‐local changes and customizations into this file.

[1mAuthors[0m
     James Clark wrote the initial GNU implementation of the [4mman[24m macro  package.
     Later,  ]8;;mailto:wl@gnu.org\Werner  Lemberg]8;;\  supplied  the  [1mS[22m, [1mLT[22m, and [1mcR [22mregisters, the last a
     4.3BSD‐Reno [4mmdoc[24m(7) feature.  ]8;;mailto:kollar@alltel.net\Larry Kollar]8;;\ added the [1mFT[22m, [1mHY[22m, and [1mSN  [22mregis‐
     ters;  the  [1mHF [22mstring; and the [1mPT [22mand [1mBT [22mmacros in [4mgroff[24m 1.19 (2003).  Lem‐
     berg and ]8;;mailto:esr@thyrsus.com\Eric S. Raymond]8;;\ contributed [1mEX[22m/[1mEE[22m, [1mMT[22m/[1mME[22m, [1mUR[22m/[1mUE[22m, [1mTQ[22m, and an  early
     version  of the [1mSY[22m/[1mYS [22mmacros to [4mgroff[24m 1.20 (2009).  ]8;;mailto:g.branden.robinson@gmail.com\G. Branden Robinson]8;;\ im‐
     plemented the [1mAD [22mand [1mMF [22mstrings; [1mCS[22m, [1mCT[22m, and [1mU [22mregisters; and the [1mMR  [22mmacro
     for  [4mgroff[24m  1.23 (2023), and the [1mBP[22m, [1mPO[22m, and [1mTS [22mregisters and a revised im‐
     plementation of the [1mSY[22m/[1mYS [22mmacros for [4mgroff[24m 1.24 (2026).

     ]8;;mailto:sgk@debian.org\Susan G. Kleinmann]8;;\ wrote the initial version of this document for  the  De‐
     bian  GNU/Linux system.  Lemberg imported it to [4mgroff.[24m  He and Robinson re‐
     vised and updated  it.   Raymond  and  Robinson  documented  the  extension
     macros.

[1mSee also[0m
     ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\, ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\, and ]8;;man:refer(1)\[4mrefer[24m(1)]8;;\ are preprocessors used with man pages.  ]8;;man:man(1)\[4mman[24m(1)]8;;\
     describes the man page librarian on your system.  ]8;;man:groff_mdoc(7)\[4mgroff_mdoc[24m(7)]8;;\ details the
     [4mgroff[24m version of BSD’s alternative macro package for man pages.

     ]8;;man:groff_man_style(7)\[4mgroff_man_style[24m(7)]8;;\, ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\, ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\

groff 1.24.0                       2026‐02‐28                       [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 and font  style  to
     defaults, and restore the configured hyphenation mode.

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

     Do  not  put  blank  (empty) lines in a man page source document.  They can
     produce excessive space in the output, or  less  than  is  attempted;  some
     ]8;;man:man(1)\[4mman[24m(1)]8;;\ programs “squeeze” multiple blank output lines into one.

     The  wise [4mman[24m author quotes multi‐word section and subsection headings; the
     [1mSH [22mand [1mSS [22mmacros of ]8;;man:man(7)\[4mman[24m(7)]8;;\ implementations descended from  Seventh  Edition
     Unix supported six arguments at most.  This restriction also applied to the
     [1mB[22m, [1mI[22m, [1mSM[22m, and font style alternation macros.

     Exercise restraint with escape sequences as with requests.  Some escape se‐
     quences  are however required for correct typesetting even in man pages and
     usually do not cause portability problems.  Several of these render  glyphs
     corresponding  to  punctuation code points in the Unicode basic Latin range
     (U+0020–U+007F) that are handled specially in [4mroff[24m input;  the  escape  se‐
     quences below must be used to render them correctly and portably when docu‐
     menting material that uses them as literals——namely, any of the set [1m' - \ ^[0m
     [1m`  ~  [22m(apostrophe,  dash  or  hyphen‐minus, backslash, caret, grave accent,
     tilde).

     [1m\"        [22mComment.  The formatter ignores everything after the double quote
               to the end of the input line.  Place  whole‐line  comments  on  a
               control line immediately after the empty request (“[1m.[22m”).

     [1m\[4m[22mnewline[24m  Join  the next input line to the current one.  Except for the up‐
               date of the input line counter (used for diagnostic messages  and
               related  purposes), a series of lines ending in backslash‐newline
               appears to [4mgroff[24m as a single input line.   Splitting  excessively
               long input lines can ease document maintenance.

     [1m\%        [22mControl hyphenation.  The location of this escape sequence within
               a word marks a hyphenation point, supplementing [4mgroff[24m’s automatic
               hyphenation  patterns.  At the beginning of a word, it suppresses
               any hyphenation breaks within [4mexcept[24m those specified with [1m\%[22m.

     [1m\:        [22mInsert a non‐printing break point.  A word can break  at  such  a
               point,  but  a  hyphen  glyph  is not written to the output if it
               does.  The remainder of the word is  subject  to  hyphenation  as
               normal.  You can use [1m\: [22mand [1m\% [22min combination to control breaking
               of a file name or URI or to permit hyphenation only after certain
               explicit  hyphens  within  a  word.   See  subsection  “Hyperlink
               macros” above for an example.

               [1m\: [22mis a GNU extension also supported by Heirloom  Doctools  [4mtroff[0m
               050915 (September 2005), [4mmandoc[24m 1.13.1 (2014‐08‐10), and [4mneatroff[0m
               (commit 399a4936, 2014‐02‐17), but not by DWB, Plan 9, or Solaris
               [4mtroff[24ms.

     [1m\~        [22mAdjustable  non‐breaking space.  Use this escape sequence to pre‐
               vent a break inside a short phrase or between a  numerical  quan‐
               tity and its corresponding unit(s).

                      Before starting the motor,
                      set the output speed to\~1.
                      There are 1,024\~bytes in 1\~KiB.
                      CSTR\~#8 documents the B\~language.

               [1m\~  [22mis  a GNU extension also supported by Heirloom Doctools [4mtroff[0m
               050915 (September 2005),  [4mmandoc[24m  1.9.14  (2009‐11‐16),  [4mneatroff[0m
               (commit  1c6ab0f6e, 2016‐09‐13), and Plan 9 from User Space [4mtroff[0m
               (commit 93f8143600,  2022‐08‐12),  but  not  by  DWB  or  Solaris
               [4mtroff[24ms.

     [1m\&        [22mDummy  character.   Prefix an input line with it to prevent a dot
               or apostrophe from being interpreted as beginning a [4mroff[24m  control
               line.   Append  [1m\&  [22mto an end‐of‐sentence punctuation sequence to
               keep it from being recognized as such.

     [1m\|        [22mThin space (one‐sixth em on  typesetters,  zero‐width  on  termi‐
               nals);   a   non‐breaking  space.   Used  primarily  in  ellipses
               (“.\|.\|.”) to space the dots more pleasantly on typesetters.

     [1m\c        [22mEnd a text line without inserting space or  attempting  a  break.
               Nothing  on  the input line after this escape sequence is format‐
               ted.  [1m\c [22mis useful when three font styles are needed in a  single
               word, as in a command synopsis.

                      .RB [ \-\-stylesheet=\c
                      .IR name ]

               [1m\c  [22malso helps when changing font styles in [1mEX[22m/[1mEE [22mexamples, since
               they are not filled.

                      .EX
                      $ \c
                      .B groff \-T utf8 \-Z \c
                      .I file \c
                      .B | grotty \-i
                      .EE

               Normally, if filling is enabled, the formatter treats the end  of
               a  text  line like a space.  It checks for the end of a sentence,
               and [4mmay[24m break the output line (if not, it inserts  an  adjustable
               space).   If  filling  is  disabled, the formatter [4mwill[24m break the
               output line, as in [1mEX[22m/[1mEE [22mexamples.  The formatter interprets  the
               next  input  line  as usual, recognizing control lines, including
               macro calls (contrast with [1m\[4m[22mnewline[24m).

               The [1m\f [22mfont selection escape sequence is an  alternative  to  [1m\c[22m;
               see below.  Using [1m\c [22mto continue a [1mTP [22mparagraph tag across multi‐
               ple  input  lines  renders  incorrectly with [4mgroff[24m 1.22.3, [4mmandoc[0m
               1.14.1, older versions of these programs, and perhaps  with  some
               other formatters.

     [1m\e        [22mFormat  the  [4mroff[24m  escape character on the output; widely used in
               man pages to render a backslash glyph.  It works reliably as long
               as the “ec” request is not used, which should never happen in man
               pages, and it is slightly more portable than  the  more  explicit
               [1m\[rs] [22m(“reverse solidus”) special character escape sequence.

     [1m\fB[22m, [1m\fI[22m, [1m\fR[22m, [1m\fP[0m
               Switch to bold, italic, roman, or back to the previous style, re‐
               spectively.   Either [1m\f [22mor [1m\c [22mis needed when three different font
               styles are required in a word.

                      .RB [ \-\-reference\-dictionary=\fI\,name\/\fP ]

                      .RB [ \-\-reference\-dictionary=\c
                      .IR name ]

               Style escape sequences may be more portable than  [1m\c[22m.   As  shown
               above,  it  is  up  to you to account for italic corrections with
               “[1m\/[22m” and “[1m\,[22m”, which are themselves GNU  extensions,  if  desired
               and if supported by your implementation.

               [1m\fP  [22mreliably  returns  to the style in use immediately preceding
               the previous [1m\f [22mescape sequence only if no sectioning, paragraph,
               example, or style macro calls have intervened.

               As long as at most two styles are needed in a word, style  macros
               like [1mB [22mand [1mBI [22musually result in more readable [4mroff[24m source than [1m\f[0m
               escape sequences do.

     Several special characters are also widely portable.  Except for [1m\-[22m, [1m\[em][22m,
     and [1m\[ga][22m, AT&T [4mtroff[24m did not consistently define the characters listed be‐
     low,  but  its descendants, like DWB, Plan 9, or Solaris [4mtroff[24m, can be made
     to support them by defining them in font  description  files,  making  them
     aliases  of  existing  glyphs if necessary; see ]8;;man:groff_font(5)\[4mgroff_font[24m(5)]8;;\.  [4mgroff[24m’s ex‐
     tended notation  for  special  characters,  [1m\[[4m[22mxx[24m[1m][22m,  is  also  supported  by
     ]8;;man:mandoc(1)\[4mmandoc[24m(1)]8;;\,  Heirloom  Doctools [4mtroff[24m, and [4mneatroff[24m, but not DWB, Plan 9, or
     Solaris [4mtroff[24ms.

     [1m\-     [22mMinus sign.  [1m\- [22mproduces the basic Latin hyphen‐minus (U+002D) spec‐
            ifying Unix command‐line options and frequently used in file  names.
            “[1m-[22m”  is  a  hyphen  in [4mroff[24m; some output devices format it as U+2010
            (hyphen).

     [1m\[aq]  [22mBasic Latin neutral apostrophe.  Some output devices format “[1m'[22m” as a
            right single quotation mark.

     [1m\[oq][0m
     [1m\[cq]  [22mOpening (left) and closing  (right)  single  quotation  marks.   Use
            these for paired directional single quotes, ‘like this’.

     [1m\[dq]  [22mBasic Latin quotation mark (double quote).  Employ it in macro calls
            to work around interpretation of ‘[1m"[22m’ as an argument delimiter.

                   .TP
                   .BI "split \[dq]" text \[dq]

     [1m\[lq][0m
     [1m\[rq]  [22mLeft  and right double quotation marks.  Use these for paired direc‐
            tional double quotes, “like this”.

     [1m\[em]  [22mEm dash.  Use for an interruption——such as this one——in a sentence.

     [1m\[en]  [22mEn dash.  Use to separate the ends of a range, as  between  numbers;
            for example, “the digits 1–9”.

     [1m\[ga]  [22mBasic  Latin grave accent.  Some output devices format “[1m`[22m” as a left
            single quotation mark.

     [1m\[ha]  [22mBasic Latin circumflex accent (“hat”).  Some output  devices  format
            “[1m^[22m” as U+02C6 (modifier letter circumflex accent).

     [1m\[rs]  [22mReverse  solidus  (backslash).   The backslash is the default escape
            character in the [4mroff[24m language, so it does not represent  itself  in
            output.  Also see [1m\e [22mabove.

     [1m\[ti]  [22mBasic  Latin tilde.  Some output devices format “[1m~[22m” as U+02DC (small
            tilde).

     For maximum portability, avoid escape sequences (including special  charac‐
     ters) not listed above.

   [1mHooks[0m
     Two  macros,  both  GNU  extensions, are called internally by the [4mgroff[24m [4mman[0m
     package to format page headers and footers and can be redefined by the  ad‐
     ministrator  in  a  site’s [4mman.local[24m file (see section “Files” below).  The
     presentation of [1mTH [22mabove describes the default headers  and  footers.   Be‐
     cause  these  macros  are  hooks for [4mgroff[24m [4mman[24m internals, man pages have no
     reason to call them.  Such hook definitions typically consist of  “sp”  and
     “tl”  requests.   [1mPT  [22mfurthermore  has the responsibility of emitting a PDF
     bookmark after writing the first page header in a  document.   Consult  the
     existing implementations in [4man.tmac[24m when drafting replacements.

     [1m.BT    [22mSet the page footer text (“bottom trap”).

     [1m.PT    [22mSet the page header text (“page trap”).

     To remove a page header or footer entirely, define the appropriate macro as
     empty rather than deleting it.

   [1mDeprecated features[0m
     Use of the following in man pages for public distribution is discouraged.

     [1m.AT [22m[[4msystem[24m [[4mrelease[24m]]
            Alter  the footer for use with legacy AT&T man pages, overriding any
            definition of the [4mfooter‐inside[24m argument to [1mTH[22m.  This  macro  exists
            only to render man pages from historical systems.

            The inside footer is populated per the value of [4msystem.[0m

                   3      7th edition [4m(default)[0m

                   4      System III

                   5      System V

            The  optional  [4mrelease[24m  argument specifies the release number, as in
            “System V Release 3”.

     [1m.DT    [22mReset tab stops to the default (every 0.5i [inches]).

            Use of this presentation‐oriented macro is  deprecated.   It  trans‐
            lates poorly to HTML, under which exact space control and tabulation
            are  not  readily available.  Thus, information or distinctions that
            you use tab stops to express are likely to be  lost.   If  you  feel
            tempted  to  change the tab stops such that calling this macro later
            to restore them is  desirable,  consider  composing  a  table  using
            ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\ instead.

     [1m.OP [4m[22moption‐name[24m [[4moption‐argument[24m]
            Indicate  an optional command parameter called [4moption‐name[24m, which is
            set in bold.  If the option takes an argument, specify  [4moption‐argu‐[0m
            [4mment[24m  using  a  noun,  abbreviation,  or hyphenated noun phrase.  If
            present, [4moption‐argument[24m is preceded by a space and set in  italics.
            Square brackets in roman surround both arguments.

            Use of this quasi‐semantic macro, an extension whose name originated
            in DWB [4mtroff[24m, is deprecated; [4mgroff[24m’s interface differs.  Neither can
            easily  be  used to annotate options that take optional arguments or
            options whose arguments have internal structure (such as  a  mixture
            of  literal  and  variable components).  One could work around these
            limitations with font selection escape sequences, but font style al‐
            ternation macros are preferable; they are more flexible and  perform
            italic corrections on typesetters.

     [1m.PD [22m[[4mvertical‐space[24m]
            Configure  the  amount  of  vertical  space  between  paragraphs  or
            (sub)sections.  The optional argument [4mvertical‐space[24m  specifies  the
            amount;  the  default scaling unit is “v”.  Without an argument, in‐
            ter‐paragraph spacing resets to its default  value;  see  subsection
            “Horizontal and vertical spacing” above.

            Use  of  this  presentation‐oriented macro is deprecated.  It trans‐
            lates poorly to HTML, under which exact control  of  inter‐paragraph
            spacing is not readily available.  Thus, information or distinctions
            that you use [1mPD [22mto express are likely to be lost.

     [1m.SB [22m[[4mtext[24m]
            Set [4mtext[24m in bold and (on typesetters) one point smaller than the de‐
            fault  type  size.   Given  no  argument, [1mSB [22mplants a one‐line input
            trap; text on the next line, which can be further formatted  with  a
            macro,  is set smaller and in bold.  Use of this macro, an extension
            originating in SunOS 4.0 [4mtroff[24m, is deprecated.  [1mSM [22mwithout an  argu‐
            ment,  followed  immediately  by  “[1mB [4m[22mtext[24m”, produces the same output
            more portably.  The macros’ order is interchangeable; put [4mtext[24m  with
            the latter.

            [4mNote:[24m  terminals render [4mtext[24m in bold at the normal size instead.  Do
            not rely upon [1mSB [22mto communicate semantic information  distinct  from
            using  bold  style  at  normal size; it is hidden from readers using
            such devices.

     [1m.UC [22m[[4mversion[24m]
            Alter the footer for use with legacy BSD man pages,  overriding  any
            definition  of  the [4mfooter‐inside[24m argument to [1mTH[22m.  This macro exists
            only to render man pages from historical systems.

            The inside footer is populated per the value of [4mversion.[0m

                   3      3rd Berkeley Distribution [4m(default)[0m

                   4      4th Berkeley Distribution

                   5      4.2 Berkeley Distribution

                   6      4.3 Berkeley Distribution

                   7      4.4 Berkeley Distribution

   [1mHistory[0m
     ]8;;mailto:m.douglas.mcilroy@dartmouth.edu\M. Douglas McIlroy]8;;\ designed,  implemented,  and  documented  the  AT&T  [4mman[0m
     macros  for Unix Version 7 (1979) and employed them to edit Volume 1 of its
     [4mProgrammer’s[24m [4mManual[24m, a compilation of all man pages supplied by the system.
     The package supported the macros listed in this page not described  as  ex‐
     tensions,  except  [1mP [22mand the deprecated [1mAT [22mand [1mUC[22m.  It documented no regis‐
     ters and defined only [1mR [22mand [1mS [22mstrings.

     [1mUC [22mappeared in 3BSD (1980).  Unix System III (1980) introduced  [1mP  [22mand  ex‐
     posed  the  registers [1mIN [22mand [1mLL[22m, which had been internal to Seventh Edition
     Unix [4mman[24m.  PWB/Unix 2.0 (1980) added the [1mTm [22mstring.  4BSD (1980)  added  [1mlq[0m
     and  [1mrq  [22mstrings.   SunOS  2.0  (1985) recognized [1mC[22m, [1mD[22m, [1mP[22m, and [1mX [22mregisters.
     4.3BSD (1986) added [1mAT [22mand [1mP[22m.  Ninth Edition Unix (1986) introduced [1mEX  [22mand
     [1mEE[22m.   SunOS  4.0 (1988) added [1mSB[22m.  Unix System V (1988) incorporated the [1mlq[0m
     and [1mrq [22mstrings.

     Except for [1mEX[22m/[1mEE[22m, James Clark implemented the foregoing features  in  early
     versions  of  [4mgroff.[24m  Later, [4mgroff[24m 1.20 (2009) resurrected [1mEX[22m/[1mEE [22mand origi‐
     nated [1mSY[22m/[1mYS[22m, [1mTQ[22m, [1mMT[22m/[1mME[22m, and [1mUR[22m/[1mUE[22m.  Plan 9 from User Space’s  [4mtroff[24m  intro‐
     duced [1mMR [22min 2020, and incorporated the [1mlq [22mand [1mrq [22mstrings in 2025.

[1mOptions[0m
     The  following  [4mgroff[24m options set registers (with [1m-r[22m) and strings (with [1m-d[22m)
     recognized and used by the [4mman[24m macro package.  To ensure rendering  consis‐
     tent  with  output  device  capabilities  and reader preferences, man pages
     should never manipulate them.

     [1m-dAD=[4m[22madjustment‐mode[0m
              Set line adjustment to [4madjustment‐mode,[24m which is typically “[1mb[22m” for
              adjustment to both margins (the default), or “[1ml[22m” for  left  align‐
              ment  (ragged  right  margin).  Any valid argument to [4mgroff[24m’s “ad”
              request may be used.  See ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\ for less‐common choices.

     [1m-rBP=[4m[22mbase‐paragraph‐inset[0m
              Set the inset amount for ordinary paragraphs not within  an  [1mRS[22m/[1mRE[0m
              inset.  The default is 5n.

     [1m-rcR=1   [22mEnable  continuous  rendering.   Output is not paginated; instead,
              one (potentially very long) page is produced.  This is the default
              for terminal and HTML devices.  Use [1m-rcR=0 [22mto disable it on termi‐
              nals; on HTML devices, it cannot be disabled.

     [1m-rC1     [22mNumber output pages  consecutively,  in  strictly  increasing  se‐
              quence,  rather  than resetting the page number to 1 (or the value
              of register [1mP[22m) with each new [4mman[24m document.

     [1m-rCHECKSTYLE=[4m[22mn[0m
              Report problems with usage of this macro package exhibited by  the
              input  at  verbosity  level  [4mn[24m, where [4mn[24m is an integer in the range
              0–3, inclusive; [1m0 [22mdisables the messages and is the default.   This
              feature  is a development and debugging aid for man page maintain‐
              ers; the problems diagnosed, and range and meanings  of  the  sup‐
              ported levels, are subject to change.

     [1m-rCS=1   [22mSet  section  headings  (the  argument(s) to [1mSH[22m) in full capitals.
              This transformation is off by default because it discards  letter‐
              case distinctions.

     [1m-rCT=1   [22mSet  the  man  page  identifier (the first argument to [1mTH[22m) in full
              capitals in headers and footers.  This transformation  is  off  by
              default because it discards lettercase distinctions.

     [1m-rD1     [22mEnable  double‐sided  layout,  formatting footers for even and odd
              pages differently; see the description of [1mTH [22min subsection  “Docu‐
              ment structure macros” above.

     [1m-rFT=[4m[22mfooter‐distance[0m
              Set  distance  of the footer relative to the bottom of the page to
              [4mfooter‐distance;[24m this amount is always negative.  At one half‐inch
              above this location, the page text is broken  before  writing  the
              footer.   Ignored if continuous rendering is enabled.  The default
              is “-0.5i - 1v”.

     [1m-dHF=[4m[22mheading‐font[0m
              Select the font used for section and subsection headings; the  de‐
              fault  is “[1mB[22m” (bold style of the default family).  Any valid argu‐
              ment to [4mgroff[24m’s “ft” request may be used.  See ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\.

     [1m-rHY=0   [22mDisable automatic hyphenation.  Normally, it is enabled (1).   The
              hyphenation  mode  is  determined by the [4mgroff[24m locale; see section
              “Localization“ of ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\.

     [1m-rIN=[4m[22mstandard‐indentation[0m
              Set the default indentation amount used by [1mIP[22m, [1mTP[22m, and [1mHP[22m, and the
              inset amount used by [1mRS[22m.  The default is 7n on terminals and  7.2n
              on  typesetters.  Use only integer multiples of unit “n” on termi‐
              nals for consistent indentation.

     [1m-rLL=[4m[22mline‐length[0m
              Set line length; the default is 80n on terminals and 6.5i on type‐
              setters.

     [1m-rLT=[4m[22mtitle‐length[0m
              Set the line length for titles.  (“Titles” is the  [4mroff[24m  term  for
              headers  and  footers.)   By default, it is set to the line length
              (see [1m-rLL [22mabove).

     [1m-dMF=[4m[22mman‐page‐topic‐font[0m
              Select the font used for man page identifiers in [1mTH [22mcalls and top‐
              ics named in [1mMR [22mcalls; the default is “[1mI[22m” (italic style of the de‐
              fault family).  Any valid argument to [4mgroff[24m’s “ft” request may  be
              used.   If the [1mMF [22mstring ends in “I”, the package assumes it to be
              an oblique typeface, and applies italic corrections before and af‐
              ter man page topics and identifiers.

     [1m-rP[4m[22mn[24m     Start enumeration of pages at [4mn[24m.  The default is 1.

     [1m-rPO=[4m[22mpage‐offset[0m
              Set page offset; the default is 0 on terminals and 1i on  typeset‐
              ters.

     [1m-rS[4m[22mtype‐size[0m
              Use  [4mtype‐size[24m for the document’s body text; acceptable values are
              10, 11, or 12 points.  See subsection “Font  style  macros”  above
              for the default.

     [1m-rSN=[4m[22msubsection‐indentation[0m
              Set  indentation of subsection headings to [4msubsection‐indentation.[0m
              The default is 3n.

     [1m-rTS=[4m[22mseparation[0m
              Require the given [4mseparation[24m between a [1mTP [22mparagraph’s tag and  its
              body.  The default is 2n.

     [1m-rU0     [22mDisable  generation of URI hyperlinks in output drivers capable of
              them, making the arguments to [1mMT [22mand [1mUR [22mcalls visible as formatted
              text.  ]8;;man:grohtml(1)\[4mgrohtml[24m(1)]8;;\, ]8;;man:gropdf(1)\[4mgropdf[24m(1)]8;;\, and ]8;;man:grotty(1)\[4mgrotty[24m(1)]8;;\ enable  hyperlinks  by
              default (the last only if not in its legacy output mode).

     [1m-rX[4m[22mp[24m     Number successors of page [4mp[24m as [4mp[24ma, [4mp[24mb, [4mp[24mc, and so forth.  The reg‐
              ister  tracking  the suffixed page letter uses format “a” (see the
              “af” request in ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\).  For example, the option [1m-rX2  [22mproduces
              the  following  page  numbers: 1, 2, 2a, 2b, ..., 2aa, 2ab, and so
              on.

[1mFiles[0m
     [4m/usr/share/groff/1.24.0/tmac/an.tmac[0m
            Most [4mman[24m macros are defined in this file.  It also loads  extensions
            from [4man-ext.tmac[24m (see below).

     [4m/usr/share/groff/1.24.0/tmac/andoc.tmac[0m
            This brief [4mgroff[24m program detects whether the [4mman[24m or [4mmdoc[24m macro pack‐
            age  is  used by a document and loads the correct macro definitions,
            taking advantage of the fact that pages using them must call  [1mTH  [22mor
            [1mDd[22m,  respectively, before any other macros.  A [4mman[24m program or a user
            typing, for example, “[1mgroff -mandoc page.1[22m”,  need  not  know  which
            package the file [4mpage.1[24m uses.  Multiple man pages, in either format,
            can  be  handled;  [4mandoc[24m  reloads  each  macro package as necessary.
            Page‐local redefinitions of names used by the [4mman[24m or  [4mmdoc[24m  packages
            prior  to  [1mTH  [22mor [1mDd [22mcalls are “clobbered” by the reloading process.
            If you want to provide your own definition of an extension macro  to
            ensure its availability, the [4man-ext.tmac[24m entry below offers advice.

     [4m/usr/share/groff/1.24.0/tmac/an-ext.tmac[0m
            Definitions  of macros described above as extensions (and not depre‐
            cated) are contained in this file; in some cases, they  are  simpler
            versions of definitions appearing in [4man.tmac[24m, and are ignored if the
            formatter is GNU [4mtroff[24m.  They are written to be compatible with AT&T
            [4mtroff[24m and permissively licensed——not copylefted.  To reduce the risk
            of  name space collisions, string and register names begin only with
            “[1mm[22m”.  We encourage man page authors who are concerned  about  porta‐
            bility  to  legacy Unix systems to copy these definitions into their
            pages, and maintainers of [4mtroff[24m implementations or  work‐alike  sys‐
            tems  that format man pages to re‐use them.  To ensure reliable ren‐
            dering, define them after your page calls [1mTH[22m; see the discussion  of
            [4mandoc.tmac[24m  above.   Further,  it  is wise to define such page‐local
            macros (if at all) after the “Name”  section  to  accommodate  timid
            ]8;;man:makewhatis(8)\[4mmakewhatis[24m(8)]8;;\  or ]8;;man:mandb(8)\[4mmandb[24m(8)]8;;\ implementations that easily give up scan‐
            ning for indexing material.

     [4m/usr/share/groff/1.24.0/tmac/man.tmac[0m
            is a wrapper enabling the package to be loaded with the  option  “[1m-m[0m
            [1mman[22m”.

     [4m/usr/share/groff/1.24.0/tmac/mandoc.tmac[0m
            is  a  wrapper  enabling [4mandoc.tmac[24m to be loaded with the option “[1m-m[0m
            [1mmandoc[22m”.

     [4m/usr/share/groff/site-tmac/man.local[0m
            Put site‐local changes and customizations into this file.

                   .\" Put only one space after the end of a sentence.
                   .ss 12 0 \" See groff(7).
                   .\" Keep pages narrow even on wide terminals.
                   .if n .if \n[LL]>80n .nr LL 80n

            On multi‐user systems, it is more considerate to users whose prefer‐
            ences may differ from the administrator’s to be less aggressive with
            such settings, or to permit  their  override  with  a  user‐specific
            [4mman.local[24m file.  Place the requests below at the end of the site‐lo‐
            cal file to manifest courtesy.
                   .soquiet \V[XDG_CONFIG_HOME]/man.local
                   .soquiet \V[HOME]/.man.local
            However,  a security‐sandboxed ]8;;man:man(1)\[4mman[24m(1)]8;;\ program may lack permission to
            open such files.

[1mNotes[0m
     Some tips on composing and troubleshooting your man pages follow.

     • What’s the difference between a man page topic and identifier?

       A single man page may document several related but distinct topics.   For
       example,  ]8;;man:printf(3)\[4mprintf[24m(3)]8;;\  and  ]8;;man:fprintf(3)\[4mfprintf[24m(3)]8;;\ are often presented together.  More‐
       over, multiple programming languages have functions named  “printf”,  and
       may  document  these  in a man page.  The identifier is intended to (with
       the section) uniquely identify a page on the system; it  may  furthermore
       correspond closely to the file name of the document.

       The  ]8;;man:man(1)\[4mman[24m(1)]8;;\  librarian  makes access to man pages convenient by resolving
       topics to man page identifiers.  Thus, you can type  “[1mman  fprintf[22m”,  and
       other  pages can refer to it, without knowing whether the installed docu‐
       ment uses “printf”, “fprintf”, or even “c_printf” as its identifier.

     • Some ASCII characters look funny or copy and paste wrong.

       On devices with large glyph repertoires, like UTF‐8‐capable terminals and
       PDF, GNU [4mtroff[24m, like AT&T [4mtroff[24m before it, maps several keycaps  to  code
       points  outside  the Unicode basic Latin range (historically “ASCII”) be‐
       cause that usually results in better  typography  in  the  general  case.
       When  documenting  GNU/Linux  command or C language syntax, however, this
       translation is sometimes not desirable.

       [1mTo get a “literal”...   ...should be input.[0m
       ────────────────────────────────────────────
                           '   \[aq]
                           -   \-
                           \   \[rs]
                           ^   \[ha]
                           `   \[ga]
                           ~   \[ti]
       ────────────────────────────────────────────

       If a neutral double quote (") is needed in a macro argument, you can  use
       [1m\[dq]  [22mto  get  it.   Do  [4mnot[24m use [1m\[aq] [22mfor an ordinary apostrophe (as in
       “can’t”) or [1m\- [22mfor an ordinary hyphen (as in “word‐aligned”).

     • Do I ever need to use an empty macro argument ("")?

       Probably not.  When this seems necessary, often a shorter or clearer  al‐
       ternative is available.

              [1mInstead of...               ...should be considered.[0m
       ────────────────────────────────────────────────────────────────
       .TP ""                         .TP
       ────────────────────────────────────────────────────────────────
       .BI "" [4mitalic‐text[24m [4mbold‐text[24m   .IB [4mitalic‐text[24m [4mbold‐text[0m
       ────────────────────────────────────────────────────────────────
       .TH foo 1 "" "foo 1.2.3"       .TH foo 1 [4myyyy[24m‐[4mmm[24m‐[4mdd[24m "foo 1.2.3"
       ────────────────────────────────────────────────────────────────
       .IP "" 4n                      .IP
       ────────────────────────────────────────────────────────────────
       .IP "" 4n                      .RS 4n
       [4mparagraph[24m                      .P
       ...                            [4mparagraph[0m
       ...                            .RE
       ────────────────────────────────────────────────────────────────
       .B one two "" three            .B one two three

       In  the  title heading ([1mTH[22m), the date of the page’s last revision is more
       important than packaging information; it should not be omitted.  Ideally,
       a page maintainer keeps both up to date.

       [1mIP [22mis sometimes ill‐understood and misused, especially when no mark argu‐
       ment is supplied——an indentation argument is not required.  By setting an
       explicit indentation, you may be overriding the  reader’s  preference  as
       set  with  the [1m-rIN [22moption.  If your page renders adequately without one,
       use the simpler form.  If you need to indent  multiple  (unmarked)  para‐
       graphs, consider setting an inset region with [1mRS [22mand [1mRE [22minstead.

       In  the last example, the empty argument does have a subtly different ef‐
       fect than its suggested replacement: the empty argument causes  an  addi‐
       tional space character to be interpolated between the arguments “two” and
       “three”——but  it  is  a regular breaking space, so it can be discarded at
       the end of an output line.  It is better not to be  subtle,  particularly
       with space, which can be overlooked in source and rendered forms.

     • [1mRS [22mdoesn’t indent relative to my indented paragraph.

       The  [1mRS [22mmacro determines the [4minset[24m [4mamount,[24m the position at which an [4mordi‐[0m
       [4mnary[24m paragraph ([1mP [22mand its synonyms) is set; the value of the [1mIN  [22mregister
       determines its default amount.  This register also determines the default
       indentation  used  by  [1mIP[22m, [1mTP[22m, and [1mHP[22m.  To create an inset relative to an
       indented paragraph, call [1mRS [22mrepeatedly until an acceptable indentation is
       achieved, or give [1mRS [22man indentation argument that is at least as much  as
       the  paragraph’s  indentation amount relative to an adjacent ordinary ([1mP[22m)
       paragraph.

       Another approach to tagged paragraphs places an [1mRS [22mcall immediately after
       the tag; this also forces a break regardless of the  tag’s  width,  which
       some  authors prefer.  Follow‐up paragraphs under the tag can then be set
       with [1mP [22minstead of [1mIP[22m.  Remember to use [1mRE [22mto end the indented region  be‐
       fore  starting  the  next  tagged  paragraph  (at the appropriate nesting
       level).

     • [1mRE [22mdoesn’t move the inset back to the expected level.

       [1mRE [22mtakes an inset  [4mlevel[24m  as  an  argument,  unlike  [1mRS[22m’s  inset  [4mamount.[0m
       “[1m.RE  1[22m” goes to the level before any [1mRS [22mmacros were called, [1mRE 2 [22mgoes to
       the level of the first [1mRS [22mcall you made, and so  forth.   If  you  desire
       symmetry in your macro calls, simply issue one [1mRE [22mwithout an argument for
       each [1mRS [22mthat precedes it.

       The  [1mSH  [22mand [1mSS [22msectioning macros clear relative insets; [1mRE [22mcalls have no
       effect until [1mRS [22mis used again.

     • Do I need to keep typing the indentation in a series of [1mIP [22mcalls?

       Not if you don’t want to change it.  Review  subsection  “Horizontal  and
       vertical spacing” above.

         [1mInstead of...     ...should be considered.[0m
       ─────────────────────────────────────────────
       .IP \[bu] 4n        .IP \[bu] 4n
       [4mparagraph[24m           [4mparagraph[0m
       .IP \[bu] 4n        .IP \[bu]
       [4manother‐paragraph[24m   [4manother‐paragraph[0m
       ─────────────────────────────────────────────

     • Why doesn’t the package provide a string to insert an ellipsis?

       Examples  of  ellipsis  usage  are  shown  above, in subsection “Synopsis
       macros”.  The idiomatic [4mroff[24m ellipsis is three dots (periods)  with  thin
       space  escape  sequences  [1m\| [22minternally separating them.  Since dots both
       begin control lines and are candidate  end‐of‐sentence  characters,  how‐
       ever,  it is sometimes necessary to prefix and/or suffix an ellipsis with
       the dummy character escape sequence [1m\&[22m.   That  fact  stands  even  if  a
       string  is  defined  to contain the sequence; further, if the string ends
       with [1m\&[22m, end‐of‐sentence detection is defeated when you use the string at
       the end of an actual sentence.  (Ending a sentence with  an  ellipsis  is
       often  poor  style,  but not always.)  A hypothetical string [1mEL [22mthat con‐
       tained an ellipsis, but not the trailing dummy character [1m\&[22m,  would  then
       need to be suffixed with the latter when not ending a sentence.

           [1mInstead of...              ...do this.[0m
       ──────────────────────────────────────────────────
       .ds EL \&.\|.\|.         Arguments are
       Arguments are            .IR src‐file\~ .\|.\|.\&
       .IR src‐file\~ \*(EL\&   .IR dest‐dir .
       .IR dest‐dir .
       ──────────────────────────────────────────────────

       The first column practices a false economy; the savings in typing is off‐
       set  by the cost of obscuring even the suggestion of an ellipsis to a ca‐
       sual reader of the source document, and reduced portability  to  non‐[4mroff[0m
       man page formatters that cannot handle string definitions.

       Unicode  defines  an ellipsis code point, and some fonts have an ellipsis
       glyph, which some man pages have accessed non‐portably with the  font‐de‐
       pendent  [1m\N [22mescape sequence.  We discourage their use; on terminals, they
       may crowd the dots into a half‐width character cell, and do not render at
       all if the output device lacks the glyph.  In synopses, missing  ellipses
       can mislead the reader.  Dots and space are universally supported.

     • When and how should I use quotation marks?

       As  noted  above in subsection “Font style macros”, apply quotation marks
       to “brief specimens of literal text, such as article titles, inline exam‐
       ples, mentions of individual characters or short strings,  and  (sub)sec‐
       tion  headings in man pages”.  Multi‐word literals, such as Unix commands
       with arguments, when set inline (as opposed to displayed between  [1mEX  [22mand
       [1mEE[22m),  should  be  quoted to ensure that the boundaries of the literal are
       clear even when the material is stripped of font styling by, for example,
       copy‐and‐paste operations.  [4mgroff[24m, Heirloom Doctools [4mtroff[24m, [4mneatroff[24m, and
       [4mmandoc[24m support all of the special characters [1m\[oq][22m, [1m\[cq][22m, [1m\[lq][22m,  [1m\[rq][22m,
       [1m\[aq][22m,  and  [1m\[dq]  [22mdescribed  in  subsection  “Portability” above.  DWB,
       Plan 9, and Solaris [4mtroff[24ms do not.  Interpolating the strings  [1m\*(lq  [22mand
       [1m\*(rq  [22mportably  yields directional double quotation marks, if available,
       in all these formatters (though [4mneatroff[24m does  not  supply  a  [4mman[24m  macro
       package), but they cannot reliably be used in macro arguments.

       Obtaining  directional  single  quotation  marks  is more of a challenge.
       Historically, man pages used [1m` [22mand [1m', [22mwhich [4mtroff[24m rendered on typesetters
       as ‘ and ’, exclusively for them.  However, in recent  years,  some  dis‐
       tributors  of [4mgroff[24m have chosen to override the meanings of these charac‐
       ters in man pages, remapping them  to  their  Unicode  Basic  Latin  code
       points.   Unfortunately, [1m` [22mand [1m' [22mare the [4monly[24m reliable means of obtaining
       directional single quotation marks in AT&T [4mtroff[24m; in that implementation,
       often no special character escape sequences exist to obtain  them.   Fur‐
       ther,  AT&T  [4mtroff[24m’s  special character identifiers, like its font names,
       were device‐specific.  To achieve quotation portably in  man  pages  ren‐
       dered  both by AT&T and more modern [4mtroff[24ms, consider adding a preamble to
       your page after the [1mTH [22mcall as follows.

              .ie \n(.g \{\
              .  ds oq \[oq]\"
              .  ds cq \[cq]\"
              .\}
              .el \{\
              .  ds oq `\"
              .  ds cq '\"
              .\}

       You must then use the [1m\* [22mescape sequence  to  interpolate  the  quotation
       mark strings.

              The command
              .RB \*(oq "while !\& git pull; do sleep 10; done" \*(cq
              retries an update from the repository until it succeeds.

       If  this  procedure  seems  complex,  petition your distributor to revert
       their remapping of the ` and ' characters.

     • Escape sequences of the form [1m\[[4m[22mxx[24m[1m] [22mdon’t format correctly.

       The [1m\[[4m[22mxx[24m[1m] [22mspecial character escape sequence is a GNU [4mtroff[24m extension also
       supported by [4mmandoc,[24m Heirloom Doctools [4mtroff,[24m and [4mneatroff.[24m  DWB, Plan 9,
       and Solaris [4mtroff[24ms don’t implement it.  If your man page requires  porta‐
       bility  to  these  formatters,  spell such escape sequences as “[1m\([4m[22mxx[24m”; no
       closing  parenthesis  is  used.   [4mxx[24m  must  be  exactly  two  characters;
       ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\ lists portable special character identifiers.

[1mAuthors[0m
     James  Clark wrote the initial GNU implementation of the [4mman[24m macro package.
     Later, ]8;;mailto:wl@gnu.org\Werner Lemberg]8;;\ supplied the [1mS[22m, [1mLT[22m, and  [1mcR  [22mregisters,  the  last  a
     4.3BSD‐Reno  [4mmdoc[24m(7) feature.  ]8;;mailto:kollar@alltel.net\Larry Kollar]8;;\ added the [1mFT[22m, [1mHY[22m, and [1mSN [22mregis‐
     ters; the [1mHF [22mstring; and the [1mPT [22mand [1mBT [22mmacros in [4mgroff[24m 1.19  (2003).   Lem‐
     berg  and ]8;;mailto:esr@thyrsus.com\Eric S. Raymond]8;;\ contributed [1mEX[22m/[1mEE[22m, [1mMT[22m/[1mME[22m, [1mUR[22m/[1mUE[22m, [1mTQ[22m, and an early
     version of the [1mSY[22m/[1mYS [22mmacros to [4mgroff[24m 1.20 (2009).  ]8;;mailto:g.branden.robinson@gmail.com\G. Branden Robinson]8;;\  im‐
     plemented  the [1mAD [22mand [1mMF [22mstrings; [1mCS[22m, [1mCT[22m, and [1mU [22mregisters; and the [1mMR [22mmacro
     for [4mgroff[24m 1.23 (2023), and the [1mBP[22m, [1mPO[22m, and [1mTS [22mregisters and a  revised  im‐
     plementation of the [1mSY[22m/[1mYS [22mmacros for [4mgroff[24m 1.24 (2026).

     ]8;;mailto:sgk@debian.org\Susan  G.  Kleinmann]8;;\ wrote the initial version of this document for the De‐
     bian GNU/Linux system.  Lemberg imported it to [4mgroff.[24m  He and Robinson  re‐
     vised  and  updated  it.   Raymond  and  Robinson  documented the extension
     macros.  Raymond also originated the portability  section,  to  which  ]8;;mailto:schwarze@usta.de\Ingo
     Schwarze]8;;\ contributed most of the material on escape sequences.

[1mSee also[0m
     ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\, ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\, and ]8;;man:refer(1)\[4mrefer[24m(1)]8;;\ are preprocessors used with man pages.  ]8;;man:man(1)\[4mman[24m(1)]8;;\
     describes the man page librarian on your system.  ]8;;man:groff_mdoc(7)\[4mgroff_mdoc[24m(7)]8;;\ details the
     [4mgroff[24m version of BSD’s alternative macro package for man pages.

     ]8;;man:groff_man(7)\[4mgroff_man[24m(7)]8;;\, ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\, ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\

groff 1.24.0                       2026‐02‐28                 [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 identifers,
     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.0[22m” whereas a locally produced  page  might  employ  “[1m.Os[0m
             [1m"UXYZ CS Department"[22m”, omitting versioning.

             This macro is neither callable nor parsed.

[1mIntroduction to manual and general text domains[0m
   [1mWhat's in a Name[22m...
     The manual domain macro names are derived from the day to day informal lan‐
     guage  used  to describe commands, subroutines and related files.  Slightly
     different variations of this language are used to describe the  three  dif‐
     ferent  aspects  of writing a man page.  First, there is the description of
     [4mmdoc[24m macro command usage.  Second is the description of a Unix command [4mwith[0m
     [4mmdoc[24m macros, and third, the description of a command to a user in the  ver‐
     bal sense; that is, discussion of a command in the text of a man page.

     In  the first case, [4mtroff[24m macros are themselves a type of command; the gen‐
     eral syntax for a [4mtroff[24m command is:

           [1m.Xx argument1 argument2 [22m...

     ‘.Xx’ is a macro command, and anything following it  are  arguments  to  be
     processed.  In the second case, the description of a Unix command using the
     manual  domain  macros is a bit more involved; a typical “Synopsis” command
     line might be displayed as:

           [1mfilter [22m[[1m-flag[22m] ⟨[4minfile[24m⟩ ⟨[4moutfile[24m⟩

     Here, [1mfilter [22mis the command name and the bracketed string [1m-flag [22mis  a  [4mflag[0m
     argument  designated  as  optional  by the option brackets.  In [4mmdoc[24m terms,
     ⟨[4minfile[24m⟩ and ⟨[4moutfile[24m⟩ are called [4mmeta[24m [4marguments[24m; in this example, the user
     has to replace the meta expressions given in angle brackets with real  file
     names.  Note that in this document meta arguments are used to describe [4mmdoc[0m
     commands;  in  most  man pages, meta variables are not specifically written
     with angle brackets.  The macros that formatted the above example:

           .Nm filter
           .Op Fl flag
           .Ao Ar infile Ac Ao Ar outfile Ac

     In the third case, discussion of commands and command syntax includes  both
     examples  above,  but  may  add  more  detail.   The arguments ⟨[4minfile[24m⟩ and
     ⟨[4moutfile[24m⟩ from the example above might be referred to as [4moperands[24m  or  [4mfile[0m
     [4marguments[24m.  Some command-line argument lists are quite long:

           [1mmake  [22m[[1m-eiknqrstv[22m] [[1m-D [4m[22mvariable[24m] [[1m-d [4m[22mflags[24m] [[1m-f [4m[22mmakefile[24m] [[1m-I[0m
                 [4mdirectory[24m] [[1m-j [4m[22mmax_jobs[24m] [[4mvariable[24m=[4mvalue[24m] [[4mtarget[24m ...]

     Here  one  might  talk  about  the  command  [4mmake[24m and qualify the argument,
     [4mmakefile[24m, as an argument to the flag, [1m-f[22m,  or  discuss  the  optional  file
     operand  [4mtarget[24m.  In the verbal context, such detail can prevent confusion,
     however the [4mmdoc[24m package does not have a macro for an argument [4mto[24m  a  flag.
     Instead  the  ‘Ar’  argument  macro is used for an operand or file argument
     like [4mtarget[24m as well as an argument to a flag like [4mvariable[24m.  The make  com‐
     mand line was produced from:

           .Nm make
           .Op Fl eiknqrstv
           .Op Fl D Ar variable
           .Op Fl d Ar flags
           .Op Fl f Ar makefile
           .Op Fl I Ar directory
           .Op Fl j Ar max_jobs
           .Op Ar variable Ns = Ns Ar value
           .Bk
           .Op Ar target ...
           .Ek

     The ‘.Bk’ and ‘.Ek’ macros are explained in “Keeps”.

   [1mGeneral Syntax[0m
     The  manual  domain  and  general text domain macros share a similar syntax
     with a few minor deviations; most notably, ‘.Ar’, ‘.Fl’, ‘.Nm’,  and  ‘.Pa’
     differ  only  when  called without arguments; and ‘.Fn’ and ‘.Xr’ impose an
     order on their argument lists.  All manual domain  macros  are  capable  of
     recognizing  and  properly  handling punctuation, provided each punctuation
     character is separated by a leading space.  If a command is given:

           [1m.Ar sptr, ptr),[0m

     The result is:

           [4msptr,[24m [4mptr),[0m

     The punctuation is not recognized and all is output in  the  font  used  by
     ‘.Ar’.  If the punctuation is separated by a leading whitespace:

           [1m.Ar sptr , ptr ) ,[0m

     The result is:

           [4msptr[24m, [4mptr[24m),

     The  punctuation  is  now recognized and output in the default font distin‐
     guishing it from the argument strings.  To remove the special meaning  from
     a punctuation character, escape it with ‘\&’.

     The following punctuation characters are recognized by [4mmdoc[24m:

               [1m.         ,         :         ;         ([0m
               [1m)         [         ]         ?         ![0m

     [4mtroff[24m  is  limited  as  a macro language, and has difficulty when presented
     with a string containing certain mathematical, logical, or quotation  char‐
     acter sequences:

                 {+,-,/,*,%,<,>,<=,>=,=,==,&,`,',"}

     The problem is that [4mtroff[24m may assume it is supposed to actually perform the
     operation  or evaluation suggested by the characters.  To prevent the acci‐
     dental evaluation of these characters, escape them with ‘\&’.  Typical syn‐
     tax is shown in the first manual domain macro displayed below, ‘.Ad’.

[1mManual domain[0m
   [1mAddresses[0m
     The address macro identifies an address construct.

           [1mUsage: .Ad [22m⟨address⟩ ...

                    [1m.Ad addr1           [4m[22maddr1[0m
                    [1m.Ad addr1 .         [4m[22maddr1[24m.
                    [1m.Ad addr1 , file2   [4m[22maddr1[24m, [4mfile2[0m
                    [1m.Ad f1 , f2 , f3 :  [4m[22mf1[24m, [4mf2[24m, [4mf3[24m:
                    [1m.Ad addr ) ) ,      [4m[22maddr[24m)),

     The default width is 12n.

   [1mAuthor Name[0m
     The ‘.An’ macro is used to specify the name of the author of the item being
     documented, or the name of the author of the actual manual page.

           [1mUsage: .An [22m⟨author name⟩ ...

                    [1m.An "Joe Author"        [22mJoe Author

                    [1m.An "Joe Author" ,      [22mJoe Author,

                    [1m.An "Joe Author" Aq nobody@FreeBSD.org[0m
                                            Joe Author <nobody@FreeBSD.org>

                    [1m.An "Joe Author" ) ) ,  [22mJoe Author)),

     The default width is 12n.

     In a section titled “Authors”, ‘An’ causes a break, allowing each new  name
     to appear on its own line.  If this is not desirable,

           .An -nosplit

     call will turn this off.  To turn splitting back on, write

           .An -split

   [1mArguments[0m
     The  [1m.Ar [22margument macro may be used whenever an argument is referenced.  If
     called without arguments, ‘[4mfile[24m ...’ is output.

           [1mUsage: .Ar [22m[⟨argument⟩] ...

                    [1m.Ar                    [4m[22mfile[24m ...
                    [1m.Ar file1              [4m[22mfile1[0m
                    [1m.Ar file1 .            [4m[22mfile1[24m.
                    [1m.Ar file1 file2        [4m[22mfile1[24m [4mfile2[0m
                    [1m.Ar file ... dest-dir  [4m[22mfile[24m ... [4mdest-dir[0m
                    [1m.Ar f1 f2 f3 :         [4m[22mf1[24m [4mf2[24m [4mf3[24m:
                    [1m.Ar file ) ) ,         [4m[22mfile[24m)),

     The default width is 12n.

   [1mConfiguration Declaration (Section Four Only)[0m
     The ‘.Cd’ macro is used to demonstrate a ]8;;man:config(8)\[4mconfig[24m(8)]8;;\ declaration for a device
     interface in a section four manual.

           [1mUsage: .Cd [22m⟨argument⟩ ...

                    [1m.Cd "device le0 at scode?"  device le0 at scode?[0m

     In a section titled “Synopsis”, ‘Cd’ causes a break before  and  after  its
     arguments.

     The default width is 12n.

   [1mCommand Modifiers[0m
     The  command modifier is identical to the ‘.Fl’ (flag) command with the ex‐
     ception that the ‘.Cm’ macro does not assert a dash in front of every argu‐
     ment.  Traditionally flags are marked by the preceding dash, however,  some
     commands  or  subsets  of  commands do not use them.  Command modifiers may
     also be specified in conjunction with interactive commands such  as  editor
     commands.  See “Flags”.

     The default width is 10n.

   [1mDefined Variables[0m
     A variable (or constant) that is defined in an include file is specified by
     the macro ‘.Dv’.

           [1mUsage: .Dv [22m⟨defined-variable⟩ ...

                    [1m.Dv MAXHOSTNAMELEN  [22mMAXHOSTNAMELEN
                    [1m.Dv TIOCGPGRP )     [22mTIOCGPGRP)

     The default width is 12n.

   [1mErrnos[0m
     The  ‘.Er’  errno  macro specifies the error return value for section 2, 3,
     and 9 library routines.  The second example below shows ‘.Er’ used with the
     ‘.Bq’ general text domain macro, as it would be used in a section two  man‐
     ual page.

           [1mUsage: .Er [22m⟨errno type⟩ ...

                    [1m.Er ENOENT      [22mENOENT
                    [1m.Er ENOENT ) ;  [22mENOENT);
                    [1m.Bq Er ENOTDIR  [22m[ENOTDIR]

     The default width is 17n.

   [1mEnvironment Variables[0m
     The ‘.Ev’ macro specifies an environment variable.

           [1mUsage: .Ev [22m⟨argument⟩ ...

                    [1m.Ev DISPLAY        [4m[22mDISPLAY[0m
                    [1m.Ev PATH .         [4m[22mPATH[24m.
                    [1m.Ev PRINTER ) ) ,  [4m[22mPRINTER[24m)),

     The default width is 15n.

   [1mFlags[0m
     The  ‘.Fl’  macro  handles command-line flags.  It prepends a dash, ‘-’, to
     the flag.  For interactive command flags that  are  not  prepended  with  a
     dash,  the  ‘.Cm’  (command  modifier)  macro is identical, but without the
     dash.

           [1mUsage: .Fl [22m⟨argument⟩ ...

                    [1m.Fl          -[0m
                    [1m.Fl cfv      -cfv[0m
                    [1m.Fl cfv .    -cfv[22m.
                    [1m.Cm cfv .    cfv[22m.
                    [1m.Fl s v t    -s -v -t[0m
                    [1m.Fl - ,      --[22m,
                    [1m.Fl xyz ) ,  -xyz[22m),
                    [1m.Fl |        - [22m|

     The ‘.Fl’ macro without  any  arguments  results  in  a  dash  representing
     stdin/stdout.   Note  that  giving  ‘.Fl’  a single dash will result in two
     dashes.

     The default width is 12n.

   [1mFunction Declarations[0m
     The ‘.Fd’ macro is used in the “Synopsis” section with section two or three
     functions.  It is neither callable nor parsed.

           [1mUsage: .Fd [22m⟨argument⟩ ...

                    [1m.Fd "#include <sys/types.h>"  #include <sys/types.h>[0m

     In a section titled “Synopsis”, ‘Fd’ causes a break if a function  has  al‐
     ready  been  presented and a break has not occurred, leaving vertical space
     between one function declaration and the next.

     In a section titled “Synopsis”, the  ‘In’  macro  represents  the  [1m#include[0m
     statement,  and  is  the short form of the above example.  It specifies the
     C header file as being included in a C program.  It also causes a break.

     While not in the “Synopsis” section, it represents the header file enclosed
     in angle brackets.

           [1mUsage: .In [22m⟨header file⟩

                    [1m.In stdio.h  [22m<[4mstdio.h[24m>
                    [1m.In stdio.h  [22m<[4mstdio.h[24m>

   [1mFunction Types[0m
     This macro is intended for the “Synopsis” section.  It may be used anywhere
     else in the man page without problems, but its main purpose is  to  present
     the  function  type  (in BSD kernel normal form) for the “Synopsis” of sec‐
     tions two and three.  (It causes a break, allowing the function name to ap‐
     pear on the next line.)

           [1mUsage: .Ft [22m⟨type⟩ ...

                    [1m.Ft struct stat  [4m[22mstruct[24m [4mstat[0m

   [1mFunctions (Library Routines)[0m
     The ‘.Fn’ macro is modeled on ANSI C conventions.

           [1mUsage: .Fn [22m⟨function⟩ [⟨parameter⟩] ...

                    [1m.Fn getchar              getchar[22m()
                    [1m.Fn strlen ) ,           strlen[22m()),
                    [1m.Fn align "char *ptr" ,  align[22m([4mchar[24m [4m*ptr[24m),

     Note that any call to another macro signals the end of the ‘.Fn’  call  (it
     will insert a closing parenthesis at that point).

     For functions with many parameters (which is rare), the macros ‘.Fo’ (func‐
     tion  open) and ‘.Fc’ (function close) may be used with ‘.Fa’ (function ar‐
     gument).

     Example:

           .Ft int
           .Fo res_mkquery
           .Fa "int op"
           .Fa "char *dname"
           .Fa "int class"
           .Fa "int type"
           .Fa "char *data"
           .Fa "int datalen"
           .Fa "struct rrec *newrr"
           .Fa "char *buf"
           .Fa "int buflen"
           .Fc

     Produces:

           [4mint[24m [1mres_mkquery[22m([4mint[24m [4mop[24m, [4mchar[24m [4m*dname[24m, [4mint[24m [4mclass[24m, [4mint[24m [4mtype[24m, [4mchar[24m [4m*data[24m,
           [4mint[24m [4mdatalen[24m, [4mstruct[24m [4mrrec[24m [4m*newrr[24m, [4mchar[24m [4m*buf[24m, [4mint[24m [4mbuflen[24m)

     Typically, in a “Synopsis” section, the function declaration will begin the
     line.  If more than one function is presented in the “Synopsis” section and
     a function type has not been given, a break will  occur,  leaving  vertical
     space between the current and prior function names.

     The default width values of ‘.Fn’ and ‘.Fo’ are 12n and 16n, respectively.

   [1mFunction Arguments[0m
     The ‘.Fa’ macro is used to refer to function arguments (parameters) outside
     of the “Synopsis” section of the manual or inside the “Synopsis” section if
     the  enclosure macros ‘.Fo’ and ‘.Fc’ instead of ‘.Fn’ are used.  ‘.Fa’ may
     also be used to refer to structure members.

           [1mUsage: .Fa [22m⟨function argument⟩ ...

                    [1m.Fa d_namlen ) ) ,  [4m[22md_namlen[24m)),
                    [1m.Fa iov_len         [4m[22miov_len[0m

     The default width is 12n.

   [1mReturn Values[0m
     The ‘.Rv’ macro generates text for use in the “Return values” section.

           [1mUsage: .Rv [22m[-std] [⟨function⟩ ...]

     For example, ‘.Rv -std atexit’ produces:

           The [1matexit[22m() function returns the value 0 if successful; otherwise
           the value -1 is returned and the global variable [4merrno[24m is set to in‐
           dicate the error.

     The [1m-std [22moption is valid only for manual page sections 2 and 3.  Currently,
     this macro does nothing if used without the [1m-std [22mflag.

   [1mExit Status[0m
     The ‘.Ex’ macro generates text for use in the “Diagnostics” section.

           [1mUsage: .Ex [22m[-std] [⟨utility⟩ ...]

     For example, ‘.Ex -std cat’ produces:

           The [1mcat [22mutility exits 0 on success, and >0 if an error occurs.

     The [1m-std [22moption is valid only for manual page sections 1, 6  and  8.   Cur‐
     rently, this macro does nothing if used without the [1m-std [22mflag.

   [1mInteractive Commands[0m
     The ‘.Ic’ macro designates an interactive or internal command.

           [1mUsage: .Ic [22m⟨argument⟩ ...

                    [1m.Ic :wq                :wq[0m
                    [1m.Ic "do while {...}"   do while {...}[0m
                    [1m.Ic setenv , unsetenv  setenv[22m, [1munsetenv[0m

     The default width is 12n.

   [1mLibrary Names[0m
     The  ‘.Lb’ macro is used to specify the library where a particular function
     is compiled in.

           [1mUsage: .Lb [22m⟨argument⟩ ...

     Available arguments to ‘.Lb’ and their results are:

           [1mlibarchive     [22mReading  and  Writing   Streaming   Archives   Library
                          (libarchive, -larchive)
           [1mlibarm         [22mARM Architecture Library (libarm, -larm)
           [1mlibarm32       [22mARM32 Architecture Library (libarm32, -larm32)
           [1mlibbluetooth   [22mBluetooth Library (libbluetooth, -lbluetooth)
           [1mlibbsm         [22mBasic Security Module Library (libbsm, -lbsm)
           [1mlibc           [22mStandard C Library (libc, -lc)
           [1mlibc_r         [22mReentrant C Library (libc_r, -lc_r)
           [1mlibcalendar    [22mCalendar Arithmetic Library (libcalendar, -lcalendar)
           [1mlibcam         [22mCommon Access Method User Library (libcam, -lcam)
           [1mlibcdk         [22mCurses Development Kit Library (libcdk, -lcdk)
           [1mlibcipher      [22mFreeSec Crypt Library (libcipher, -lcipher)
           [1mlibcompat      [22mCompatibility Library (libcompat, -lcompat)
           [1mlibcrypt       [22mCrypt Library (libcrypt, -lcrypt)
           [1mlibcurses      [22mCurses Library (libcurses, -lcurses)
           [1mlibdevinfo     [22mDevice   and   Resource  Information  Utility  Library
                          (libdevinfo, -ldevinfo)
           [1mlibdevstat     [22mDevice Statistics Library (libdevstat, -ldevstat)
           [1mlibdisk        [22mInterface  to  Slice  and  Partition  Labels   Library
                          (libdisk, -ldisk)
           [1mlibdwarf       [22mDWARF Access Library (libdwarf, -ldwarf)
           [1mlibedit        [22mCommand Line Editor Library (libedit, -ledit)
           [1mlibelf         [22mELF Access Library (libelf, -lelf)
           [1mlibevent       [22mEvent Notification Library (libevent, -levent)
           [1mlibfetch       [22mFile Transfer Library for URLs (libfetch, -lfetch)
           [1mlibform        [22mCurses Form Library (libform, -lform)
           [1mlibgeom        [22mUserland   API   Library  for  kernel  GEOM  subsystem
                          (libgeom, -lgeom)
           [1mlibgpib        [22mGeneral-Purpose   Instrument   Bus   (GPIB)    library
                          (libgpib, -lgpib)
           [1mlibi386        [22mi386 Architecture Library (libi386, -li386)
           [1mlibintl        [22mInternationalized  Message  Handling Library (libintl,
                          -lintl)
           [1mlibipsec       [22mIPsec Policy Control Library (libipsec, -lipsec)
           [1mlibipx         [22mIPX Address Conversion Support Library (libipx, -lipx)
           [1mlibiscsi       [22miSCSI protocol library (libiscsi, -liscsi)
           [1mlibjail        [22mJail Library (libjail, -ljail)
           [1mlibkiconv      [22mKernel side iconv library (libkiconv, -lkiconv)
           [1mlibkse         [22mN:M Threading Library (libkse, -lkse)
           [1mlibkvm         [22mKernel Data Access Library (libkvm, -lkvm)
           [1mlibm           [22mMath Library (libm, -lm)
           [1mlibm68k        [22mm68k Architecture Library (libm68k, -lm68k)
           [1mlibmagic       [22mMagic Number Recognition Library (libmagic, -lmagic)
           [1mlibmd          [22mMessage  Digest  (MD4,  MD5,  etc.)  Support   Library
                          (libmd, -lmd)
           [1mlibmemstat     [22mKernel    Memory    Allocator    Statistics    Library
                          (libmemstat, -lmemstat)
           [1mlibmenu        [22mCurses Menu Library (libmenu, -lmenu)
           [1mlibnetgraph    [22mNetgraph User Library (libnetgraph, -lnetgraph)
           [1mlibnetpgp      [22mNetpgp signing, verification, encryption  and  decryp‐
                          tion (libnetpgp, -lnetpgp)
           [1mlibossaudio    [22mOSS Audio Emulation Library (libossaudio, -lossaudio)
           [1mlibpam         [22mPluggable   Authentication   Module  Library  (libpam,
                          -lpam)
           [1mlibpcap        [22mPacket Capture Library (libpcap, -lpcap)
           [1mlibpci         [22mPCI Bus Access Library (libpci, -lpci)
           [1mlibpmc         [22mPerformance Counters Library (libpmc, -lpmc)
           [1mlibposix       [22mPOSIX Compatibility Library (libposix, -lposix)
           [1mlibprop        [22mProperty Container Object Library (libprop, -lprop)
           [1mlibpthread     [22mPOSIX Threads Library (libpthread, -lpthread)
           [1mlibpuffs       [22mpuffs Convenience Library (libpuffs, -lpuffs)
           [1mlibrefuse      [22mFile   System   in   Userspace   Convenience   Library
                          (librefuse, -lrefuse)
           [1mlibresolv      [22mDNS Resolver Library (libresolv, -lresolv)
           [1mlibrpcsec_gss  [22mRPC  GSS-API  Authentication  Library  (librpcsec_gss,
                          -lrpcsec_gss)
           [1mlibrpcsvc      [22mRPC Service Library (librpcsvc, -lrpcsvc)
           [1mlibrt          [22mPOSIX Real-time Library (librt, -lrt)
           [1mlibsdp         [22mBluetooth  Service  Discovery  Protocol  User  Library
                          (libsdp, -lsdp)
           [1mlibssp         [22mBuffer Overflow Protection Library (libssp, -lssp)
           [1mlibSystem      [22mSystem Library (libSystem, -lSystem)
           [1mlibtermcap     [22mTermcap Access Library (libtermcap, -ltermcap)
           [1mlibterminfo    [22mTerminal Information Library (libterminfo, -lterminfo)
           [1mlibthr         [22m1:1 Threading Library (libthr, -lthr)
           [1mlibufs         [22mUFS File System Access Library (libufs, -lufs)
           [1mlibugidfw      [22mFile  System  Firewall  Interface  Library (libugidfw,
                          -lugidfw)
           [1mlibulog        [22mUser Login Record Library (libulog, -lulog)
           [1mlibusbhid      [22mUSB  Human  Interface  Devices   Library   (libusbhid,
                          -lusbhid)
           [1mlibutil        [22mSystem Utilities Library (libutil, -lutil)
           [1mlibvgl         [22mVideo Graphics Library (libvgl, -lvgl)
           [1mlibx86_64      [22mx86_64 Architecture Library (libx86_64, -lx86_64)
           [1mlibz           [22mCompression Library (libz, -lz)

     Site-specific  additions might be found in the file [4mmdoc.local[24m; see section
     “Files” below.

     In a section titled “Library”, ‘Lb’ causes a break before and after its ar‐
     guments.

   [1mLiterals[0m
     The ‘Li’ literal macro may be used for special  characters,  symbolic  con‐
     stants,  and  other  syntactical items that should be typed exactly as dis‐
     played.

           [1mUsage: .Li [22m⟨argument⟩ ...

                    [1m.Li \en          \n[0m
                    [1m.Li M1 M2 M3 ;   M1 M2 M3[22m;
                    [1m.Li cntrl-D ) ,  cntrl-D[22m),
                    [1m.Li 1024 ...     1024 [22m...

     The default width is 16n.

   [1mNames[0m
     The ‘Nm’ macro identifies the document's central  topic.   Upon  its  first
     call,  it  has  the  peculiarity  of remembering its argument.  When subse‐
     quently called without arguments, ‘Nm’ regurgitates this initial  name  for
     the  sole  purpose  of  making less work for the document's author.  Use of
     ‘Nm’ is also appropriate when presenting a command synopsis for  the  topic
     of  a  man page in section 1, 6, or 8.  Its behavior changes when presented
     with arguments of various forms.

                    [1m.Nm groff_mdoc  groff_mdoc[0m
                    [1m.Nm             groff_mdoc[0m
                    [1m.Nm \-mdoc      -mdoc[0m
                    [1m.Nm foo ) ) ,   foo[22m)),
                    [1m.Nm :           groff_mdoc[22m:

     By default, the topic is set in boldface to reflect its prime importance in
     the discussion.  Cross references to other man page topics should use ‘Xr’;
     including a second argument for the section number enables them to  be  hy‐
     perlinked.  By default, cross-referenced topics are set in italics to avoid
     cluttering the page with boldface.

     The default width is 10n.

   [1mOptions[0m
     The  ‘.Op’  macro  places option brackets around any remaining arguments on
     the command line, and places any trailing punctuation outside the brackets.
     The macros ‘.Oo’ and ‘.Oc’ (which produce an opening and a  closing  option
     bracket,  respectively)  may be used across one or more lines or to specify
     the exact position of the closing parenthesis.

           [1mUsage: .Op [22m[⟨option⟩] ...

                    [1m.Op                                [22m[]
                    [1m.Op Fl k                           [22m[[1m-k[22m]
                    [1m.Op Fl k ) .                       [22m[[1m-k[22m]).
                    [1m.Op Fl k Ar kookfile               [22m[[1m-k [4m[22mkookfile[24m]
                    [1m.Op Fl k Ar kookfile ,             [22m[[1m-k [4m[22mkookfile[24m],
                    [1m.Op Ar objfil Op Ar corfil         [22m[[4mobjfil[24m [[4mcorfil[24m]]
                    [1m.Op Fl c Ar objfil Op Ar corfil ,  [22m[[1m-c [4m[22mobjfil[24m [[4mcorfil[24m]],
                    [1m.Op word1 word2                    [22m[word1 word2]
                    [1m.Li .Op Oo Ao option Ac Oc ...     .Op [22m[⟨option⟩] ...

     Here a typical example of the ‘.Oo’ and ‘.Oc’ macros:

           .Oo
           .Op Fl k Ar kilobytes
           .Op Fl i Ar interval
           .Op Fl c Ar count
           .Oc

     Produces:

           [[[1m-k [4m[22mkilobytes[24m] [[1m-i [4m[22minterval[24m] [[1m-c [4m[22mcount[24m]]

     The default width values of ‘.Op’ and ‘.Oo’ are 14n and 10n, respectively.

   [1mPathnames[0m
     The ‘.Pa’ macro formats file specifications.  If called without  arguments,
     ‘[4m~[24m’ (recognized by many shells) is output, representing the user's home di‐
     rectory.

           [1mUsage: .Pa [22m[⟨pathname⟩] ...

                    [1m.Pa                    [4m[22m~[0m
                    [1m.Pa /usr/share         [4m[22m/usr/share[0m
                    [1m.Pa /tmp/fooXXXXX ) .  [4m[22m/tmp/fooXXXXX[24m).

     The default width is 32n.

   [1mStandards[0m
     The ‘.St’ macro replaces standard abbreviations with their formal names.

           [1mUsage: .St [22m⟨abbreviation⟩ ...

     Available pairs for “Abbreviation/Formal Name” are:

     ANSI/ISO C

           [1m-ansiC          [22mANSI X3.159-1989 (“ANSI C89”)
           [1m-ansiC-89       [22mANSI X3.159-1989 (“ANSI C89”)
           [1m-isoC           [22mISO/IEC 9899:1990 (“ISO C90”)
           [1m-isoC-90        [22mISO/IEC 9899:1990 (“ISO C90”)
           [1m-isoC-99        [22mISO/IEC 9899:1999 (“ISO C99”)
           [1m-isoC-2011      [22mISO/IEC 9899:2011 (“ISO C11”)
           [1m-isoC-2023      [22mISO/IEC 9899:2024 (“ISO C23”)

     POSIX Part 1: System API

           [1m-iso9945-1-90   [22mISO/IEC 9945-1:1990 (“POSIX.1”)
           [1m-iso9945-1-96   [22mISO/IEC 9945-1:1996 (“POSIX.1”)
           [1m-p1003.1        [22mIEEE Std 1003.1 (“POSIX.1”)
           [1m-p1003.1-88     [22mIEEE Std 1003.1-1988 (“POSIX.1”)
           [1m-p1003.1-90     [22mISO/IEC 9945-1:1990 (“POSIX.1”)
           [1m-p1003.1-96     [22mISO/IEC 9945-1:1996 (“POSIX.1”)
           [1m-p1003.1b-93    [22mIEEE Std 1003.1b-1993 (“POSIX.1”)
           [1m-p1003.1c-95    [22mIEEE Std 1003.1c-1995 (“POSIX.1”)
           [1m-p1003.1g-2000  [22mIEEE Std 1003.1g-2000 (“POSIX.1”)
           [1m-p1003.1i-95    [22mIEEE Std 1003.1i-1995 (“POSIX.1”)
           [1m-p1003.1-2001   [22mIEEE Std 1003.1-2001 (“POSIX.1”)
           [1m-p1003.1-2004   [22mIEEE Std 1003.1-2004 (“POSIX.1”)
           [1m-p1003.1-2008   [22mIEEE Std 1003.1-2008 (“POSIX.1”)
           [1m-p1003.1-2024   [22mIEEE Std 1003.1-2024 (“POSIX.1”)

     POSIX Part 2: Shell and Utilities

           [1m-iso9945-2-93   [22mISO/IEC 9945-2:1993 (“POSIX.2”)
           [1m-p1003.2        [22mIEEE Std 1003.2 (“POSIX.2”)
           [1m-p1003.2-92     [22mIEEE Std 1003.2-1992 (“POSIX.2”)
           [1m-p1003.2a-92    [22mIEEE Std 1003.2a-1992 (“POSIX.2”)

     X/Open

           [1m-susv1          [22mVersion 1 of the Single UNIX Specification (“SUSv1”)
           [1m-susv2          [22mVersion 2 of the Single UNIX Specification (“SUSv2”)
           [1m-susv3          [22mVersion 3 of the Single UNIX Specification (“SUSv3”)
           [1m-susv4          [22mVersion 4 of the Single UNIX Specification (“SUSv4”)
           [1m-svid4          [22mSystem   V   Interface   Definition,  Fourth  Edition
                           (“SVID4”)
           [1m-xbd5           [22mX/Open Base Definitions Issue 5 (“XBD5”)
           [1m-xcu5           [22mX/Open Commands and Utilities Issue 5 (“XCU5”)
           [1m-xcurses4.2     [22mX/Open Curses Issue 4, Version 2 (“XCURSES4.2”)
           [1m-xns5           [22mX/Open Networking Services Issue 5 (“XNS5”)
           [1m-xns5.2         [22mX/Open Networking Services Issue 5.2 (“XNS5.2”)
           [1m-xpg3           [22mX/Open Portability Guide Issue 3 (“XPG3”)
           [1m-xpg4           [22mX/Open Portability Guide Issue 4 (“XPG4”)
           [1m-xpg4.2         [22mX/Open  Portability  Guide   Issue   4,   Version   2
                           (“XPG4.2”)
           [1m-xsh5           [22mX/Open System Interfaces and Headers Issue 5 (“XSH5”)

     Miscellaneous

           [1m-ieee754        [22mIEEE Std 754-1985
           [1m-iso8601        [22mISO 8601
           [1m-iso8802-3      [22mISO/IEC 8802-3:1989

   [1mVariable Types[0m
     The  ‘.Vt’  macro  may be used whenever a type is referenced.  In a section
     titled “Synopsis”, ‘Vt’ causes a break (useful for old-style C variable de‐
     clarations).

           [1mUsage: .Vt [22m⟨type⟩ ...

                    [1m.Vt extern char *optarg ;  [4m[22mextern[24m [4mchar[24m [4m*optarg[24m;
                    [1m.Vt FILE *                 [4m[22mFILE[24m [4m*[0m

   [1mVariables[0m
     Generic variable reference.

           [1mUsage: .Va [22m⟨variable⟩ ...

                    [1m.Va count             [4m[22mcount[0m
                    [1m.Va settimer ,        [4m[22msettimer[24m,
                    [1m.Va "int *prt" ) :    [4m[22mint[24m [4m*prt[24m):
                    [1m.Va "char s" ] ) ) ,  [4m[22mchar[24m [4ms[24m])),

     The default width is 12n.

   [1mManual Page Cross References[0m
     The ‘.Xr’ macro expects the first argument to be a manual page  name.   The
     optional second argument, if a string (defining the manual section), is put
     into parentheses.

           [1mUsage: .Xr [22m⟨man page name⟩ [⟨section⟩] ...

                    [1m.Xr mdoc        [4m[22mmdoc[0m
                    [1m.Xr mdoc ,      [4m[22mmdoc[24m,
                    [1m.Xr mdoc 7      [22m]8;;man:mdoc(7)\[4mmdoc[24m(7)]8;;\
                    [1m.Xr xinit 1x ;  [22m]8;;man:xinit(1x)\[4mxinit[24m(1x)]8;;\;

     The default width is 10n.

[1mGeneral text domain[0m
   [1mAT&T Macro[0m
           [1mUsage: .At [22m[⟨version⟩] ...

                    [1m.At       [22mAT&T UNIX
                    [1m.At v6 .  [22mVersion 6 AT&T UNIX.

     The following values for ⟨version⟩ are possible:

           [1m32v, v1, v2, v3, v4, v5, v6, v7, III, V, V.1, V.2, V.3, V.4[0m

   [1mBSD Macro[0m
           [1mUsage: .Bx [22m{-alpha | -beta | -devel} ...
                  [1m.Bx [22m[⟨version⟩ [⟨release⟩]] ...

                    [1m.Bx         [22mBSD
                    [1m.Bx 4.3 .   [22m4.3BSD.
                    [1m.Bx -devel  [22mBSD (currently under development)

     ⟨version⟩  will be prepended to the string ‘BSD’.  The following values for
     ⟨release⟩ are possible:

           [1mReno, reno, Tahoe, tahoe, Lite, lite, Lite2, lite2[0m

   [1mNetBSD Macro[0m
           [1mUsage: .Nx [22m[⟨version⟩] ...

                    [1m.Nx        [22mNetBSD
                    [1m.Nx 1.4 .  [22mNetBSD 1.4.

     For possible values of ⟨version⟩ see the description of the  ‘.Os’  command
     above in section “Title macros”.

   [1mFreeBSD Macro[0m
           [1mUsage: .Fx [22m[⟨version⟩] ...

                    [1m.Fx        [22mFreeBSD
                    [1m.Fx 2.2 .  [22mFreeBSD 2.2.

     For  possible  values of ⟨version⟩ see the description of the ‘.Os’ command
     above in section “Title macros”.

   [1mDragonFly Macro[0m
           [1mUsage: .Dx [22m[⟨version⟩] ...

                    [1m.Dx        [22mDragonFly
                    [1m.Dx 1.4 .  [22mDragonFly 1.4.

     For possible values of ⟨version⟩ see the description of the  ‘.Os’  command
     above in section “Title macros”.

   [1mOpenBSD Macro[0m
           [1mUsage: .Ox [22m[⟨version⟩] ...

                    [1m.Ox 1.0  [22mOpenBSD 1.0

   [1mBSD/OS Macro[0m
           [1mUsage: .Bsx [22m[⟨version⟩] ...

                    [1m.Bsx 1.0  [22mBSD/OS 1.0

   [1mUnix Macro[0m
           [1mUsage: .Ux [22m...

                    [1m.Ux  [22mUnix

   [1mEmphasis Macro[0m
     Text  may  be  stressed or emphasized with the ‘.Em’ macro.  The usual font
     for emphasis is italic.

           [1mUsage: .Em [22m⟨argument⟩ ...

                    [1m.Em does not          [4m[22mdoes[24m [4mnot[0m
                    [1m.Em exceed 1024 .     [4m[22mexceed[24m [4m1024[24m.
                    [1m.Em vide infra ) ) ,  [4m[22mvide[24m [4minfra[24m)),

     The default width is 10n.

   [1mFont Mode[0m
     The ‘.Bf’ font mode must be ended with the ‘.Ef’ macro (the latter takes no
     arguments).  Font modes may be nested within other font modes.

     ‘.Bf’ has the following syntax:

           [1m.Bf [22m⟨font mode⟩

     ⟨font mode⟩ must be one of the following three types:

           [1mEm [22m| [1m-emphasis  [22mSame as if the ‘.Em’ macro was used  for  the  entire
                           block of text.
           [1mLi [22m| [1m-literal   [22mSame  as  if  the ‘.Li’ macro was used for the entire
                           block of text.
           [1mSy [22m| [1m-symbolic  [22mSame as if the ‘.Sy’ macro was used  for  the  entire
                           block of text.

     Both macros are neither callable nor parsed.

   [1mEnclosure and Quoting Macros[0m
     The  concept  of  enclosure is similar to quoting.  The object being to en‐
     close one or more strings between a  pair  of  characters  like  quotes  or
     parentheses.   The  terms  quoting  and  enclosure are used interchangeably
     throughout this document.  Most of the one-line  enclosure  macros  end  in
     small letter ‘q’ to give a hint of quoting, but there are a few irregulari‐
     ties.   For  each  enclosure  macro, there is a pair of opening and closing
     macros that end with the lowercase letters ‘o’ and ‘c’ respectively.

     [1mQuote   Open   Close   Function                  Result[0m
     .Aq     .Ao    .Ac     Angle Bracket Enclosure   <string>
     .Bq     .Bo    .Bc     Bracket Enclosure         [string]
     .Brq    .Bro   .Brc    Brace Enclosure           {string}
     .Dq     .Do    .Dc     Double Quote              “string”
     .Eq     .Eo    .Ec     Enclose String (in XY)    XstringY
     .Pq     .Po    .Pc     Parenthesis Enclosure     (string)
     .Ql                    Quoted or Literal         “string” or string
     .Qq     .Qo    .Qc     Straight Double Quote     "string"
     .Sq     .So    .Sc     Single Quote              ‘string’

     All macros ending with ‘q’ and ‘o’ have a default width value of 12n.

     [1m.Eo[22m, [1m.Ec  [22mThese macros expect the first argument  to  be  the  opening  and
               closing strings, respectively.

     [1m.Es[22m, [1m.En  [22mTo work around the nine-argument limit in the original [4mtroff[24m pro‐
               gram,  [4mmdoc[24m  supports  two  other  macros  that are now obsolete.
               ‘.Es’ uses its first and second parameters as opening and closing
               marks which are then used to enclose the arguments of ‘.En’.  The
               default width value is 12n for both macros.

     [1m.Eq       [22mThe first and second arguments of this macro are the opening  and
               closing strings respectively, followed by the arguments to be en‐
               closed.

     [1m.Ql       [22mThe  quoted-or-literal  macro  behaves  differently  in [4mtroff[24m and
               [4mnroff[24m modes.  When formatting with ]8;;man:nroff(1)\[4mnroff[24m(1)]8;;\, [4mmdoc[24m quotes the  ar‐
               guments.  With [4mtroff[24m, [4mmdoc[24m sets them in a constant-width font.

               The default width is 16n.

     [1m.Pf       [22mThe  prefix macro suppresses the whitespace between its first and
               second argument:

                     [1m.Pf ( Fa name2  [22m([4mname2[0m

               The default width is 12n.

               The ‘.Ns’ macro (see below) performs the analogous  suffix  func‐
               tion.

     [1m.Ap       [22mThe  ‘.Ap’ macro inserts an apostrophe and exits any special text
               modes, continuing in ‘.No’ mode.

     Examples of quoting:

           [1m.Aq                      [22m⟨⟩
           [1m.Aq Pa ctype.h ) ,       [22m⟨[4mctype.h[24m⟩),
           [1m.Bq                      [22m[]
           [1m.Bq Em Greek , French .  [22m[[4mGreek[24m, [4mFrench[24m].
           [1m.Dq                      [22m“”
           [1m.Dq string abc .         [22m“string abc”.
           [1m.Dq '\[ha][A-Z]'         [22m“'^[A-Z]'”
           [1m.Ql man mdoc             [22m‘man mdoc’
           [1m.Qq                      [22m""
           [1m.Qq string ) ,           [22m"string"),
           [1m.Qq string Ns ),         [22m"string),"
           [1m.Sq                      [22m‘’
           [1m.Sq string               [22m‘string’
           [1m.Em or Ap ing            [4m[22mor[24m'ing

     For a good example of nested enclosure macros, see the ‘.Op’ option  macro.
     It was created from the same underlying enclosure macros as those presented
     in  the  list above.  The ‘.Xo’ and ‘.Xc’ extended argument list macros are
     discussed below.

   [1mNormal text macro[0m
     ‘No’ formats subsequent argument(s) normally, ending the effect of ‘Em’ and
     similar.  Parsing is [4mnot[24m suppressed, so you must  prefix  words  like  ‘No’
     with ‘\&’ to avoid their interpretation as [4mmdoc[24m macros.

           [1mUsage: .No [4m[22margument[24m ...

                    [1m.Em Use caution No here .  [22m→ [4mUse[24m [4mcaution[24m here.
                    [1m.Em No dogs allowed .      [22m→ [4mNo[24m dogs allowed.
                    [1m.Em \&No dogs allowed .    [22m→ [4mNo[24m [4mdogs[24m [4mallowed[24m.

     The default width is 12n.

   [1mNo-Space Macro[0m
     The  ‘.Ns’  macro suppresses insertion of a space between the current posi‐
     tion and its first parameter.  For example, it is useful for old style  ar‐
     gument lists where there is no space between the flag and argument:

           [1mUsage: [22m... ⟨argument⟩ Ns [⟨argument⟩] ...
                  [1m.Ns [22m⟨argument⟩ ...

                    [1m.Op Fl I Ns Ar directory  [22m[[1m-I[4m[22mdirectory[24m]

     Note:  The ‘.Ns’ macro always invokes the ‘.No’ macro after eliminating the
     space unless another macro name follows it.  If used as  a  command  (i.e.,
     the second form above in the ‘Usage’ line), ‘.Ns’ is identical to ‘.No’.

   [1m(Sub)section cross references[0m
     Use  the  ‘.Sx’ macro to cite a (sub)section heading within the given docu‐
     ment.

           [1mUsage: .Sx [22m⟨section-reference⟩ ...

                    [1m.Sx Files  [22m→ “Files”

     The default width is 16n.

   [1mSymbolics[0m
     The symbolic emphasis macro is generally a boldface  macro  in  either  the
     symbolic sense or the traditional English usage.

           [1mUsage: .Sy [22m⟨symbol⟩ ...

                    [1m.Sy Important Notice  [22m→ [1mImportant Notice[0m

     The default width is 6n.

   [1mMathematical Symbols[0m
     Use this macro for mathematical symbols and similar things.

           [1mUsage: .Ms [22m⟨math symbol⟩ ...

                    [1m.Ms sigma  [22m→ [1msigma[0m

     The default width is 6n.

   [1mReferences and Citations[0m
     The  following macros make a modest attempt to handle references.  At best,
     the macros make it convenient to manually drop  in  a  subset  of  ]8;;man:refer(1)\[4mrefer[24m(1)]8;;\
     style references.

           [1m.Rs     [22mReference  start (does not take arguments).  In a section ti‐
                   tled “See also”, it causes a break and begins  collection  of
                   reference information until the reference end macro is read.
           [1m.Re     [22mReference  end  (does  not take arguments).  The reference is
                   printed.
           [1m.%A     [22mReference author name; one name per invocation.
           [1m.%B     [22mBook title.
           [1m.%C     [22mCity/place.
           [1m.%D     [22mDate.
           [1m.%I     [22mIssuer/publisher name.
           [1m.%J     [22mJournal name.
           [1m.%N     [22mIssue number.
           [1m.%O     [22mOptional information.
           [1m.%P     [22mPage number.
           [1m.%Q     [22mCorporate or foreign author.
           [1m.%R     [22mReport name.
           [1m.%T     [22mTitle of article.
           [1m.%U     [22mOptional hypertext reference.
           [1m.%V     [22mVolume.

     Macros beginning with ‘%’ are not callable but accept multiple arguments in
     the usual way.  Only the ‘.Tn’ macro is handled properly  as  a  parameter;
     other  macros  will cause strange output.  ‘.%B’ and ‘.%T’ can be used out‐
     side of the ‘.Rs/.Re’ environment.

     Example:

           .Rs
           .%A "Matthew Bar"
           .%A "John Foo"
           .%T "Implementation Notes on foobar(1)"
           .%R "Technical Report ABC-DE-12-345"
           .%Q "Drofnats College"
           .%C "Nowhere"
           .%D "April 1991"
           .Re

     produces

           Matthew Bar and John Foo, [4mImplementation[24m [4mNotes[24m [4mon[24m [4mfoobar(1)[24m, Techni‐
           cal Report ABC-DE-12-345, Drofnats College, Nowhere, April 1991.

   [1mTrade Names or Acronyms[0m
     The trade name macro prints its arguments at a smaller type  size.   It  is
     intended to imitate a small caps fonts for fully capitalized acronyms.

           [1mUsage: .Tn [22m⟨symbol⟩ ...

                    [1m.Tn DEC    [22mDEC
                    [1m.Tn ASCII  [22mASCII

     The default width is 10n.

   [1mExtended Arguments[0m
     The  [1m.Xo  [22mand  [1m.Xc  [22mmacros  allow one to extend an argument list on a macro
     boundary for the ‘.It’ macro (see below).  Note that [1m.Xo [22mand [1m.Xc [22mare imple‐
     mented similarly to all other  macros  opening  and  closing  an  enclosure
     (without  inserting  characters, of course).  This means that the following
     is true for those macros also.

     Here is an example of ‘.Xo’ using the space mode macro to turn spacing off:

           .Bd -literal -offset indent
           .Sm off
           .It Xo Sy I Ar operation
           .No \en Ar count No \en
           .Xc
           .Sm on
           .Ed

     produces

           [1mI[4m[22moperation[24m\n[4mcount[24m\n

     Another one:

           .Bd -literal -offset indent
           .Sm off
           .It Cm S No / Ar old_pattern Xo
           .No / Ar new_pattern
           .No / Op Cm g
           .Xc
           .Sm on
           .Ed

     produces

           [1mS[22m/[4mold_pattern[24m/[4mnew_pattern[24m/[[1mg[22m]

     Another example of ‘.Xo’ and enclosure macros: Test the value  of  a  vari‐
     able.

           .Bd -literal -offset indent
           .It Xo
           .Ic .ifndef
           .Oo \&! Oc Ns Ar variable Oo
           .Ar operator variable No ...
           .Oc Xc
           .Ed

     produces

           [1m.ifndef [22m[!][4mvariable[24m [[4moperator[24m [4mvariable[24m ...]

[1mPage structure domain[0m
   [1mSection headings[0m
     The  following ‘.Sh’ section heading macros are required in every man page.
     The remaining section headings are recommended at the discretion of the au‐
     thor writing the manual page.  The ‘.Sh’ macro is parsed but not  generally
     callable.   It  can be used as an argument in a call to ‘.Sh’ only; it then
     reactivates the default font for ‘.Sh’.

     The default width is 8n.

     [1m.Sh Name           [22mThe ‘.Sh Name’ macro is mandatory.   If  not  specified,
                        headers,  footers,  and page layout defaults will not be
                        set and things will be rather unpleasant.  The [4mName[24m sec‐
                        tion consists of at least three items.  The first is the
                        ‘.Nm’ name macro naming the subject  of  the  man  page.
                        The  second  is the name description macro, ‘.Nd’, which
                        separates the subject name from the third item, which is
                        the description.  The description  should  be  the  most
                        terse  and  lucid  possible,  as  the space available is
                        small.

                        ‘.Nd’ first prints ‘-’, then all its arguments.

     [1m.Sh Library        [22mThis section is  for  section  two  and  three  function
                        calls.   It should consist of a single ‘.Lb’ macro call;
                        see “Library Names”.

     [1m.Sh Synopsis       [22mThe “Synopsis” section describes the  typical  usage  of
                        the  subject of a man page.  The macros required are ei‐
                        ther ‘.Nm’, ‘.Cd’, or ‘.Fn’ (and possibly ‘.Fo’,  ‘.Fc’,
                        ‘.Fd’, and ‘.Ft’).  The function name macro ‘.Fn’ is re‐
                        quired for manual page sections 2 and 3; the command and
                        general  name macro ‘.Nm’ is required for sections 1, 5,
                        6, 7, and 8.  Section 4 manuals require a  ‘.Nm’,  ‘.Fd’
                        or  a  ‘.Cd’  configuration device usage macro.  Several
                        other macros may be necessary to  produce  the  synopsis
                        line as shown below:

                              [1mcat [22m[[1m-benstuv[22m] [[1m-[22m] [4mfile[24m ...

                        The following macros were used:

                              [1m.Nm cat[0m
                              [1m.Op Fl benstuv[0m
                              [1m.Op Fl[0m
                              [1m.Ar file No ...[0m

     [1m.Sh Description    [22mIn  most  cases the first text in the “Description” sec‐
                        tion is a brief paragraph on the  command,  function  or
                        file,  followed by a lexical list of options and respec‐
                        tive explanations.  To create such  a  list,  the  ‘.Bl’
                        (begin  list),  ‘.It’  (list  item) and ‘.El’ (end list)
                        macros are used (see “Lists and Columns” below).

     [1m.Sh Implementation notes[0m
                        Implementation specific  information  should  be  placed
                        here.

     [1m.Sh Return values  [22mSections  2,  3  and  9 function return values should go
                        here.  The ‘.Rv’ macro may be used to generate text  for
                        use  in  the  “Return values” section for most section 2
                        and 3 library functions; see “Return Values”.

     The following ‘.Sh’ section headings are part of the preferred manual  page
     layout  and  must  be used appropriately to maintain consistency.  They are
     listed in the order in which they would be used.

     [1m.Sh Environment    [22mThe [4mEnvironment[24m section should reveal any related  envi‐
                        ronment variables and clues to their behavior and/or us‐
                        age.

     [1m.Sh Files          [22mFiles  which are used or created by the man page subject
                        should be listed via the ‘.Pa’ macro in the “Files” sec‐
                        tion.

     [1m.Sh Examples       [22mThere are several ways to create examples.  See  subsec‐
                        tion “Examples and Displays” below for details.

     [1m.Sh Diagnostics    [22mDiagnostic  messages  from a command should be placed in
                        this section.  The ‘.Ex’ macro may be used  to  generate
                        text  for use in the “Diagnostics” section for most sec‐
                        tion 1, 6 and 8 commands; see “Exit Status”.

     [1m.Sh Compatibility  [22mKnown compatibility issues (e.g. deprecated  options  or
                        parameters) should be listed here.

     [1m.Sh Errors         [22mSpecific  error  handling, especially from library func‐
                        tions (man page sections 2, 3, and 9)  should  go  here.
                        The ‘.Er’ macro is used to specify an error (errno).

     [1m.Sh See also       [22mReferences  to  other material on the man page topic and
                        cross references to other relevant man pages  should  be
                        placed  in the “See also” section.  Cross references are
                        specified using the  ‘.Xr’  macro.   Currently  ]8;;man:refer(1)\[4mrefer[24m(1)]8;;\
                        style references are not accommodated.

                        It is recommended that the cross references be sorted by
                        section  number, then alphabetically by name within each
                        section, then separated by commas.  Example:

                        ]8;;man:ls(1)\[4mls[24m(1)]8;;\, ]8;;man:ps(1)\[4mps[24m(1)]8;;\, ]8;;man:group(5)\[4mgroup[24m(5)]8;;\, ]8;;man:passwd(5)\[4mpasswd[24m(5)]8;;\

     [1m.Sh Standards      [22mIf the command, library function, or file adheres  to  a
                        specific   implementation   such   as  IEEE  Std  1003.2
                        (“POSIX.2”) or ANSI X3.159-1989 (“ANSI C89”) this should
                        be noted here.  If the command does not  adhere  to  any
                        standard,  its  history  should  be noted in the [4mHistory[0m
                        section.

     [1m.Sh History        [22mAny command which does not adhere to any specific  stan‐
                        dards should be outlined historically in this section.

     [1m.Sh Authors        [22mCredits  should be placed here.  Use the ‘.An’ macro for
                        names and the ‘.Aq’ macro for email addresses within op‐
                        tional contact information.  Explicitly indicate whether
                        the person authored the initial manual page or the soft‐
                        ware or whatever the person is being credited for.

     [1m.Sh Bugs           [22mBlatant problems with the topic go here.

     User-specified ‘.Sh’ sections may be added; for example, this  section  was
     set with:

                    .Sh "Page structure domain"

   [1mSubsection headings[0m
     Subsection headings have exactly the same syntax as section headings: ‘.Ss’
     is  parsed  but not generally callable.  It can be used as an argument in a
     call to ‘.Ss’ only; it then reactivates the default font for ‘.Ss’.

     The default width is 8n.

   [1mParagraphs and Line Spacing[0m
     [1m.Pp  [22mThe ‘.Pp’ paragraph command may be used to specify a line space  where
          necessary.  The macro is not necessary after a ‘.Sh’ or ‘.Ss’ macro or
          before  a  ‘.Bl’ or ‘.Bd’ macro (which both assert a vertical distance
          unless the [1m-compact [22mflag is given).

          The macro is neither callable nor parsed and takes  no  arguments;  an
          alternative name is ‘.Lp’.

   [1mKeeps[0m
     The  only  keep  that is implemented at this time is for words.  The macros
     are ‘.Bk’ (begin keep) and ‘.Ek’ (end keep).  The only  option  that  ‘.Bk’
     currently accepts is [1m-words [22m(also the default); this prevents breaks in the
     middle  of  options.   In  the example for [1mmake [22mcommand-line arguments (see
     “What's in a Name”), the keep prevents [4mnroff[24m from placing the flag and  the
     argument on separate lines.

     Neither macro is callable or parsed.

     More work needs to be done on the keep macros; specifically, a [1m-line [22moption
     should be added.

   [1mExamples and Displays[0m
     There are seven types of displays.

     [1m.D1  [22m(This  is  D-one.)   Display one line of indented text.  This macro is
          parsed but not callable.

                [1m-ldghfstru[0m

          The above was produced by: [1m.D1 Fl ldghfstru[22m.

     [1m.Dl  [22m(This is D-ell.)  Display one line  of  indented  [4mliteral[24m  text.   The
          ‘.Dl’ example macro has been used throughout this file.  It allows the
          indentation (display) of one line of text.  Its default font is set to
          constant width (literal).  ‘.Dl’ is parsed but not callable.

                [1m% ls -ldg /usr/local/bin[0m

          The above was produced by: [1m.Dl % ls \-ldg /usr/local/bin[22m.

     [1m.Bd  [22mBegin  display.  The ‘.Bd’ display must be ended with the ‘.Ed’ macro.
          It has the following syntax:

                [1m.Bd [22m{-literal | -filled | -unfilled | -ragged | -centered}
                     [-offset ⟨string⟩] [-file ⟨file name⟩] [-compact]

          [1m-ragged            [22mFill, but do not adjust  (leave  the  right  margin
                             ragged).
          [1m-centered          [22mCenter  lines  between  the  current left and right
                             margin.  Note that each single line is centered.
          [1m-unfilled          [22mDo not fill; break lines where  their  input  lines
                             are  broken.  This can produce overlong lines with‐
                             out warning messages.
          [1m-filled            [22mDisplay a filled block.  Text  is  filled  and  ad‐
                             justed; the left and right margins are straight.
          [1m-literal           [22mDisplay  block  with  literal  font (usually fixed-
                             width).  Useful for source code or simple tabbed or
                             spaced text.
          [1m-file [22m⟨[4mfile[24m [4mname[24m⟩  The file whose name follows the [1m-file [22mflag is  read
                             and  displayed  before any data enclosed with ‘.Bd’
                             and ‘.Ed’, using the selected  display  type.   Any
                             [4mtroff/mdoc[24m commands in the file will be processed.
          [1m-offset [22m⟨[4mstring[24m⟩   If  [1m-offset  [22mis specified with one of the following
                             strings, the string is interpreted to indicate  the
                             level  of  indentation for the forthcoming block of
                             text:

                             [4mleft[24m        Align block on the current left margin;
                                         this is the default mode of ‘.Bd’.
                             [4mcenter[24m      Supposedly center the block.   At  this
                                         time  unfortunately,  the  block merely
                                         gets left aligned  about  an  imaginary
                                         center margin.
                             [4mindent[24m      Indent  by  one default indent value or
                                         tab.  The default indent value is  also
                                         used for the ‘.D1’ and ‘.Dl’ macros, so
                                         one is guaranteed the two types of dis‐
                                         plays  will  line  up.  The indentation
                                         value is normally set to  6n  or  about
                                         two  thirds  of  an  inch (six constant
                                         width characters).
                             [4mindent-two[24m  Indent two  times  the  default  indent
                                         value.
                             [4mright[24m       This  [4mleft[24m  aligns  the block about two
                                         inches from the right side of the page.
                                         This macro needs work and  perhaps  may
                                         never do the right thing within [4mtroff[24m.

                             If  ⟨string⟩  is a valid numeric expression instead
                             ([4mwith[24m [4ma[24m [4mscaling[24m [4mindicator[24m [4mother[24m [4mthan[24m ‘[4mu[24m’), use that
                             value for indentation.  The most useful scaling in‐
                             dicators are ‘m’ and ‘n’, specifying the  so-called
                             [4mEm[24m  and [4mEn[24m [4msquare[24m.  This is approximately the width
                             of the letters ‘m’ and ‘n’ respectively of the cur‐
                             rent font (for [4mnroff[24m output, both  scaling  indica‐
                             tors  give  the  same values).  If ⟨string⟩ isn't a
                             numeric expression, it is tested whether it  is  an
                             [4mmdoc[24m macro name, and the default offset value asso‐
                             ciated  with  this  macro is used.  Finally, if all
                             tests fail, the width of ⟨string⟩ (typeset  with  a
                             fixed-width font) is taken as the offset.
          [1m-compact           [22mSuppress  insertion  of vertical space before begin
                             of display.

     [1m.Ed  [22mEnd display (takes no arguments).

   [1mLists and Columns[0m
     There are several types of lists which may be initiated with the ‘.Bl’  be‐
     gin-list  macro.   Items  within the list are specified with the ‘.It’ item
     macro, and each list must end with the ‘.El’ macro.  Lists  may  be  nested
     within  themselves and within displays.  The use of columns inside of lists
     or lists inside of columns is untested.

     In addition, several list attributes may be specified such as the width  of
     a  tag, the list offset, and compactness (blank lines between items allowed
     or disallowed).  Most of this document has been formatted with a tag  style
     list ([1m-tag[22m).

     It has the following syntax forms:

           [1m.Bl [22m{-hang | -ohang | -tag | -diag | -inset} [-width ⟨string⟩]
                [-offset ⟨string⟩] [-compact]
           [1m.Bl [22m-column [-offset ⟨string⟩] ⟨string1⟩ ⟨string2⟩ ...
           [1m.Bl [22m{-item | -enum [-nested] | -bullet | -hyphen | -dash} [-offset
                ⟨string⟩] [-compact]

     And now a detailed description of the list types.

     [1m-bullet  [22mA bullet list.

                    .Bl -bullet -offset indent -compact
                    .It
                    Bullet one goes here.
                    .It
                    Bullet two here.
                    .El

              Produces:

                    [1m•   [22mBullet one goes here.
                    [1m•   [22mBullet two here.

     [1m-dash [22m(or [1m-hyphen[22m)
              A dash list.

                    .Bl -dash -offset indent -compact
                    .It
                    Dash one goes here.
                    .It
                    Dash two here.
                    .El

              Produces:

                    [1m-   [22mDash one goes here.
                    [1m-   [22mDash two here.

     [1m-enum    [22mAn enumerated list.

                    .Bl -enum -offset indent -compact
                    .It
                    Item one goes here.
                    .It
                    And item two here.
                    .El

              The result:

                    1.   Item one goes here.
                    2.   And item two here.

              If you want to nest enumerated lists, use the [1m-nested [22mflag (start‐
              ing with the second-level list):

                    .Bl -enum -offset indent -compact
                    .It
                    Item one goes here
                    .Bl -enum -nested -compact
                    .It
                    Item two goes here.
                    .It
                    And item three here.
                    .El
                    .It
                    And item four here.
                    .El

              Result:

                    1.   Item one goes here.
                         1.1.   Item two goes here.
                         1.2.   And item three here.
                    2.   And item four here.

     [1m-item    [22mA list of type [1m-item [22mwithout list markers.

                    .Bl -item -offset indent
                    .It
                    Item one goes here.
                    Item one goes here.
                    Item one goes here.
                    .It
                    Item two here.
                    Item two here.
                    Item two here.
                    .El

              Produces:

                    Item  one  goes  here.   Item  one goes here.  Item one goes
                    here.

                    Item two here.  Item two here.  Item two here.

     [1m-tag     [22mA list with tags.  Use [1m-width [22mto specify the tag width.

                    SL    sleep time of the process (seconds blocked)
                    PAGEIN
                          number of disk I/O operations  resulting  from  refer‐
                          ences by the process to pages not loaded in core.
                    UID   numerical user-id of process owner
                    PPID  numerical  id of parent of process priority (non-posi‐
                          tive when in non-interruptible wait)

              The raw text:

                    .Bl -tag -width "PPID" -compact -offset indent
                    .It SL
                    sleep time of the process (seconds blocked)
                    .It PAGEIN
                    number of disk I/O operations resulting from references
                    by the process to pages not loaded in core.
                    .It UID
                    numerical user-id of process owner
                    .It PPID
                    numerical id of parent of process priority
                    (non-positive when in non-interruptible wait)
                    .El

     [1m-diag    [22mDiag lists create section four diagnostic lists and are similar to
              inset lists except callable macros are ignored.  The  [1m-width  [22mflag
              is not meaningful in this context.

              Example:

                    .Bl -diag
                    .It You can't use Sy here.
                    The message says all.
                    .El

              produces

              [1mYou can't use Sy here.  [22mThe message says all.

     [1m-hang    [22mA list with hanging tags.

                    [4mHanged[24m  labels appear similar to tagged lists when the label
                            is smaller than the label width.

                    [4mLonger[24m  [4mhanged[24m  [4mlist[24m  [4mlabels[24m blend into the paragraph unlike
                            tagged paragraph labels.

              And the unformatted text which created it:

                    .Bl -hang -offset indent
                    .It Em Hanged
                    labels appear similar to tagged lists when the
                    label is smaller than the label width.
                    .It Em Longer hanged list labels
                    blend into the paragraph unlike
                    tagged paragraph labels.
                    .El

     [1m-ohang   [22mLists with overhanging tags do not use indentation for the  items;
              tags are written to a separate line.

                    [1mSL[0m
                    sleep time of the process (seconds blocked)

                    [1mPAGEIN[0m
                    number  of  disk I/O operations resulting from references by
                    the process to pages not loaded in core.

                    [1mUID[0m
                    numerical user-id of process owner

                    [1mPPID[0m
                    numerical id of parent  of  process  priority  (non-positive
                    when in non-interruptible wait)

              The raw text:

                    .Bl -ohang -offset indent
                    .It Sy SL
                    sleep time of the process (seconds blocked)
                    .It Sy PAGEIN
                    number of disk I/O operations resulting from references
                    by the process to pages not loaded in core.
                    .It Sy UID
                    numerical user-id of process owner
                    .It Sy PPID
                    numerical id of parent of process priority
                    (non-positive when in non-interruptible wait)
                    .El

     [1m-inset   [22mHere is an example of inset labels:

                    [4mTag[24m  The tagged list (also called a tagged paragraph) is the
                    most common type of list used in the Berkeley manuals.   Use
                    a [1m-width [22mattribute as described below.

                    [4mDiag[24m Diag lists create section four diagnostic lists and are
                    similar to inset lists except callable macros are ignored.

                    [4mHang[24m Hanged labels are a matter of taste.

                    [4mOhang[24m Overhanging labels are nice when space is constrained.

                    [4mInset[24m  Inset  labels  are  useful  for controlling blocks of
                    paragraphs and are valuable for converting [4mmdoc[24m  manuals  to
                    other formats.

              Here is the source text which produced the above example:

                    .Bl -inset -offset indent
                    .It Em Tag
                    The tagged list (also called a tagged paragraph)
                    is the most common type of list used in the
                    Berkeley manuals.
                    .It Em Diag
                    Diag lists create section four diagnostic lists
                    and are similar to inset lists except callable
                    macros are ignored.
                    .It Em Hang
                    Hanged labels are a matter of taste.
                    .It Em Ohang
                    Overhanging labels are nice when space is constrained.
                    .It Em Inset
                    Inset labels are useful for controlling blocks of
                    paragraphs and are valuable for converting
                    .Xr mdoc
                    manuals to other formats.
                    .El

     [1m-column  [22mThis  list type generates multiple columns.  The number of columns
              and the width of each column is determined by the arguments to the
              [1m-column [22mlist, ⟨[4mstring1[24m⟩, ⟨[4mstring2[24m⟩, etc.  If ⟨[4mstringN[24m⟩ starts with
              a ‘.’ (dot) immediately followed by a valid [4mmdoc[24m macro  name,  in‐
              terpret ⟨[4mstringN[24m⟩ and use the width of the result.  Otherwise, the
              width  of  ⟨[4mstringN[24m⟩ (typeset with a fixed-width font) is taken as
              the [4mN[24mth column width.

              Each ‘.It’ argument is parsed to make a row,  each  column  within
              the  row  is  a  separate argument separated by a tab or the ‘.Ta’
              macro.

              The table:

                    [1mString    Nroff    Troff[0m
                    [1m<=        [22m<=       ≤
                    [1m>=        [22m>=       ≥

              was produced by:

              .Bl -column -offset indent ".Sy String" ".Sy Nroff" ".Sy Troff"
              .It Sy String Ta Sy Nroff Ta Sy Troff
              .It Li <= Ta <= Ta \*(<=
              .It Li >= Ta >= Ta \*(>=
              .El

              Don't abuse this list type!  For more complicated cases  it  might
              be far better and easier to use ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\, the table preprocessor.

     Other keywords:

     [1m-width [22m⟨[4mstring[24m⟩   If  ⟨[4mstring[24m⟩ starts with a ‘.’ (dot) immediately followed
                       by a valid [4mmdoc[24m macro name, interpret  ⟨[4mstring[24m⟩  and  use
                       the  width of the result.  Almost all lists in this docu‐
                       ment use this option.

                       Example:

                             .Bl -tag -width ".Fl test Ao Ar string Ac"
                             .It Fl test Ao Ar string Ac
                             This is a longer sentence to show how the
                             .Fl width
                             flag works in combination with a tag list.
                             .El

                       gives:

                       [1m-test [22m⟨[4mstring[24m⟩  This is a longer sentence to show how the
                                       [1m-width [22mflag works in combination  with  a
                                       tag list.

                       (Note  that  the  current  state  of [4mmdoc[24m is saved before
                       ⟨[4mstring[24m⟩ is interpreted; afterward, all variables are re‐
                       stored again.  However, boxes (used for enclosures) can't
                       be saved in GNU ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\;  as  a  consequence,  arguments
                       must always be [4mbalanced[24m to avoid nasty errors.  For exam‐
                       ple,  do not write ‘.Ao Ar string’ but ‘.Ao Ar string Xc’
                       instead  if  you  really  need  only  an  opening   angle
                       bracket.)

                       Otherwise,  if  ⟨[4mstring[24m⟩  is  a  valid numeric expression
                       ([4mwith[24m [4ma[24m [4mscaling[24m [4mindicator[24m [4mother[24m [4mthan[24m ‘[4mu[24m’), use that value
                       for indentation.  The most useful scaling indicators  are
                       ‘m’  and  ‘n’, specifying the so-called [4mEm[24m and [4mEn[24m [4msquare[24m.
                       This is approximately the width of the  letters  ‘m’  and
                       ‘n’  respectively  of the current font (for [4mnroff[24m output,
                       both  scaling  indicators  give  the  same  values).   If
                       ⟨[4mstring[24m⟩ isn't a numeric expression, it is tested whether
                       it is an [4mmdoc[24m macro name, and the default width value as‐
                       sociated  with this macro is used.  Finally, if all tests
                       fail, the width of ⟨[4mstring[24m⟩ (typeset with  a  fixed-width
                       font) is taken as the width.

                       If  a  width is not specified for the tag list type, ‘6n’
                       is used.

     [1m-offset [22m⟨[4mstring[24m⟩  If ⟨[4mstring[24m⟩ is [4mindent[24m, a default indent  value  (normally
                       set  to  6n, similar to the value used in ‘.Dl’ or ‘.Bd’)
                       is used.  If ⟨[4mstring[24m⟩ is a valid numeric  expression  in‐
                       stead ([4mwith[24m [4ma[24m [4mscaling[24m [4mindicator[24m [4mother[24m [4mthan[24m ‘[4mu[24m’), use that
                       value  for  indentation.  The most useful scaling indica‐
                       tors are ‘m’ and ‘n’, specifying the so-called [4mEm[24m and  [4mEn[0m
                       [4msquare[24m.   This  is approximately the width of the letters
                       ‘m’ and ‘n’ respectively of the current font  (for  [4mnroff[0m
                       output,  both  scaling  indicators give the same values).
                       If ⟨[4mstring[24m⟩ isn't a  numeric  expression,  it  is  tested
                       whether  it is an [4mmdoc[24m macro name, and the default offset
                       value associated with this macro is  used.   Finally,  if
                       all  tests  fail,  the  width of ⟨[4mstring[24m⟩ (typeset with a
                       fixed-width font) is taken as the offset.

     [1m-compact          [22mSuppress insertion of vertical space before the list  and
                       between list items.

[1mMiscellaneous macros[0m
     A  double  handful  of  macros fit only uncomfortably into one of the above
     sections.  Of these, we couldn't find attested examples for ‘Me’  or  ‘Ot’.
     They  are documented here for completeness——if you know their proper usage,
     please send a mail to ]8;;mailto:groff@gnu.org\groff@gnu.org]8;;\ and include a specimen with its  prove‐
     nance.

     [1m.Bt  [22mformats boilerplate text.

                [1m.Bt  [22m→ is currently in beta test.

          It is neither callable nor parsed and takes no arguments.  Its default
          width is 6n.

     [1m.Fr  [22mis an obsolete means of specifying a function return value.

                Usage: .[1mFr [4m[22mreturn-value[24m ...

          ‘Fr’  allows  a  break right before the return value (usually a single
          digit) which is bad typographical behaviour.  Instead, set the  return
          value with the rest of the code, using ‘\~’ to tie the return value to
          the previous word.

          Its default width is 12n.

     [1m.Hf  [22mInlines the contents of a (header) file into the document.

                Usage: .[1mHf [4m[22mfile[0m

          It  first  prints ‘File:’ followed by the file name, then the contents
          of [4mfile[24m.  It is neither callable nor parsed.

     [1m.Lk  [22mEmbed hyperlink.  This is a GNU extension  introduced  in  [4mgroff[24m  1.17
          (April 2001).

                Usage: .[1mLk [4m[22muri[24m [[4mlink-text[24m]

          Its default width is 6n.

     [1m.Me  [22mUsage  unknown.  The [4mmdoc[24m sources describe it as a macro for “menu en‐
          tries”.

          Its default width is 6n.

     [1m.Mt  [22mEmbed email address.  This is a GNU extension introduced in [4mgroff[24m 1.17
          (April 2001).

                Usage: .[1mMt [4m[22memail-address[0m

          Its default width is 6n.

     [1m.Ot  [22mUsage unknown.  The [4mmdoc[24m sources describe it  as  “old  function  type
          (fortran)”.

     [1m.Sm  [22mManipulate or toggle argument-spacing mode.

                Usage: .[1mSm [22m[[1mon [22m| [1moff[22m] ...

          If argument-spacing mode is off, no spaces between macro arguments are
          inserted.   If called without a parameter (or if the next parameter is
          neither ‘on’ nor ‘off’), ‘Sm’ toggles argument-spacing mode.

          Its default width is 8n.

     [1m.Ud  [22mformats boilerplate text.

                [1m.Ud  [22m→ currently under development.

          It is neither callable nor parsed and takes no arguments.  Its default
          width is 8n.

[1mPredefined strings[0m
     The following strings are predefined for  compatibility  with  legacy  [4mmdoc[0m
     documents.   Contemporary  ones  should  use  the alternatives shown in the
     “Prefer” column below.  See ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\ for a full  discussion  of  these
     special character escape sequences.

     [1mString   7-bit     8-bit     UCS   Prefer    Meaning[0m
     \*(<=    <=        <=        ≤     \[<=]     less than or equal to
     \*(>=    >=        >=        ≥     \[>=]     greater than or equal to
     \*(Rq    "         "         ”     \[rq]     right double quote
     \*(Lq    "         "         “     \[lq]     left double quote
     \*(ua    ^         ^         ↑     \[ua]     vertical arrow up
     \*(aa    '         ´         ´     \[aa]     acute accent
     \*(ga    `         `         `     \[ga]     grave accent
     \*(q     "         "         "     \[dq]     neutral double quote
     \*(Pi    pi        pi        π     \[*p]     lowercase pi
     \*(Ne    !=        !=        ≠     \[!=]     not equals
     \*(Le    <=        <=        ≤     \[<=]     less than or equal to
     \*(Ge    >=        >=        ≥     \[>=]     greater than or equal to
     \*(Lt    <         <         <     <         less than
     \*(Gt    >         >         >     >         greater than
     \*(Pm    +-        ±         ±     \[+-]     plus or minus
     \*(If    infinity  infinity  ∞     \[if]     infinity
     \*(Am    &         &         &     &         ampersand
     \*(Na    [4mNaN[24m       [4mNaN[24m       [4mNaN[24m   .Em NaN   not a number (slanted)
     \*(Ba    |         |         |     |         bar (upright)

     Some  column  headings  are shorthand for standardized character encodings;
     “7-bit” for ISO 646:1991 IRV (US-ASCII), “8-bit” for ISO Latin-1  (8859-1),
     and  “UCS”  for ISO 10646 (Unicode character set).  Historically, [4mmdoc[24m con‐
     figured the string definitions to fit the capabilities expected of the out‐
     put device.  Old typesetters lacked directional  double  quotes,  producing
     repeated directional single quotes ‘‘like this’’; early versions of [4mmdoc[24m in
     fact  defined the ‘Lq’ and ‘Rq’ strings this way.  Nowadays, output drivers
     take on the responsibility of glyph substitution, as they possess  relevant
     knowledge  of their available repertoires.  The ‘Ba’ and ‘Na’ strings imply
     a mandatory typeface: upright (roman) in the former, and slanted  (italics)
     with the latter.

[1mDiagnostics[0m
     The  debugging macro ‘.Db’ offered by previous versions of [4mmdoc[24m is unavail‐
     able in GNU ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ since the latter provides better facilities  to  check
     parameters; additionally, [4mgroff[24m [4mmdoc[24m implements many error and warning mes‐
     sages, making the package more robust and more verbose.

     The  remaining  debugging  macro is ‘.Rd’, which dumps the package's global
     register and string contents to the standard error stream.  A  normal  user
     will never need it.

[1mOptions[0m
     The  following  [4mgroff[24m options set registers (with [1m-r[22m) and strings (with [1m-d[22m)
     recognized and used by the [4mmdoc[24m macro package.  To ensure rendering consis‐
     tent with output device capabilities  and  reader  preferences,  man  pages
     should never manipulate them.

     Setting string ‘AD’ configures the adjustment mode for most formatted text.
     Typical values are ‘b’ for adjustment to both margins (the default), or ‘l’
     for  left  alignment  (ragged right margin).  Any valid argument to [4mgroff[24m's
     ‘ad’ request may be used.  See ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\ for less-common choices.
           [1mgroff -Tutf8 -dAD=l -mdoc groff_mdoc.7 [22m| [1mless -R[0m

     Setting register ‘C’ to 1 numbers output pages consecutively,  rather  than
     resetting the page number to 1 (or the value of register ‘P’) with each new
     [4mmdoc[24m document.

     By  default,  the package inhibits page breaks, headers, and footers in the
     midst of the document text if it is being displayed with a terminal  device
     such  as  ‘latin1’ or ‘utf8’, to enable more efficient viewing of the page.
     This behavior can be changed to format the page as if for 66-line  Teletype
     output  by  setting  the  continuous  rendering register ‘cR’ to zero while
     calling ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\.
           [1mgroff -Tlatin1 -rcR=0 -mdoc foo.man > foo.txt[0m
     On HTML devices, it cannot be disabled.

     Section headings (defined with ‘.Sh’) and page titles in  headers  (defined
     with ‘.Dt’) can be presented in full capitals by setting the registers ‘CS’
     and ‘CT’, respectively, to 1.  These transformations are off by default be‐
     cause they discard case distinction information.

     Setting  register  ‘D’ to 1 enables double-sided page layout, which is only
     distinct when not continuously rendering.  It places the page number at the
     bottom right on odd-numbered (recto) pages, and at the bottom left on even-
     numbered (verso) pages, swapping places with the arguments to ‘.Os’.
           [1mgroff -Tps -rD1 -mdoc foo.man > foo.ps[0m

     The value of the ‘FT’ register determines the footer's  distance  from  the
     page  bottom;  this  amount is always negative and should specify a scaling
     unit.  At one half-inch above this location, the page text is broken before
     writing the footer.  It is ignored if continuous rendering is enabled.  The
     default is “-0.5i - 1v”.

     The ‘HF’ string sets the font used for section and subsection headings; the
     default is ‘B’ (bold style of the default family).  Any valid  argument  to
     [4mgroff[24m's ‘ft’ request may be used.

     Normally,  automatic hyphenation is enabled using a mode appropriate to the
     [4mgroff[24m locale; see section “Localization“ of ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\.  It can  be  disabled
     by setting the ‘HY’ register to zero.
           [1mgroff -Tutf8 -rHY=0 -mdoc foo.man [22m| [1mless -R[0m

     The  paragraph and subsection heading indentation amounts can be changed by
     setting the registers ‘BP’ and ‘SN’.
           [1mgroff -Tutf8 -rBP=4n -rSN=2n -mdoc foo.man [22m| [1mless -R[0m
     The default paragraph and subsection heading indentation amounts are 5n and
     3n, respectively.  Section headings are set with an indentation of zero.

     The line and title lengths can be changed by setting the registers ‘LL’ and
     ‘LT’, respectively:
           [1mgroff -Tutf8 -rLL=100n -rLT=100n -mdoc foo.man [22m| [1mless -R[0m
     If not set, both registers default to 80n for  terminal  devices  and  6.5i
     otherwise.

     The  ‘MF’  string  sets  the font used for man page identifiers in document
     headers and footers and in the formatted output of the ‘Xr’ macro.  The de‐
     fault is ‘I’ (italic style of the default family).  Any valid  argument  to
     [4mgroff[24m's ‘ft’ request may be used.

     Setting the ‘P’ register starts enumeration of pages at its value.  The de‐
     fault is 1.

     The ‘PO’ register configures the page offset.  The default is device-depen‐
     dent; typically 0 for terminal devices and 1i otherwise.

     To  change  the  document font size to 11p or 12p, set register ‘S’ accord‐
     ingly:
           [1mgroff -Tdvi -rS11 -mdoc foo.man > foo.dvi[0m
     Register ‘S’ is ignored when formatting for terminal devices.

     By default, [4mgroff[24m hyperlinks the formatted text of  ‘Lk’,  ‘Mt’,  and  ‘Xr’
     calls  on output devices that support hyperlinking (“html”, “pdf”, and ter‐
     minal devices).  Set the ‘U’ register to 0 to disable this feature.

     Setting the ‘X’ register to a page number [4mp[24m numbers its successors  as  [4mp[24m[1ma[22m,
     [4mp[24m[1mb[22m,  [4mp[24m[1mc[22m, and so forth.  The register tracking the suffixed page letter uses
     format ‘a’ (see the ‘af’ request in ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\).

[1mFiles[0m
     [4m/usr/share/groff/1.24.0/tmac/andoc.tmac[0m
             This brief [4mgroff[24m program detects whether  the  [4mman[24m  or  [4mmdoc[24m  macro
             package is being used by a document and loads the correct macro de‐
             finitions,  taking advantage of the fact that pages using them must
             call [1mTH [22mor [1mDd[22m, respectively, before any other macros.  A user  typ‐
             ing, for example,
                   [1mgroff -mandoc page.1[0m
             need  not  know  which  package the file [4mpage.1[24m uses.  Multiple man
             pages, in either format, can be handled;  [4mandoc.tmac[24m  reloads  each
             macro package as necessary.

     [4m/usr/share/groff/1.24.0/tmac/doc.tmac[0m
             implements  the  bulk  of  the [4mgroff[24m [4mmdoc[24m package and loads further
             components as needed from the [4mmdoc[24m subdirectory.

     [4m/usr/share/groff/1.24.0/tmac/doc-old.tmac[0m
             implements a legacy version of the [4mmdoc[24m package; it was  superseded
             in  4.4BSD  (1994)  and  is needed only to render certain man pages
             from 4.3BSD-Reno.

     [4m/usr/share/groff/1.24.0/tmac/mdoc.tmac[0m
             is a wrapper enabling the package to be loaded with the option  “[1m-m[0m
             [1mmdoc[22m”.

     [4m/usr/share/groff/1.24.0/tmac/mdoc/doc-common[0m
             defines  macros,  registers, and strings concerned with the produc‐
             tion  of  formatted  output.   It  includes  strings  of  the  form
             ‘doc-volume-ds-[4mX[24m’  and  ‘doc-volume-as-[4mX[24m’ for manual section titles
             and architecture identifiers, respectively, where [4mX[24m is an  argument
             recognized by .[1mDt[22m.

     [4m/usr/share/groff/1.24.0/tmac/mdoc/doc-nroff[0m
             defines parameters appropriate for rendering to terminal devices.

     [4m/usr/share/groff/1.24.0/tmac/mdoc/doc-ditroff[0m
             defines parameters appropriate for rendering to typesetter devices.

     [4m/usr/share/groff/1.24.0/tmac/mdoc/doc-syms[0m
             defines  many  strings  and macros that interpolate formatted text,
             such as names of operating system  releases,  *BSD  libraries,  and
             standards   documents.    The   string   names   are  of  the  form
             ‘doc-str-[4mO[24m[1m-[4m[22mV[24m’, ‘doc-str-St[1m--[4m[22mS[24m[1m-[4m[22mI[24m’ (observe the  double  dashes),  or
             ‘doc-str-Lb-[4mL[24m’,  where [4mO[24m is one of the operating system macros from
             section “General text domain” above, [4mV[24m is an encoding of an operat‐
             ing system release (sometimes omitted along with the ‘-’  preceding
             it),  [4mS[24m  an identifier for a standards body or committee, [4mI[24m one for
             an issue of a standard promulgated by [4mS[24m, and [4mL[24m a keyword  identify‐
             ing a *BSD library.

     [4m/usr/share/groff/site-tmac/mdoc.local[0m
             This file houses local additions and customizations to the package.
             It can be empty.

[1mSee also[0m
     The ]8;;https://mandoc.bsd.lv/\mandoc]8;;\ project maintains an independent implementation of the [4mmdoc[24m lan‐
     guage  and  a  renderer  that directly parses its markup as well as that of
     [4mman[24m.

     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\, ]8;;man:man(1)\[4mman[24m(1)]8;;\, ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\, ]8;;man:groff_man(7)\[4mgroff_man[24m(7)]8;;\, ]8;;man:mdoc(7)\[4mmdoc[24m(7)]8;;\

[1mBugs[0m
     Section 3f has not been added to the header routines.

     ‘.Fn’ needs to have a check to prevent splitting up the line if its  length
     is  too  short.   Occasionally it separates the last parenthesis, and some‐
     times looks ridiculous if output lines are being filled.

     The list and display macros do not do any keeps  and  certainly  should  be
     able to.

     As  of [4mgroff[24m 1.23, ‘Tn’ no longer changes the type size; this functionality
     may return in a future release.

groff 1.24.0                       2026-02-14                      [4mgroff_mdoc[24m(7)
────────────────────────────────────────────────────────────────────────────────
[4mgroff_me[24m(7)             Miscellaneous Information Manual             [4mgroff_me[24m(7)

[1mName[0m
     groff_me - “me” macro package for formatting [4mroff[24m documents

[1mSynopsis[0m
     [1mgroff -me [22m[[4moption[24m ...] [[4mfile[24m ...]
     [1mgroff -m me [22m[[4moption[24m ...] [[4mfile[24m ...]

[1mDescription[0m
     The GNU implementation of the [4mme[24m macro package is part of the  [4mgroff[24m  docu‐
     ment  formatting  system.  The [4mme[24m package of macro definitions for the [4mroff[0m
     language provides a convenient facility for preparing technical  papers  in
     various  formats.   This version is based on the [4mme[24m distributed with 4.4BSD
     and can be used with the GNU [4mtroff[24m formatter as  well  as  those  descended
     from AT&T [4mtroff[24m.

     Some  formatter requests affect page layout unpredictably when used in con‐
     junction with this package; however, the following may  be  used  with  im‐
     punity  after  the  first call to a paragraphing macro like [1mlp [22mor [1mpp[22m.  Some
     arguments are optional; see ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\ for details, particularly of  requests
     whose  argument  list  is designated with an ellipsis.  An asterisk [1m* [22mmarks
     [4mgroff[24m extensions.

     [1mad [4m[22mc[24m       set text adjustment mode to [4mc[0m
     [1maf [4m[22mr[24m [4mf[24m     assign format [4mf[24m to register [4mr[0m
     [1mam [4m[22mm[24m [4me[24m     append to macro [4mm[24m until [4me[24m called
     [1mas [4m[22ms[24m [4mt[24m     append rest of line [4mt[24m to string [4ms[0m
     [1mbp [4m[22mn[24m       begin new page numbered [4mn[0m
     [1mbr         [22mbreak output line
     [1mce [4m[22mn[24m       center next [4mn[24m productive input lines
     [1mcp [4m[22mn[24m       en-/disable AT&T [4mtroff[24m compatibility mode[1m*[0m
     [1mde [4m[22mm[24m [4me[24m     define macro [4mm[24m until [4me[24m called
     [1mdo [4m[22mt[24m       interpret input [4mt[24m with compatibility mode off[1m*[0m
     [1mds [4m[22ms[24m [4mt[24m     define rest of line [4mt[24m as string [4ms[0m
     [1mel [4m[22mt[24m       interpret [4mt[24m if corresponding [1mie[22m's [4mp[24m false
     [1mfc [4m[22mc[24m [4md[24m     set field delimiter [4mc[24m and padding glyph [4md[0m
     [1mfi         [22menable filling
     [1mhc [4m[22mc[24m       set hyphenation character to [4mc[0m
     [1mhy [4m[22mm[24m       set automatic hyphenation mode to [4mm[0m
     [1mie [4m[22mp[24m [4mt[24m     as [1mif[22m, but enable interpretation of later [1mel[0m
     [1mif [4m[22mp[24m [4mt[24m     if condition [4mp[24m, interpret rest of line [4mt[0m
     [1min [4m[22mh[24m       set indentation to distance [4mh[0m
     [1mlc [4m[22mc[24m       set leader repetition glyph to [4mc[0m
     [1mls [4m[22mn[24m       set line spacing to [4mn[0m
     [1mmc [4m[22mc[24m [4mh[24m     set (right) margin glyph to [4mc[24m at distance [4mh[0m
     [1mmk [4m[22mr[24m       mark vertical position in register [4mr[0m
     [1mna         [22mdisable adjustment of text
     [1mne [4m[22mv[24m       need vertical space of distance [4mv[0m
     [1mnf         [22mdisable filling
     [1mnh         [22mdisable automatic hyphenation
     [1mnr [4m[22mr[24m [4mn[24m [4mi[24m   assign register [4mr[24m value [4mn[24m with auto-increment [4mi[0m
     [1mns         [22mbegin no-space mode
     [1mpl [4m[22mv[24m       set page length to [4mv[0m
     [1mpn [4m[22mn[24m       set next page number to [4mn[0m
     [1mpo [4m[22mh[24m       set page offset to [4mh[0m
     [1mrj [4m[22mn[24m       right-align next [4mn[24m productive input lines[1m*[0m
     [1mrm [4m[22mm[24m       remove macro, string, or request [4mm[0m
     [1mrn [4m[22mm[24m [4mn[24m     rename macro, string, or request [4mm[24m to [4mn[0m
     [1mrr [4m[22mr[24m       remove register [4mr[0m
     [1mrs         [22mresume spacing (end no-space mode)
     [1mrt [4m[22mv[24m       return to vertical position set by [1mmk[22m, or [4mv[0m
     [1mso [4m[22mf[24m       source (interpolate) input file [4mf[0m
     [1msp [4m[22mn[24m       insert [4mn[24m lines of vertical space
     [1mta [22m...     set tab stops
     [1mtc [4m[22mc[24m       set tab repetition glyph to [4mc[0m
     [1mti [4m[22mh[24m       set temporary indentation (next line only) to [4mh[0m
     [1mtl [22m...     output three-part title
     [1mtr [22m...     translate characters
     [1mul [4m[22mn[24m       underline next [4mn[24m productive input lines

     Except on title pages (produced by calling [1mtp[22m), [4mme[24m suppresses the output of
     vertical space at the tops of pages (after the output of any page  header);
     the  [1msp  [22mrequest  thus does not work there.  You can instead call [1mbl [22mor en‐
     close the desired spacing request in a diversion, for instance  by  calling
     [1m(b  [22mand  [1m)b[22m.  [4mme[24m also intercepts the [1mll [22mrequest; see the “[4mme[24m Reference Man‐
     ual” for details.

   [1mName space[0m
     Objects in [4mme[24m follow a rigid naming convention.   To  avoid  conflict,  any
     user-defined  register, string, or macro names should be single numerals or
     uppercase letters, or any longer sequence of letters and numerals  with  at
     least  one  uppercase  letter.   (For portability between BSD and [4mgroff[24m [4mme[24m,
     limit names to two characters, and avoid the name [1m[ [22m(left square bracket).)
     The names employed by any preprocessors in use should also  not  be  repur‐
     posed.

   [1mMacros[0m
     [1m$0   [22mpost-section heading hook
     [1m$1   [22mpre-section depth 1 hook
     [1m$2   [22mpre-section depth 2 hook
     [1m$3   [22mpre-section depth 3 hook
     [1m$4   [22mpre-section depth 4 hook
     [1m$5   [22mpre-section depth 5 hook
     [1m$6   [22mpre-section depth 6 hook
     [1m$C   [22mpost-chapter title hook
     [1m$H   [22mpage/column heading hook
     [1m$c   [22moutput chapter number and title
     [1m$f   [22moutput footer
     [1m$h   [22moutput header
     [1m$p   [22moutput section heading
     [1m$s   [22moutput footnote area separator
     [1m(b   [22mbegin block
     [1m(c   [22mbegin centered block
     [1m(d   [22mbegin delayed text
     [1m(f   [22mbegin footnote
     [1m(l   [22mbegin list
     [1m(q   [22mbegin long quotation
     [1m(x   [22mbegin index entry
     [1m(z   [22mbegin floating keep
     [1m)b   [22mend block
     [1m)c   [22mend centered block
     [1m)d   [22mend delayed text
     [1m)f   [22mend footnote
     [1m)l   [22mend list
     [1m)q   [22mend long quotation
     [1m)x   [22mend index entry
     [1m)z   [22mend floating keep
     [1m++   [22mset document segment type
     [1m+c   [22mbegin chapter
     [1m1c   [22mend multi-column layout
     [1m2c   [22mbegin multi-column layout
     [1mEN   [22mend [4meqn[24m equation
     [1mEQ   [22mbegin [4meqn[24m equation
     [1mGE   [22mend [4mgrn[24m picture with drawing position at bottom
     [1mGF   [22mend [4mgrn[24m picture with drawing position at top
     [1mGS   [22mstart [4mgrn[24m picture
     [1mIE   [22mend [4mideal[24m picture with drawing position at bottom
     [1mIF   [22mend [4mideal[24m picture with drawing position at top
     [1mIS   [22mstart [4mideal[24m picture
     [1mPE   [22mend [4mpic[24m picture with drawing position at bottom
     [1mPF   [22mend [4mpic[24m picture with drawing position at top
     [1mPS   [22mstart [4mpic[24m picture
     [1mTE   [22mend [4mtbl[24m table
     [1mTH   [22mend heading for multi-page [4mtbl[24m table
     [1mTS   [22mstart [4mtbl[24m table
     [1mb    [22membolden argument
     [1mba   [22mset base indentation
     [1mbc   [22mbegin new column
     [1mbi   [22membolden and italicize argument
     [1mbx   [22mbox argument
     [1mef   [22mset even-numbered page footer
     [1meh   [22mset even-numbered page header
     [1mep   [22mend page
     [1mfo   [22mset footer
     [1mhe   [22mset header
     [1mhl   [22mdraw horizontal line
     [1mhx   [22msuppress next page's headers/footers
     [1mi    [22mitalicize argument
     [1mip   [22mbegin indented paragraph
     [1mld   [22mreset localization and date registers and strings[1m*[0m
     [1mll   [22mset line length
     [1mlp   [22mbegin fully left-aligned paragraph
     [1mnp   [22mbegin numbered paragraph
     [1mof   [22mset odd-numbered page footer
     [1moh   [22mset odd-numbered page header
     [1mpd   [22moutput delayed text
     [1mpp   [22mbegin first-line indented paragraph
     [1mq    [22mquote argument
     [1mr    [22mset argument in roman
     [1mre   [22mreset tab stops
     [1msh   [22mbegin numbered section
     [1msm   [22mset argument at smaller type size
     [1msx   [22mchange section depth
     [1msz   [22mset type size and vertical spacing
     [1mtp   [22mbegin title page
     [1mu    [22munderline argument
     [1muh   [22mbegin unnumbered section
     [1mxl   [22mset line length (current environment only)
     [1mxp   [22moutput index

     Some  macros  are provided for “old” ]8;;man:roff(1)\[4mroff[24m(1)]8;;\ compatibility.  The “[4mme[24m Refer‐
     ence Manual” describes alternatives for modern documents.

     [1mar   [22muse Arabic numerals for page numbers
     [1mbl   [22minsert space (even at page top; cf. [1msp[22m)
     [1mix   [22mset indentation without break
     [1mm1   [22mset page top to header distance
     [1mm2   [22mset header to text distance
     [1mm3   [22mset text to footer distance
     [1mm4   [22mset footer to page bottom distance
     [1mn1   [22mbegin output line numbering
     [1mn2   [22mend or alter output line numbering
     [1mpa   [22mbegin page
     [1mro   [22muse Roman numerals for page numbers
     [1msk   [22mskip next page

   [1mRegisters[0m
     [1m$0   [22msection depth
     [1m$1   [22mfirst section number component
     [1m$2   [22msecond section number component
     [1m$3   [22mthird section number component
     [1m$4   [22mfourth section number component
     [1m$5   [22mfifth section number component
     [1m$6   [22msixth section number component
     [1m$c   [22mcurrent column number
     [1m$d   [22mdelayed text number
     [1m$f   [22mfootnote number
     [1m$i   [22mparagraph base indentation
     [1m$l   [22mcolumn width
     [1m$m   [22mnumber of available columns
     [1m$p   [22mnumbered paragraph number
     [1m$s   [22mcolumn spacing (indentation)
     [1mbi   [22mdisplay (block) indentation
     [1mbm   [22mdistance from text area to page bottom
     [1mbs   [22mdisplay (block) pre/post space
     [1mbt   [22mblock threshold for keeps
     [1mch   [22mcurrent chapter number
     [1mdf   [22mdisplay font
     [1mdv   [22mvertical spacing of displayed text (as percentage)[1m*[0m
     [1mes   [22mequation pre/post space
     [1mff   [22mfootnote font
     [1mfi   [22mfootnote indentation (first line only)
     [1mfm   [22mfooter margin
     [1mfp   [22mfootnote type size in points
     [1mfs   [22mfootnote prespace
     [1mfu   [22mfootnote undent (right indentation)
     [1mhm   [22mheader margin
     [1mii   [22mindented paragraph indentation
     [1mno   [22mline numbering offset[1m*[0m
     [1mpf   [22mparagraph font
     [1mpi   [22mparagraph indentation
     [1mpo   [22mpage offset
     [1mpp   [22mparagraph type size in points
     [1mps   [22mparagraph prespace
     [1mqi   [22mlong quotation left/right indentation
     [1mqp   [22mlong quotation type size in points
     [1mqs   [22mlong quotation pre/post space
     [1msf   [22msection title font
     [1msi   [22msection indentation per level of depth
     [1mso   [22madditional section title offset
     [1msp   [22msection title type size in points
     [1mss   [22msection prespace
     [1msx   [22msuper/subscript line height increase[1m*[0m
     [1mtf   [22mtitle font
     [1mtm   [22mdistance from page top to text area
     [1mtp   [22mtitle type size in points
     [1mtv   [22mvertical spacing of text (as percentage)[1m*[0m
     [1mxs   [22mindex entry prespace
     [1mxu   [22mindex undent (right indentation)
     [1my2   [22myear of the century[1m*[0m
     [1my4   [22myear[1m*[0m
     [1myr   [22myear minus 1900
     [1mzs   [22mfloating keep pre/post space

   [1mStrings[0m
     [1m#    [22mdelayed text marker
     [1m$n   [22mcatenated section number
     [1m*    [22mfootnote marker
     [1m-    [22mem dash
     [1m<    [22mbegin subscripting
     [1m>    [22mend subscripting
     [1mdw   [22mweekday name
     [1mlq   [22mleft double quotation mark
     [1mmo   [22mmonth name
     [1mrq   [22mright double quotation mark
     [1mtd   [22mdate
     [1mwa   [22mterm for “appendix” used by [1m.$c*[0m
     [1mwc   [22mterm for “chapter” used by [1m.$c*[0m
     [1m{    [22mbegin superscripting
     [1m}    [22mend superscripting

[1mFiles[0m
     [4m/usr/share/groff/1.24.0/tmac/e.tmac[0m
            implements the package.

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

     [4m/usr/share/groff/1.24.0/tmac/me.tmac[0m
            is a wrapper enabling the package to be loaded with the  option  “[1m-m[0m
            [1mme[22m”.

[1mNotes[0m
     Some  early  [4mroff[24m  macro  packages  limited their names to a single letter,
     which followed the formatter's [1mm [22moption, resulting  in  “names”  like  [4m-mm[24m,
     [4m-ms[24m, [4m-mv[24m, and [4m-mn[24m.  [4mme[24m's “e” stands for “Eric P. Allman”, the author of the
     original macro package and the technical papers documenting it.

[1mSee also[0m
     Two  manuals  are  available  in source and rendered form.  On your system,
     they may be compressed and/or available in additional formats.

     [4m/usr/share/doc/groff-1.24.0/meintro.me[0m
     [4m/usr/share/doc/groff-1.24.0/meintro.ps[0m
            is “Writing Papers with [4mGroff[24m Using -[4mme[24m”, by Eric P. Allman, adapted
            for [4mgroff[24m by James Clark.

     [4m/usr/share/doc/groff-1.24.0/meref.me[0m
     [4m/usr/share/doc/groff-1.24.0/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.0                       2026-02-14                        [4mgroff_me[24m(7)
────────────────────────────────────────────────────────────────────────────────
[4mgroff_mm[24m(7)             Miscellaneous Information Manual             [4mgroff_mm[24m(7)

[1mName[0m
     groff_mm - memorandum macros for GNU [4mroff[0m

[1mSynopsis[0m
     [1mgroff -mm [22m[[4moption[24m ...] [[4mfile[24m ...]
     [1mgroff -m mm [22m[[4moption[24m ...] [[4mfile[24m ...]

[1mDescription[0m
     The [4mmm[24m macro package distributed with the [4mgroff[24m document formatting  system
     is suitable for the composition of letters, memoranda, reports, and books.

     Call  an [4mmm[24m macro at the beginning of a document to initialize the package.
     A simple [4mmm[24m document might use only [1mP [22mfor paragraphing.  Set  numbered  and
     unnumbered  section headings with [1mH [22mand [1mHU[22m, respectively.  Change the style
     of the typeface with [1mB[22m, [1mI[22m, and [1mR[22m; you can alternate styles  within  a  word
     with [1mBI[22m, [1mBR[22m, [1mIB[22m, [1mIR[22m, [1mRB[22m, and [1mRI[22m.  Several nestable list types are available
     via  [1mAL[22m, [1mBL[22m, [1mBVL[22m, [1mDL[22m, [1mML[22m, [1mRL[22m, and [1mVL[22m; each of these begins a list, to which
     [1mLI [22madds an item and [1mLE [22mends the (nested) list.  [1mLB [22mbegins a list with  cus‐
     tomizable layout parameters.  [1mDS [22mand [1mDF [22mstart static and floating displays,
     respectively; [1mDE [22mterminates either.

     [4mgroff[24m  [4mmm[24m  is intended to be compatible with the [4mmm[24m implementation found in
     the AT&T Documenter's Workbench 3.3 (“DWB”), with the following limitations
     and changes.

     •  Omitted features include the logo and company name strings, [1m}Z  [22mand  [1m]S[22m,
        respectively;  the encoded company site location addresses recognized as
        the third argument to the [1mAU [22mmacro; the [1mPv [22m(“private” heading) register;
        and the [1mOK [22m(other keywords) and [1mPM [22m(proprietary markings) macros.

     •  [4mgroff[24m [4mmm[24m implements the [1mCS [22m(output cover page or “sheet”) macro only for
        memorandum type 4.

     •  The [4mgrap[24m preprocessor is not explicitly supported; [4mgroff[24m [4mmm[24m  defines  no
        [1mG1 [22mor [1mG2 [22mmacros.

     •  Registers [1mA[22m, [1mC[22m, [1mT[22m, and [1mU[22m, set from the [4mtroff[24m or [4mnroff[24m command lines with
        DWB, are not recognized.

     •  When setting the registers [1mL [22mor [1mW [22mfrom the command line, use an explicit
        scaling unit to avoid surprises.

     •  The  [1mLe [22mregister defaults to [1m1[22m, consistently with [1mLf[22m, [1mLt[22m, and [1mLx [22min DWB;
        equations captioned with [1mEC [22mappear in tables of contents produced by [1mTC[22m.

     •  The [1mLi [22mregister configures the text indentation of [1mRL  [22mlist  items;  DWB
        used a hard-coded value of 6 ens.

     •  [4mgroff[24m  [4mmm[24m  uses the same adjustment and font style defaults in [4mnroff[24m and
        [4mtroff[24m modes.

     •  Cut marks are not supported.

     DWB supported only seven heading levels.  As a compatible extension,  [4mgroff[0m
     [4mmm[24m supports fourteen, introducing new registers [1mH8 [22mthrough [1mH14[22m, and affect‐
     ing the interpretation of the [1mHF [22mand [1mHP [22mstrings.

     [4mgroff[24m  [4mmm[24m  features a citation (or “bookmark”) system, permitting the docu‐
     ment to make (customizable) internal references like “See chapter  5,  page
     128.”.   Forward  references  require  two-pass  formatting.  See the [1mINITR[0m
     macro description below and ]8;;man:mmroff(1)\[4mmmroff[24m(1)]8;;\.

     Macro, register, and string descriptions in this  page  frequently  mention
     each  other;  most references are to macros.  Where a register or string is
     referenced, its type is explicitly identified.  [4mmm[24m's macro names  are  usu‐
     ally in full capitals; registers and strings tend to have mixed-case names.

     Except where noted, [4mmm[24m assumes that horizontal measurements are reckoned in
     ens  (scaling unit [1mn[22m) and vertical ones in vees (scaling unit [1mv[22m).  [4mgroff[24m [4mmm[0m
     permits use of non-integral [4mtypographical[24m [4mpoints[24m (scaling unit [1mz[22m).  Use ex‐
     plicit scaling units for clarity and predictable behavior.

   [1mDocument styles[0m
     [4mgroff[24m [4mmm[24m offers three frameworks for document  organization.   [1mCOVER[22m/[1mCOVEND[0m
     is  a  flexible  means  of  preparing  any document requiring a cover page.
     [1mLT[22m/[1mLO [22maids preparation of typical Anglophone correspondence (business  let‐
     ters, for example).  The [1mMT [22mmemorandum type mechanism implements a group of
     formal  styles  historically used by AT&T Bell Laboratories.  Your document
     can select at most one of these approaches; when used,  each  disables  the
     others.

   [1mLocalization[0m
     [4mgroff[24m [4mmm[24m is designed to be easily localized.  For languages other than Eng‐
     lish,  strings  that  can  appear in output are collected in the file [4m/usr/[0m
     [4mshare/groff/1.24.0/tmac/[24mxx[4m.tmac[24m, where [4mxx[24m is an ISO 639 two-letter language
     identifier.  Localization packages should be loaded after [4mmm[24m; for  example,
     you might format a Swedish [4mmm[24m document with the command “[1mgroff -mm -msv[22m”.

     This package can also be localized by site or territory; for example, [4m/usr/[0m
     [4mshare/groff/1.24.0/tmac/mse.tmac[24m  illustrates  how to adapt the output to a
     national standard using its ISO 3166 territory code.  Such  a  package  can
     define  a  string that causes a macro file [4m/usr/share/groff/1.24.0/tmac/mm/[0m
     territory[4m_locale[24m to be loaded at package initialization.  If this mechanism
     is not used, [4m/usr/share/groff/1.24.0/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).  Select a different one by invoking [4mgroff[24m's [1mfam [22mre‐
     quest or using its [1m-f [22mcommand-line option.

[1mMacros[0m
     Double-quote macro arguments that contain space characters.  An  explicitly
     empty  argument  may  be specified with an empty pair of double quotes; for
     example, the following macro call has three arguments.

            .XX "foo bar" "" baz

     Some macros are documented as causing a page break; this does not occur  if
     such a macro is called when the drawing position is already at the top of a
     page (after a page heading, if any).

     [4mHook[24m macros are undefined by default; [4mmm[24m calls them to enable customization
     of its behavior.  (DWB termed these “exits”.)

     Macro  names  longer than two characters are extensions; some shorter names
     were not part of DWB's published interface but are  documented  aspects  of
     [4mgroff[24m [4mmm.[0m

     [1m1C [22m[[1m1[22m]  Format  page  text in one column (the default layout).  The page is
             broken.  A [1m1 [22margument suppresses this break; its use may cause body
             text and a pending footnote to overprint.  See [1m2C[22m, [1mMC[22m, and [1mNCOL[22m.

     [1m2C      [22mBegin two-column formatting.  This is a special case of [1mMC[22m.  See [1m1C[0m
             and [1mNCOL[22m.

     [1mAE      [22mAbstract end; stop collecting abstract text.  See [1mAS[22m.

     [1mAF [22m[[4morg-name[24m]
             Specify a memorandum's organizational affiliation.  At most one can
             be declared; [4morg-name[24m is used by  [1mMT  [22mmemoranda  and  available  to
             cover pages.  See [1mCOVER[22m.

     [1mAFX     [22mDefine  this hook macro to assume responsibility for formatting the
             affiliated firm name defined by [1mAF [22min memorandum types 0 and 4  and
             documents  using  the [4mms[24m cover page style.  If not defined (the de‐
             fault), internally defined macros handle this task; see  subsection
             “Internals”  and  section “Files” below.  Applications include set‐
             ting the firm name in a different font family or at a  larger  type
             size,  drawing  a  rule across the page, and including a logo image
             using  [4mgroff[24m's  [1mPDFPIC  [22mor  [1mPSPIC  [22mmacros.   See  [1mMT[22m,  [1mCOVER[22m,   and
             ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\.

     [1mAL [22m[[4mnumber-format[24m [[4mtext-indent[24m [[1m1[22m]]]
             Begin  an auto-incrementing numbered list, where item numbers start
             at one and are followed by a dot.  [4mnumber-format[24m assigns the regis‐
             ter format (see above) [4mmm[24m uses for the list item enumerators.   The
             default  is  [1m0[22m.   A  [4mtext-indent[24m argument overrides register [1mLi[22m.  A
             third argument suppresses the vertical space that normally precedes
             each list item; see register [1mLsp[22m.  Vertical space in the amount  of
             [1mLsp [22mprecedes the list itself, but does not accumulate with pre-item
             space  when this list is nested in another.  [1mAL [22mcalls [1mLB[22m; use [1mLI [22mto
             declare list items, and [1mLE [22mto end the list.

     [1mAPP [22m[[4msequence-number[24m [[4mtitle[24m]]
             Begin an appendix.  If [4msequence-number[24m is  omitted,  it  increments
             (or  is  initialized to [1m1[22m, if necessary).  The register format used
             for [4msequence-number[24m is “A”.  The page is broken.  The register  [1mAph[0m
             determines  whether  an  appendix  heading is then formatted.  This
             heading uses the string [1mApp [22mfollowed  by  [4msequence-number[24m.   Appen‐
             dices  appear in any table of contents (see [1mTC[22m).  The string [1mApptxt[0m
             is set to [4mtitle[24m if the latter is present, and made empty otherwise.

     [1mAPPSK [4m[22msequence-number[24m [4mn[24m [[4mtitle[24m]
             As [1mAPP[22m, but increment the page number by  [4mn[24m.   Use  this  macro  to
             “skip  pages”  when  diagrams  or  other materials not formatted by
             [4mtroff[24m are included in appendices.

     [1mAS [22m[[4mplacement[24m [[4mindentation[24m]]
             Abstract start; begin collecting abstract.  Input up to the next [1mAE[0m
             call is included in the abstract.  [4mplacement[24m influences  the  loca‐
             tion  of  the  abstract on the cover page of a memorandum (see [1mMT[22m).
             [1mCOVER[22m, by contrast, ignores [4mplacement[24m by default, but can  be  cus‐
             tomized to interpret it.

             [4m[1mplacement[24m   Effect[0m
             0           The  abstract  appears  on page 1 and cover page if the
                         document is a “released paper”  memorandum  (“[1m.MT  4[22m”);
                         otherwise, it appears on page 1 without a cover page.
             1           The  abstract  appears  only on the cover page (“[1m.MT 4[22m”
                         only).

             An abstract does not appear at all in external letters  (“[1m.MT  5[22m”).
             A [4mplacement[24m of [1m2 [22mwas supported by DWB, but is not by [4mgroff[24m [4mmm[24m.

             A  second argument increases the indentation by [4mindentation[24m and re‐
             duces the line length by twice this amount.  The default is [1m0[22m.

     [1mAT [4m[22mtitle[24m ...
             Specify author's title(s).  If present, [1mAT [22mmust appear  just  after
             the  corresponding author's [1mAU[22m.  Each [4mtitle[24m occupies an output line
             beneath the author's name in the signature block used by [1mLT [22mletters
             (see [1mSG[22m) and in [1mMT [22mmemoranda.  The [4mms[24m cover page style also formats
             these data.

     [1mAU [22m[[4mname[24m [[4minitials[24m [[4mloc[24m [[4mdept[24m [[4mext[24m [[4mroom[24m [[4marg1[24m [[4marg2[24m [[4marg3[24m]]]]]]]]]
             Specify author.  [1mAU [22mterminates a document title  started  with  [1mTL[22m,
             and  can  be called without arguments for that purpose.  Author in‐
             formation is used by cover pages, [1mMT [22mmemoranda,  and  [1mSG[22m.   Further
             arguments comprise initials, location, department, telephone exten‐
             sion,  room  number or name, and up to three additional items.  Re‐
             peat [1mAU [22mto identify multiple authors.

             Use [1mWA[22m/[1mWE [22minstead to identify the author  for  documents  employing
             [1mLT[22m.

     [1mAV [22m[[4mname[24m [[1m1[22m]]
             Format  approval  lines  for a handwritten signature and date.  Two
             horizontal rules are drawn, with the specified [4mname[24m and the text of
             the string [1mLetdate[22m, respectively, beneath them.  Above these rules,
             [4mmm[24m formats the text in the string [1mLetapp[22m;  a  second  argument  re‐
             places this text with one vee of vertical space.  See [1mLT[22m.

     [1mAVL [22m[[4mname[24m]
             As  [1mAV[22m, but omitting the approval notation (the [1mLetapp [22mstring), the
             date rule, and the label below the date rule (the [1mLetdate [22mstring).

     [1mB [22m[[4mbold-text[24m [[4mprevious-font-text[24m]] ...
             Join [4mbold-text[24m in boldface with [4mprevious-font-text[24m in the  previous
             font, without space between the arguments.  If no arguments, switch
             font to bold style.

     [1mB1      [22mBegin  boxed  static  display.  The text is indented by [1m1n[22m, and the
             line length reduced by [1m2n[22m.  See [1mDS[22m.  This is a [4mgroff[24m [4mmm[24m extension.

     [1mB2      [22mEnd boxed static display.  See [1mB1[22m.  This is a [4mgroff[24m [4mmm[24m extension.

     [1mBE      [22mEnd bottom block; see [1mBS[22m.

     [1mBI [22m[[4mbold-text[24m [[4mitalic-text[24m]] ...
             Join [4mbold-text[24m in boldface with  [4mitalic-text[24m  in  italics,  without
             space between the arguments.

     [1mBL [22m[[4mtext-indent[24m [[1m1[22m]]
             Begin  bulleted  list.   [4mmm[24m  marks each item with the string [1mBU[22m.  A
             [4mtext-indent[24m argument overrides register [1mPi[22m.  A second argument sup‐
             presses the vertical space that normally precedes each  list  item;
             see register [1mLsp[22m.  Vertical space in the amount of [1mLsp [22mprecedes the
             list  itself, but does not accumulate with pre-item space when this
             list is nested in another.  [1mBL [22mcalls [1mLB[22m; use  [1mLI  [22mto  declare  list
             items, and [1mLE [22mto end the list.

     [1mBR [22m[[4mbold-text[24m [[4mroman-text[24m]] ...
             Join  [4mbold-text[24m in boldface with [4mroman-text[24m in roman style, without
             space between the arguments.

     [1mBS      [22mBegin bottom block.  [4mmm[24m collects input into the bottom block  until
             the document calls [1mBE[22m, and outputs it between the footnote area and
             footer of each page.

     [1mBVL [22m[[4mtext-indent[24m [[4mmark-indent[24m [[1m1[22m]]]
             Begin  broken  variable-item  (or “tagged”) list.  Each item should
             supply its own mark.  The line is always  broken  after  the  mark;
             contrast  [1mVL[22m.   A [4mtext-indent[24m argument overrides register [1mPi[22m; [4mmark-[0m
             [4mindent[24m sets the distance from the indentation of the  current  list
             to  the  mark.  A third argument suppresses the vertical space that
             normally precedes each list item; see register [1mLsp[22m.  Vertical space
             in the amount of [1mLsp [22mprecedes the list itself, but does not accumu‐
             late with pre-item space when this list is nested in another.   [1mBVL[0m
             calls [1mLB[22m; use [1mLI [22mto declare list items, and [1mLE [22mto end the list.

     [1mCOVER [22m[[4mstyle[24m]
             Begin  a cover page description.  [1mCOVER [22mmust appear before the body
             text (or main matter) of a document.  The argument [4mstyle[24m is used to
             construct the file  name  [4m/usr/share/groff/1.24.0/tmac/mm/[24mstyle[4m.cov[0m
             and  load  it with the [1mmso [22mrequest.  The default [4mstyle[24m is “[1mms[22m”; the
             [4mms.cov[24m file prepares a cover page resembling that of the  [4mms[24m  pack‐
             age.  A [4m.cov[24m file must define a [1mCOVEND [22mmacro, which a document must
             call  at  the  end of the cover description.  Use cover description
             macros in the following order; only [1mTL [22mand [1mAU [22mare required.

             .COVER
             .AF
             .TL
             .AU
             .AT
             .\" Add additional AU and AT calls as needed.
             .AS
             .AE
             .COVEND

     [1mCOVEND  [22mEnd the cover description.

     [1mDE      [22mEnd static or floating display begun with [1mDS [22mor [1mDF[22m.

     [1mDF [22m[[4mformat[24m [[4mfill[24m [[4mright-indentation[24m]]]
             Begin floating display.  A floating display is saved in a queue and
             output in the order entered.   Arguments  are  handled  as  in  [1mDS[22m.
             Floating displays cannot be nested.  Placement of floating displays
             is controlled by the registers [1mDe [22mand [1mDf[22m.

     [1mDL [22m[[4mtext-indent[24m [[1m1[22m]]
             Begin dashed list.  [4mmm[24m marks each item with the string [1mEM[22m.  A [4mtext-[0m
             [4mindent[24m  argument  overrides  register  [1mPi[22m.   A second argument sup‐
             presses the vertical space that normally precedes each  list  item;
             see register [1mLsp[22m.  Vertical space in the amount of [1mLsp [22mprecedes the
             list  itself, but does not accumulate with pre-item space when this
             list is nested in another.  [1mDL [22mcalls [1mLB[22m; use  [1mLI  [22mto  declare  list
             items, and [1mLE [22mto end the list.

     [1mDS [22m[[4mformat[24m [[4mfill[24m [[4mright-indentation[24m]]]
             Begin  static  display.  [4mmm[24m collects input into a display until the
             document calls [1mDE[22m.  The display is output on a single  page  unless
             it  is  taller than the height of the page.  [1mDS [22mcan be nested (con‐
             trast with [1mDF[22m).

             [4m[1mformat[24m   Effect[0m
             [4mnone[24m     Do not indent the display.
             L        Do not indent the display.
             I        Indent text by [1m\n[Si][22m.
             C        Center each line.
             CB       Center the whole display as a block.
             R        Right-align each line.
             RB       Right-align the whole display as a block.

             The values “L”, “I”, “C”, and “CB” can also be  specified  as  “0”,
             “1”, “2”, and “3”, respectively, for compatibility with DWB.

             [4m[1mfill[24m   Effect[0m
             [4mnone[24m   Disable filling.
             N      Disable filling.
             F      Enable filling.

             “N” and “F” can also be specified as “0” and “1”, respectively, for
             compatibility with DWB.

             A third argument reduces the line length by [4mright-indentation.[0m

             [4mmm[24m  normally  places  vertical  space before and after the display.
             Set register [1mDs [22mto “0” to suppress it.

     [1mEC [22m[[4mtitle[24m [[4moverride[24m [[4mflag[24m [[4mref-name[24m]]]]
             Caption an equation.  A caption comprises the string [1mCapec [22mfollowed
             by an automatically incrementing counter stored in the register [1mEc[22m,
             punctuation configured by the register [1mOf[22m,  then  [4mtitle[24m  (if  any).
             Use  the  [1maf [22mrequest to configure [1mEc[22m's number format.  [4moverride[24m and
             [4mflag[24m alter the equation number as follows.  Omitting [4mflag[24m and spec‐
             ifying [1m0 [22min its place are equivalent.

             [4m[1mflag[24m   Effect[0m
             0      Prefix number with [4moverride[24m.
             1      Suffix number with [4moverride[24m.
             2      Replace number with [4moverride[24m.

             [4mmm[24m centers equation captions irrespective of the alignment  of  any
             enclosing display.

             Specifying [4mref-name[24m stores the equation number as if by “[1m.SETR [4m[22mref-[0m
             [4mname[24m  [1m\n[Ec][22m”.   Recognition  of this argument is a [4mgroff[24m [4mmm[24m exten‐
             sion.

             The package lists captioned equations in a table of  contents  (see
             [1mTC[22m)  if  the  Boolean  register [1mLe [22mis true.  The string [1mLe [22mcaptions
             this list.

     [1mEF [22m[[1m"'[4m[22mleft[24m[1m'[4m[22mcenter[24m[1m'[4m[22mright[24m[1m'"[22m]
             Define the even-page footer, which is formatted just above the nor‐
             mal page footer on even-numbered pages.  See [1mPF[22m.   [1mEF  [22mdefines  the
             string [1mEOPef[22m.

     [1mEH [22m[[1m"'[4m[22mleft[24m[1m'[4m[22mcenter[24m[1m'[4m[22mright[24m[1m'"[22m]
             Define the even-page header, which is formatted just below the nor‐
             mal  page  header  on even-numbered pages.  See [1mPH[22m.  [1mEH [22mdefines the
             string [1mTPeh[22m.

     [1mEN      [22mEnd mathematical expression input preprocessed by ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\; see [1mEQ[22m.

     [1mEOP     [4m[22mgroff[24m [4mmm[24m calls this hook macro in lieu of normal page  footer  lay‐
             out.  The package uses a separate environment to format headers and
             footers.  See [1mTP[22m.

             [1mStrings available to EOP[0m
             ─────────────────────────
             [1mEOPf     [22margument to [1mPF[0m
             [1mEOPef    [22margument to [1mEF[0m
             [1mEOPof    [22margument to [1mOF[0m

     [1mEPIC [22m[[1m-L[22m] [4mwidth[24m [4mheight[24m [[4mname[24m]
             Draw  a box with the given [4mwidth[24m and [4mheight[24m.  The text [4mname[24m (or de‐
             fault text) is formatted inside the box; no attempt is made to size
             the box to fit the text.  An application of this macro is to  indi‐
             cate  the  placement  of an image to be determined later, or exter‐
             nally composited in postprocessing.  [1m-L [22mas the first argument left-
             aligns the box; the default is to center it.  See [1mPIC[22m.

     [1mEQ [22m[[4mlabel[24m]
             Start mathematical expression input preprocessed by ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\.  [1mEQ [22mand
             [1mEN [22mmacro calls bracket an equation region.  Such  regions  must  be
             contained  in displays ([1mDS[22m/[1mDE[22m), except when the region is used only
             to configure [4meqn[24m and not to produce output.  If present, [4mlabel[24m  ap‐
             pears  aligned to the right and centered vertically within the dis‐
             play; see register [1mEq[22m.  If multiple [4meqn[24m regions occur within a dis‐
             play, only the last [4mlabel[24m (if any) is used.

     [1mEX [22m[[4mtitle[24m [[4moverride[24m [[4mflag[24m [[4mref-name[24m]]]]
             Caption an exhibit.  Arguments are handled analogously to [1mEC[22m.   The
             register  [1mEx [22mis the exhibit counter.  The string [1mCapex [22mprecedes the
             exhibit number and any [4mtitle.[24m  [4mmm[24m centers  exhibit  captions  irre‐
             spective of the alignment of any enclosing display.

             The  package  lists  captioned exhibits in a table of contents (see
             [1mTC[22m) if the Boolean register [1mLx [22mis true.   The  string  [1mLx  [22mcaptions
             this list.

     [1mFC [22m[[4mclosing-text[24m]
             Output the string [1mLetfc[22m, or the specified [4mclosing-text,[24m as the for‐
             mal closing of a letter or memorandum.  See [1mLT [22mand [1mMT[22m.

     [1mFD [22m[[4marg[24m [[1m1[22m]]
             Configure display of footnotes.  The first argument encodes enable‐
             ment of automatic hyphenation, adjustment to both margins, indenta‐
             tion  of  footnote text, and left- vs. right-alignment of the foot‐
             note label within the space allocated for it.

             [4m[1marg[24m   Hyphenate?   Adjust?   Indent?   Label alignment[0m
             0     no           yes       yes       left
             1     yes          yes       yes       left
             2     no           no        yes       left
             3     yes          no        yes       left
             4     no           yes       no        left
             5     yes          yes       no        left
             6     no           no        no        left
             7     yes          no        no        left
             8     no           yes       yes       right
             9     yes          yes       yes       right
             10    no           no        yes       right
             11    yes          no        yes       right

             An [4marg[24m greater than 11 is treated as [1m0[22m.  [4mmm[24m's default is [1m0[22m.

             A second argument resets  footnote  numbering  when  a  first-level
             heading is encountered.  See [1mFS[22m.

     [1mFE      [22mEnd footnote; see [1mFS[22m.

     [1mFG [22m[[4mtitle[24m [[4moverride[24m [[4mflag[24m [[4mref-name[24m]]]]
             Caption  a  figure.   Arguments are handled analogously to [1mEC[22m.  The
             register [1mFg [22mis the figure counter.  The string [1mCapfg  [22mprecedes  the
             figure  number and any [4mtitle.[24m  [4mmm[24m centers figure captions irrespec‐
             tive of the alignment of any enclosing display.

             The package lists captioned figures in a table of contents (see [1mTC[22m)
             if the Boolean register [1mLf [22mis true.  The string  [1mLf  [22mcaptions  this
             list.

     [1mFS [22m[[4mmark[24m]
             Start  footnote.  [4mmm[24m collects input into a footnote until the docu‐
             ment calls [1mFE[22m, outputting it when  the  vertical  drawing  position
             nears  the page bottom.  By default, [4mmm[24m automatically numbers foot‐
             notes starting at 1; the number is available in register [1mFtnum [22mand,
             with a trailing period, in string [1mF[22m.  If desired, interpolate  this
             string  in  the body text to format the footnote mark.  [4mmm[24m interpo‐
             lates string [1mF [22mprior to the footnote text.   Footnotes  are  verti‐
             cally  separated  by the product of registers [1mFs [22mand [1mLsp[22m.  In [4mgroff[0m
             [4mmm[24m, footnotes may be used in displays.

             A [4mmark[24m argument, which need not be numeric,  replaces  the  default
             footnote  mark, leaving the string [1mF [22munchanged.  In that event, you
             must explicitly write any footnote mark to appear in  the  footnote
             itself.

     [1mGETHN [4m[22mref-name[24m [[4mstring[24m]
             Interpolate  [4mref-name[24m's  heading  mark, or, if [4mstring[24m is specified,
             store it there.  In neither case does [1mGETHN [22msuffix  the  interpola‐
             tion with space.  See [1mINITR[22m.

     [1mGETPN [4m[22mref-name[24m [[4mstring[24m]
             Interpolate  [4mref-name[24m's  page  number,  or, if [4mstring[24m is specified,
             store it there.  In neither case does [1mGETPN [22msuffix  the  interpola‐
             tion with space.  See [1mINITR[22m.

     [1mGETR [4m[22mref-name[0m
             Retrieve location data for reference [4mref-name[24m, call [1mGETHN [22mand [1mGETPN[0m
             to  populate  strings  [1mQrfh [22mand [1mQrfn[22m, respectively, and interpolate
             string [1mQrf [22mas an internal reference to it.  See [1mINITR[22m.

     [1mGETST [4m[22mref-name[24m [[4mstring[24m]
             Interpolate [4mref-name[24m's auxiliary reference datum, or, if [4mstring[24m  is
             specified,  store  it there.  In neither case does [1mGETST [22msuffix the
             interpolation with space.  See [1mINITR[22m.

     [1mH [4m[22mlevel[24m [[4mtitle[24m [[4msuffix[24m]]
             Set a numbered section heading at [4mlevel[24m.  [4mmm[24m calls [1mLC [22mto clear  any
             lists,  then  produces numbered [4mheading[24m [4mmarks[24m of the form [4ma[24m.[4mb[24m.[4mc[24m...,
             with up to fourteen levels of nesting.  Each level's number  incre‐
             ments  automatically  with  each [1mH [22mcall and is reset to zero when a
             more significant [4mlevel[24m is specified.  “[1m1[22m” is the  most  significant
             or coarsest division of the document.  Text after an [1mH [22mcall is for‐
             matted as a paragraph; calling [1mP [22mis unnecessary.

             The optional [4mtitle[24m must be double-quoted if it contains spaces.  [4mmm[0m
             appends  [4msuffix[24m  to [4mtitle[24m in the body of the document, but omits it
             from any table of contents (see [1mTC[22m).  This facility can be used  to
             annotate  the heading title with a footnote.  [4msuffix[24m should not in‐
             terpolate the [1mF [22mstring; specify a footnote  mark  explicitly.   See
             [1mFS[22m.

             Heading  behavior  is  configurable.  Several registers set [4mthresh‐[0m
             [4molds,[24m where heading levels at or below a threshold value  are  han‐
             dled in one way, and those above it another.  For example, [4mmm[24m popu‐
             lates  a  table of contents (see [1mTC[22m) with the title of a heading if
             its level is within the [1mCl [22mregister threshold.

             [4mHeading[24m [4mlayout.[24m  Register [1mEj [22msets a  threshold  for  page  breaking
             (ejection)  prior to a heading.  If not preceded by a page break, a
             heading level within the threshold in register [1mHps [22mis  preceded  by
             the amount of vertical space in register [1mHps1[22m, and by the amount in
             [1mHps2  [22motherwise.  The [1mHb [22mregister sets a threshold at which a break
             occurs after the heading, and register [1mHs [22msets a  threshold  within
             which  vertical  space  follows  it.  If the heading level is above
             both of these, and the paragraph is not  numbered,  [4mmm[24m  produces  a
             [4mrun-in[24m  [4mheading[24m;  paragraph  text  follows on the same output line.
             Otherwise, register [1mHi [22mconfigures the  indentation  of  text  after
             headings.   Threshold  register  [1mHc [22mpermits centering; [4mmm[24m centers a
             heading with a level within both of the [1mHb [22mand [1mHc [22mthresholds.

             [4mHeading[24m [4mtypeface[24m [4mand[24m [4msize.[24m  The [1mHF [22mstring configures the fonts used
             for heading marks and titles at each level.  The string [1mHP [22mlikewise
             assigns a type size to each heading  level.   The  hook  macros  [1mHX[0m
             and/or [1mHZ [22mcan control the vertical spacing used by headings.

             [4mHeading[24m  [4mnumber[24m [4mformat.[24m  Registers named [1mH1 [22mthrough [1mH14 [22mstore coun‐
             ters for each heading level.  Their values are printed using Arabic
             numerals by default; see [1mHM[22m.  The heading levels are catenated with
             dots for formatting; to typeset only the deepest, set the [1mHt [22mregis‐
             ter.  Heading numbers are not suffixed with a trailing  dot  except
             when  only the first level is output; to omit a dot in this case as
             well, clear the [1mH1dot [22mregister.

             [4mCustomizing[24m [4mheading[24m [4mbehavior.[24m  [1mH [22mcalls [1mHX[22m, [1mHY[22m, and [1mHZ  [22mhook  macros
             to further customize headings.  These can change the heading's [4mmark[0m
             (the numbered portion before any heading title), its vertical spac‐
             ing,  and its vertical space requirements (for instance, to require
             a minimum quantity of subsequent output lines on the page, breaking
             the page otherwise).  Define hook macros in expectation of the fol‐
             lowing parameters.  The argument [4mdeclared-level[24m is the [4mlevel[24m  argu‐
             ment  to [1mH[22m, or [1m0 [22mfor unnumbered headings (see [1mHU[22m).  [4mactual-level[24m is
             the same as [4mdeclared-level[24m for numbered headings, and the value  of
             register  [1mHu  [22mfor unnumbered headings.  [4mtitle-suffix[24m is the catena‐
             tion of the corresponding arguments to [1mH [22mor [1mHU[22m.

             [1mHX [4m[22mdeclared-level[24m [4mactual-level[24m [4mtitle-suffix[0m
                    [4mmm[24m calls [1mHX [22mbefore setting the heading.  Your definition may
                    alter [1m}0[22m, [1m}2[22m, and [1m;3[22m.

                    [1m}0 [22m(string)
                           contains the heading mark  plus  two  spaces  if  [4mde‐[0m
                           [4mclared-level[24m is non-zero, and otherwise is empty.

                    [1m;0 [22m(register)
                           encodes  a  position  for the text after the heading.
                           0 means that the heading is to be  run  in,  1  means
                           that a break is to occur before the text, and 2 means
                           that vertical space is to separate heading and text.

                    [1m}2 [22m(string)
                           is  the  suffix  that separates a run-in heading from
                           the text.  It contains  two  spaces  if  register  [1m;0[0m
                           is 0, and otherwise is empty.

                    [1m;3 [22m(register)
                           contains  the vertical space required for the heading
                           to be typeset.  If that amount is not available,  the
                           page  is broken prior to the heading.  The default is
                           [1m2v[22m.

             [1mHY [4m[22mdeclared-level[24m [4mactual-level[24m [4mtitle-suffix[0m
                    [4mmm[24m calls [1mHY [22mafter determining the heading typeface and size.
                    It could be used to change indentation.

             [1mHZ [4m[22mdeclared-level[24m [4mactual-level[24m [4mtitle-suffix[0m
                    [4mmm[24m calls [1mHZ [22mafter formatting the heading, just before  [1mH  [22mor
                    [1mHU  [22mreturns.   It could be used to change the page header to
                    include a section heading.

     [1mHC [22m[[4mhyphenation-character[24m]
             Set hyphenation character, selecting the default, “\%”,  if  called
             without argument.

     [1mHM [22m[[4marg1[24m [[4marg2[24m [... [[4marg14[24m]]]]
             Set  the  heading  mark style.  Each argument assigns the specified
             register format (see above) to  the  corresponding  heading  level.
             The default is [1m1 [22mfor all levels.  An explicitly empty argument also
             indicates the default.

     [1mHU [4m[22mtitle[24m [[4msuffix[24m]
             Set an unnumbered section heading with [4mtitle[24m and, as a [4mgroff[24m [4mmm[24m ex‐
             tension,  an optional [4msuffix.[24m  The heading is treated as a numbered
             heading of the level stored in register [1mHu[22m, but no heading mark  is
             output; see [1mH[22m.

     [1mI [22m[[4mitalic-text[24m [[4mprevious-font-text[24m]] ...
             Join [4mitalic-text[24m in italics with [4mprevious-font-text[24m in the previous
             font, without space between the arguments.  If no arguments, switch
             font to italic style.

     [1mIA [22m[[4mrecipient-name[24m [[4mtitle[24m]]
             Specify  the  inside  address in a letter.  The arguments give each
             recipient a name and title.  [4mmm[24m collects input into the inside  ad‐
             dress  until the document calls [1mIE[22m, then outputs it.  You can spec‐
             ify multiple recipients with empty [1mIA[22m/[1mIE [22mpairs; [4mmm[24m  uses  only  the
             last address.  See [1mLT[22m.

     [1mIB [22m[[4mitalic-text[24m [[4mbold-text[24m]] ...
             Join  [4mitalic-text[24m  in  italics  with [4mbold-text[24m in boldface, without
             space between the arguments.

     [1mIE      [22mEnd the inside address begun with [1mIA[22m.

     [1mIND [4m[22margument[24m ...
             If the Boolean register [1mRef [22mis true, write an index entry as a spe‐
             cially prepared [4mroff[24m comment to the  standard  error  stream,  with
             each  [4margument[24m  separated  from its predecessor by a tab character.
             The entry's location information is arranged as configured  by  the
             most recent [1mINITI [22mcall.

     [1mINDP    [22mOutput  the  index  set up by [1mINITI [22mand populated by [1mIND [22mcalls.  By
             default, [1mINDP [22mcalls [1mSK [22mand writes a centered caption  interpolating
             the  string  [1mIndex[22m.   It then disables filling and calls [1m2C[22m; after‐
             ward, it restores filling and calls [1m1C[22m.

             Define macros to customize this behavior.  [1mINDP [22mcalls [1mTXIND  [22mbefore
             the  caption, [1mTYIND [4m[22minstead[24m of writing the caption, and [1mTZIND [22mafter
             formatting the index.

     [1mINITI [4m[22mlocation-type[24m [4mfile-name[24m [[4mmacro[24m]
             Initialize [4mgroff[24m [4mmm[24m's indexing system.  Argument [4mlocation-type[24m  se‐
             lects  how the location of each index entry is reported.  [4mfile-name[0m
             populates an internal string used later by [1mINDP[22m.

             [4m[1mlocation-type[24m   Entry format[0m
             N               page number
             H               heading mark
             B               page number, tab character, heading mark

             If [4mmacro[24m is specified, [4mgroff[24m [4mmm[24m calls it for each index entry  with
             the arguments given to [1mIND[22m.

     [1mINITR [4m[22mfile-name-prefix[0m
             Initialize  the internal reference macros.  Internal references are
             written to the standard error stream, which  should  be  redirected
             into a file named file-name-prefix[4m.qrf[24m.  ]8;;man:mmroff(1)\[4mmmroff[24m(1)]8;;\ handles this and
             the  two  formatting passes it requires.  The first pass identifies
             internal references; the second includes them.   See  [1mSETR[22m,  [1mGETHN[22m,
             [1mGETPN[22m, and [1mGETST[22m.

     [1mIR [22m[[4mitalic-text[24m [[4mroman-text[24m]] ...
             Join [4mitalic-text[24m in italics with [4mroman-text[24m in roman style, without
             space between the arguments.

     [1mLB [4m[22mtext-indent[24m [4mmark-indent[24m [4mpad[24m [4mtype[24m [[4mmark-or-format[24m [[4mpre-item-space[24m [[4mpre-[0m
     [4mlist-space[24m]]]
             Begin  list.  The macros [1mAL[22m, [1mBL[22m, [1mBVL[22m, [1mDL[22m, [1mML[22m, [1mRL[22m, and [1mVL [22mcall [1mLB [22min
             various ways; they are simpler to use and may be preferred if  they
             suit the desired purpose.

             [4mmm[24m  tracks  the nesting level of lists; the outermost is 0.  It in‐
             dents each list item (text formatted after an [1mLI [22mcall) by  [4mtext-in‐[0m
             [4mdent.[24m   The  mark is left-aligned at [4mmark-indent[24m, and padded on the
             left with [4mpad[24m ens of space.  [4mtype[24m determines the mark's format.

             [4m[1mtype[24m   Output for a mark “x”[0m
             0      x
             1      x.
             2      x)
             3      (x)
             4      [x]
             5      <x>
             6      {x}

             If [4mtype[24m is [1m0[22m, [4mmark-or-format[24m specifies each item's mark (which  can
             be  overridden  by  an argument to [1mLI[22m).  If [4mmark-or-format[24m is empty
             (or the dummy character “[1m\&[22m”) [4mmm[24m sets items at [4mmark-indent[24m  with  a
             hanging indent at [4mtext-indent.[0m

             If  [4mtype[24m  is greater than zero, [4mmm[24m supplies an automatically incre‐
             menting numeric mark, and interprets [4mmark-or-format[24m as  a  register
             format.

             A  [4mtype[24m of [1m-1 [22mcauses [4mgroff[24m [4mmm[24m to break the line after the mark even
             if it fits within [4mtext-indent;[24m this is a [4mgroff[24m [4mmm[24m extension.

             The last two arguments manage  vertical  space.   Unless  a  list's
             nesting  level  is greater than the value of register [1mLs[22m, its items
             are preceded by [4mpre-item-space[24m multiplied by the register [1mLsp[22m;  the
             default is [1m1[22m.  [1mLB [22mprecedes the list by [4mpre-list-space[24m multiplied by
             the register [1mLsp[22m; the default is [1m0[22m.

     [1mLC [22m[[4mlist-level[24m]
             Clear  list  state.  Active lists are terminated as if with [1mLE[22m, ei‐
             ther all (the default) or only those from the current level down to
             [4mlist-level[24m if specified.

     [1mLE [22m[[1m1[22m]  End list.  The current list is terminated.  An argument of [1m1 [22mcauses
             vertical space in the amount of register [1mLsp [22mto follow the list.

     [1mLI [22m[[4mmark[24m [[4mpad-prefix[24m]]
             Begin a list item.  [4mmm[24m collects input into a list  item  until  the
             document  terminates  the  current  list or calls [1mLI [22magain.  By de‐
             fault, the item's text is preceded by any mark  configured  by  the
             current  list.   If [4mmark[24m is the only argument, it replaces the mark
             configured in the corresponding [1mLB [22mcall.  If the width of the  mark
             plus any [4mpad[24m specified in the [1mLB [22mcall exceeds the text indentation,
             [4mgroff[24m  [4mmm[24m warns and uses one en of padding between the mark and the
             text.  The presence of a second argument prefixes [4mmark[24m to  the  [1mLB[22m-
             configured mark and, as a [4mgroff[24m [4mmm[24m extension, conditionally puts an
             unbreakable  space  between  the prefix and mark per the argument's
             Boolean value.

     [1mLO [4m[22moption[24m [[4mvalue[24m]
             Specify letter options; see [1mLT[22m.  By default, [4mmm[24m recognizes the fol‐
             lowing [4moption[24m values.  See [1mIA  [22mregarding  the  inside  address  and
             string [1mDT [22mregarding the date.

             [4m[1moption[24m   Meaning and Effect[0m
             AT       Attention;  put  contents  of string [1mLetAT [22mand [4mvalue[24m left-
                      aligned after the inside address.
             CN       Confidential; put [4mvalue,[24m  or  contents  of  string  [1mLetCN[22m,
                      left-aligned after the date.
             RN       Reference;  put  contents  of string [1mLetRN [22mand [4mvalue[24m after
                      the confidential notation (if any) and the  date,  aligned
                      with the latter.
             SA       Salutation;  put [4mvalue,[24m or contents of string [1mLetSA[22m, left-
                      aligned after the inside address and the confidential  no‐
                      tation (if any).
             SJ       Subject;  put  contents  of  string  [1mLetSJ [22mand [4mvalue[24m left-
                      aligned after the inside address  and  the  attention  and
                      salutation notations (if any).  In letter type “SP”, [1mLetSJ[0m
                      is ignored and [4mvalue[24m is set in full capitals.

     [1mLT [22m[[4mstyle[24m]
             Format  a letter in the designated [4mstyle,[24m defaulting to [1mBL [22m(see be‐
             low).  A letter begins with the writer's address ([1mWA[22m/[1mWE[22m),  followed
             by  the date ([1mND[22m), the inside address ([1mIA[22m/[1mIE[22m), the body of the let‐
             ter ([1mP [22mand other general-purpose [4mmm[24m  macros),  the  formal  closing
             ([1mFC[22m),  the signature ([1mSG[22m), and notations ([1mNS[22m/[1mNE[22m).  Any of these ex‐
             cept the body text may be omitted.  Letter options  specified  with
             [1mLO  [22madd  further  annotations, which are extensible; see subsection
             “Internals” below.

             [4m[1mstyle[24m   Description[0m
             BL      Blocked: the writer's address, date,  formal  closing,  and
                     signature  are  indented to the center of the line.  Every‐
                     thing else is left-aligned.
             SB      Semi-blocked: as [1mBL[22m, but the first line of  each  paragraph
                     is indented by [1m\n[Pi] [22mens.
             FB      Fully blocked: everything is left-aligned.
             SP      Simplified: as [1mFB[22m, but a formal closing is omitted, and the
                     signature is set in full capitals.

     [1mMC [4m[22mcolumn-width[24m [[4mgutter-width[24m]
             Begin  multi-column  layout.   [4mgroff[24m  [4mmm[24m creates as many columns of
             [4mcolumn-width[24m as the line length will permit.  [4mgutter-width[24m  is  the
             interior  spacing between columns.  It defaults to [4mcolumn-width[24m/15.
             [1mNCOL [22mmoves to the next column, and [1m1C [22mreturns to single-column lay‐
             out.  [1mMC [22mis a [4mgroff[24m [4mmm[24m extension, generalizing [1m2C[22m.  See [1mMULB [22mfor an
             alternative.

     [1mML [4m[22mmark[24m [[4mtext-indent[24m [[1m1[22m]]
             Start a [4mmarked[24m [4mlist;[24m the [4mmark[24m argument precedes each  item.   [4mtext-[0m
             [4mindent[24m  overrides  the default indentation of the list items, which
             is the width of [4mmark[24m plus one en.  A third argument suppresses  the
             vertical  space that normally precedes each list item; see register
             [1mLsp[22m.  Vertical space in the amount of [1mLsp [22mprecedes the list itself,
             but does not accumulate with  pre-item  space  when  this  list  is
             nested  in another.  [1mML [22mcalls [1mLB[22m; use [1mLI [22mto declare list items, and
             [1mLE [22mto end the list.

     [1mMT [22m[[4mtype[24m [[4maddressee[24m]]
             Select memorandum type.  These correspond to formats used  by  AT&T
             Bell  Laboratories,  where  the [4mmm[24m package was initially developed,
             affecting the document layout.  Some of these included a cover page
             with a caption categorizing the document.  [4mgroff[24m [4mmm[24m  uses  [4mtype[24m  to
             construct the file name [4m/usr/share/groff/1.24.0/tmac/mm/[24mtype[4m.MT[24m and
             load  it  with  the  [1mmso [22mrequest.  Memorandum types 0 to 5 are sup‐
             ported; any other value of [4mtype[24m is mapped to type 6.  Omitting [4mtype[0m
             implies [1m1[22m.  [4maddressee[24m sets a string analogous to one used  by  AT&T
             cover page macros not implemented in [4mgroff[24m [4mmm[24m.

             [4m[1mtype[24m     Description[0m
             0        normal memorandum; no caption
             1        captioned “TECHNICAL MEMORANDUM”
             2        captioned “INTERNAL MEMORANDUM”
             3        captioned “ADMINISTRATIVE MEMORANDUM”
             4        released paper
             5        external letter
             [4mstring[24m   captioned [4mstring[0m

             See [1mCOVER [22mfor a more flexible cover page mechanism.

     [1mMOVE [4m[22my-pos[24m [[4mx-pos[24m [[4mline-length[24m]]
             Move  to  a position, setting page offset to [4mx-pos[24m.  If [4mline-length[0m
             is not given, the difference between current and new page offset is
             used.  Use [1mPGFORM [22mwithout arguments to return to normal.

     [1mMULB [4m[22mcw1[24m [4msp1[24m [[4mcw2[24m [4msp2[24m] ... [4mcwn[0m
             Begin alternative multi-column mode.  All column widths [4mcw[24mi must be
             specified, as must the amount of  space  [4msp[24mi  between  each  column
             pair.   [1mMULB  [22muses  a diversion and operates in a separate environ‐
             ment.

     [1mMULE    [22mEnd alternative multi-column mode and emit the columns.

     [1mMULN    [22mStart next column in alternative column mode.

     [1mNCOL    [22mStart next column (only when using [1m2C [22mor [1mMC[22m).  Contrast with [1mMULN[22m.

     [1mND [22m[[4marg[24m]
             Set the document's date.  [4mmm[24m does not interpret [4marg[24m; it  can  be  a
             revision identifier (or empty).  [4mmm[24m calls [1mND [22mitself when initializ‐
             ing.

     [1mNE      [22mEnd notation begun with [1mNS[22m; filling is enabled.

     [1mnP [22m[[4mtype[24m]
             As  [1mP[22m,  but set a paragraph number in the form [4mx[24m.[4myy[24m, where [4mx[24m is the
             number of the second heading level, and [4myy[24m increments with each  [1mnP[0m
             call;  its  value is not reset when the second-level heading number
             changes.  [4mmm[24m uses a register format of “00” for [4myy.[0m

     [1mNS [22m[[4mcode[24m [[1m1[22m]]
             Declare notations, typically for letters or memoranda, of the  type
             specified  by  [4mcode[24m.  The text corresponding to [4mcode[24m is output, and
             filling is disabled until the document calls [1mNE[22m.  Typically, a list
             of names or attachments lies within [1mNS[22m/[1mNE[22m.  If [4mcode[24m  is  absent  or
             does  not match one of the values listed under the [1mLetns [22mstring de‐
             scription below, each line  of  notations  is  formatted  as  “Copy
             ([4mline[24m) to”.  If a second argument, conventionally [1m1[22m, is given, [4mcode[0m
             becomes  the entire notation and [1mNE [22mis not necessary.  In [4mgroff[24m [4mmm[24m,
             you can set up further notations to be recognized by  [1mNS[22m;  see  the
             strings [1mLetns [22mand [1mLetnsdef [22mbelow.

     [1mOF [22m[[1m"'[4m[22mleft[24m[1m'[4m[22mcenter[24m[1m'[4m[22mright[24m[1m'"[22m]
             Define  the odd-page footer, which is formatted just above the nor‐
             mal page footer on odd-numbered pages.  See  [1mPF[22m.   [1mOF  [22mdefines  the
             string [1mEOPof[22m.

     [1mOH [22m[[1m"'[4m[22mleft[24m[1m'[4m[22mcenter[24m[1m'[4m[22mright[24m[1m'"[22m]
             Define  the odd-page header, which is formatted just below the nor‐
             mal page header on odd-numbered pages.  See  [1mPH[22m.   [1mOH  [22mdefines  the
             string [1mTPoh[22m.

     [1mOP      [22mEnsure  that subsequent text is formatted at the top of an odd-num‐
             bered page; no page break is performed if the drawing  position  is
             already there.

     [1mP [22m[[4mtype[24m]
             Begin new paragraph.  If [4mtype[24m is missing or [1m0[22m, [1mP [22msets the paragraph
             fully  left-aligned.   A  [4mtype[24m of [1m1 [22mindents the first line by [1m\[Pi][0m
             ens.  Set the register [1mPt [22mto select a default paragraph indentation
             style.  The register [1mPs [22mdetermines the amount of vertical space be‐
             tween paragraphs.

             To set a paragraph with a hanging indent, use [1mVL [22mwith  the  desired
             indentation as the argument, [1mLI [22m(with no argument), and [1mLE[22m.

     [1mPE      [22mEnd picture input preprocessed by ]8;;man:pic(1)\[4mpic[24m(1)]8;;\; see [1mPS[22m.

     [1mPF [22m[[1m"'[4m[22mleft[24m[1m'[4m[22mcenter[24m[1m'[4m[22mright[24m[1m'"[22m]
             Define  the  page footer.  The footer is formatted at the bottom of
             each page; the argument is otherwise as described in  [1mPH[22m.   [1mPF  [22mde‐
             fines the string [1mEOPf[22m.  See [1mEF[22m, [1mOF[22m, and [1mEOP[22m.

     [1mPGFORM [22m[[4mline-length[24m [[4mpage-length[24m [[4mpage-offset[24m [[1m1[22m]]]]
             Set  line  length, page length, and/or page offset.  This macro can
             be used for letterheads and similar.   It  is  normally  the  first
             macro  call  in  a file, though it is not necessary.  [1mPGFORM [22mcan be
             used without arguments to reset everything after a  [1mMOVE  [22mcall.   A
             line  break  is done unless the fourth argument is given.  This can
             be used to avoid the page number on the first  page  while  setting
             new width and length.  (It seems as if this macro sometimes doesn't
             work  too  well.   Use  the  command-line  arguments to change line
             length, page length, and page offset instead.)

     [1mPGNH    [22mSuppress header on the next page.  To  suppress  a  header  on  the
             first  page,  call  this  macro prior to formatting any text in the
             document.  Also see register [1mN[22m.

     [1mPH [22m[[1m"'[4m[22mleft[24m[1m'[4m[22mcenter[24m[1m'[4m[22mright[24m[1m'"[22m]
             Define the page header, formatted at the top of each page,  as  the
             argument,  where [4mleft[24m, [4mcenter[24m, and [4mright[24m are aligned to the respec‐
             tive locations on the line.  A “[1m%[22m” character in [4marg[24m is replaced  by
             the page number.  If the argument is absent, no page header is set.
             The default page header is
                    "''- % -''"
             which  centers  the page number between hyphens and formats nothing
             at the upper left and right.  Header macros call  [1mPX  [22m(if  defined)
             after  formatting  the header.  [1mPH [22mdefines the string [1mTPh[22m.  See [1mEH[22m,
             [1mOH[22m, and [1mTP[22m.

     [1mPIC [22m[[1m-B[22m] [[1m-C[22m|[1m-I [4m[22mn[24m|[1m-L[22m|[1m-R[22m] [4mfile[24m [[4mwidth[24m [[4mheight[24m]]
             Include PostScript document [4mfile[24m.  The optional [1m-B [22margument draws a
             box around the picture.  The optional [1m-L[22m, [1m-C[22m, [1m-R[22m, and  [1m-I  [4m[22mn[24m  argu‐
             ments align the picture or indent it by [4mn[24m.  By default, the picture
             is  left-aligned.   Optional  [4mwidth[24m and [4mheight[24m arguments resize the
             picture.  Use of this macro requires two-pass processing; see [1mINITR[0m
             and ]8;;man:mmroff(1)\[4mmmroff[24m(1)]8;;\.

     [1mPS      [22mStart picture input preprocessed by ]8;;man:pic(1)\[4mpic[24m(1)]8;;\.

     [1mPY      [22mAs [1mPE[22m, but with “flyback”, returning the drawing position to  where
             it was prior to the picture.  This is a [4mgroff[24m [4mmm[24m extension.

     [1mR [22m[[4mroman-text[24m [[4mprevious-font-text[24m]] ...
             Join  [4mroman-text[24m in roman style with [4mprevious-font-text[24m in the pre‐
             vious font, without space between the arguments.  If no  arguments,
             switch font to roman style.

     [1mRB [22m[[4mroman-text[24m [[4mbold-text[24m]] ...
             Join  [4mroman-text[24m in roman style with [4mbold-text[24m in boldface, without
             space between the arguments.

     [1mRD [22m[[4mprompt[24m [[4mdiv[24m [[4mstr[24m]]]
             Write [4mprompt[24m (if specified, a tab and colon “:” to the standard er‐
             ror stream and read response from standard input stream, optionally
             into a diversion [4mdiv[24m and/or string [4mstr.[24m  Interpolate the saved text
             by calling its name like a macro.  If [4mstring[24m is present, the  input
             is also stored in a string of that name.

     [1mRF      [22mEnd a bibliographic reference citiation started with [1mRS[22m.  See [1mRP[22m.

     [1mRI [22m[[4mroman-text[24m [[4mitalic-text[24m]] ...
             Join [4mroman-text[24m in roman style with [4mitalic-text[24m in italics, without
             space between the arguments.

     [1mRL [22m[[4mtext-indent[24m [[1m1[22m]]
             Begin  an auto-incrementing numbered list, where item numbers start
             at one and set between square  brackets.   A  [4mtext-indent[24m  argument
             overrides  register  [1mLi[22m.  A second argument suppresses the vertical
             space that normally precedes each  list  item;  see  register  [1mLsp[22m.
             Vertical  space  in the amount of [1mLsp [22mprecedes the list itself, but
             does not accumulate with pre-item space when this list is nested in
             another.  [1mRL [22mcalls [1mLB[22m; use [1mLI [22mto declare list items, and [1mLE [22mto  end
             the  list.  “RL” is a mnemonic for “reference list”, but this macro
             has no relationship with [4mmm[24m's bibliographic reference list  facili‐
             ties.

     [1mRP [22m[[4msuppress-counter-reset[24m [[4mpage-ejection-policy[24m]]
             Format  a  reference  list,  listing items accumulated within [1mRS[22m/[1mRF[0m
             pairs.  The reference counter is reset unless  the  first  argument
             is  [1m1[22m.  Normally, page breaks occur before and after the references
             are output; the register [1mRpej [22mconfigures this behavior, and a  sec‐
             ond  argument  overrides  its  value.  [1mTC [22mcalls [1mRP [22mautomatically if
             references have accumulated.

             [4mgroff[24m [4mmm[24m calls [1mLB [22mto format the reference list;  the  [1mRpfmt  [22mstring
             configures  the  list's  appearance.  Setting register [1mLs [22mto [1m0 [22msup‐
             presses spacing after the list.  The string [1mRp [22mcontains the  refer‐
             ence list caption.

     [1mRPX     [22mThis  hook  macro assumes responsibility for formatting the heading
             of the reference page that [1mRP [22mproduces.  If not  defined  (the  de‐
             fault),  [4mmm[24m  sets the reference list caption in the string [1mRp [22mafter
             two vees of space, centered in italics, followed by another vee  of
             space.

     [1mRS [22m[[4mreference-string[24m]
             Begin citation of an automatically numbered bibliographic reference
             entry.  [4mmm[24m collects input into a reference entry until the document
             calls  [1mRF[22m.   A  subsequent  [1mRP  [22mcall emits the accumulated entries.
             References are numbered starting at 1; the register [1m:R  [22mstores  the
             most recently assigned number.  Interpolate the string [1mRf [22mwhere the
             reference  mark  should  be, then place the entry between [1mRS [22mand [1mRF[0m
             calls on text lines after the reference mark.  The [1mRfstyle [22mregister
             determines whether the mark is bracketed, superscripted,  or  both.
             If [4mreference-string[24m is specified, [4mmm[24m also stores the reference mark
             in a string of that name.

     [1mS [22m[[4mtype-size[24m [[4mvertical-spacing[24m]]
             Set  type size and vertical spacing.  Each argument is a [4mgroff[24m mea‐
             surement, using an appropriate scaling unit and an optional [1m+ [22mor  [1m-[0m
             prefix to increment or decrement the current value.  An argument of
             [1mP  [22mrestores  the previous value, [1mC [22mretains the current value, and [1mD[0m
             requests the default.  [4mmm[24m treats an empty or omitted argument as [1mP[22m.

     [1mSA [22m[[4mmode[24m]
             Set or restore the default enablement of adjustment.  Specify [1m0  [22mor
             [1m1  [22mas [4mmode[24m to set a document's default explicitly; [4mgroff[24m [4mmm[24m assumes
             [1m1[22m.  Invoke the [1mna [22mrequest as desired to temporarily suspend adjust‐
             ment.  [1mH [22mand [1mHU[22m, and [1mSA [22mwhen called without a  [4mmode[24m  argument,  re‐
             store the default adjustment.

     [1mSETR [4m[22mref-name[24m [[4mstring[24m]
             Create  reference  [4mref-name[24m,  storing its heading and page numbers.
             If [4mstring[24m is present, [4mgroff[24m [4mmm[24m saves it as an auxiliary  datum  for
             retrieval by [1mGETST[22m.  See [1mINITR[22m.

     [1mSG [22m[[4marg[24m [[1m1[22m]]
             Output  author  signature  block(s) in [1mLT [22mletters and [1mMT [22mmemoranda.
             The format of a signature block depends on the letter or memorandum
             type.  See subsection “Internals” below.

             [1mLT [22mletters emit a signature for one author at most (see  [1mWA[22m).   The
             author's  title, if any, is set on the next line, indented to align
             with the name, except in letter type “SP”, where it is set in  full
             capitals (like the name) after a comma and space.

             Memorandum  type  4  uses  no signature block.  In other memoranda,
             each of an author's titles is set on a subsequent line, indented to
             align with the name.  They furthermore encode a secretarial annota‐
             tion including the location, department, and initials specified  in
             each  author's [1mAU [22mcall, followed by any [4marg[24m, writing it at the left
             margin preceding the last author's name, or preceding the first  if
             a second [1mSG [22margument is present.

     [1mSK [22m[[4mn[24m]  Skip  [4mn[24m  pages.  If [4mn[24m is [1m0 [22mor omitted, [4mmm[24m breaks the page if neces‐
             sary.  Otherwise, [4mmm[24m prints [4mn[24m pages, blank except for  any  headers
             and footers.

     [1mSM [4m[22mtext[24m [[4mpost[24m]
     [1mSM [4m[22mpre[24m [4mtext[24m [4mpost[0m
             Format  [4mtext[24m  at a smaller type size, joined with any specified [4mpre[0m
             and [4mpost[24m at normal size, without space between the arguments.

     [1mSP [22m[[4mdistance[24m]
             Space downward by [4mdistance.[24m  Multiple [1mSP [22mcalls in sequence  produce
             only  the largest of the specified [4mdistances.[24m  [1mSP [22maccepts boundary-
             relative motions specified with a prefixed [1m| [22moperator, but not neg‐
             ative ones.

             [1mSP [22mhas no effect when the drawing position is at  the  top  of  the
             page.   Put  the dummy character escape sequence [1m\& [22m(followed by [1m\c[0m
             if desired to prevent a break) on a text line prior to an  [1mSP  [22mcall
             to overcome this restriction.

     [1mTAB     [22mReset tab stops to every 5 ens.  The [1mta [22mrequest customizes them.

     [1mTB [22m[[4mtitle[24m [[4moverride[24m [[4mflag[24m [[4mref-name[24m]]]]
             Caption  a  table.   Arguments  are handled analogously to [1mEC[22m.  The
             register [1mTb [22mis the table counter.  The string  [1mCaptb  [22mprecedes  the
             table number and any [4mtitle.[24m  [4mmm[24m centers table captions irrespective
             of the alignment of any enclosing display.

             The  package lists captioned tables in a table of contents (see [1mTC[22m)
             if the Boolean register [1mLt [22mis true.  The string  [1mLt  [22mcaptions  this
             list.

     [1mTC [22m[[4mslevel[24m [[4mspacing[24m [[4mtlevel[24m [[4mtab[24m [[4mh1[24m [[4mh2[24m [[4mh3[24m [[4mh4[24m [[4mh5[24m]]]]]]]]]
             Output  table  of contents.  This macro is normally the last called
             in the document.  It flushes any pending displays and, if any  ref‐
             erences  are pending (see [1mRS[22m), calls [1mRP[22m.  It then begins a new page
             with the contents caption, stored in the string [1mCaptc[22m, centered  at
             the top.  The entries follow after three vees of space.  Each entry
             is  a  saved  section (number and) heading title (see the [1mCl [22mregis‐
             ter), along with its associated page number.  By  default,  [4mmm[24m  in‐
             dents  an entry by an amount corresponding to its heading level and
             the maximum heading length encountered at that  heading  level;  if
             defined,  the  string  [1mCi [22moverrides these indentations.  Entries at
             heading levels up to and including [4mslevel[24m are preceded  by  [4mspacing[0m
             vees  of  space.   Entries  at  heading  levels up to and including
             [4mtlevel[24m are followed by a leader and a  right-aligned  page  number.
             If  the Boolean-valued [4mtab[24m argument is true, the leader is replaced
             with horizontal motion in the same amount.  For entries above head‐
             ing level [4mtlevel[24m, the page number follows the heading text after  a
             word  space.   Each  argument  [4mh1[24m...[4mh5[24m  appears in order on its own
             line,  centered,  above  the  contents  caption.   Page   numbering
             restarts at 1, in register format “i”.  If the [1mOc [22mregister is true,
             numbering of these pages is suppressed.

             If  the document calls [1mTC [22mwith at most four arguments, [4mmm[24m calls the
             hook macro [1mTX [22mprior to formatting the contents caption, and [1mTY  [22m(if
             defined) [4minstead[24m of formatting the contents caption.

             [4mmm[24m then presents lists of figures, tables, equations, and exhibits,
             in  that order.  A list appears only if at least one such captioned
             item is present, and if its corresponding register ([1mLe[22m, [1mLf[22m, [1mLt[22m,  or
             [1mLx[22m) is set.  [1mTX[4m[22mxx[24m and [1mTY[4m[22mxx[24m macros, where [4mxx[24m is “FG”, “TB”, “EC”, or
             “EX”,  and  strings [1mCapfg[22m, [1mCaptb[22m, [1mCapec[22m, and [1mCapex [22manalogously con‐
             figure the output of each captioned list.

     [1mTE      [22mEnd ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\ table.  See [1mTS[22m.

     [1mTH      [22mMark the end of a [1mTS[22m/[1mTE [22mtable heading.  When a table spans multiple
             pages, the heading repeats at the top of each page.  [4mgroff[24m [4mmm[24m  does
             not implement the [1mN [22margument supported by DWB.

     [1mTL [22m[[4mcharging-case-number[24m [[4mfiling-case-number[24m]]
             Begin  document  title.   [4mmm[24m  collects input into the title until a
             subsequent [1mAU [22mcall and formats it as directed by the [1mMT  [22mmemorandum
             type  or cover page macros.  [4mmm[24m saves [4mcharging-case-number[24m and [4mfil‐[0m
             [4ming-case-number[24m for use in all memorandum types except 4.

     [1mTM [4m[22mnumber[24m ...
             Declare technical memorandum number(s) used with [1mMT [22mmemoranda.

     [1mTP      [4m[22mmm[24m calls this hook macro in lieu of normal page header layout.  The
             package uses a separate environment to format headers and  footers.
             See [1mEOP[22m.

             [1mStrings available to TP[0m
             ────────────────────────
             [1mTPh     [22margument to [1mPH[0m
             [1mTPeh    [22margument to [1mEH[0m
             [1mTPoh    [22margument to [1mOH[0m

     [1mTS [22m[[1mH[22m]  Start ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\ table.  Argument “H” tells [4mmm[24m that the table's heading
             should repeat after page breaks.  See [1mTE[22m, [1mTH[22m, and ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\.

     [1mVERBON [22m[[4mformat[24m [[4mtype-size[24m [[4mfont[24m]]]
             Begin display of verbatim content.  [4mformat[24m controls several parame‐
             ters.   Add  up  the  values of desired features; the default is [1m0[22m.
             Further arguments configure the [4mtype-size[24m in  typographical  points
             (on  typesetting devices), and the face ([4mfont[24m).  On typesetting de‐
             vices, the default face is [1mCR [22m(Courier roman), a  monospaced  font:
             all glyphs are equally wide.

             [1mValue   Effect[0m
             1       Disable the formatter's escape character (\).
             2       Vertically space before the display.
             4       Vertically space after the display.
             8       Number output lines; call formatter's [1mnm [22mrequest with argu‐
                     ments in string [1mVerbnm[22m.
             16      Indent by the amount stored in register [1mVerbin[22m.

     [1mVERBOFF[0m
             End verbatim display.

     [1mVL [22m[[4mtext-indent[24m [[4mmark-indent[24m [[1m1[22m]]]
             Begin  variable-item  (or  “tagged”) list.  Each item should supply
             its own mark, or tag.  A [4mtext-indent[24m  argument  overrides  register
             [1mPi[22m;  [4mmark-indent[24m sets the distance from the indentation of the cur‐
             rent list to the mark.  A third argument  suppresses  the  vertical
             space  that  normally  precedes  each  list item; see register [1mLsp[22m.
             Vertical space in the amount of [1mLsp [22mprecedes the list  itself,  but
             does not accumulate with pre-item space when this list is nested in
             another.   [1mRL [22mcalls [1mLB[22m; use [1mLI [22mto declare list items, and [1mLE [22mto end
             the list.

     [1mVM [22m[[1m-T[22m] [[4mtop[24m [[4mbottom[24m]]
             Configure vertical margins.

             Without a [1m-T [22margument, increment the top and bottom margins by  [4mtop[0m
             and  [4mbottom[24m, respectively.  If absent, set the corresponding margin
             to zero.

             With the [1m-T [22margument, set the top and bottom  margins  to  [4mtop[24m  and
             [4mbottom[24m,  respectively.  If absent, set the respective margin to the
             default (top: [1m7v[22m, bottom: [1m6v[22m).

             We recommend defining the hook macros [1mTP [22mand/or [1mEOP [22mif using [1m-T [22mand
             setting top and/or bottom margin to values less than  the  default.
             [4mgroff[24m [4mmm[24m exposes this undocumented DWB macro to enable greater user
             control of page layout.

     [1mWA [22m[[4mwriter's-name[24m [[4mtitle[24m]]
             Specify  the writer(s) of an [1mLT [22mletter.  [4mmm[24m collects input into the
             writer's address until the document calls [1mWE[22m, then outputs it.  You
             can specify multiple writers with empty [1mWA[22m/[1mWE [22mpairs; only the  last
             address is used.  The arguments give each writer a name and title.

     [1mWC [22m[[4mformat[24m ...]
             Control width of footnotes and displays.

             [4m[1mformat[24m   Effect[0m
             [1mN        [22mequivalent to “[1m-WF -FF -WD[22m” (default)
             [1mWF       [22mset footnotes at full line length, even in two-column mode
             [1m-WF      [22mset footnotes using column line length
             [1mFF       [22mapply width of first footnote to encountered to subsequent
                      ones
             [1m-FF      [22mfootnote width determined by [1mWF [22mand [1m-WF[0m
             [1mWD       [22mset displays at full line length, even in two-column mode
             [1m-WD      [22mset displays using column line length

     [1mWE      [22mEnd the writer's address begun with [1mWA[22m.

[1mStrings[0m
     Many [4mmm[24m strings interpolate predefined, localizable text.  We present their
     contents in quotation marks.

     [1mAbstract  [22m“ABSTRACT”

     [1mApp       [22m“APPENDIX”

     [1mApptxt    [22mstores the [4mtitle[24m argument to the most recent [1mAPP [22mcall.

     [1mAumt      [22mlists  space-separated  indices of positional arguments to the [1mAU[0m
               macro that should be suppressed from appearance in  the  document
               heading  on  the first page of [1mMT [22mmemorandum types 0–3 and 6.  By
               default, it is undefined; all arguments are formatted except  the
               second (author initials).

     [1mBU        [22minterpolates a bullet mark, [1m\[bu][22m.

     [1mCapec     [22m“Equation”

     [1mCapex     [22m“Exhibit”

     [1mCapfg     [22m“Figure”

     [1mCaptb     [22m“Table”

     [1mCaptc     [22m“CONTENTS”

     [1mCi        [22massigns  indentation amounts used by each heading level listed in
               a table of contents,  in  one-to-one  correspondence,  overriding
               those computed by [1mTC[22m.  Each word must be a horizontal measurement
               (like “[1m1i[22m”).

     [1mDT        [22mstores  the  date  or  other identifier set by [1mND[22m, if called, and
               otherwise one constructed using the formatter's  date  registers;
               see ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\.  The [4mgroff[24m locale determines its format, but regis‐
               ter [1mIsodate [22mmay override it.

     [1mEM        [22minterpolates an em dash, [1m\[em][22m.

     [1mF         [22minterpolates  an automatically numbered footnote mark; the number
               is used by the next [1mFS [22mcall without an argument.  In [4mtroff[24m  mode,
               the  mark  is  superscripted;  in [4mnroff[24m mode, it is surrounded by
               square brackets.

     [1mH1txt     [22mstores the text of the current first-level heading; [1mH [22mand [1mHU  [22mup‐
               date it, as does [1mTC [22mwhen processing table of contents entries and
               captions of displayed figures, tables, equations, and exhibits.

     [1mHF        [22massigns  font identifiers, separated by spaces, to heading levels
               in one-to-one correspondence.  Each  identifier  may  be  a  font
               mounting  position, font name, or style name.  Omitted values are
               assumed to be 1.  The default is “[1m2 2 2 2 2 2 2 2 2 2 2 2  2  2[22m”,
               which places all headings in italics.  DWB's default was “[1m3 3 2 2[0m
               [1m2 2 2[22m”.

     [1mHP        [22massigns  type  sizes,  separated  by spaces, to heading levels in
               one-to-one correspondence.  [4mgroff[24m [4mmm[24m interprets each size in  ty‐
               pographical  points, translating zero values to [1m10[22m.  Omitted val‐
               ues are assumed to be 0 (and are  translated  accordingly).   The
               default is “[1m0 0 0 0 0 0 0 0 0 0 0 0 0 0[22m”.

     [1mIndex     [22m“INDEX”

     [1mLe        [22m“LIST OF EQUATIONS”

     [1mLetfc     [22m“Yours very truly,” (see [1mFC[22m)

     [1mLetapp    [22m“APPROVED:” (see [1mAV[22m)

     [1mLetAT     [22m“ATTENTION:” (see [1mLO[22m)

     [1mLetCN     [22m“CONFIDENTIAL” (see [1mLO[22m)

     [1mLetdate   [22m“Date” (see [1mAV[22m)

     [1mLetns     [22mis  a  group of strings structuring the notations produced by [1mNS[22m.
               If the [4mcode[24m argument to [1mNS [22mhas no corresponding string, the nota‐
               tion is included between parentheses, prefixed  with  [1mLetns!copy[22m,
               and  suffixed with [1mLetns!to[22m.  Observe the spaces after “Copy” and
               before “to”.

               [1mNS code   String       Contents[0m
               0         Letns!0      Copy to
               1         Letns!1      Copy (with att.) to
               2         Letns!2      Copy (without att.) to
               3         Letns!3      Att.
               4         Letns!4      Atts.
               5         Letns!5      Enc.
               6         Letns!6      Encs.
               7         Letns!7      Under separate cover
               8         Letns!8      Letter to
               9         Letns!9      Memorandum to
               10        Letns!10     Copy (with atts.) to
               11        Letns!11     Copy (without atts.) to
               12        Letns!12     Abstract Only to
               13        Letns!13     Complete Memorandum to
               14        Letns!14     CC
               ——        Letns!copy   Copy [4m(with[24m [4mtrailing[24m [4mspace)[0m
               ——        Letns!to      to [4m(note[24m [4mleading[24m [4mspace)[0m

     [1mLetnsdef  [22mselects the notation format when [1mNS [22mis given  no  argument.   The
               default is [1m0[22m.

     [1mLetRN     [22m“In reference to:” (see [1mLO[22m)

     [1mLetSA     [22m“To Whom It May Concern:” (see [1mLO[22m)

     [1mLetSJ     [22m“SUBJECT:” (see [1mLO[22m)

     [1mLf        [22m“LIST OF FIGURES”

     [1mLt        [22m“LIST OF TABLES”

     [1mLx        [22m“LIST OF EXHIBITS”

     [1mMO1[0m
     ...
     [1mMO12      [22m“January” through “December”

     [1mQrf       [22m“See  chapter  \E*[Qrfh], page \En[Qrfp].”  If your document uses
               multiple heading levels, you might redefine this  string  to  use
               the word “section” instead of “chapter”.

     [1mQrfh      [22mstores  the  heading  mark  corresponding to the most recent [1mGETR[0m
               call.

     [1mQrfp      [22mstores the page number corresponding  to  the  most  recent  [1mGETR[0m
               call.

     [1mRf        [22minterpolates an automatically numbered reference mark; the number
               is used by the next [1mRS [22mcall.

     [1mRp        [22m“REFERENCES”

     [1mRpfmt     [22mspecifies the [1mLB [22marguments that [4mgroff[24m [4mmm[24m uses to format the items
               in an [1mRP [22mreference list.  The default is “[1m\\n[Li] 0 1 0 \& 0[22m”.

     [1mRg        [22minterpolates the registered (trade) mark sign.

     [1mSm        [22minterpolates the service mark sign.

     [1mTcstatus  [22minterpolates  an  indicator  of the [1mTC [22mmacro's processing status.
               If [1mTC [22mis not operating, it is  empty.   User-defined  [1mTP  [22mor  [1mEOP[0m
               macros might condition page headers or footers on its contents.

               [1mValue   Meaning[0m
               co      Table of contents
               fg      List of figures
               tb      List of tables
               ec      List of equations
               ex      List of exhibits
               ap      Appendix

     [1mTm        [22minterpolates ™, the trade mark sign.

     [1mVerbnm    [22msupplies  argument(s)  to  the  [1mnm [22mrequest employed by the [1mVERBON[0m
               macro.  The default is [1m1[22m.

[1mRegisters[0m
     Default register values, where meaningful, are shown in parentheses.

     [1m.mgm     [22mindicates that [4mgroff[24m [4mmm[24m is in use (Boolean-valued; [1m1[22m).

     [1mAph      [22mformats an appendix heading (and  title,  if  supplied);  see  [1mAPP[0m
              (Boolean-valued; [1m1[22m).

     [1mAu       [22mincludes supplemental author information (the third and subsequent
              arguments  to  [1mAU[22m) in memorandum “from” information; see [1mCOVER [22mand
              [1mMT[22m, and the [1mAumt [22mstring (Boolean-valued; [1m1[22m).

     [1mCl       [22msets the threshold for inclusion of headings in a  table  of  con‐
              tents.   Headings  at  levels above this value are excluded; see [1mH[0m
              and [1mTC[22m.  The [1mCl [22mregister controls whether a heading is  [4msaved[24m  for
              output  in the table of contents at the time [1mH [22mor [1mHU [22mis called; if
              you change [1mCl[22m's value immediately prior to calling [1mTC[22m, you are un‐
              likely to get the result you want ([1m2[22m).

     [1mCp       [22msuppresses page breaks before lists of  captioned  equations,  ex‐
              hibits,  figures, and tables, and before an index; see [1mEC[22m, [1mEX[22m, [1mFG[22m,
              [1mTB[22m, and [1mINDP [22m(Boolean-valued; [1m0[22m).

     [1mD        [22mproduces debugging information for the [4mmm[24m package on the  standard
              error  stream.  A value of 0 outputs nothing; 1 reports formatting
              progress.  Higher values communicate internal state information of
              increasing verbosity ([1m0[22m).

     [1mDe       [22mcauses a page break after a floating display  is  output;  see  [1mDF[0m
              (Boolean-valued; [1m0[22m).

     [1mDf       [22mconfigures  the  behavior  of [1mDF[22m.  The following values are recog‐
              nized; 4 and 5 do not override the [1mDe [22mregister ([1m5[22m).

              [1mValue   Effect[0m
              0       Flush pending displays at the end  of  each  section  when
                      section-page  numbering is active, otherwise at the end of
                      the document.
              1       Flush a pending display on the current page or  column  if
                      there  is  enough space, otherwise at the end of the docu‐
                      ment.
              2       Flush one pending display at the top of each page or  col‐
                      umn.
              3       Flush  a  pending display on the current page or column if
                      there is enough space, otherwise at the top of the next.
              4       Flush as many pending displays as possible in a  new  page
                      or column.
              5       Fill columns or pages with flushed displays until none re‐
                      main.

     [1mDs       [22mputs  vertical space in the amount of register [1mDsp [22m(if defined) or
              [1mLsp [22mbefore and after each static display; see [1mDS  [22m(Boolean-valued;
              [1m1[22m).

     [1mDsp      [22mconfigures  the  amount  of vertical space placed before and after
              static displays; see [1mDS [22mand register [1mDs [22m([4mundefined[24m).

     [1mEc       [22mis an auto-incrementing equation counter; see [1mEC[22m.

     [1mE        [22mdetermines the font style used by [1mMT [22mmemoranda,  [1mLT  [22mletters,  and
              the [4mms.cov[24m cover page style to set the date and certain other doc‐
              ument data; [1m0 [22mselects roman, and [1m1 [22mbold (Boolean-valued; [1m1[22m).

     [1mEj       [22msets  the threshold for page breaks (ejection) prior to the format
              of headings.  Headings at levels above this value are set  on  the
              same page and column as any preceding text if possible; see [1mH [22m([1m0[22m).

     [1mEq       [22maligns  an  equation label to the left of a display instead of the
              right (Boolean-valued; [1m0[22m).

     [1mEx       [22mis an auto-incrementing exhibit counter; see [1mEX[22m.

     [1mFg       [22mis an auto-incrementing figure counter; see [1mFG[22m.

     [1mFs       [22mis multiplied by register [1mLsp [22mto  vertically  separate  footnotes;
              see [1mFS [22m([1m1[22m).

     [1mFtnum    [22mis an auto-incrementing footnote counter; see [1mFS[22m.  [4mgroff[24m [4mmm[24m recog‐
              nizes [1m:p [22mas an alias of [1mFtnum [22mfor DWB compatibility.

     [1mH1[0m
     ...
     [1mH14      [22mare  auto-incrementing  counters  corresponding  to  each  heading
              level; see [1mH[22m.

     [1mH1dot    [22mappends a period to the number of  a  level  one  heading;  see  [1mH[0m
              (Boolean-valued; [1m1[22m).

     [1mH1h      [22mis a copy of register [1mH1[22m, but it is incremented just before a page
              break.  This can be useful in hook macros; see [1mH [22mand [1mHX[22m.

     [1mHb       [22msets  the threshold for breaking the line after formatting a head‐
              ing.  Text after headings at levels above this value is set on the
              same output line if possible.  Paragraphs numbered via [1mnP  [22mor  the
              [1mNp [22mregister cause a break regardless; see [1mH [22m([1m2[22m).

     [1mHc       [22msets  the  threshold  for centering a heading.  Headings at levels
              above this value use the prevailing alignment (that is,  they  are
              not centered); see [1mH [22m([1m0[22m).

     [1mHi       [22mselects  an  indentation policy for text formatted after headings.
              It does not affect “run-in” headings.  The  following  values  are
              recognized; see [1mH [22mand [1mP [22m([1m1[22m).

              [1mValue   Effect[0m
              0       no indentation
              1       indent per the paragraph type
              2       indent to align with heading title

     [1mHps      [22msets the heading level threshold for application of preceding ver‐
              tical  space; see [1mH[22m.  Headings at levels above the value in regis‐
              ter [1mHps [22muse the amount of space in register [1mHps1[22m;  otherwise  that
              in [1mHps2[22m.  The value of [1mHps [22mshould be strictly greater than that of
              [1mEj [22m([1m1[22m).

     [1mHps1     [22mconfigures  the amount of vertical space preceding a heading above
              the [1mHps [22mthreshold; see [1mH [22m([4mtroff[24m devices: [1m0.5v[22m; [4mnroff[24m devices: [1m1v[22m).

     [1mHps2     [22mconfigures the amount of vertical space preceding a heading within
              the [1mHps [22mthreshold; see [1mH [22m([4mtroff[24m devices: [1m1v[22m; [4mnroff[24m devices: [1m2v[22m).

     [1mHs       [22msets the heading level threshold  for  application  of  succeeding
              vertical  space.   If  the  heading  level is greater than [1mHs[22m, the
              heading is followed by vertical space  in  the  amount  of  regis‐
              ter [1mHss[22m; see [1mH [22m([1m2[22m).

     [1mHss      [22mis  multiplied  by  register  [1mLsp  [22mto produce vertical space after
              headings above the threshold in register [1mHs[22m; see [1mH [22m([1m1[22m).

     [1mHt       [22msuppresses output of heading level counters above the deepest when
              a heading mark is formatted; see [1mH [22m(Boolean-valued; [1m0[22m).

     [1mHu       [22msets the heading level used by unnumbered headings; see [1mHU [22m([1m2[22m).

     [1mHy       [22menables automatic hyphenation of words (Boolean-valued; [1m0[22m).

     [1mIsodate  [22mconfigures the use of ISO 8601 date format;  that  is,  [4mYYYY[24m-[4mMM[24m-[4mDD[0m
              instead of the format specified by the localization file.  Call [1mND[0m
              without arguments after updating its value (Boolean-valued; [1m0[22m).

     [1mL        [22mdefines the page length for the document, and must be set from the
              command  line.  A scaling unit should be appended.  The default is
              that of the selected [4mgroff[24m output device.

     [1mLe[0m
     [1mLf[0m
     [1mLt[0m
     [1mLx       [22mconfigure the report of lists of equation, figure, table, and  ex‐
              hibit  captions,  respectively,  after a table of contents; see [1mTC[0m
              (all: Boolean-valued; [1m1[22m).

     [1mLetwam   [22msets the maximum number of input lines permitted in a writer's ad‐
              dress; see [1mWA [22mand [1mWE [22m([1m14[22m).

     [1mLi       [22mconfigures the text indentation (in  ens)  applied  to  enumerated
              list  types; that is, to items in [1mAL [22mand [1mRL [22mlists, and in [1mLB [22mlists
              whose [4mtype[24m argument is greater than zero ([1m5[22m).

     [1mLs       [22msets a threshold for  placement  of  vertical  space  before  list
              items.   If  the list nesting level is greater than this value, no
              such spacing occurs; see [1mLI [22m([1m\n[.R][22m).

     [1mLsp      [22mconfigures the base amount of vertical space used  for  separation
              in  the document.  [4mmm[24m applies this spacing to many contexts, some‐
              times with multipliers; see [1mDS[22m, [1mFS[22m, [1mH[22m, [1mLI[22m, and [1mP  [22m([4mtroff[24m  devices:
              [1m0.5v[22m; [4mnroff[24m devices: [1m1v[22m).

     [1mN        [22mconfigures  the  header and footer placements used by [1mPH[22m.  The de‐
              fault footer is empty.  If “section-page” numbering  is  selected,
              the  default  header  becomes empty and the default footer becomes
              “[4mx[24m-[4my[24m”, where [4mx[24m is is the section number (the number of the current
              first-level heading) and [4my[24m the page  number  within  the  section.
              The  following  values  are recognized; for finer control, see [1mPH[22m,
              [1mPF[22m, [1mEH[22m, [1mEF[22m, [1mOH[22m, and [1mOF[22m, and registers [1mSectf [22mand [1mSectp[22m.  Value 5 is
              a [4mgroff[24m [4mmm[24m extension ([1m0[22m).

              [1mValue   Effect[0m
              0       Set header on all pages.
              1       Move header to footer on page 1.
              2       Omit header on page 1.
              3       Use “section-page” numbering style on all pages.
              4       Omit header on all pages.
              5       Use “section-page” and “section-figure” numbering style on
                      all pages.

     [1mNp       [22mnumbers paragraphs with a leading mark in the  format  [4ms[24m.[4mp[24m,  where
              [4ms[24m  is is first-level heading number and [4mp[24m is the paragraph number,
              starting at 1; see [1mH [22mand [1mP [22m(Boolean-valued; [1m0[22m).

     [1mO        [22mdefines the page offset of the document, and must be set from  the
              command  line.   A  scaling  unit should be appended.  The default
              is [1m.75i [22mon terminal devices.  On typesetters, it is [1m.963i  [22mor  set
              to [1m1i [22mby the [4mpapersize.tmac[24m package; see ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\.

     [1mOc       [22msuppresses  the  appearance  of  page numbers in the table of con‐
              tents; see [1mTC [22m(Boolean-valued; [1m0[22m).

     [1mOf       [22mselects a separator format within equation, exhibit,  figure,  and
              table  captions;  see  [1mEC[22m, [1mEX[22m, [1mFG[22m, and [1mTB[22m.  The punctuation in the
              separator is either a dot or the [1mEM [22mstring.  The following  values
              are recognized; the spaces shown are unpaddable ([1m0[22m).

              [1mValue   Effect[0m
              0       ".  "
              1       " —— "

     [1mP        [22minterpolates the current page number; it is the same as register [1m%[0m
              except when “section-page” numbering is enabled.

     [1mPi       [22mconfigures  the  indentation (in ens) applied to the first line of
              an unnumbered paragraph that has such (see [1mP[22m); and the text inden‐
              tation of non-enumerated list items; that is, to items in [1mBL[22m, [1mBVL[22m,
              [1mDL[22m, and [1mVL [22mlists (but not [1mML[22m), and in [1mLB [22mlists whose [4mtype[24m argument
              is zero or less ([1m5[22m).

     [1mPgps     [22mcauses the type size and vertical spacing set by  [1mS  [22mto  apply  to
              headers  and  footers,  overriding  the  [1mHP [22mstring.  If not set, [1mS[0m
              calls affect headers and footers only when followed by [1mPH[22m, [1mPF[22m, [1mOH[22m,
              [1mEH[22m, [1mOF[22m, or [1mEF [22mcalls (Boolean-valued; [1m1[22m).

     [1mPs       [22mis multiplied by register [1mLsp [22mto vertically  separate  paragraphs;
              see [1mP [22m([1m1[22m).

     [1mPt       [22mdetermines  when  a  first-line  indentation is applied to a para‐
              graph; see [1mP [22m([1m0[22m).

              [1mValue   Effect[0m
              0       never
              1       always
              2       always, except immediately after [1mH[22m, [1mHU[22m, [1mDE[22m, or [1mLE[0m

     [1mRef      [22mis used internally to control ]8;;man:mmroff(1)\[4mmmroff[24m(1)]8;;\'s two-pass approach to in‐
              dex and reference management; see [1mIND[22m, [1mINDP[22m, [1mINITI[22m, [1mINITR[22m, and [1mPIC[0m
              (Boolean-valued; [1m0[22m).

     [1mRfnum    [22mis an auto-incrementing reference counter; see [1mRS[22m.  [4mgroff[24m [4mmm[24m  rec‐
              ognizes [1m:R [22mas an alias of [1mRfnum [22mfor DWB compatibility.

     [1mRfstyle  [22mdetermines  the  format  of the reference number in the [1mRf [22mstring.
              [4mgroff[24m [4mmm[24m maps [1m0 [22mto [1m1 [22min [4mnroff[24m mode and [1m2 [22min [4mtroff[24m mode ([1m0[22m).

              [1mValue   Meaning[0m
              0       automatic
              1       bracketed
              2       superscripted
              3       bracketed and superscripted

              Changes to [1mRfstyle[22m's value may not  take  effect  until  the  next
              heading or paragraphing macro call.

     [1mRpej     [22mconfigures  the  default page ejection policy for reference pages;
              see [1mRP [22m([1m0[22m).

              [1mValue   Effect[0m
              0       Break the page before and after the reference list.
              1       Suppress page break after the list.
              2       Suppress page break before the list.
              3       Suppress page breaks before and after the list.

     [1mS        [22mdefines the type size for the document, and must be set  from  the
              command  line.   A  scaling  unit should be appended; [1mp [22mis typical
              ([1m10p[22m).

     [1mSectf    [22mselects the “section-figure” numbering style.  Its  default  is  [1m0[0m
              unless  register  [1mN  [22mis set to [1m5 [22mat the command line (Boolean-val‐
              ued).

     [1mSectp    [22mselects the “section-page” numbering style.  Its default is [1m0  [22mun‐
              less register [1mN [22mis set to [1m3 [22mor [1m5 [22mat the command line (Boolean-val‐
              ued).

     [1mSi       [22mconfigures the amount of display indentation in ens; see [1mDS [22m([1m5[22m).

     [1mTb       [22mis an auto-incrementing table counter; see [1mTB[22m.

     [1mV        [22mdefines  the  vertical  spacing  for the document, and must be set
              from the command line.  A scaling unit should be  appended;  [1mp  [22mis
              typical.   The  default vertical spacing is 120% of the type size.
              This register is a [4mgroff[24m [4mmm[24m extension.

     [1mVerbin   [22mconfigures the amount of indentation for  verbatim  displays  when
              indentation is selected; see [1mVERBON [22m([1m5n[22m).

     [1mW        [22mdefines  the  “width”  of  the document (that is, the length of an
              output line with no indentation); it must be set from the  command
              line.   A  scaling  unit should be appended.  The default is [1m6i [22mor
              assigned by the [4mpapersize.tmac[24m package; see ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\.

   [1mInternals[0m
     The argument (if any) to a [1mCOVER [22mor [1mMT [22mcall determines the file that  [4mgroff[0m
     [4mmm[24m loads to configure the document's layout; see section “Files” below.

     [1mLT[22m's  behavior  depends  on the [4mstyle[24m argument given to it; it calls macros
     with names suffixed accordingly.  It is therefore possible to define  addi‐
     tional letter types, either in the territory-specific macro file, or as lo‐
     cal  additions.   [1mLT [22msets the registers [1mPt [22mand [1mPi [22mto 0 and 5, respectively.
     (DWB used a value of 3 for [1mPi[22m.)  It then calls an initialization macro cor‐
     responding to the type.  Define the following macros to support a new  let‐
     ter type.

     [1mlet@init_[4m[22mtype[0m
            initializes any registers and other data needed by the letter type.

     [1mlet@head_[4m[22mtype[0m
            formats  the  letterhead;  it  is  called  instead of the usual page
            header macro.  Its definition should remove the alias [1mlet@header [22mun‐
            less the letterhead is desired on subsequent pages.

     [1mlet@sg_[4m[22mtype[24m [4mname[24m [4mtitle[24m [4mn[24m [4mis-final[24m [[4mSG-arg[24m ...]
            is called by [1mSG [22monly for [1mLT [22mletters; [1mMT  [22mmemoranda  implement  their
            own  signature  processing.   [4mname[24m  and  [4mtitle[24m are specified through
            [1mWA[22m/[1mWE[22m.  [4mn[24m is the index of the [4mn[24mth writer, and [4mis-final[24m is  true  for
            the  last writer to be listed.  Further [1mSG [22marguments are appended to
            the signature line.

     [1mlet@fc_[4m[22mtype[24m [4mclosing[0m
            is called by [1mFC[22m, and takes the formal closing as its argument.

     [1mLO [22mimplements letter options.  It requires that a string named  [1mLet[4m[22mtype[24m  be
     defined,  where  [4mtype[24m is the letter type.  [1mLO [22mthen assigns its second argu‐
     ment ([4mvalue[24m) to the string [1mlet*lo-[4m[22mtype[24m.

[1mFiles[0m
     [4m/usr/share/groff/1.24.0/tmac/m.tmac[0m
            is the [4mgroff[24m implementation of the memorandum macros.

     [4m/usr/share/groff/1.24.0/tmac/mm.tmac[0m
            is a wrapper enabling the package to be loaded with the  option  “[1m-m[0m
            [1mmm[22m”.

     [4m/usr/share/groff/1.24.0/tmac/refer-mm.tmac[0m
            implements ]8;;man:refer(1)\[4mrefer[24m(1)]8;;\ support for [4mmm[24m.

     [4m/usr/share/groff/1.24.0/tmac/mm/ms.cov[0m
            implements an [4mms[24m-like cover page.

     [4m/usr/share/groff/1.24.0/tmac/mm/0.MT[0m
            implements memorandum types 0–3 and 6.

     [4m/usr/share/groff/1.24.0/tmac/mm/4.MT[0m
            implements memorandum type 4.

     [4m/usr/share/groff/1.24.0/tmac/mm/5.MT[0m
            implements memorandum type 5.

     [4m/usr/share/groff/1.24.0/tmac/mm/locale[0m
            performs any (further) desired localization if present.

     [4m/usr/share/doc/groff-1.24.0/examples/letter.mm[0m
            illustrates features of the [1mLT [22mletter formats.

     [4m/usr/share/doc/groff-1.24.0/examples/memorandum.mm[0m
            illustrates features of the [1mMT [22mmemorandum formats.

     [4m/usr/share/doc/groff-1.24.0/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.0                       2026-02-23                        [4mgroff_mm[24m(7)
────────────────────────────────────────────────────────────────────────────────
[4mgroff_mmse[24m(7)            Handbok för diverse information           [4mgroff_mmse[24m(7)

[1mNamn[0m
     groff_mmse - svenska ”memorandum” makro för GNU [4mroff[0m

[1mSyntax[0m
     [1mgroff -mmse [22m[[4mflaggor[24m ...] [[4mfiler[24m ...]
     [1mgroff -m mmse [22m[[4mflaggor[24m ...] [[4mfiler[24m ...]

[1mBeskrivning[0m
     [4mmmse[24m  är  en svensk variant av [4mmm[24m. Alla texter är översatta. En A4 sida får
     text som är 13 cm bred, 3,5 cm indragning samt är 28,5 cm  hög.  Det  finns
     stöd  för  brevuppställning enligt svensk standard för vänster och högerju‐
     sterad text.

     [1mCOVER [22mkan använda [4mse_ms[24m som argument. Detta ger ett  svenskt  försättsblad.
     Se ]8;;man:groff_mm(7)\[4mgroff_mm[24m(7)]8;;\ för övriga detaljer.

[1mBrev[0m
     Tillgängliga brevtyper:

     [1m.LT SVV[0m
            Vänsterställd löptext med adressat i position T0 (vänsterställt).

     [1m.LT SVH[0m
            Högerställd  löptext  med  adressat i position T4 (passar fönsterku‐
            vert).

     Följande extra LO-variabler används.

     [1m.LO DNAMN [4m[22mnamn[0m
            Anger dokumentets namn.

     [1m.LO MDAT [4m[22mdatum[0m
            Mottagarens datum, anges under [1mErt datum: [22m([1mLetMDAT[22m).

     [1m.LO BIL [4m[22msträng[0m
            Anger bilaga, nummer eller sträng med [1mBilaga [22m([1mLetBIL[22m) som prefix.

     [1m.LO KOMP [4m[22mtext[0m
            Anger kompletteringsuppgift.

     [1m.LO DBET [4m[22mbeteckning[0m
            Anger dokumentbeteckning eller dokumentnummer.

     [1m.LO BET [4m[22mbeteckning[0m
            Anger beteckning (ärendebeteckning i form av diarienummer eller lik‐
            nande).

     [1m.LO SIDOR [4m[22mantal[0m
            Anger totala antalet sidor och skrivs ut efter sidnumret inom paren‐
            teser.

     Om makrot [1m.TP [22mär definierat anropas det efter utskrift av brevhuvudet.  Där
     lägger man lämpligen in postadress och annat som brevfot.

[1mSkrivet av[0m
     ]8;;mailto:Jorgen.Hagg@axis.se\Jörgen Hägg]8;;\, Lund, Sweden

[1mFiler[0m
     [4m/usr/share/groff/1.24.0/tmac/mse.tmac[0m

     [4m/usr/share/groff/1.24.0/tmac/mm/se_[24m*[4m.cov[0m

[1mSe också[0m
     ]8;;man:groff_mm(7)\[4mgroff_mm[24m(7)]8;;\

groff 1.24.0                       2025-12-30                      [4mgroff_mmse[24m(7)
────────────────────────────────────────────────────────────────────────────────
[4mgroff_mom[24m(7)            Miscellaneous Information Manual            [4mgroff_mom[24m(7)

[1mName[0m
     groff_mom - modern macros for document composition with GNU [4mroff[0m

[1mSynopsis[0m
     [1mgroff -mom [22m[[4moption[24m ...] [[4mfile[24m ...]
     [1mgroff -m mom [22m[[4moption[24m ...] [[4mfile[24m ...]

[1mDescription[0m
     [4mmom[24m  is  a macro set for [4mgroff[24m, designed primarily to prepare documents for
     PDF and PostScript output.  [4mmom[24m provides macros in two categories: typeset‐
     ting and document processing.  The former provide access to  [4mgroff[24m's  type‐
     setting  capabilities  in  ways that are simpler to master than [4mgroff[24m's re‐
     quests and escape sequences.  The latter provide highly customizable markup
     tags that allow the user to design and  output  professional-looking  docu‐
     ments with a minimum of typesetting intervention.

     Files  processed  with  ]8;;man:pdfmom(1)\[4mpdfmom[24m(1)]8;;\ produce PDF documents.  The documents in‐
     clude a PDF outline that appears in the navigation pane panel  of  document
     viewers, and may contain clickable internal and external links.

     Normally,  [4mgroff[24m's  native  PDF  driver, ]8;;man:gropdf(1)\[4mgropdf[24m(1)]8;;\, is used to generate the
     output.  When [4mpdfmom[24m is given the “[1m-T ps[22m” option, it  still  produces  PDF,
     but  processing is delegated to [4mpdfroff[24m, which uses [4mgroff[24m's PostScript dri‐
     ver, ]8;;man:grops(1)\[4mgrops[24m(1)]8;;\.  Not all PDF features are available when [1m-T ps [22mis given; its
     primary use is to allow processing of files with  embedded  PostScript  im‐
     ages.

     Files processed with [1mgroff -mom [22m(or [1m-m mom[22m) format for the device specified
     with  the  [1m-T  [22moption.  (In this installation, [1mps [22mis the default output de‐
     vice.)

     [4mmom[24m comes with her own comprehensive documentation in HTML.  A PDF  manual,
     “Producing PDFs with [4mgroff[24m and [4mmom[24m”, discusses preparation of PDF documents
     with [4mmom[24m in detail.

[1mFiles[0m
     [4m/usr/share/groff/1.24.0/tmac/mom.tmac[0m
            is  a  wrapper enabling the package to be loaded with the option “[1m-m[0m
            [1mmom[22m”.

     [4m/usr/share/groff/1.24.0/tmac/om.tmac[0m
            implements the package.

     [4m/usr/share/doc/groff-1.24.0/html/mom/toc.html[0m
            is the entry point to the HTML documentation.

     [4m/usr/share/doc/groff-1.24.0/pdf/mom-pdf.pdf[0m
            is “Producing PDFs with [4mgroff[24m and [4mmom[24m”,  by  Deri  James  and  Peter
            Schaffter.

     [4m/usr/share/doc/groff-1.24.0/examples/mom/[24m*[4m.mom[0m
            are examples of [4mmom[24m usage.

[1mReference[0m
   [1mEscape sequences[0m
     [1m\*[[4m[22m<colorname>[24m[1m][0m
            begin using an initialized colour inline

     [1m\*[BCK [4m[22mn[24m[1m][0m
            move backward in a line

     [1m\*[BOLDER][0m
            invoke pseudo bold inline (related to macro [1m.SETBOLDER[22m)

     [1m\*[BOLDERX][0m
            off pseudo bold inline (related to macro [1m.SETBOLDER[22m)

     [1m\*[BU [4m[22mn[24m[1m][0m
            move  characters  pairs  closer  together  inline  (related to macro
            [1m.KERN[22m)

     [1m\*[COND][0m
            invoke pseudo condensing inline (related to macro [1m.CONDENSE[22m)

     [1m\*[CONDX][0m
            off pseudo condensing inline (related to macro [1m.CONDENSE[22m)

     [1m\*[CONDSUP][22m...[1m\*[CONDSUPX][0m
            pseudo-condensed superscript

     [1m\*[DOWN [4m[22mn[24m[1m][0m
            temporarily move downward in a line

     [1m\*[EN-MARK][0m
            mark initial line of a range of line numbers (for use with line num‐
            bered endnotes)

     [1m\*[EXT][0m
            invoke pseudo extending inline (related to macro [1m.EXTEND[22m)

     [1m\*[EXTX][0m
            off pseudo condensing inline (related to macro [1m.EXTEND[22m)

     [1m\*[EXTSUP][22m...[1m\*[EXTSUPX][0m
            pseudo extended superscript

     [1m\*[FU [4m[22mn[24m[1m][0m
            move characters pairs further apart inline (related to macro [1m.KERN[22m)

     [1m\*[FWD [4m[22mn[24m[1m][0m
            move forward in a line

     [1m\*[LEADER][0m
            insert leaders at the end of a line

     [1m\*[RULE][0m
            draw a full measure rule

     [1m\*[SIZE [4m[22mn[24m[1m][0m
            change the point size inline (related to macro [1m.PT_SIZE[22m)

     [1m\*[SLANT][0m
            invoke pseudo italic inline (related to macro [1m.SETSLANT[22m)

     [1m\*[SLANTX][0m
            off pseudo italic inline (related to macro [1m.SETSLANT[22m)

     [1m\*[ST[4m[22m<n>[24m[1m][22m...[1m\*[ST[4m[22m<n>[24m[1mX][0m
            string tabs (mark tab positions inline)

     [1m\*[SUP][22m...[1m\*[SUPX][0m
            superscript

     [1m\*[TB+][0m
            inline escape for [1m.TN [22m([4mTab[24m [4mNext[24m)

     [1m\*[UL][22m...[1m\*[ULX][0m
            invoke underlining inline (fixed width fonts only)

     [1m\*[UP [4m[22mn[24m[1m][0m
            temporarily move upward in a line

   [1mMacros[0m
     [1m.AUTOLEAD[0m
            set the linespacing relative to the point size

     [1m.B_MARGIN[0m
            set a bottom margin

     [1m.BR    [22mbreak a justified line

     [1m.CENTER[0m
            set line-by-line quad centre

     [1m.CONDENSE[0m
            set the amount to pseudo condense

     [1m.EL    [22mbreak a line without advancing on the page

     [1m.EXTEND[0m
            set the amount to pseudo extend

     [1m.FALLBACK_FONT[0m
            establish a fallback font (for missing fonts)

     [1m.FAM   [22malias to [1m.FAMILY[0m

     [1m.FAMILY [4m[22m<family>[0m
            set the [4mfamily[24m [4mtype[0m

     [1m.FT    [22mset the font style (roman, italic, etc.)

     [1m.HI [ [4m[22m<measure>[24m [1m][0m
            hanging indent

     [1m.HY    [22mautomatic hyphenation on/off

     [1m.HY_SET[0m
            set automatic hyphenation parameters

     [1m.IB [ [4m[22m<left[24m [4mmeasure>[24m [4m<right[24m [4mmeasure>[24m [1m][0m
            indent both

     [1m.IBX [ CLEAR ][0m
            exit indent both

     [1m.IL [ [4m[22m<measure>[24m [1m][0m
            indent left

     [1m.ILX [ CLEAR ][0m
            exit indent left

     [1m.IQ [ CLEAR ][0m
            quit any/all indents

     [1m.IR [ [4m[22m<measure>[24m [1m][0m
            indent right

     [1m.IRX [ CLEAR ][0m
            exit indent right

     [1m.JUSTIFY[0m
            justify text to both margins

     [1m.KERN  [22mautomatic character pair kerning on/off

     [1m.L_MARGIN[0m
            set a left margin (page offset)

     [1m.LEFT  [22mset line-by-line quad left

     [1m.LL    [22mset a line length

     [1m.LS    [22mset a linespacing (leading)

     [1m.PAGE  [22mset explicit page dimensions and margins

     [1m.PAGEWIDTH[0m
            set a custom page width

     [1m.PAGELENGTH[0m
            set a custom page length

     [1m.PAPER [4m[22m<paper_type>[0m
            set common paper sizes (letter, A4, etc)

     [1m.PT_SIZE[0m
            set the point size

     [1m.QUAD  [22m"justify" text left, centre, or right

     [1m.R_MARGIN[0m
            set a right margin

     [1m.RIGHT[0m
            set line-by-line quad right

     [1m.SETBOLDER[0m
            set the amount of emboldening

     [1m.SETSLANT[0m
            set the degree of slant

     [1m.SPREAD[0m
            force justify a line

     [1m.SS    [22mset the sentence space size

     [1m.T_MARGIN[0m
            set a top margin

     [1m.TI [ [4m[22m<measure>[24m [1m][0m
            temporary left indent

     [1m.WS    [22mset the minimum word space size

[1mDocumentation of details[0m
   [1mDetails of inline escape sequences in alphabetical order[0m
     [1m\*[[4m[22m<colorname>[24m[1m][0m
            begin using an initialized colour inline

     [1m\*[BCK [4m[22mn[24m[1m][0m
            move backward in a line

     [1m\*[BOLDER][0m
     [1m\*[BOLDERX][0m
            Emboldening on/off

            [1m\*[BOLDER] [22mbegins emboldening type.  [1m\*[BOLDERX] [22mturns  the  feature
            off.   Both  are inline escape sequences; therefore, they should not
            appear as separate lines, but rather be embedded in text lines, like
            this:
                   Not [1m\*[BOLDER][22meverything[1m\*[BOLDERX] [22mis as it seems.

            Alternatively, if you wanted the whole line emboldened,  you  should
            do
                   [1m\*[BOLDER][22mNot everything is as it seems.[1m\*[BOLDERX][0m
            Once [1m\*[BOLDER] [22mis invoked, it remains in effect until turned off.

            Note:   If   you're   using  the  document  processing  macros  with
            [1m.PRINTSTYLE TYPEWRITE[22m, [4mmom[24m ignores [1m\*[BOLDER] [22mrequests.

     [1m\*[BU [4m[22mn[24m[1m][0m
            move characters pairs  closer  together  inline  (related  to  macro
            [1m.KERN[22m)

     [1m\*[COND][0m
     [1m\*[CONDX][0m
            Pseudo-condensing on/off

            [1m\*[COND] [22mbegins pseudo-condensing type.  [1m\*[CONDX] [22mturns the feature
            off.   Both  are inline escape sequences; therefore, they should not
            appear as separate lines, but rather be embedded in text lines, like
            this:
                   [1m\*[COND][4m[22mNot[24m [4meverything[24m [4mis[24m [4mas[24m [4mit[24m [4mseems.[24m[1m\*[CONDX][0m
            [1m\*[COND] [22mremains in effect until you turn it off with [1m\*[CONDX][22m.

            IMPORTANT: You must turn [1m\*[COND] [22moff before making any  changes  to
            the  point  size of your type, either via the [1m.PT_SIZE [22mmacro or with
            the [1m\s [22minline escape sequence.  If you wish the new point size to be
            pseudo-condensed,  simply  reinvoke  [1m\*[COND]  [22mafterward.   Equally,
            [1m\*[COND]  [22mmust be turned off before changing the condense percentage
            with [1m.CONDENSE[22m.

            Note:  If  you're  using  the  document   processing   macros   with
            [1m.PRINTSTYLE TYPEWRITE[22m, [4mmom[24m ignores [1m\*[COND] [22mrequests.

     [1m\*[CONDSUP][22m...[1m\*[CONDSUPX][0m
            pseudo-condensed superscript

     [1m\*[DOWN [4m[22mn[24m[1m][0m
            temporarily move downward in a line

     [1m\*[EN-MARK][0m
            mark initial line of a range of line numbers (for use with line num‐
            bered endnotes)

     [1m\*[EXT][0m
     [1m\*[EXTX][0m
            Pseudo-extending on/off

            [1m\*[EXT]  [22mbegins  pseudo-extending  type.  [1m\*[EXTX] [22mturns the feature
            off.  Both are inline escape sequences; therefore, they  should  not
            appear as separate lines, but rather be embedded in text lines, like
            this:
                   [1m\*[EXT][4m[22mNot[24m [4meverything[24m [4mis[24m [4mas[24m [4mit[24m [4mseems.[24m[1m\*[EXTX][0m
            [1m\*[EXT] [22mremains in effect until you turn it off with [1m\*[EXTX][22m.

            IMPORTANT:  You  must  turn [1m\*[EXT] [22moff before making any changes to
            the point size of your type, either via the [1m.PT_SIZE [22mmacro  or  with
            the [1m\s [22minline escape sequence.  If you wish the new point size to be
            [4mpseudo-extended[24m,   simply   reinvoke  [1m\*[EXT]  [22mafterward.   Equally,
            [1m\*[EXT] [22mmust be turned off before  changing  the  extend  percentage
            with [1m.EXTEND[22m.

            Note:   If  you  are  using  the  document  processing  macros  with
            [1m.PRINTSTYLE TYPEWRITE[22m, [4mmom[24m ignores [1m\*[EXT] [22mrequests.

     [1m\*[EXTSUP][22m...[1m\*[EXTSUPX][0m
            pseudo extended superscript

     [1m\*[FU [4m[22mn[24m[1m][0m
            move characters pairs further apart inline (related to macro [1m.KERN[22m)

     [1m\*[FWD [4m[22mn[24m[1m][0m
            move forward in a line

     [1m\*[LEADER][0m
            insert leaders at the end of a line

     [1m\*[RULE][0m
            draw a full measure rule

     [1m\*[SIZE [4m[22mn[24m[1m][0m
            change the point size inline (related to macro [1m.PT_SIZE[22m)

     [1m\*[SLANT][0m
     [1m\*[SLANTX][0m
            Pseudo italic on/off

            [1m\*[SLANT] [22mbegins [4mpseudo-italicizing[24m [4mtype[24m.  [1m\*[SLANTX] [22mturns the fea‐
            ture off.  Both are inline escape sequences; therefore, they  should
            not  appear as separate lines, but rather be embedded in text lines,
            like this:
                   Not [1m\*[SLANT][22meverything[1m\*[SLANTX] [22mis as it seems.

            Alternatively, if you wanted the whole line [4mpseudo-italicized[24m, you'd
            do
                   [1m\*[SLANT][22mNot everything is as it seems.[1m\*[SLANTX][0m

            Once [1m\*[SLANT] [22mis invoked, it remains in effect until turned off.

            Note:  If  you're  using  the  document   processing   macros   with
            [1m.PRINTSTYLE TYPEWRITE[22m, [4mmom[24m underlines pseudo-italics by default.  To
            change this behaviour, use the special macro [1m.SLANT_MEANS_SLANT[22m.

     [1m\*[ST[4m[22m<number>[24m[1m][22m...[1m\*[ST[4m[22m<number>[24m[1mX][0m
            Mark positions of string tabs

            The  [4mquad[24m direction must be [1mLEFT [22mor [1mJUSTIFY [22m(see [1m.QUAD [22mand [1m.JUSTIFY[22m)
            or the [4mno-fill[24m [4mmode[24m set to [1mLEFT [22min order for these inlines to  func‐
            tion properly.  Please see [4mIMPORTANT[24m, below.

            String  tabs  need to be marked off with inline escape sequences be‐
            fore being set up with the [1m.ST [22mmacro.  Any input  line  may  contain
            string  tab  markers.  [4m<number>[24m, above, means the numeric identifier
            of the tab.

            The following shows a sample input line with string tab markers.
                   [1m\*[ST1][22mDe minimus[1m\*[ST1X][22mnon curat[1m\*[ST2][22mlex[1m\*[ST2X][22m.

            String [4mtab[24m [4m1[24m begins at the start of the line and ends after the word
            [4mtime[24m.  String [4mtab[24m [4m2[24m starts at [4mgood[24m and ends after [4mmen[24m.   [4mInline[24m  [4mes‐[0m
            [4mcape[24m  [4msequences[24m  (e.g.,  [4mfont[24m  or  [4mpoint[24m [4msize[24m [4mchanges[24m, or horizontal
            movements, including padding) are taken into account when [4mmom[24m deter‐
            mines the [4mposition[24m and [4mlength[24m of [4mstring[24m [4mtabs[24m.

            Up to nineteen string tabs may be marked (not necessarily all on the
            same line, of course), and they must be numbered between 1 and 19.

            Once string tabs have been marked in input lines, they  have  to  be
            [4mset[24m with [1m.ST[22m, after which they may be called, by number, with [1m.TAB[22m.

            Note:  Lines  with  string  tabs marked off in them are normal input
            lines, i.e. they get printed, just like any input line.  If you want
            to set up string tabs without the line  printing,  use  the  [1m.SILENT[0m
            macro.

            [4mIMPORTANT:[24m  Owing  to  the way [4mgroff[24m processes input lines and turns
            them into output lines, it is not possible for [4mmom[24m to [4mguess[24m the cor‐
            rect starting position of string tabs marked off in lines  that  are
            centered or set flush right.

            Equally,  she  cannot guess the starting position if a line is fully
            justified and broken with [1m.SPREAD[22m.

            In other words, in order to use string tabs, [1mLEFT  [22mmust  be  active,
            or,  if  [1m.QUAD  LEFT  [22mor  [1mJUSTIFY  [22mare active, the line on which the
            [4mstring[24m [4mtabs[24m are marked must be broken [4mmanually[24m  with  [1m.BR  [22m(but  not
            [1m.SPREAD[22m).

            To  circumvent  this  behaviour, I recommend using the [1mPAD [22mto set up
            string tabs in centered or flush right lines.  Say, for example, you
            want to use a [4mstring[24m [4mtab[24m to [4munderscore[24m the text of a  centered  line
            with a rule.  Rather than this,
                   [1m.CENTER[0m
                   [1m\*[ST1]A line of text\*[ST1X]\c[0m
                   [1m.EL[0m
                   [1m.ST 1[0m
                   [1m.TAB 1[0m
                   [1m.PT_SIZE 24[0m
                   [1m.ALD 3p[0m
                   [1m\*[RULE][0m
                   [1m.RLD 3p[0m
                   [1m.TQ[0m
            you should do:
                   .QUAD CENTER
                   .PAD "#\*[ST1]A line of text\*[ST1X]#"
                   .EL
                   .ST 1
                   .TAB 1
                   .PT_SIZE 24
                   .ALD 3p
                   \" You can't use \*[UP] or \*[DOWN] with \*[RULE].
                   .RLD 3p
                   .TQ

     [1m\*[SUP][22m...[1m\*[SUPX][0m
            superscript

     [1m\*[TB+][0m
            Inline escape for [1m.TN [22m([4mTab[24m [4mNext[24m)

     [1m\*[UL][22m...[1m\*[ULX][0m
            invoke underlining inline (fixed width fonts only)

     [1m\*[UP [4m[22mn[24m[1m][0m
            temporarily move upward in a line

   [1mDetails of macros in alphabetical order[0m
     [1m.AUTOLEAD[0m
            set the linespacing relative to the point size

     [1m.B_MARGIN [4m[22m<bottom[24m [4mmargin>[0m
            Bottom Margin

            Requires a unit of measure

            [1m.B_MARGIN  [22msets  a nominal position at the bottom of the page beyond
            which you don't want your type to go.  When  the  bottom  margin  is
            reached,  [4mmom[24m  starts a new page.  [1m.B_MARGIN requires a unit of mea‐[0m
            [1msure.  [22mDecimal fractions are allowed.  To set a nominal bottom  mar‐
            gin of 3/4 inch, enter
                   [1m.B_MARGIN .75i[0m

            Obviously,  if you haven't spaced the type on your pages so that the
            last lines fall perfectly at the bottom margin, the margin will vary
            from page to page.  Usually, but not always, the last line  of  type
            that  fits  on a page before the bottom margin causes mom to start a
            new page.

            Occasionally, owing to a peculiarity in [4mgroff[24m, an  extra  line  will
            fall  below the nominal bottom margin.  If you're using the document
            processing macros, this is unlikely to happen; the document process‐
            ing macros are very hard-nosed about aligning bottom margins.

            Note: The meaning of [1m.B_MARGIN [22mis slightly different when you're us‐
            ing the document processing macros.

     [1m.FALLBACK_FONT [4m[22m<fallback[24m [4mfont>[24m [1m[ ABORT | WARN ][0m
            Fallback Font

            In the event that you pass an invalid argument to  [1m.FAMILY  [22m(i.e.  a
            non-existent  [4mfamily[24m),  [4mmom[24m,  by  default,  uses  the [4mfallback[24m [4mfont[24m,
            [1mCourier Medium Roman [22m([1mCR[22m), in  order  to  continue  processing  your
            file.

            If  you'd prefer another [4mfallback[24m [4mfont[24m, pass [1m.FALLBACK_FONT [22mthe full
            [4mfamily+font[24m [4mname[24m of the [4mfont[24m you'd  like.   For  example,  if  you'd
            rather the [4mfallback[24m [4mfont[24m were [1mTimes Roman Medium Roman[22m,
                   [1m.FALLBACK_FONT TR[0m
            would do the trick.

            [1mMom [22missues a warning whenever a [4mfont[24m [4mstyle[24m [4mset[24m with [1m.FT [22mdoes not ex‐
            ist,  either because you haven't registered the style or because the
            [4mfont[24m [4mstyle[24m does not exist in the current [4mfamily[24m  [4mset[24m  with  [1m.FAMILY[22m.
            By  default,  [1mmom [22mthen aborts, which allows you to correct the prob‐
            lem.

            If you'd prefer that [1mmom [22mnot abort on non-existent [4mfonts[24m, but rather
            continue  processing  using  a   [4mfallback[24m   [4mfont[24m,   you   can   pass
            [1m.FALLBACK_FONT  [22mthe  argument [1mWARN[22m, either by itself, or in conjunc‐
            tion with your chosen [4mfallback[24m [4mfont[24m[1m.[0m

            Some examples of invoking [1m.FALLBACK_FONT[22m:

            [1m.FALLBACK_FONT WARN[0m
                   [4mmom[24m will issue a warning whenever you try to access a non-ex‐
                   istent [4mfont[24m but will continue processing your file  with  the
                   default [4mfallback[24m [4mfont[24m, [1mCourier Medium Roman[22m.

            [1m.FALLBACK_FONT TR WARN[0m
                   [1mmom [22mwill issue a warning whenever you try to access a non-ex‐
                   istent  [4mfont[24m  but  will  continue processing your file with a
                   [4mfallback[24m [4mfont[24m of [1mTimes Roman Medium Roman[22m;  additionally,  [1mTR[0m
                   will be the [4mfallback[24m [4mfont[24m whenever you try to access a [4mfamily[0m
                   that does not exist.

            [1m.FALLBACK_FONT TR ABORT[0m
                   [1mmom  [22mwill  abort  whenever  you  try to access a non-existent
                   [1mfont[22m, and will use the [4mfallback[24m [4mfont[24m [1mTR [22mwhenever you  try  to
                   access  a  [4mfamily[24m  that does not exist.  If, for some reason,
                   you want to  revert  to  [1mABORT[22m,  just  enter  [1m".FALLBACK_FONT[0m
                   [1mABORT" [22mand [4mmom[24m will once again abort on [4mfont[24m [4merrors[24m.

     [1m.FAM [4m[22m<family>[0m
            Type Family, alias of [1m.FAMILY[0m

     [1m.FAMILY [4m[22m<family>[0m
            Type Family, alias of [1m.FAM[0m

            [1m.FAMILY  [22mtakes one argument: the name of the [4mfamily[24m you want.  [4mGroff[0m
            comes with a small set of basic families, each identified by  a  1-,
            2- or 3-letter mnemonic.  The standard families are:
                   [1mA   = Avant Garde[0m
                   [1mBM  = Bookman[0m
                   [1mH   = Helvetica[0m
                   [1mHN  = Helvetica Narrow[0m
                   [1mN   = New Century Schoolbook[0m
                   [1mP   = Palatino[0m
                   [1mT   = Times Roman[0m
                   [1mZCM = Zapf Chancery[0m

            The  argument  you pass to [1m.FAMILY [22mis the identifier at left, above.
            For example, if you want [1mHelvetica[22m, enter
                   [1m.FAMILY H[0m

            Note: The font macro ([1m.FT[22m) lets you specify both the type [4mfamily[24m and
            the desired font with a single macro.  While this saves a  few  key‐
            strokes, I recommend using [1m.FAMILY for [4m[22mfamily[24m, and [1m.FT for [4m[22mfont[24m, ex‐
            cept  where  doing  so is genuinely inconvenient.  [1mZCM[22m, for example,
            only exists in one style: [1mItalic [22m([1mI[22m).

            Therefore,
                   [1m.FT ZCMI[0m
            makes more sense than setting the [4mfamily[24m to [1mZCM[22m,  then  setting  the
            [4mfont[24m to [4mI[24m.

            Additional note: If you are running a [4mgroff[24m version prior to 1.19.2,
            you  must  follow all [1m.FAMILY [22mrequests with a [1m.FT [22mrequest, otherwise
            [4mmom[24m will set all type up to the next [1m.FT  [22mrequest  in  the  fallback
            font.

            When  running [4mgroff[24m 1.19.2 or later, and you call the [1m.FAMILY [22mmacro,
            [4mmom[24m [4mremembers[24m the font style (such as roman or italic) currently  in
            use  (if  the  font style exists in the new [4mfamily[24m) and continues to
            use the same font style in the new family.  For example:
                   [1m.FAMILY BM [4m[22m\"[24m [4mBookman[24m [4mfamily[0m
                   [1m.FT I [4m[22m\"[24m [4mMedium[24m [4mItalic[0m
                   [4m<some[24m [4mtext>[24m [4m\"[24m [4mBookman[24m [4mMedium[24m [4mItalic[0m
                   [1m.FAMILY H [4m[22m\"[24m [4mHelvetica[24m [4mfamily[0m
                   [4m<more[24m [4mtext>[24m [4m\"[24m [4mHelvetica[24m [4mMedium[24m [4mItalic[0m

            However, if the font style does not exist in  the  new  family,  [4mmom[0m
            sets  all  subsequent type in the fallback font (by default, [1mCourier[0m
            [1mMedium Roman[22m) until she encounters a [1m.FT [22mcall that's valid  for  the
            [4mfamily[24m.

            For example, assuming you don't have the font [1mMedium Condensed Roman[0m
            ([4mmom[24m extension [4mCD[24m) in the [4mHelvetica[24m [4mfamily[24m:
                   [1m.FAMILY UN [4m[22m\"[24m [4mUnivers[24m [4mfamily[0m
                   [1m.FT CD [4m[22m\"[24m [4mMedium[24m [4mCondensed[0m
                   [4m<some[24m [4mtext>[24m [4m\"[24m [4mUnivers[24m [4mMedium[24m [4mCondensed[0m
                   [1m.FAMILY H [4m[22m\"[24m [4mHelvetica[24m [4mfamily[0m
                   [4m<more[24m [4mtext>[24m [4m\"[24m [4mCourier[24m [4mMedium[24m [4mRoman![0m

            In  the  above example, you must follow [1m.FAMILY H [22mwith a [1m.FT [22mrequest
            that's valid for [1mHelvetica[22m.

            Please see the Appendices, [4mAdding[24m [4mfonts[24m [4mto[24m [4mgroff[24m, for information on
            adding fonts and families to [4mgroff[24m,[4mas[24mwell[4mas[24mto see a list of the  ex‐
            tensions [4mmom[24m provides to [4mgroff[24m's basic [1mR[22m, [1mI[22m, [1mB[22m, [1mBI [22mstyles.

            Suggestion: When adding [4mfamilies[24m [4mto[24m [4mgroff[24m, I recommend following the
            established  standard  for the naming families and fonts.  For exam‐
            ple, if you add the [1mGaramond [22mfamily, name the font files
                   [1mGARAMONDR[0m
                   [1mGARAMONDI[0m
                   [1mGARAMONDB[0m
                   [1mGARAMONDBI[0m
            [1mGARAMOND then becomes a valid [4m[22mfamily[24m [4mname[24m you can pass  to  [1m.FAMILY[22m.
            (You could, of course, shorten [1mGARAMOND [22mto just [1mG[22m, or [1mGD[22m.)  [1mR[22m, [1mI[22m, [1mB[22m,
            and  [1mBI  [22mafter  [1mGARAMOND [22mare the [4mroman[24m, [4mitalic[24m, [4mbold[24m and [4mbold-italic[0m
            fonts respectively.

     [1m.FONT R | B | BI | [4m[22m<any[24m [4mother[24m [4mvalid[24m [4mfont[24m [4mstyle>[0m
            Alias to [1m.FT[0m

     [1m.FT R | B | BI | [4m[22m<any[24m [4mother[24m [4mvalid[24m [4mfont[24m [4mstyle>[0m
            Set font

            By default, [4mgroff[24m permits [1m.FT [22mto take one of four possible arguments
            specifying the desired font:
                   [1mR = (Medium) Roman[0m
                   [1mI = (Medium) Italic[0m
                   [1mB = Bold (Roman)[0m
                   [1mBI = Bold Italic[0m

            For example, if your [4mfamily[24m is [1mHelvetica[22m, entering
                   [1m.FT B[0m
            will give  you  the  [4mHelvetica[24m  [4mbold[24m  [4mfont[24m.   If  your  [4mfamily[24m  were
            [1mPalatino[22m, you'd get the [4mPalatino[24m [4mbold[24m [4mfont[24m.

            [1mMom [22mconsiderably extends the range of arguments you can pass to [1m.FT[22m,
            making  it  more  convenient  to  add  and access fonts of differing
            weights and shapes within the same family.

            Have a look here for a list of the weight/style  arguments  [4mmom[24m  al‐
            lows.  Be aware, though, that you must have the fonts, correctly in‐
            stalled and named, in order to use the arguments.  (See [4mAdding[24m [4mfonts[0m
            [4mto[24m  [4mgroff[24m  for  instructions and information.)  Please also read the
            [4mADDITIONAL[24m [4mNOTE[24m found in the description of the [1m.FAMILY [22mmacro.

            How [4mmom[24m reacts to an invalid argument to [1m.FT [22mdepends on  which  ver‐
            sion  of  [4mgroff[24m  you're  using.   If your [4mgroff[24m version is 1.19.2 or
            later, [4mmom[24m will issue a warning and, depending on how you've set  up
            the  fallback  font,  either  continue processing using the fallback
            font, or abort (allowing you to correct the  problem).   In  earlier
            versions,  [4mmom[24m  will  silently continue processing, using either the
            fallback font or the font that was in effect prior  to  the  invalid
            [1m.FT [22mcall.

            [1m.FT [22mwill also accept, as an argument, a full [4mfamily[24m and [4mfont[24m [4mname[24m.

            For example,
                   [1m.FT HB[0m
            will set subsequent type in [4mHelvetica[24m [4mBold[24m.

            However,  I  strongly recommend keeping [4mfamily[24m and [4mfont[24m separate ex‐
            cept where doing so is genuinely inconvenient.

            For inline control of [4mfonts[24m, see [4mInline[24m [4mEscapes[24m, font control.

     [1m.HI [ [4m[22m<measure>[24m [1m][0m
            Hanging indent —— the optional argument requires a unit of measure.

            A hanging indent looks like this:
                   The thousand injuries of Fortunato I had borne as best I
                     could, but when he ventured upon insult, I vowed
                     revenge.  You who so well know the nature of my soul
                     will not suppose, however, that I gave utterance to a
                     threat, at length I would be avenged...
            The first line of text [4mhangs[24m outside the [4mleft[24m [4mmargin[24m.

            In order to use [4mhanging[24m [4mindents[24m, you must first have a  [4mleft[24m  [4mindent[0m
            active (set with either [1m.IL [22mor [1m.IB[22m).  [1mMom [22mwill not hang text outside
            the  [4mleft[24m  [4mmargin[24m [4mset[24m with [1m.L_MARGIN [22mor outside the [4mleft[24m [4mmargin[24m of a
            [4mtab[24m.

            The first time you invoke [1m.HI[22m, you must give it a [1mmeasure[22m.   If  you
            want the first line of a paragraph to [4mhang[24m [4mby[24m, say, [4m1[24m [4mpica[24m, do
                   [1m.IL 1P[0m
                   [1m.HI 1P[0m
            Subsequent  invocations  of  [1m.HI [22mdo not require you to supply a [4mmea‐[0m
            [4msure[24m; [4mmom[24m keeps track of the last measure you gave it.

            Generally speaking, you should invoke [1m.HI [22mimmediately prior  to  the
            line  you  want  hung  (i.e. without any intervening control lines).
            And because [4mhanging[24m [4mindents[24m affect only one line, there's no need to
            turn them off.

            [4mIMPORTANT:[24m Unlike [1mIL[22m, [1mIR [22mand [1mIB[22m, measures given to [1m.HI [22mare NOT addi‐
            tive.  Each time you pass a measure to [1m.HI[22m, the measure  is  treated
            literally.  [4mRecipe:[24m A numbered list using [4mhanging[24m [4mindents[0m

            [4mNote:[24m  [4mmom[24m  has  macros  for  setting  lists.  This recipe exists to
            demonstrate the use of [4mhanging[24m [4mindents[24m only.
                   .PAGE 8.5i 11i 1i 1i 1i 1i
                   .FAMILY  T
                   .FT      R
                   .PT_SIZE 12
                   .LS      14
                   .JUSTIFY
                   .KERN
                   .SS 0
                   .IL \w'\0\0.'
                   .HI \w'\0\0.'
                   1.\0The most important point to be considered is whether
                   the answer to the meaning of Life, the Universe, and
                   Everything really is 42.  We have no one's word on the
                   subject except Mr. Adams's.
                   .HI
                   2.\0If the answer to the meaning of Life, the Universe,
                   and Everything is indeed 42, what impact does this have on
                   the politics of representation?  42 is, after all not a
                   prime number.  Are we to infer that prime numbers don't
                   deserve equal rights and equal access in the universe?
                   .HI
                   3.\0If 42 is deemed non-exclusionary, how do we present
                   it as the answer and, at the same time, forestall debate
                   on its exclusionary implications?

            First, we invoke a left indent with a measure equal to the width  of
            2  figures  spaces  plus  a period (using the \w inline escape).  At
            this point, the left indent is active; text afterward would normally
            be indented.  However, we invoke a hanging  indent  of  exactly  the
            same width, which hangs the first line (and first line only!) to the
            left  of  the  indent by the same distance (in this case, that means
            “out to the left margin”).  Because we begin the first line  with  a
            number,  a period, and a figure space, the actual text ([4mThe[24m [4mmost[24m [4mim‐[0m
            [4mportant[24m [4mpoint...[24m) starts at exactly the same spot  as  the  indented
            lines that follow.

            Notice that subsequent invocations of [1m.HI [22mdon't require a [4mmeasure[24m to
            be given.

            Paste the example above into a file and preview it with
                   [1mpdfmom filename.mom | ps2pdf - filename.pdf[0m
            to see hanging indents in action.

     [1m.IB [ [4m[22m<left[24m [4mmeasure>[24m [4m<right[24m [4mmeasure>[24m [1m][0m
            Indent both —— the optional argument requires a unit of measure

            [1m.IB  [22mallows  you  to  set or invoke a left and a right indent at the
            same time.

            At its first invocation, you must supply a measure for both indents;
            at subsequent invocations when you wish to supply  a  measure,  both
            must be given again.  As with [1m.IL [22mand [1m.IR[22m, the measures are added to
            the  values  previously  passed to the macro.  Hence, if you wish to
            change just one of the values, you must give an argument of zero  to
            the other.

            [4mA[24m  [4mword[24m  [4mof[24m [4madvice:[24m If you need to manipulate left and right indents
            separately, use a combination of [1m.IL [22mand [1m.IR [22minstead of [1m.IB[22m.  You'll
            save yourself a lot of grief.

            A [4mminus[24m [4msign[24m may be prepended to  the  arguments  to  subtract  from
            their  current  values.  The \w inline escape may be used to specify
            text-dependent measures, in which case no unit  of  measure  is  re‐
            quired.  For example,
                   [1m.IB \w'margarine' \w'jello'[0m
            left  indents  text by the width of the word [4mmargarine[24m and right in‐
            dents by the width of [4mjello[24m.

            Like [1m.IL [22mand [1m.IR[22m, [1m.IB [22mwith no argument indents by  its  last  active
            values.   See  the  brief explanation of how mom handles indents for
            more details.

            [4mNote:[24m Calling a [4mtab[24m (with [1m.TAB <n>[22m) automatically cancels any active
            indents.

            [4mAdditional[24m [4mnote:[24m Invoking [1m.IB [22mautomatically turns off [1m.IL [22mand [1m.IR[22m.

     [1m.IL [ [4m[22m<measure>[24m [1m][0m
            Indent left —— the optional argument requires a unit of measure

            [1m.IL [22mindents text from the left margin of the page, or if you're in a
            [4mtab[24m, from the left edge of the [4mtab[24m.  Once [4mIL[24m is on, the [4mleft[24m  [4mindent[0m
            is  applied  uniformly to every subsequent line of text, even if you
            change the line length.

            The first time you invoke [1m.IL[22m, you must give it a  measure.   Subse‐
            quent invocations with a measure add to the previous measure.  A mi‐
            nus  sign may be prepended to the argument to subtract from the cur‐
            rent measure.  The [1m\w [22minline escape may be used to specify  a  text-
            dependent  measure,  in  which  case no unit of measure is required.
            For example,
                   [1m.IL \w'margarine'[0m
            indents text by the width of the word [4mmargarine[24m.

            With no argument, [1m.IL [22mindents by its last  active  value.   See  the
            brief explanation of how [4mmom[24m handles indents for more details.

            [4mNote:[24m Calling a [4mtab[24m (with [1m.TAB <n>[22m) automatically cancels any active
            indents.

            [4mAdditional[24m [4mnote:[24m Invoking [1m.IL [22mautomatically turns off [1mIB[22m.

     [1m.IQ [ [4m[22m<measure>[24m [1m][0m
            IQ —— quit any/all indents

            [4mIMPORTANT[24m [4mNOTE:[24m The original macro for quitting all indents was [1m.IX[22m.
            This  usage  has been deprecated in favour of [1mIQ[22m.  [1m.IX [22mwill continue
            to behave as before, but [4mmom[24m will issue a warning to [4mstderr[24m indicat‐
            ing that you should update your documents.

            As a consequence of this change, [1m.ILX[22m, [1m.IRX [22mand [1m.IBX [22mmay now also be
            invoked as [1m.ILQ[22m, [1m.IRQ [22mand [1m.IBQ[22m.  Both forms are acceptable.

            Without an argument, the macros to quit indents merely restore  your
            original margins and line length.  The measures stored in the indent
            macros  themselves are saved so you can call them again without hav‐
            ing to supply a measure.

            If you pass these macros the optional argument [1mCLEAR[22m, they not  only
            restore  your  original  left margin and line length, but also clear
            any values associated with a particular indent style.  The next time
            you need an indent of the same style, you have to supply  a  measure
            again.

            [1m.IQ CLEAR[22m, as you'd suspect, quits and clears the values for all in‐
            dent styles at once.

     [1m.IR [ [4m[22m<measure>[24m [1m][0m
            Indent right —— the optional argument requires a unit of measure

            [1m.IR  [22mindents text from the [4mright[24m [4mmargin[24m of the page, or if you're in
            a [4mtab[24m, from the end of the [4mtab[24m.

            The first time you invoke [1m.IR[22m, you must give it a  measure.   Subse‐
            quent invocations with a measure add to the previous indent measure.
            A  [4mminus[24m  [4msign[24m may be prepended to the argument to subtract from the
            current indent measure.  The \w inline escape may be used to specify
            a text-dependent measure, in which case no [4munit[24m [4mof[24m  [4mmeasure[24m  is  re‐
            quired.  For example,
                   [1m.IR \w'jello'[0m
            indents text by the width of the word [4mjello[24m.

            With  no  argument,  [1m.IR  [22mindents by its last active value.  See the
            brief explanation of how [4mmom[24m handles indents for more details.

            [4mNote:[24m Calling a [4mtab[24m (with [1m.TAB <n>[22m) automatically cancels any active
            indents.

            [4mAdditional[24m [4mnote:[24m Invoking [1m.IR [22mautomatically turns off [1mIB[22m.

     [1m.L_MARGIN [4m[22m<left[24m [4mmargin>[0m
            Left Margin

            L_MARGIN establishes the distance from the left edge of the  printer
            sheet  at  which  you  want  your type to start.  It may be used any
            time, and remains in effect until you enter a new value.

            Left indents and tabs are calculated from  the  value  you  pass  to
            [1m.L_MARGIN[22m,  hence it's always a good idea to invoke it before start‐
            ing any serious typesetting.  A unit of measure is required.   Deci‐
            mal  fractions  are allowed.  Therefore, to set the left margin at 3
            picas (1/2 inch), you'd enter either
                   [1m.L_MARGIN 3P[0m
            or
                   [1m.L_MARGIN .5i[0m

            If you use the macros [1m.PAGE[22m, [1m.PAGEWIDTH [22mor [1m.PAPER  [22mwithout  invoking
            [1m.L_MARGIN  [22m(either  before  or  afterward),  [4mmom[24m  automatically sets
            [1m.L_MARGIN [22mto [4m1[24m [4minch[24m.

            Note: [1m.L_MARGIN [22mbehaves in a special way when you're using the docu‐
            ment processing macros.

     [1m.MCO   [22mBegin multi-column setting.

            [1m.MCO [22m([4mMulti-Column[24m [4mOn[24m) is the [4mmacro[24m you use  to  begin  [4mmulti-column[0m
            [4msetting[24m.   It marks the current baseline as the top of your columns,
            for use later with [1m.MCR[22m.  See the introduction to columns for an ex‐
            planation of [4mmulti-columns[24m and some sample input.

            [4mNote:[24m Do not confuse [1m.MCO [22mwith the [1m.COLUMNS [22mmacro  in  the  document
            processing macros.

     [1m.MCR   [22mOnce  you've turned [4mmulti-columns[24m on (with [1m.MCO[22m), [1m.MCR[22m, at any time,
            returns you to the [4mtop[24m [4mof[24m [4myour[24m [4mcolumns[24m.

     [1m.MCX [ [4m[22m<distance[24m [4mto[24m [4madvance[24m [4mbelow[24m [4mlongest[24m [4mcolumn>[24m [1m][0m
            Optional argument requires a unit of measure.

            Exit multi-columns.

            [1m.MCX [22mtakes you out of any [4mtab[24m you were in (by silently invoking [1m.TQ[22m)
            and advances to the bottom of the longest column.

            Without an argument, [1m.MCX [22madvances [4m1[24m  [4mlinespace[24m  below  the  longest
            column.

            Linespace,  in this instance, is the leading in effect at the moment
            [1m.MCX [22mis invoked.

            If you pass the [4m<distance>[24m argument to [1m.MCX[22m, it advances [4m1[24m [4mlinespace[0m
            below the longest column (see above) [4mPLUS[24m the distance specified  by
            the  argument.   The argument requires a unit of measure; therefore,
            to advance an extra 6 points below where [1m.MCX [22mwould  normally  place
            you, you'd enter
                   [1m.MCX 6p[0m

            [4mNote:[24m  If  you wish to advance a precise distance below the baseline
            of the longest column, use [1m.MCX [22mwith an argument of [1m0 [22m(zero; no [4munit[0m
            [4mof[24m [4mmeasure[24m required) in conjunction with the [1m.ALD [22mmacro, like this:
                   [1m.MCX 0[0m
                   [1m.ALD 24p[0m
            The above advances to precisely [4m24[24m [4mpoints[24m below the baseline of  the
            longest column.

     [1m.NEWPAGE[0m

            Whenever  you want to start a new page, use [1m.NEWPAGE[22m, by itself with
            no argument.  [1mMom [22mwill finish up processing  the  current  page  and
            move you to the top of a new one (subject to the top margin set with
            [1m.T_MARGIN[22m).

     [1m.PAGE [4m[22m<width>[24m [1m[ [4m[22m<length>[24m [1m[ [4m[22m<lm>[24m [1m[ [4m[22m<rm>[24m [1m[ [4m[22m<tm>[24m [1m[ [4m[22m<bm>[24m [1m] ] ] ] ][0m

            All arguments require a unit of measure

            [4mIMPORTANT:[24m  If  you're  using  the document processing macros, [1m.PAGE[0m
            must come after [1m.START[22m.  Otherwise, it should go at  the  top  of  a
            document,  prior  to  any text.  And remember, when you're using the
            document processing macros, top margin and bottom margin mean  some‐
            thing slightly different than when you're using just the typesetting
            macros (see Top and bottom margins in document processing).

            [1m.PAGE  [22mlets  you  establish paper dimensions and page margins with a
            single macro.  The only required argument is page width.   The  rest
            are  optional, but they must appear in order and you can't skip over
            any.  [4m<lm>[24m, [4m<rm>[24m, [4m<tm>[24m and [4m<bm>[24m refer to the left,  right,  top  and
            bottom margins respectively.

            Assuming your page dimensions are 11 inches by 17 inches, and that's
            all you want to set, enter
                   [1m.PAGE 11i 17i[0m
            If  you  want  to  set the left margin as well, say, at 1 inch, [1mPAGE[0m
            would look like this:
                   [1m.PAGE 11i 17i 1i[0m

            Now suppose you also want to set  the  top  margin,  say,  at  1–1/2
            inches.   [4m<tm>[24m  comes  after [4m<rm>[24m in the optional arguments, but you
            can't skip over any arguments, therefore to set the top margin,  you
            must  also  give  a  right  margin.  The [1m.PAGE [22mmacro would look like
            this:
                   .PAGE 11i 17i 1i 1i 1.5i
                                    |   |
                   required right---+   +---top margin
                           margin

            Clearly, [1m.PAGE [22mis best used when you want a convenient way  to  tell
            [4mmom[24m just the dimensions of your printer sheet (width and length), or
            when  you want to tell her everything about the page (dimensions and
            all the margins), for example
                   [1m.PAGE 8.5i 11i 45p 45p 45p 45p[0m
            This sets up an 8½ by  11  inch  page  with  margins  of  45  points
            (5/8-inch) all around.

            Additionally,  if  you  invoke [1m.PAGE [22mwith a top margin argument, any
            macros you invoke after [1m.PAGE [22mwill almost certainly move  the  base‐
            line  of  the  first line of text down by one linespace.  To compen‐
            sate, do
                   [1m.RLD 1v[0m
            immediately before entering any text, or,  if  it's  feasible,  make
            [1m.PAGE [22mthe last macro you invoke prior to entering text.

            Please  read the [4mImportant[24m [4mnote[24m on page dimensions and papersize for
            information on ensuring [4mgroff[24m respects  your  [1m.PAGE  [22mdimensions  and
            margins.

     [1m.PAGELENGTH [4m[22m<length[24m [4mof[24m [4mprinter[24m [4msheet>[0m
            tells  [4mmom[24m  how  long  your  printer  sheet  is.  It works just like
            [1m.PAGEWIDTH[22m.

            Therefore, to tell [4mmom[24m your printer sheet is 11 inches long, you en‐
            ter
                   [1m.PAGELENGTH 11i[0m
            Please read the important note on page dimensions and papersize  for
            information on ensuring [4mgroff[24m respects your [4mPAGELENGTH[24m.

     [1m.PAGEWIDTH [4m[22m<width[24m [4mof[24m [4mprinter[24m [4msheet>[0m

            The argument to [1m.PAGEWIDTH [22mis the width of your printer sheet.

            [1m.PAGEWIDTH  [22mrequires  a  unit of measure.  Decimal fractions are al‐
            lowed.  Hence, to tell [4mmom[24m that the width of your printer  sheet  is
            8½ inches, you enter
                   .PAGEWIDTH 8.5i

            Please  read the Important note on page dimensions and papersize for
            information on ensuring [4mgroff[24m respects your [4mPAGEWIDTH[24m.

     [1m.PAPER [4m[22m<paper[24m [4mtype>[0m
            provides a convenient way to set the page dimensions for some common
            printer sheet sizes.  The argument [4m<paper[24m [4mtype>[24m can be one of:  [1mLET‐[0m
            [1mTER[22m,  [1mLEGAL[22m,  [1mSTATEMENT[22m,  [1mTABLOID[22m, [1mLEDGER[22m, [1mFOLIO[22m, [1mQUARTO[22m, [1mEXECUTIVE[22m,
            [1m10x14[22m, [1mA3[22m, [1mA4[22m, [1mA5[22m, [1mB4[22m, [1mB5[22m.

     [1m.PRINTSTYLE[0m

     [1m.PT_SIZE [4m[22m<size[24m [4mof[24m [4mtype[24m [4min[24m [4mpoints>[0m
            Point size of type, does not require a [4munit[24m [4mof[24m [4mmeasure[24m.

            [1m.PT_SIZE [22m([4mPoint[24m [4mSize[24m) takes  one  argument:  the  [4msize[24m  [4mof[24m  [4mtype[24m  in
            [4mpoints[24m.  Unlike most other macros that establish the [4msize[24m or [4mmeasure[0m
            of  something,  [1m.PT_SIZE  [22mdoes not require that you supply a [4munit[24m [4mof[0m
            [4mmeasure[24m since it's a near universal convention  that  [4mtype[24m  [4msize[24m  is
            measured  in [4mpoints[24m.  Therefore, to change the [4mtype[24m [4msize[24m to, say, [4m11[0m
            [4mpoints[24m, enter
                   [1m.PT_SIZE 11[0m
            [4mPoint[24m [4msizes[24m may be [4mfractional[24m (e.g., [4m10.25[24m or [4m12.5[24m).

            You can prepend a [4mplus[24m or a [4mminus[24m [4msign[24m to the argument to  [1m.PT_SIZE[22m,
            in  which case the [4mpoint[24m [4msize[24m will be changed by [4m+[24m or [4m-[24m the original
            value.  For example, if the [4mpoint[24m [4msize[24m is [4m12[24m, and you want  [4m14[24m,  you
            can do
                   [1m.PT_SIZE +2[0m
            then later reset it to [4m12[24m with
                   [1m.PT_SIZE -2[0m
            The [4msize[24m [4mof[24m [4mtype[24m can also be changed inline.

            [4mNote:[24m  It is unfortunate that the [1mpic [22mpreprocessor has already taken
            the name, PS, and thus [4mmom[24m's macro for setting [4mpoint[24m [4msizes[24m can't use
            it.  However, if you aren't using  [1mpic[22m,  you  might  want  to  alias
            [1m.PT_SIZE [22mas [1m.PS[22m, since there'd be no conflict.  For example
                   [1m.ALIAS PS PT_SIZE[0m
            would allow you to set [4mpoint[24m [4msizes[24m with [1m.PS[22m.

     [1m.R_MARGIN [4m[22m<right[24m [4mmargin>[0m
            Right Margin

            Requires a unit of measure.

            IMPORTANT:  [1m.R_MARGIN[22m,  if used, must come after [1m.PAPER[22m, [1m.PAGEWIDTH[22m,
            [1m.L_MARGIN[22m, and/or [1m.PAGE [22m(if a right margin  isn't  given  to  PAGE).
            The reason is that [1m.R_MARGIN [22mcalculates line length from the overall
            page dimensions and the left margin.

            Obviously, it can't make the calculation if it doesn't know the page
            width and the left margin.

            [1m.R_MARGIN  [22mestablishes  the amount of space you want between the end
            of typeset lines and the right hand edge of the printer  sheet.   In
            other  words, it sets the line length.  [1m.R_MARGIN [22mrequires a unit of
            measure.  Decimal fractions are allowed.

            The line length macro (LL) can be used in place  of  [1m.R_MARGIN[22m.   In
            either  case, the last one invoked sets the line length.  The choice
            of which to use is up to you.  In some instances, you  may  find  it
            easier  to  think of a section of type as having a right margin.  In
            others, giving a line length may make more sense.

            For example, if you're setting a page of type you know  should  have
            6-pica  margins  left  and right, it makes sense to enter a left and
            right margin, like this:
                   [1m.L_MARGIN 6P[0m
                   [1m.R_MARGIN 6P[0m

            That way, you don't have to worry about calculating the line length.
            On the other hand, if you know the line length for a patch  of  type
            should be 17 picas and 3 points, entering the line length with LL is
            much easier than calculating the right margin, e.g.,
                   [1m.LL 17P+3p[0m

            If  you  use  the macros [1m.PAGE[22m, [1m.PAGEWIDTH [22mor [1mPAPER [22mwithout invoking
            [1m.R_MARGIN [22mafterward, [4mmom[24m automatically sets [1m.R_MARGIN [22mto [4m1[24m [4minch[24m.  If
            you set a line length after these macros (with [1m.LL[22m), the line length
            calculated by [1m.R_MARGIN [22mis, of course, overridden.

            Note: [1m.R_MARGIN [22mbehaves in a special way when you're using the docu‐
            ment processing macros.

     [1m.ST [4m[22m<tab[24m [4mnumber>[24m [1mL | R | C | J [ QUAD ][0m

            After [4mstring[24m [4mtabs[24m have  been  marked  off  on  an  input  line  (see
            [1m\*[ST]...\*[STX][22m),  you  need to [4mset[24m them by giving them a direction
            and, optionally, the [1mQUAD [22margument.

            In this respect, [1m.ST [22mis like [1m.TAB_SET [22mexcept that you don't have  to
            give  [1m.ST  [22man indent or a line length (that's already taken care of,
            inline, by [1m\*[ST]...\*[STX][22m).

            If you want string [4mtab[24m [4m1[24m to be [1mleft[22m, enter
                   [1m.ST 1 L[0m
            If you want it to be [4mleft[24m and [4mfilled[24m, enter
                   [1m.ST 1 L QUAD[0m
            If you want it to be justified, enter
                   [1m.ST 1 J[0m

     [1m.TAB [4m[22m<tab[24m [4mnumber>[0m
            After [4mtabs[24m have been defined (either with  [1m.TAB_SET  [22mor  [1m.ST[22m),  [1m.TAB[0m
            moves to whatever [4mtab[24m [4mnumber[24m you pass it as an argument.

            For example,
                   [1m.TAB 3[0m
            moves you to [4mtab[24m [4m3[24m.

            Note:  [1m.TAB  [22mbreaks  the line preceding it and advances 1 linespace.
            Hence,
                   [1m.TAB 1[0m
                   [1mA line of text in tab 1.[0m
                   [1m.TAB 2[0m
                   [1mA line of text in tab 2.[0m
            produces, on output
                   [1mA line of text in tab 1.[0m
                                                [1mA line of text in tab 2.[0m

            If you want the tabs to line up, use [1m.TN [22m(“Tab Next”) or, more  con‐
            veniently, the inline escape sequence [1m\*[TB+][22m:
                   [1m.TAB [22m1
                   A line of text in tab 1.\*[TB+]
                   A line of text in tab 2.
            which produces
                   [1mA line of text in tab 1.   A line of text in tab 2.[0m

            If  the  text  in  your tabs runs to several lines, and you want the
            first lines of each tab to align,  you  must  use  the  multi-column
            macros.

            [4mAdditional[24m  [4mnote:[24m  Any  indents in effect prior to calling a tab are
            automatically turned off by [1mTAB[22m.  If you were happily  zipping  down
            the page with a left indent of [4m2[24m [4mpicas[24m turned on, and you call a [4mtab[0m
            whose indent from the left margin is [4m6[24m [4mpicas[24m, your new distance from
            the  [4mleft[24m  [4mmargin[24m will be [4m6[24m [4mpicas[24m, not I 6 picas plus the 2 pica in‐
            dent.

            [4mTabs[24m are not by nature columnar, which is to say that  if  the  text
            inside a [4mtab[24m runs to several lines, calling another [4mtab[24m does not au‐
            tomatically  move  to the baseline of the first line in the [4mprevious[0m
            [4mtab[24m.  To demonstrate:
                   TAB 1
                   Carrots
                   Potatoes
                   Broccoli
                   .TAB 2
                   $1.99/5 lbs
                   $0.25/lb
                   $0.99/bunch
            produces, on output
                   Carrots
                   Potatoes
                   Broccoli
                               $1.99/5 lbs
                               $0.25/lb
                               $0.99/bunch

     [1m.TB [4m[22m<tab[24m [4mnumber>[0m
            Alias to [1m.TAB[0m

     [1m.TI [ [4m[22m<measure>[24m [1m][0m
            Temporary left indent —— the optional argument requires  a  [4munit[24m  [4mof[0m
            [4mmeasure[0m

            A  temporary  indent  is  one that applies only to the first line of
            text that comes after it.  Its chief use is indenting the first line
            of paragraphs.  ([1mMom's .PP [22mmacro, for example, uses a [4mtemporary[24m  [4min‐[0m
            [4mdent[24m.)

            The  first  time you invoke [1m.TI[22m, you must give it a measure.  If you
            want to [4mindent[24m the first line of a paragraph by, say, 2 ems, do
                   [1m.TI 2m[0m

            Subsequent invocations of [1m.TI [22mdo not require you to  supply  a  mea‐
            sure; [4mmom[24m keeps track of the last measure you gave it.

            Because  [4mtemporary[24m  [4mindents[24m  are  temporary, there's no need to turn
            them off.

            [4mIMPORTANT:[24m Unlike [1m.IL[22m, [1m.IR [22mand [1mIB[22m, measures given to [1m.TI [22mare NOT ad‐
            ditive.  In the following example, the second [1m".TI 2P" [22mis exactly  [4m2[0m
            [4mpicas[24m.
                   [1m.TI 1P[0m
                   [1mThe beginning of a paragraph...[0m
                   [1m.TI 2P[0m
                   [1mThe beginning of another paragraph...[0m

     [1m.TN    [22mTab Next

            Inline escape [1m\*[TB+][0m

            [1mTN  [22mmoves over to the [4mnext[24m [4mtab[24m in numeric sequence ([4mtab[24m [4mn+1[24m) without
            advancing on the page.  See the [4mNOTE[24m in the description of the  [1m.TAB[0m
            macro for an example of how [1mTN [22mworks.

            In [4mtabs[24m that aren't given the [1mQUAD [22margument when they're set up with
            [1m.TAB_SET  [22mor  [1mST[22m, you must terminate the line preceding [1m.TN [22mwith the
            [1m\c [22minline escape sequence.  Conversely, if you did give a [1mQUAD [22margu‐
            ment to [1m.TAB_SET [22mor [1mST[22m, the [1m\c must not be used.[0m

            If you find remembering whether to put in the [1m\c [22mbothersome, you may
            prefer to use the inline escape alternative to [1m.TN[22m,  [1m\*[TB+][22m,  which
            works consistently regardless of the fill mode.

            [4mNote:[24m  You  must  put  text in the input line immediately after [1m.TN[22m.
            Stacking of [1m.TN[22m's is not allowed.  In other words, you cannot do
                   .TAB 1
                   Some text\c
                   .TN
                   Some more text\c
                   .TN
                   .TN
                   Yet more text
            The above example, assuming [4mtabs[24m numbered from [4m1[24m to [4m4[24m, should be en‐
            tered
                   .TAB 1
                   Some text\c
                   .TN
                   Some more text\c
                   .TN
                   \&\c
                   .TN
                   Yet more text
            \& is a zero-width, non-printing character that [4mgroff[24m recognizes  as
            valid  input,  hence  meets the requirement for input text following
            [1m.TN[22m.

     [1m.TQ    TQ [22mtakes you out of whatever [4mtab[24m you were in, advances [4m1[24m  [4mlinespace[24m,
            and  restores  the [4mleft[24m [4mmargin[24m, [4mline[24m [4mlength[24m, [4mquad[24m [4mdirection[24m and [4mfill[0m
            [4mmode[24m that were in effect prior to invoking any [4mtabs[24m.

     [1m.T_MARGIN [4m[22m<top[24m [4mmargin>[0m
            Top margin

            Requires a unit of measure

            [1m.T_MARGIN [22mestablishes the distance from the top of the printer sheet
            at which you want your type to start.  It requires a  unit  of  mea‐
            sure,  and decimal fractions are allowed.  To set a top margin of 2½
            centimetres, you'd enter
                   [1m.T_MARGIN 2.5c[0m
            [1m.T_MARGIN [22mcalculates the vertical position of the first line of type
            on a page by treating the top edge of the printer sheet as  a  base‐
            line.  Therefore,
                   [1m.T_MARGIN 1.5i[0m
            puts  the  baseline  of the first line of type 1½ inches beneath the
            top of the page.

            Note: [1m.T_MARGIN [22mmeans something slightly different when you're using
            the document processing macros.  See Top and bottom margins in docu‐
            ment processing for an explanation.

            IMPORTANT: [1m.T_MARGIN [22mdoes two things: it establishes the top  margin
            for  pages  that  come after it and it moves to that position on the
            current page.  Therefore, [1m.T_MARGIN [22mshould only be used at  the  top
            of a file (prior to entering text) or after NEWPAGE, like this:
                   [1m.NEWPAGE[0m
                   [1m.T_MARGIN 6P[0m
                   [4m<text>[0m

[1mAuthors[0m
     ]8;;mailto:peter@schaffter.ca\Peter  Schaffter]8;;\  wrote  [4mmom[24m.   ]8;;mailto:deri@chuzzlewit.myzen.co.uk\Deri James]8;;\ added PDF support.  ]8;;mailto:groff-bernd.warken-72@web.de\Bernd Warken]8;;\
     contributed this man page.

[1mSee also[0m
     [4m/usr/share/doc/groff-1.24.0/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.0                       2025-12-18                       [4mgroff_mom[24m(7)
────────────────────────────────────────────────────────────────────────────────
[4mgroff_ms[24m(7)             Miscellaneous Information Manual             [4mgroff_ms[24m(7)

[1mName[0m
     groff_ms - GNU [4mroff[24m manuscript macro package for formatting documents

[1mSynopsis[0m
     [1mgroff -ms [22m[[4moption[24m ...] [[4mfile[24m ...]
     [1mgroff -m ms [22m[[4moption[24m ...] [[4mfile[24m ...]

[1mDescription[0m
     The GNU implementation of the [4mms[24m macro package is part of the  [4mgroff[24m  docu‐
     ment  formatting system.  The [4mms[24m package is suitable for the composition of
     letters, memoranda, reports, and books.

     These [4mgroff[24m macros support cover page and table of contents generation, au‐
     tomatically numbered headings, several paragraph styles, a variety of  text
     styling options, footnotes, and multi-column page layouts.  [4mms[24m supports the
     ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\, ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\, ]8;;man:pic(1)\[4mpic[24m(1)]8;;\, and ]8;;man:refer(1)\[4mrefer[24m(1)]8;;\ preprocessors for inclusion of tables,
     mathematical  equations, diagrams, and consistently formatted bibliographic
     citations.

     [4mgroff[24m [4mms[24m is mostly compatible with the documented interface and behavior of
     AT&T Unix Version 7 [4mms[24m.  It recreates most extensions from  4.2BSD  (Berke‐
     ley) and Research Tenth Edition Unix.

[1mDocument structure[0m
     The  [4mms[24m  macro package expects a certain amount of structure: a well-formed
     document contains at least one paragraphing or heading macro call.  To com‐
     pose a simple document from scratch, begin it by calling [1mLP [22mor  [1mPP[22m.   Orga‐
     nize longer documents as follows.

     [1mDocument type[0m
            Calling the [1mRP [22mmacro at the beginning of your document puts the doc‐
            ument description (see below) on a cover page.  Otherwise, [4mms[24m places
            this information on the first page, followed immediately by the body
            text.   Some  document  types  found in other [4mms[24m implementations are
            specific to AT&T or Berkeley, and are not supported in [4mgroff[24m [4mms[24m.

     [1mFormat and layout[0m
            By setting registers and strings, you can configure your  document's
            typeface,  margins,  spacing,  headers  and  footers,  and  footnote
            arrangement.  See subsection “Document control settings” below.

     [1mDocument description[0m
            A document description consists of any of: a title, one or more  au‐
            thors' names and affiliated institutions, an abstract, and a date or
            other  identifier.  See subsection “Document description macros” be‐
            low.

     [1mBody text[0m
            The main matter of your document follows its description  (if  any).
            [4mms[24m  supports  highly structured text consisting of paragraphs inter‐
            spersed with multi-level headings (chapters, sections,  subsections,
            and  so  forth) and augmented by lists, footnotes, tables, diagrams,
            and similar material.  The preponderance of subsections below covers
            these matters.

     [1mTable of contents[0m
            Macros enable the collection of entries for a table of contents  (or
            index)  as  the  material  they  discuss appears in the document.  A
            macro call at the end of the document emits the  collected  entries.
            This  material  necessarily  follows  the rest of the text since GNU
            [4mtroff[24m is a single-pass formatter; it cannot determine the page  num‐
            ber  of  a  division  of  the text until it has been set and output.
            Since [4mms[24m output was designed for the production of  hard  copy,  the
            traditional  procedure was to manually relocate the pages containing
            the table of contents between the cover page and the body text.  To‐
            day, page resequencing is more often done in the digital domain.  An
            index works similarly, but because it typically needs to  be  sorted
            after collection, its preparation requires separate processing.

   [1mDocument control settings[0m
     The following tables list the document control registers, strings, and spe‐
     cial characters.  For any parameter whose default is unsatisfactory, define
     it before calling any [4mms[24m macro other than [1mRP[22m.

                                  [1mMargin settings[0m
     [1mParameter              Definition                Effective       Default[0m
     ───────────────────────────────────────────────────────────────────────────
     \n[PO]      Page offset (left margin)          next page        1i (0)
     \n[LL]      Line length                        next paragraph   6.5i (65n)
     \n[LT]      Title line length                  next paragraph   6.5i (65n)
     \n[HM]      Top (header) margin                next page        1i
     \n[FM]      Bottom (footer) margin             next page        1i
     ───────────────────────────────────────────────────────────────────────────

                             [1mTitles (headers, footers)[0m
     [1mParameter                 Definition                  Effective    Default[0m
     ───────────────────────────────────────────────────────────────────────────
     \*[LH]      Left header text                         next header   [4mempty[0m
     \*[CH]      Center header text                       next header   -\n[%]-
     \*[RH]      Right header text                        next header   [4mempty[0m
     \*[LF]      Left footer text                         next footer   [4mempty[0m
     \*[CF]      Center footer text                       next footer   [4mempty[0m
     \*[RF]      Right footer text                        next footer   [4mempty[0m
     ───────────────────────────────────────────────────────────────────────────

                                   [1mText settings[0m
     [1mParameter               Definition                  Effective      Default[0m
     ───────────────────────────────────────────────────────────────────────────
     \n[PS]      Point (type) size                     next paragraph   10p
     \n[VS]      Vertical spacing (leading)            next paragraph   12p
     \n[HY]      Hyphenation mode                      next paragraph   6
     \*[FAM]     Font family                           next paragraph   T
     ───────────────────────────────────────────────────────────────────────────

                                 [1mParagraph settings[0m
      [1mParameter              Definition                Effective       Default[0m
     ───────────────────────────────────────────────────────────────────────────
     \n[PI]        Indentation                       next paragraph   5n
     \n[PD]        Paragraph distance (spacing)      next paragraph   0.3v (1v)
     \n[QI]        Quotation indentation             next paragraph   5n
     \n[PORPHANS]  # of initial lines kept           next paragraph   1
     ───────────────────────────────────────────────────────────────────────────

                                  [1mHeading settings[0m
      [1mParameter               Definition               Effective      Default[0m
     ───────────────────────────────────────────────────────────────────────────
     \n[PSINCR]     Point (type) size increment       next heading   1p
     \n[GROWPS]     Size increase depth limit         next heading   0
     \n[HORPHANS]   # of following lines kept         next heading   1
     \*[SN-STYLE]   Numbering style (alias)           next heading   \*[SN-DOT]
     ───────────────────────────────────────────────────────────────────────────

     [1m\*[SN-STYLE]  [22mcan  alternatively be made an alias of [1m\*[SN-NO-DOT] [22mwith the
     [1mals [22mrequest.

                                 [1mFootnote settings[0m
     [1mParameter              Definition                 Effective      Default[0m
     ───────────────────────────────────────────────────────────────────────────
     \n[FI]      Indentation                         next footnote   2n
     \n[FF]      Format                              next footnote   0
     \n[FPS]     Point (type) size                   next footnote   \n[PS]-2p
     \n[FVS]     Vertical spacing (leading)          next footnote   \n[FPS]+2p
     \n[FPD]     Paragraph distance (spacing)        next footnote   \n[PD]/2
     \*[FR]      Line length ratio                   [4mspecial[24m         11/12
     ───────────────────────────────────────────────────────────────────────────

                                  [1mDisplay settings[0m
     [1mParameter                 Definition                 Effective    Default[0m
     ───────────────────────────────────────────────────────────────────────────
     \n[DD]      Display distance (spacing)               [4mspecial[24m     0.5v (1v)
     \n[DI]      Display indentation                      [4mspecial[24m     0.5i
     ───────────────────────────────────────────────────────────────────────────

                                   [1mOther settings[0m
       [1mParameter                Definition                Effective     Default[0m
     ───────────────────────────────────────────────────────────────────────────
     \n[MINGW]       Minimum gutter width                next page      2n
     \n[TC-MARGIN]   TOC page number margin width        next [1mPX [22mcall   \w'000'
     \[TC-LEADER]    TOC leader character                next [1mPX [22mcall   .\h'1m'
     ───────────────────────────────────────────────────────────────────────────

     For entries marked “[4mspecial[24m” in the “Effective” column, see the  discussion
     in the applicable section below.  The [1mPO[22m, [1mLL[22m, and [1mLT [22mregister defaults vary
     by output device and paper format; the values shown are for typesetters us‐
     ing  U.S.  letter paper, and then terminals.  See section “Paper format” of
     ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\.  The [1mPD [22mand [1mDD [22mregisters use the larger value if the vertical mo‐
     tion quantum of the output device is too coarse for the smaller  one;  usu‐
     ally, this is the case only for output to terminals.  The “gutter” affected
     by  [1m\n[MINGW]  [22mis  the gap between columns in multiple-column page arrange‐
     ments.  The [1mTC-MARGIN [22mregister and [1mTC-LEADER [22mspecial character  affect  the
     formatting of tables of contents assembled by the [1mXS[22m, [1mXA[22m, and [1mXE [22mmacros.

   [1mDocument description macros[0m
     Define  information  describing the document by calling the macros below in
     the order shown; [1mDA [22mor [1mND [22mcan be called to set the document date (or  other
     identifier) at any time before (a) the abstract, if present, or (b) its in‐
     formation  is  required  in a header or footer.  Use of these macros is op‐
     tional, except that [1mTL [22mis mandatory if any of [1mRP[22m, [1mAU[22m, [1mAI[22m, or [1mAB [22mis  called,
     and [1mAE [22mis mandatory if [1mAB [22mis called.

     [1m.RP [22m[[1mno-repeat-info[22m] [[1mno-renumber[22m]
            Use  the “report” (AT&T: “released paper”) format for your document,
            creating a separate cover page.  The default arrangement is to place
            most of the document description (title, author names  and  institu‐
            tions, and abstract, but not the date) at the top of the first page.
            If  the  optional  [1mno-repeat-info  [22margument  is given, [4mms[24m produces a
            cover page but does not repeat any of its  information  subsequently
            (but  see the [1mDA [22mmacro below regarding the date).  Normally, [1mRP [22msets
            the page number following the cover page to 1.  Specifying  the  op‐
            tional  [1mno-renumber  [22margument  suppresses this alteration.  Optional
            arguments can occur in any order.  [4mms[24m recognizes [1mno [22mas a synonym  of
            [1mno-repeat-info  [22mto  maintain AT&T compatibility.  Options other than
            [1mno [22mare GNU extensions.

     [1m.TL    [22mSpecify the document title.  [4mms[24m collects text on input lines follow‐
            ing this call into the title until reaching [1mAU[22m, [1mAB[22m, or a heading  or
            paragraphing macro call.

     [1m.AU    [22mSpecify an author's name.  [4mms[24m collects text on input lines following
            this  call into the author's name until reaching [1mAI[22m, [1mAB[22m, another [1mAU[22m,
            or a heading or paragraphing macro  call.   Call  it  repeatedly  to
            specify multiple authors.

     [1m.AI    [22mSpecify  the  preceding  author's  institutional affiliation.  An [1mAU[0m
            call is usefully followed by at most one [1mAI [22mcall; if there are more,
            the last [1mAI [22mcall controls.  [4mms[24m collects text on input lines  follow‐
            ing  this  call into the author's institution until reaching [1mAU[22m, [1mAB[22m,
            or a heading or paragraphing macro call.

     [1m.DA [22m[[4mx[24m ...]
            Typeset the current date, or any arguments [4mx[24m, in the center  footer,
            and,  if  [1mRP [22mis also called, left-aligned at the end of the document
            description on the cover page.

     [1m.ND [22m[[4mx[24m ...]
            Typeset the current date, or any arguments [4mx[24m, if [1mRP [22mis also  called,
            left-aligned  at  the  end  of the document description on the cover
            page.  This is [4mgroff[24m [4mms[24m's default.

     [1m.AB [22m[[1mno[22m]
            Begin the abstract.  [4mms[24m collects text on input lines following  this
            call  into  the  abstract until reaching an [1mAE [22mcall.  By default, [4mms[0m
            places the word “ABSTRACT” centered and in italics above the text of
            the abstract.  The optional argument “[1mno[22m” suppresses this heading.

     [1m.AE    [22mEnd the abstract.

   [1mText settings[0m
     The [1mFAM [22mstring, a GNU extension, sets the font family for  body  text;  the
     default  is  “[1mT[22m”.   The  [1mPS [22mand [1mVS [22mregisters set the type size and vertical
     spacing (distance between text baselines), respectively.  The  font  family
     and  type  size  are ignored on terminals.  Set these parameters before the
     first call of a heading, paragraphing, or (non-date)  document  description
     macro to apply them to headers, footers, and (for [1mFAM[22m) footnotes.

     The [1mHY [22mregister defines the automatic hyphenation mode used with the [1mhy [22mre‐
     quest.   Setting [1m\n[HY] [22mto [1m0 [22mdisables automatic hyphenation.  This is a Re‐
     search Tenth Edition Unix extension.

   [1mTypographical symbols[0m
     [4mms[24m provides a few strings to obtain typographical symbols  not  easily  en‐
     tered  with  the  keyboard.  These and many others are available as special
     character escape sequences——see ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\.

     [1m\*[-]  [22mInterpolate an em dash.

     [1m\*[Q][0m
     [1m\*[U]  [22mInterpolate typographer's quotation marks where available, and  neu‐
            tral double quotes otherwise.  [1m\*[Q] [22mis the left quote and [1m\*[U] [22mthe
            right.

   [1mParagraphs[0m
     Paragraphing  macros [4mbreak[24m, or terminate, any pending output line so that a
     new paragraph can begin.  Several paragraph types are available,  differing
     in how indentation applies to them: to left, right, or both margins; to the
     first output line of the paragraph, all output lines, or all but the first.
     These  calls insert vertical space in the amount stored in the [1mPD [22mregister,
     except at page or column breaks, or adjacent to displays.

     The [1mPORPHANS [22mregister defines the minimum number of initial  lines  of  any
     paragraph  that must be kept together to avoid isolated lines at the bottom
     of a page.  If a new paragraph starts close to the bottom of  a  page,  and
     there is insufficient space to accommodate [1m\n[PORPHANS] [22mlines before an au‐
     tomatic  page  break,  [4mgroff[24m  [4mms[24m  forces a page break before formatting the
     paragraph.  This is a GNU extension.

     [1m.LP    [22mSet a paragraph without any (additional) indentation.

     [1m.PP    [22mSet a paragraph with a first-line left  indentation  in  the  amount
            stored in the [1mPI [22mregister.

     [1m.IP [22m[[4mmark[24m [[4mwidth[24m]]
            Set  a  paragraph with a left indentation.  The optional [4mmark[24m is not
            indented, is useful in the construction of lists, and  is  empty  by
            default.   [4mwidth[24m overrides the indentation amount in [1m\n[PI][22m; its de‐
            fault unit is “[1mn[22m”.  Once specified,  [4mwidth[24m  applies  to  further  [1mIP[0m
            calls  until  specified again or a heading or different paragraphing
            macro is called.

     [1m.QP    [22mSet a paragraph indented from both left and right margins by [1m\n[QI][22m.

     [1m.QS[0m
     [1m.QE    [22mBegin ([1mQS[22m) and end ([1mQE[22m) a region where each  paragraph  is  indented
            from  both  margins  by  [1m\n[QI][22m.   The text between [1mQS [22mand [1mQE [22mcan be
            structured further by use of other paragraphing macros.

     [1m.XP    [22mSet an “exdented” paragraph——one with a left indentation  of  [1m\n[PI][0m
            on  every  line  [4mexcept[24m  the first (also known as a hanging indent).
            This is a Berkeley extension.

   [1mHeadings[0m
     Use headings to create a hierarchical structure for your document.  The  [4mms[0m
     macros  print  headings in [1mbold [22musing the same font family and, by default,
     type size as the body text.  Headings are available with and without  auto‐
     matic  numbering.  Text on input lines following the macro call becomes the
     heading's title.  Call a paragraphing macro to end  the  heading  text  and
     start the section's content.

     [1m.NH [22m[[4mdepth[24m]
            Set an automatically numbered heading.  [4mms[24m produces a numbered head‐
            ing  in  the form [4ma[24m.[4mb[24m.[4mc[24m..., to any level desired, with the numbering
            of each depth increasing automatically and being reset to zero  when
            a  more significant depth is increased.  “[1m1[22m” is the most significant
            or coarsest division of the document.  Only non-zero values are out‐
            put.  If [4mdepth[24m is omitted, [4mms[24m assumes “[1m1[22m”.   If  you  specify  [4mdepth[0m
            such that an ascending gap occurs relative to the previous [1mNH [22mcall——
            that  is,  you “skip a depth”, as by “[1m.NH 1[22m” and then “[1m.NH 3[22m”, [4mgroff[0m
            [4mms[24m emits a warning on the standard error stream.

     [1m.NH S [4m[22mheading-depth-index[24m ...
            Alternatively, you can give [1mNH [22ma first argument of “[1mS[22m”, followed  by
            integers to number the heading depths explicitly.  Further automatic
            numbering,  if  used,  resumes  using the specified indices as their
            predecessors.  This feature is a Berkeley extension.

     After [1mNH [22mis called, the assigned number is made available  in  the  strings
     [1mSN-DOT  [22m(as  it  appears in a printed heading with default formatting, fol‐
     lowed by a terminating period) and [1mSN-NO-DOT [22m(with the  terminating  period
     omitted).  These, and [1mSN-STYLE[22m, are GNU extensions.

     You  can  control  the style used to print numbered headings by defining an
     appropriate alias for the string [1mSN-STYLE[22m.   By  default,  [1m\*[SN-STYLE]  [22mis
     aliased  to  [1m\*[SN-DOT][22m.  If you prefer to omit the terminating period from
     numbers appearing in numbered headings, you may alias it to  [1m\*[SN-NO-DOT][22m.
     Any  such  change in numbering style becomes effective from the next use of
     [1mNH [22mfollowing redefinition of the alias  for  [1m\*[SN-STYLE][22m.   The  formatted
     number of the current heading is available in [1m\*[SN] [22m(a feature first docu‐
     mented by Berkeley); this string facilitates its inclusion in, for example,
     table captions, equation labels, and [1mXS[22m/[1mXA[22m/[1mXE [22mtable of contents entries.

     [1m.SH [22m[[4mdepth[24m]
            Set an unnumbered heading.  The optional [4mdepth[24m argument is a GNU ex‐
            tension  indicating the heading depth corresponding to the [4mdepth[24m ar‐
            gument of [1mNH[22m.  It matches the type size at which the heading is  set
            to  that of a numbered heading at the same depth when the [1m\n[GROWPS][0m
            and [1m\n[PSINCR] [22mheading size adjustment mechanism is in effect.

     The [1mPSINCR [22mregister defines an increment in type size to be  applied  to  a
     heading  at a lesser depth than that specified in [1m\n[GROWPS][22m.  The value of
     [1m\n[PSINCR] [22mshould be specified in points with the “[1mp[22m” scaling unit and  may
     include a fractional component.

     The [1mGROWPS [22mregister defines the heading depth above which the type size in‐
     crement  set  by [1m\n[PSINCR] [22mbecomes effective.  For each heading depth less
     than the value of [1m\n[GROWPS][22m, the type size  is  increased  by  [1m\n[PSINCR][22m.
     Setting  [1m\n[GROWPS] [22mto a value less than 2 disables the incremental heading
     size feature.

     In other words, if the value of [1mGROWPS [22mregister is greater than  the  [4mdepth[0m
     argument  to  a [1mNH [22mor [1mSH [22mcall, the type size of a heading produced by these
     macros increases by [1m\n[PSINCR] [22munits over [1m\n[PS] [22mmultiplied by the  differ‐
     ence of [1m\n[GROWPS] [22mand [4mdepth[24m.  [1mGROWPS [22mand [1mPSINCR [22mare GNU extensions.

     In  [4mgroff[24m [4mms,[24m the [1mNH [22mand [1mSH [22mmacros consult the [1mHORPHANS [22mregister to prevent
     the output of isolated headings at the bottom of a page; it  specifies  the
     minimum  number  of  lines of the subsequent paragraph that must be kept on
     the same page as the heading.  If insufficient space remains on the current
     page to accommodate the heading and this number of lines of paragraph text,
     [4mgroff[24m [4mms[24m forces a page break before setting the heading.  Any display macro
     call or [4mtbl[24m, [4mpic[24m, or [4meqn[24m region between  the  heading  and  the  subsequent
     paragraph suppresses this grouping.  This is a GNU extension.

   [1mTypeface and decoration[0m
     The  [4mms[24m  macros provide a variety of ways to style text.  Attend closely to
     the ordering of arguments labeled [4mpre[24m and [4mpost,[24m  which  is  not  intuitive.
     Support for [4mpre[24m arguments is a GNU extension.

     [1m.B [22m[[4mtext[24m [[4mpost[24m [[4mpre[24m]]]
            Style  [4mtext[24m  in  bold,  followed  by [4mpost[24m in the previous font style
            without intervening space, and preceded by [4mpre[24m  similarly.   Without
            arguments,  [4mms[24m  styles  subsequent text in bold until the next para‐
            graphing, heading, or no-argument typeface macro call.

     [1m.R [22m[[4mtext[24m [[4mpost[24m [[4mpre[24m]]]
            As [1mB[22m, but use the roman style (upright text of  normal  weight)  in‐
            stead of bold.  Argument recognition is a GNU extension.

     [1m.I [22m[[4mtext[24m [[4mpost[24m [[4mpre[24m]]]
            As [1mB[22m, but use an italic or oblique style instead of bold.

     [1m.BI [22m[[4mtext[24m [[4mpost[24m [[4mpre[24m]]]
            As [1mB[22m, but use a bold italic or bold oblique style instead of upright
            bold.  This is a Research Tenth Edition Unix extension.

     [1m.CW [22m[[4mtext[24m [[4mpost[24m [[4mpre[24m]]]
            As  [1mB[22m,  but use a constant-width (monospaced) roman typeface instead
            of bold.  This is a Research Tenth Edition Unix extension.

     [1m.BX [22m[[4mtext[24m]
            Typeset [4mtext[24m and draw a box around it.  On terminals, reverse  video
            is used instead.  If you want [4mtext[24m to contain space, use unbreakable
            space or horizontal motion escape sequences ([1m\~[22m, [1m\[4m[22mspace[24m, [1m\^[22m, [1m\|[22m, [1m\0[22m,
            or [1m\h[22m).

     [1m.UL [22m[[4mtext[24m [[4mpost[24m]]
            Typeset  [4mtext[24m  with  an  underline.  On terminals, [4mtext[24m is bracketed
            with underscores (“_”).  [4mpost,[24m if present, is set after [4mtext[24m with no
            intervening space.

     [1m.LG    [22mSet subsequent text in larger type (2 points larger than the current
            size) until the next type size, paragraphing, or heading macro call.
            Call the macro multiple times to enlarge the type size further.

     [1m.SM    [22mSet subsequent text in smaller type (2 points smaller than the  cur‐
            rent  size) until the next type size, paragraphing, or heading macro
            call.  Call the macro multiple times to reduce the  type  size  fur‐
            ther.

     [1m.NL    [22mSet subsequent text at the normal type size ([1m\n[PS][22m).

     When [4mpre[24m is used, a hyphenation control escape sequence [1m\% [22mthat would ordi‐
     narily start [4mtext[24m must start [4mpre[24m instead.

     [4mgroff[24m  [4mms[24m  also  offers  strings  to begin and end super- and subscripting.
     These are GNU extensions.

     [1m\*{[0m
     [1m\*}    [22mBegin and end superscripting, respectively.

     [1m\*<[0m
     [1m\*>    [22mBegin and end subscripting, respectively.

   [1mIndented regions[0m
     You can indent a region of text while  otherwise  formatting  it  normally.
     Such indented regions can be nested.

     [1m.RS    [22mBegin a region where headings, paragraphs, and displays are indented
            (further) by [1m\n[PI][22m.

     [1m.RE    [22mEnd the (next) most recent indented region.

   [1mKeeps, boxed keeps, and displays[0m
     On  occasion,  you may want to [4mkeep[24m several lines of text, or a region of a
     document, together on a single page, preventing  an  automatic  page  break
     within  certain  boundaries.   This can cause a page break to occur earlier
     than it normally would.

     You can alternatively specify a [4mfloating[24m [4mkeep:[24m if a keep cannot fit on  the
     current  page, [4mms[24m holds it, allowing text following the keep (in the source
     document) to fill in the remainder of the  current  page.   When  the  page
     breaks  by  reaching its bottom or by [1mbp [22mrequest, [4mms[24m puts the floating keep
     at the beginning of the next page.

     [1m.KS    [22mBegin a keep.

     [1m.KF    [22mBegin a floating keep.

     [1m.KE    [22mEnd (floating) keep.

     As an alternative to the keep mechanism, the [1mne [22mrequest forces a page break
     if there is not at least the amount of vertical space specified in its  ar‐
     gument remaining on the page.

     A [4mboxed[24m [4mkeep[24m has a frame drawn around it.

     [1m.B1    [22mBegin a keep with a box drawn around it.

     [1m.B2    [22mEnd boxed keep.

     Boxed  keep  macros  cause breaks; to box words within a line, recall [1mBX [22min
     section “Highlighting” above.  [4mms[24m draws box lines close to  the  text  they
     enclose  so  that  they  are  usable within paragraphs.  When boxing entire
     paragraphs thus, you may improve their appearance by calling [1mB1  [22mafter  the
     first paragraphing macro, and invoking the [1msp [22mrequest before calling [1mB2[22m.

     If  you  want  a  boxed keep to float, enclose the [1mB1 [22mand [1mB2 [22mcalls within a
     pair of [1mKF [22mand [1mKE [22mcalls.

     [4mDisplays[24m turn off filling; lines of verse or program code  are  shown  with
     their  lines broken as in the source document without requiring [1mbr [22mrequests
     between lines.  Displays can be kept on a single page or allowed  to  break
     across  pages.   The [1mDS [22mmacro begins a kept display of the layout specified
     in its first argument; non-kept displays are begun  with  dedicated  macros
     corresponding to their layout.

     [1m.DS L[0m
     [1m.LD    [22mBegin ([1mDS[22m: kept) left-aligned display.

     [1m.DS [22m[[1mI [22m[[4mindent[24m]]
     [1m.ID [22m[[4mindent[24m]
            Begin  ([1mDS[22m:  kept)  display  indented by [4mindent[24m if specified, [1m\n[DI][0m
            otherwise.

     [1m.DS B[0m
     [1m.BD    [22mBegin ([1mDS[22m: kept) block display: the entire display is  left-aligned,
            but  indented  such that the longest line in the display is centered
            on the page.

     [1m.DS C[0m
     [1m.CD    [22mBegin ([1mDS[22m: kept) centered display: each line in the display is  cen‐
            tered.

     [1m.DS R[0m
     [1m.RD    [22mBegin ([1mDS[22m: kept) right-aligned display.  This is a GNU extension.

     [1m.DE    [22mEnd any display.

     [4mgroff[24m  [4mms[24m  inserts the distance stored in [1m\n[DD] [22mbefore and after each pair
     of display macros; this is a Berkeley extension.   This  distance  replaces
     any adjacent inter-paragraph distance or subsequent spacing prior to a sec‐
     tion heading.  The [1mDI [22mregister is a GNU extension; its value is an indenta‐
     tion  applied  to  displays  created  with  [1mDS [22mand [1mID [22mwithout arguments, to
     “[1m.DS I[22m” without an indentation argument, and to equations set with “[1m.EQ I[22m”.
     Changes to either register take effect at the next display boundary.

   [1mTables, figures, equations, and references[0m
     [4mms[24m often sees use with the [4mtbl[24m, [4mpic[24m, [4meqn[24m, and [4mrefer[24m  preprocessors.   [4mgroff[0m
     [4mms[24m applies the [1m\n[DD] [22mdistance to regions of the document preprocessed with
     [4meqn[24m,  [4mpic[24m,  and  [4mtbl[24m.  Mark text meant for preprocessors by enclosing it in
     pairs of tokens as follows, with nothing between  the  dot  and  the  macro
     name.  Preprocessors match these tokens only at the start of an input line.
     The formatter interprets them as macro calls.

     [1m.TS [22m[[1mH[22m]
     [1m.TE    [22mDemarcate  a table to be processed by the [4mtbl[24m preprocessor.  The op‐
            tional [1mH [22margument instructs [4mms[24m to repeat table  rows  (often  column
            headings)  at  the top of each new page the table spans, if applica‐
            ble; calling the [1mTH [22mmacro marks the end of such rows.   ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\  pro‐
            vides a comprehensive reference to the preprocessor and offers exam‐
            ples of its use.

     [1m.PS [4m[22mh[24m [4mv[0m
     [1m.PE[0m
     [1m.PF    PS [22mmarks the start of a ]8;;man:pic(1)\[4mpic[24m(1)]8;;\ preprocessor diagram; either of [1mPE [22mor
            [1mPF  [22mends  it,  the latter with “flyback” to the vertical position at
            its top.  [4mh[24m and [4mv[24m are the horizontal and vertical dimensions of  the
            picture; [4mpic[24m supplies them automatically.

     [1m.EQ [22m[[4malign[24m [[4mlabel[24m]]
     [1m.EN    [22mDemarcate  mathematics  to be processed by the [4meqn[24m preprocessor.  [4mms[0m
            centers the equation by default; [4malign[24m can be [1mC[22m, [1mL[22m, or [1mI [22mto (explic‐
            itly) center, left-align, or indent it by [1m\n[DI][22m, respectively.   [4mms[0m
            right-aligns any [4mlabel[24m.  See ]8;;man:eqn(1)\[4meqn[24m(1)]8;;\.

     [1m.[[0m
     [1m.]     [22mDemarcate a bibliographic citation to be processed by the [4mrefer[24m pre‐
            processor.   ]8;;man:refer(1)\[4mrefer[24m(1)]8;;\ provides a comprehensive reference to the pre‐
            processor and the format of its bibliographic database.

     When [4mrefer[24m emits collected references (as might be done on a “Works  Cited”
     page),  it  interpolates the string [1m\*[REFERENCES] [22mas an unnumbered heading
     ([1m.SH[22m).

     Attempting to place a multi-page table inside a keep can lead to unpleasant
     results, particularly if the [4mtbl[24m “[1mallbox[22m” option is used.

   [1mFootnotes[0m
     A footnote is typically anchored to a place in the text with a [4mmark,[24m  which
     is a small integer, a symbol, or arbitrary user-specified text.

     [1m\**    [22mPlace  an [4mautomatic[24m [4mnumber,[24m an automatically generated numeric foot‐
            note mark, in the text.  Each time this string is interpolated,  the
            number it produces increments by one.  Automatic numbers start at 1.
            This is a Berkeley extension.

     Enclose the footnote text in [1mFS [22mand [1mFE [22mmacro calls to set it at the nearest
     available “foot”, or bottom, of a text column or page.

     [1m.FS [22m[[4mmark[24m]
            Begin  a  footnote.  The [1mFS-MARK [22mhook (see below) is called with any
            supplied [4mmark[24m argument, which is then also placed at  the  beginning
            of  the  footnote  text.  If [4mmark[24m is omitted, the next pending auto‐
            matic number enqueued by interpolation of the [1m* [22mstring is used,  and
            if none exists, nothing is prefixed.

     [1m.FE    [22mEnd footnote text.

     [4mgroff[24m  [4mms[24m provides a hook macro, [1mFS-MARK[22m, for user-determined operations to
     be performed when the [1mFS [22mmacro is called.  It is passed the same  arguments
     as  [1mFS [22mitself.  By default, this macro has an empty definition.  [1mFS-MARK [22mis
     a GNU extension.

     Footnote text is formatted as paragraphs are, using  analogous  parameters.
     The  registers  [1mFI[22m, [1mFPD[22m, [1mFPS[22m, and [1mFVS [22mcorrespond to [1mPI[22m, [1mPD[22m, [1mPS[22m, and [1mVS[22m, re‐
     spectively; [1mFPD[22m, [1mFPS[22m, and [1mFVS [22mare GNU extensions.

     The [1mFF [22mregister controls the formatting of automatically numbered  footnote
     paragraphs,  and those for which [1mFS [22mis given a [4mmark[24m argument, at the bottom
     of a column or page as follows.

            0      Set an automatic number, or a specified [1mFS [4m[22mmark[24m argument,  as
                   a superscript (on typesetters) or surrounded by square brack‐
                   ets  (on  terminals).   The footnote paragraph is indented as
                   with [1mPP [22mif there is an [1mFS [22margument or  an  automatic  number,
                   and as with [1mLP [22motherwise.  This is the default.

            1      As  [1m0[22m,  but set [4mmark[24m as regular text, and follow an automatic
                   number with a period.

            2      As [1m1[22m, but without indentation (like [1mLP[22m).

            3      As [1m1[22m, but set the footnote paragraph with [4mmark[24m hanging  (like
                   [1mIP[22m).

   [1mLanguage and localization[0m
     [4mgroff[24m  [4mms[24m provides several strings that you can customize for your own pur‐
     poses, or redefine to adapt the macro package to languages other than  Eng‐
     lish.  It is already localized for Czech, German, Spanish, French, Italian,
     Polish,  Russian, and Swedish.  Load the desired localization macro package
     after [4mms[24m; see ]8;;man:groff_tmac(5)\[4mgroff_tmac[24m(5)]8;;\.

                [1mString            Default[0m
            ───────────────────────────────────
            \*[REFERENCES]   References
            \*[ABSTRACT]     \f[I]ABSTRACT\f[]
            \*[TOC]          Table of Contents
            \*[MONTH1]       January
            \*[MONTH2]       February
            \*[MONTH3]       March
            \*[MONTH4]       April
            \*[MONTH5]       May
            \*[MONTH6]       June
            \*[MONTH7]       July
            \*[MONTH8]       August
            \*[MONTH9]       September
            \*[MONTH10]      October
            \*[MONTH11]      November
            \*[MONTH12]      December
            ───────────────────────────────────
     The default for [1mABSTRACT [22mincludes font selection escape  sequences  to  set
     the word in italics.

   [1mHeaders and footers[0m
     There  are  multiple ways to produce headers and footers.  One is to define
     the strings [1mLH[22m, [1mCH[22m, and [1mRH [22mto set the left, center, and right headers,  re‐
     spectively;  and [1mLF[22m, [1mCF[22m, and [1mRF [22mto set the left, center, and right footers.
     This approach suffices for documents that do not distinguish odd- and even-
     numbered pages.

     Another method is to call macros that set headers or footers  for  odd-  or
     even-numbered pages.  Each such macro takes a delimited argument separating
     the  left,  center,  and right header or footer texts from each other.  You
     can replace the neutral apostrophes (') shown below with any character  not
     appearing  in  the header or footer text.  These macros are Berkeley exten‐
     sions.

     [1m.OH [22m'[4mleft[24m'[4mcenter[24m'[4mright[24m'
     [1m.OF [22m'[4mleft[24m'[4mcenter[24m'[4mright[24m'
     [1m.EH [22m'[4mleft[24m'[4mcenter[24m'[4mright[24m'
     [1m.EF [22m'[4mleft[24m'[4mcenter[24m'[4mright[24m'
            The [1mOH [22mand [1mEH [22mmacros define headers for odd- (recto)  and  even-num‐
            bered (verso) pages, respectively; the [1mOF [22mand [1mEF [22mmacros define foot‐
            ers for them.

     With  either  method, a percent sign [1m% [22min header or footer text is replaced
     by the current page number.  By default, [4mms[24m places no header on a page num‐
     bered “1” (regardless of its number format).

     [1m.P1    [22mTypeset the header even on page 1.  To be effective, this macro must
            be called before the header trap is sprung on any page numbered “1”.
            This is a Berkeley extension.

     For even greater flexibility, [4mms[24m is designed to permit the redefinition  of
     the  macros  that are called when formatter traps that ordinarily cause the
     headers and footers to be output are sprung.  [1mPT [22m(“page trap”) is called by
     [4mms[24m when the header is to be written, and [1mBT [22m(“bottom trap”) when the footer
     is to be.  The [4mgroff[24m page location trap that  [4mms[24m  sets  up  to  format  the
     header  also  calls the (normally undefined) [1mHD [22mmacro after [1mPT[22m; you can de‐
     fine [1mHD [22mif you need additional processing after setting the header.  The [1mHD[0m
     hook is a Berkeley extension.  Any such macros you (re)define  must  imple‐
     ment any desired specialization for odd-, even-, or first numbered pages.

   [1mTab stops[0m
     Use the [1mta [22mrequest to set tab stops as needed.

     [1m.TA    [22mReset  the tab stops to the [4mms[24m default (every 5 ens).  Redefine this
            macro to create a different set of default tab stops.

   [1mMargins[0m
     Control margins using the registers summarized in the “Margins” portion  of
     the  table  in section “Document control settings” above.  There is no set‐
     ting for the right margin; the combination of page offset [1m\n[PO]  [22mand  line
     length [1m\n[LL] [22mdetermines it.

   [1mMultiple columns[0m
     [4mms[24m can set text in as many columns as reasonably fit on the page.  The fol‐
     lowing  macros  force  a page break if a multi-column layout is active when
     they are called.  [1m\n[MINGW] [22mis the default minimum gutter width;  it  is  a
     GNU  extension.   When  multiple columns are in use, keeps and the [1mHORPHANS[0m
     and [1mPORPHANS [22mregisters work with respect to column breaks instead  of  page
     breaks.

     [1m.1C    [22mArrange page text in a single column (the default).

     [1m.2C    [22mArrange page text in two columns.

     [1m.MC [22m[[4mcolumn-width[24m [[4mgutter-width[24m]]
            Arrange page text in multiple columns.  If you specify no arguments,
            it  is  equivalent  to the [1m2C [22mmacro.  Otherwise, [4mcolumn-width[24m is the
            width of each column and [4mgutter-width[24m is the  minimum  distance  be‐
            tween columns.

   [1mCreating a table of contents[0m
     Define  an  entry to appear in the table of contents by bracketing its text
     between calls to the [1mXS [22mand [1mXE [22mmacros.  A typical application  is  to  call
     them  immediately  after  [1mNH [22mor [1mSH [22mand repeat the heading text within them.
     The [1mXA [22mmacro, used within [1mXS[22m/[1mXE [22mpairs, supplements an entry——for  instance,
     when  it  requires  multiple output lines, whether because a heading is too
     long to fit or because style dictates that page numbers  not  be  repeated.
     You  may  wish to indent the text thus wrapped to correspond to its heading
     depth; this can be done in the entry text by prefixing it with tabs or hor‐
     izontal motion escape sequences, or by providing a second argument  to  the
     [1mXA [22mmacro.  [1mXS [22mand [1mXA [22mautomatically associate the page number where they are
     called  with the text following them, but they accept arguments to override
     this behavior.  At the end of the document, call [1mTC [22mor [1mPX [22mto emit the table
     of contents; [1mTC [22mresets the page number to [1mi [22m(Roman numeral one),  and  then
     calls [1mPX[22m.  All of these macros are Berkeley extensions.

     [1m.XS [22m[[4mpage-number[24m]
     [1m.XA [22m[[4mpage-number[24m [[4mindentation[24m]]
     [1m.XE    [22mBegin, supplement, and end a table of contents entry.  Each entry is
            associated  with  [4mpage-number[24m (otherwise the current page number); a
            [4mpage-number[24m of “[1mno[22m” prevents a leader and  page  number  from  being
            emitted  for that entry.  Use of [1mXA [22mwithin [1mXS[22m/[1mXE [22mis optional; it can
            be repeated.  If [4mindentation[24m is present, a supplemental entry is in‐
            dented by that amount; ens are assumed  if  no  unit  is  indicated.
            Text  on input lines between [1mXS [22mand [1mXE [22mis stored for later recall by
            [1mPX[22m.

     [1m.PX [22m[[1mno[22m]
            Switch to single-column layout.  Unless “[1mno[22m”  is  specified,  center
            and  interpolate [1m\*[TOC] [22min bold and two points larger than the body
            text.  Emit the table of contents entries.

     [1m.TC [22m[[1mno[22m]
            Set the page number to 1, the page number format to lowercase  Roman
            numerals, and call [1mPX [22m(with a “[1mno[22m” argument, if present).

     The remaining features in this subsection are GNU extensions.  [4mgroff[24m [4mms[24m ob‐
     viates  the need to repeat heading text after [1mXS [22mcalls.  Call [1mXN [22mand [1mXH [22maf‐
     ter [1mNH [22mand [1mSH[22m, respectively.  Text to be appended to the formatted  section
     heading, but not to appear in the table of contents entry, can follow these
     calls.

     [1m.XN [4m[22mheading-text[0m
            Format [4mheading-text[24m and create a corresponding table of contents en‐
            try; the indentation is computed from the [4mdepth[24m argument of the pre‐
            ceding [1mNH [22mcall.

     [1m.XH [4m[22mdepth[24m [4mheading-text[0m
            As [1mXN[22m, but use [4mdepth[24m to determine the indentation.

     [4mgroff[24m  [4mms[24m  encourages  customization of table of contents entry production.
     (Re-)define any of the following macros as desired.

     [1m.XN-REPLACEMENT [4m[22mheading-text[0m
     [1m.XH-REPLACEMENT [4m[22mdepth[24m [4mheading-text[0m
            These hook macros implement [1mXN [22mand [1mXH[22m, and call [1mXN-INIT [22mand [1mXH-INIT[22m,
            respectively, then call [1mXH-UPDATE-TOC [22mwith the arguments given them.

     [1m.XH-INIT[0m
     [1m.XN-INIT[0m
            These hook macros do nothing by default.

     [1m.XH-UPDATE-TOC [4m[22mdepth[24m [4mheading-text[0m
            Bracket [4mheading-text[24m with [1mXS [22mand [1mXE [22mcalls, indenting it by 2 ens per
            level of [4mdepth[24m beyond the first.

     You can customize the style of the leader that bridges each table  of  con‐
     tents entry with its page number; define the [1mTC-LEADER [22mspecial character by
     using the [1mchar [22mrequest.  A typical leader combines the dot glyph “[1m.[22m” with a
     horizontal  motion  escape  sequence  to spread the dots.  The width of the
     page number field is stored in the [1mTC-MARGIN [22mregister.

[1mDifferences from AT&T [4mms[0m
     The [4mgroff[24m [4mms[24m macros are an  independent  reimplementation,  using  no  AT&T
     code.   Since  they  take advantage of the extended features of [4mgroff[24m, they
     cannot be used with AT&T [4mtroff[24m.  [4mgroff[24m [4mms[24m supports features described above
     as Berkeley and Research Tenth Edition Unix extensions, and adds several of
     its own.

     •  The internals of [4mgroff[24m [4mms[24m differ from those of AT&T [4mms[24m.  Documents  that
        depend  upon  implementation  details of AT&T [4mms[24m may not format properly
        with [4mgroff[24m [4mms[24m.  Such details include macros whose function was not docu‐
        mented in the AT&T [4mms[24m manual (“Typing Documents on the UNIX System:  Us‐
        ing the -ms Macros with Troff and Nroff”, M. E. Lesk, Bell Laboratories,
        1978).

     •  The  error-handling  policy  of [4mgroff[24m [4mms[24m is to detect and report errors,
        rather than to ignore them silently.

     •  Research Tenth Edition Unix supported [1mP1[22m/[1mP2 [22mmacros to bracket code exam‐
        ples; [4mgroff[24m [4mms[24m does not.

     •  [4mgroff[24m [4mms[24m does not work in  GNU  [4mtroff[24m's  AT&T  compatibility  mode.   If
        loaded when that mode is enabled, it aborts processing with a diagnostic
        message.

     •  Multiple  line  spacing is not supported.  Use a larger vertical spacing
        instead.

     •  [4mgroff[24m [4mms[24m uses the same header and footer  defaults  in  both  [4mnroff[24m  and
        [4mtroff[24m  modes as AT&T [4mms[24m does in [4mtroff[24m mode; AT&T's default in [4mnroff[24m mode
        is to put the date,  in  U.S.  traditional  format  (e.g.,  “January  1,
        2021”), in the center footer (the [1mCF [22mstring).

     •  Many [4mgroff[24m [4mms[24m macros, including those for paragraphs, headings, and dis‐
        plays,  cause  a reset of paragraph rendering parameters, and may change
        the indentation; they do so not by incrementing or decrementing it,  but
        by  setting  it  absolutely.  This can cause problems for documents that
        define additional macros of their own that manipulate indentation.   Use
        [1mRS [22mand [1mRE [22minstead of the [1min [22mrequest.

     •  AT&T [4mms[24m interpreted the values of the registers [1mPS [22mand [1mVS [22min points, and
        did not support the use of scaling units with them.  [4mgroff[24m [4mms[24m interprets
        values  of  the  registers  [1mPS[22m,  [1mVS[22m,  [1mFPS[22m,  and  [1mFVS[22m, equal to or larger
        than 1,000 (one thousand) as  decimal  fractions  multiplied  by  1,000.
        (Register  values are converted to and stored as basic units.  See “Mea‐
        surements” in the [4mgroff[24m Texinfo manual or in ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\).  This  threshold
        makes  use  of  a scaling unit with these parameters practical for high-
        resolution devices while preserving  backward  compatibility.   It  also
        permits  expression  of  non-integral  type  sizes.  For example, “[1mgroff[0m
        [1m-rPS=10.5p[22m” at the shell prompt is equivalent to placing “[1m.nr PS  10.5p[22m”
        at the beginning of the document.

     •  AT&T  [4mms[24m's [1mAU [22mmacro supported arguments whose values were used with some
        non-[1mRP [22mdocument types; that of [4mgroff[24m [4mms[24m does not.

     •  Right-aligned displays are available.  The AT&T [4mms[24m manual observes  that
        “it  is  tempting to assume that “[1m.DS R[22m” will right adjust lines, but it
        doesn't work”.  In [4mgroff[24m [4mms[24m, it does.

     •  To make [4mgroff[24m [4mms[24m use the default page offset (which also  specifies  the
        left  margin),  the  [1mPO  [22mregister must stay undefined until the first [4mms[0m
        macro is called.  This implies that [1m\n[PO] [22mshould not be used  early  in
        the document, unless it is changed also: accessing an undefined register
        automatically defines it.

     •  [4mgroff[24m  [4mms[24m supports the [1mPN [22mregister, but it is not necessary; you can ac‐
        cess the page number via the usual [1m% [22mregister and invoke the [1maf  [22mrequest
        to  assign a different format to it if desired.  (If you redefine the [4mms[0m
        [1mPT [22mmacro and desire special  treatment  of  certain  page  numbers——like
        “[1m1[22m”——you  may  need  to handle a non-Arabic page number format, as [4mgroff[0m
        [4mms[24m's [1mPT [22mdoes; see the macro package source.  [4mgroff[24m  [4mms[24m  aliases  the  [1mPN[0m
        register to [1m%[22m.)

     •  The  AT&T [4mms[24m manual documents registers [1mCW [22mand [1mGW [22mas setting the default
        column width and “intercolumn gap”, respectively, and which applied when
        [1mMC [22mwas called with fewer than two arguments.  [4mgroff[24m [4mms[24m instead treats [1mMC[0m
        without arguments as synonymous with [1m2C[22m; there is thus no occasion for a
        default column width register.  Further, the [1mMINGW [22mregister and the sec‐
        ond argument to [1mMC [22mspecify a [4mminimum[24m  space  between  columns,  not  the
        fixed gutter width of AT&T [4mms[24m.

     •  The  AT&T [4mms[24m manual did not document the [1mQI [22mregister; Berkeley and [4mgroff[0m
        [4mms[24m do.

     •  [4mgroff[24m [4mms[24m sets the register [1mGS [22mto 1; the AT&T [4mms[24m package does not use it.
        A document can test its value to determine whether it is being formatted
        with [4mgroff[24m [4mms[24m or another implementation.

   [1mUnix Version 7 macros unimplemented by [4mgroff[24m [4mms[0m
     Several macros described in the Unix Version 7 [4mms[24m documentation  are  unim‐
     plemented by [4mgroff[24m [4mms[24m because they are specific to the requirements of doc‐
     uments produced internally by Bell Laboratories, some of which also require
     a glyph for the Bell System logo that [4mgroff[24m does not support.  These macros
     implemented  several  document  type formats ([1mEG[22m, [1mIM[22m, [1mMF[22m, [1mMR[22m, [1mTM[22m, [1mTR[22m), were
     meaningful only in conjunction with the use of certain document types  ([1mAT[22m,
     [1mCS[22m,  [1mCT[22m,  [1mOK[22m,  [1mSG[22m), stored the postal addresses of Bell Labs sites ([1mHO[22m, [1mIH[22m,
     [1mMH[22m, [1mPY[22m, [1mWH[22m), or lacked a stable definition over time ([1mUX[22m).

[1mLegacy features[0m
     [4mgroff[24m [4mms[24m retains some legacy features solely to support formatting of  his‐
     torical  documents;  contemporary ones should not use them because they can
     render poorly.  See ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\ instead.

   [1mAT&T [4mms[24m accent mark strings[0m
     AT&T [4mms[24m defined accent mark strings as follows.

     [1mString   Description[0m
     ──────────────────────────────────────────────────────
     \*[']    Apply acute accent to subsequent glyph.
     \*[`]    Apply grave accent to subsequent glyph.
     \*[:]    Apply dieresis (umlaut) to subsequent glyph.
     \*[^]    Apply circumflex accent to subsequent glyph.
     \*[~]    Apply tilde accent to subsequent glyph.
     \*[C]    Apply caron to subsequent glyph.
     \*[,]    Apply cedilla to subsequent glyph.

   [1mBerkeley [4mms[24m accent mark and glyph strings[0m
     Berkeley [4mms[24m offered an [1mAM [22mmacro; calling it redefined the AT&T accent  mark
     strings  (except for [1m\*C[22m), applied them to the [4mpreceding[24m glyph, and defined
     additional strings, some for spacing glyphs.

     [1m.AM    [22mEnable alternative accent mark and glyph-producing strings.

     [1mString   Description[0m
     ───────────────────────────────────────────────────────────────
     \*[']    Apply acute accent to preceding glyph.
     \*[`]    Apply grave accent to preceding glyph.
     \*[:]    Apply dieresis (umlaut) to preceding glyph.
     \*[^]    Apply circumflex accent to preceding glyph.
     \*[~]    Apply tilde accent to preceding glyph.
     \*[,]    Apply cedilla to preceding glyph.
     \*[/]    Apply stroke (slash) to preceding glyph.
     \*[v]    Apply caron to preceding glyph.
     \*[_]    Apply macron to preceding glyph.
     \*[.]    Apply underdot to preceding glyph.
     \*[o]    Apply ring accent to preceding glyph.
     ───────────────────────────────────────────────────────────────
     \*[?]    Interpolate inverted question mark.
     \*[!]    Interpolate inverted exclamation mark.
     \*[8]    Interpolate small letter sharp s.
     \*[q]    Interpolate small letter o with hook accent (ogonek).
     \*[3]    Interpolate small letter yogh.
     \*[d-]   Interpolate small letter eth.
     \*[D-]   Interpolate capital letter eth.
     \*[th]   Interpolate small letter thorn.
     \*[TH]   Interpolate capital letter thorn.
     \*[ae]   Interpolate small ae ligature.
     \*[AE]   Interpolate capital ae ligature.
     \*[oe]   Interpolate small oe ligature.
     \*[OE]   Interpolate capital oe ligature.

[1mNaming conventions[0m
     External names available to documents that use the [4mgroff[24m [4mms[24m macros  contain
     only  uppercase  letters and digits.  The package reserves for internal use
     the following identifiers:

     •  those containing the characters [1m*[22m, [1m@[22m, and [1m:[22m; and

     •  those containing only uppercase letters and digits.

     When selecting a name for your document's own macros, strings,  and  regis‐
     ters, avoid those reserved by [4mgroff[24m [4mms[24m and those defined by GNU [4mtroff[24m.  See
     ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\ for complete lists thereof.

     [4mgroff[24m  [4mms[24m  organizes  most  of its internal names into modules.  The naming
     convenion is as follows.

     •  Names used only within one module are of the form [4mmodule[24m[1m*[4m[22mname[24m.

     •  Names used outside the module in which they are defined are of the  form
        [4mmodule[24m[1m@[4m[22mname[24m.

     •  Names   associated  with  a  particular  environment  are  of  the  form
        [4menvironment[24m[1m:[4m[22mname[24m; these are used only within the [1mpar [22mmodule.

     •  [4mname[24m does not have a module prefix.

     •  Names constructed to implement arrays are of the form [4marray[24m[1m![4m[22mindex[24m.

[1mFiles[0m
     [4m/usr/share/groff/1.24.0/tmac/s.tmac[0m
            implements the package.

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

     [4m/usr/share/groff/1.24.0/tmac/ms.tmac[0m
            is a wrapper enabling the package to be loaded with the  option  “[1m-m[0m
            [1mms[22m”.

[1mAuthors[0m
     The GNU version of the [4mms[24m macro package was written by James Clark and con‐
     tributors.   This document was written by Clark, ]8;;mailto:lkollar@despammed.com\Larry Kollar]8;;\, and ]8;;mailto:g.branden.robinson@gmail.com\G. Bran‐
     den Robinson]8;;\.

[1mSee also[0m
     A manual is available in source and rendered form.  On your system, it  may
     be compressed and/or available in additional formats.

     [4m/usr/share/doc/groff-1.24.0/ms.ms[0m
     [4m/usr/share/doc/groff-1.24.0/ms.ps[0m
            “Using [4mgroff[24m with the [4mms[24m Macro Package”; Larry Kollar and G. Branden
            Robinson.

     [4m/usr/share/doc/groff-1.24.0/msboxes.ms[0m
     [4m/usr/share/doc/groff-1.24.0/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.0                       2026-02-14                        [4mgroff_ms[24m(7)
────────────────────────────────────────────────────────────────────────────────
[4mgroff_rfc1345[24m(7)        Miscellaneous Information Manual        [4mgroff_rfc1345[24m(7)

[1mName[0m
     groff_rfc1345 - special character names from RFC 1345 and Vim digraphs

[1mDescription[0m
     The  file  [4mrfc1345.tmac[24m  defines  special  character  escape  sequences for
     ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\ based on the glyph mnemonics specified in RFC 1345 and the digraph
     table of the text editor Vim.  Each escape sequence translates to a Unicode
     code point, and will render correctly if the underlying font is  a  Unicode
     font that covers the code point.

     For  example,  “[1m\[Rx][22m”  is  the “recipe” or “prescription take” symbol, and
     maps to the code point U+211E.  [4mgroff[24m lets you write it as “[1m\[u211E][22m”,  but
     “[1m\[Rx][22m” is more mnemonic.

     For  a  list of the glyph names provided, please see the file [4mrfc1345.tmac[24m,
     which contains definitions of the form
            .char \[Rx] \[u211E]    \" PRESCRIPTION TAKE
     where [1m.char[22m's first argument defines a [4mgroff[24m special character  escape  se‐
     quence with a mnemonic glyph name, its second argument is a special charac‐
     ter  escape sequence based on the code point, and the comment describes the
     glyph defined.

     The RFC 1345 glyph names cover a wide range of Unicode code points, includ‐
     ing  supplemental  Latin,  Greek,  Cyrillic,  Hebrew,   Arabic,   Hiragana,
     Katakana,  and  Bopomofo letters, punctuation, math notation, currency sym‐
     bols, industrial and entertainment icons, and box-drawing symbols.

     The Vim digraph table is largely a subset of RFC  1345  (being  limited  to
     two-character  mnemonics),  but,  as  a  newer implementation, adds several
     mnemonics not specified in the RFC (Latin capital and small letters W and Y
     with grave accent,  bullet,  horizontal  ellipsis,  quadruple  prime,  “ap‐
     proaches  the limit”, and two mappings each for the Euro and rouble signs).
     These have also been added to [4mrfc1345.tmac[24m.

     [4mrfc1345.tmac[24m contains about 1,700 glyph names.  It is not an error to  load
     [4mrfc1345.tmac[24m  if your font does not have all the glyphs, as long as it con‐
     tains the glyphs that you actually use in your document.

     The RFC 1345 mnemonics are not identical in every case to the mappings  for
     special  character  glyph  names  that  are built in to [4mgroff[24m; for example,
     “[1m\[<<][22m” means the “much less than” sign (U+226A) when [4mrfc1345.tmac[24m  is  not
     loaded and this special character is not otherwise defined by a document or
     macro package.  [4mrfc1345.tmac[24m redefines “[1m\[<<][22m” to the “left-pointing double
     angle  quotation  mark”  (U+00AB).   See ]8;;man:groff_char(7)\[4mgroff_char[24m(7)]8;;\ for the full list of
     predefined special character escape sequences.

   [1mUsage[0m
     Load the [4mrfc1345.tmac[24m file.  This  can  be  done  by  either  adding  “[1m.mso[0m
     [1mrfc1345.tmac[22m”  to  your  document  before the first use of any of the glyph
     names the macro file defines, or by using the ]8;;man:troff(1)\[4mtroff[24m(1)]8;;\ option “[1m-m  rfc1345[22m”
     from the shell.

[1mBugs[0m
     As  the [4mgroff[24m Texinfo manual notes, “[o]nly the current font is checked for
     ligatures and kerns; neither special fonts nor entities  defined  with  the
     [1mchar [22mrequest (and its siblings) are taken into account.”  Many of the char‐
     acters  defined in [4mrfc1345.tmac[24m are accented Latin letters, and will be af‐
     fected by this deficiency, ]8;;https://savannah.gnu.org/bugs/?59932\producing subpar typography]8;;\.

[1mFiles[0m
     [4m/usr/share/groff/1.24.0/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.0                       2026-01-20                   [4mgroff_rfc1345[24m(7)
────────────────────────────────────────────────────────────────────────────────
[4mgroff_trace[24m(7)          Miscellaneous Information Manual          [4mgroff_trace[24m(7)

[1mName[0m
     groff_trace - macros for debugging GNU [4mroff[24m documents

[1mSynopsis[0m
     [1mgroff -m trace [22m[[4moption[24m ...] [[4mfile[24m ...]

[1mDescription[0m
     [4mtrace[24m  is  a macro package for the ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\ document formatting system, de‐
     signed as an aid for debugging documents written in its language.   It  is‐
     sues  a  message  to  the standard error stream upon entry to and exit from
     each macro call.  This can ease the process of isolating  errors  in  macro
     definitions.

     Activate  the  package  by specifying the command-line option “[1m-m trace[22m” to
     the formatter program (often ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\).  You can achieve finer  control  by
     including the macro file within the document; invoke the [1mmso [22mrequest, as in
     “[1m.mso  trace.tmac[22m”.  Only macros that are defined after this invocation are
     traced.  If the [1mtrace-full [22mregister is set to a true  value,  as  with  the
     command-line  option  “[1m-r  trace-full=1[22m”,  register and string assignments,
     along with some other requests, are traced also.  If another macro  package
     should be traced as well, specify it after “[1m-m trace[22m” on the command line.

     The macro file [4mtrace.tmac[24m is unusual because it does not contain any macros
     to  be  called by a user.  Instead, [4mgroff[24m's macro definition and alteration
     facilities are wrapped such that they display diagnostic messages.

   [1mLimitations[0m
     Because [4mtrace.tmac[24m wraps the [1mde [22mrequest (and its cousins), macro  arguments
     are expanded one level more.  This causes problems if an argument uses four
     or more backslashes to delay interpretation of an escape sequence.  For ex‐
     ample, the macro call
            .foo \\\\n[bar]
     normally passes “\\n[bar]” to macro “foo”, but with [1mde [22mredefined, it passes
     “\n[bar]” instead.

     The  solution  to this problem is to use [4mgroff[24m's [1m\E [22mescape sequence, an es‐
     cape character that is not interpreted in copy mode.
            .foo \En[bar]

[1mFiles[0m
     [4m/usr/share/groff/1.24.0/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.0                       2026-02-14                     [4mgroff_trace[24m(7)
────────────────────────────────────────────────────────────────────────────────
[4mgroff_www[24m(7)            Miscellaneous Information Manual            [4mgroff_www[24m(7)

[1mName[0m
     groff_www - GNU [4mroff[24m macros for authoring web pages

[1mSynopsis[0m
     [1mgroff -m www [22m[[4moption[24m ...] [[4mfile[24m ...]

[1mDescription[0m
     This  manual page describes the GNU [4mwww[24m macro package, which is part of the
     ]8;;man:groff(7)\[4mgroff[24m(7)]8;;\ document formatting system.   This  macro  file  is  automatically
     loaded by the default [4mtroffrc[24m file when the formatter (usually ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\) is
     called with either of the options “[1m-T html[22m” or “[1m-T xhtml[22m”.  The HTML output
     driver ]8;;man:grohtml(1)\[4mgrohtml[24m(1)]8;;\ is in a beta state; [4mgroff[24m distributes these macros to en‐
     courage its testing.

     Macro       Meaning
     ────────────────────────────────────────────────────────────
     [1mJOBNAME     [22msplit output into multiple files
     [1mHX          [22mautomatic heading level cut-off
     [1mBCL         [22mspecify colours on a web page
     [1mBGIMG       [22mspecify background image
     [1mURL         [22mcreate a URL using two parameters
     [1mMTO         [22mcreate an HTML email address
     [1mTAG         [22mgenerate an HTML name
     [1mIMG         [22minclude an image file
     [1mPIMG        [22minclude PNG image
     [1mMPIMG       [22mplace PNG on the margin and wrap text around it
     [1mHnS         [22mbegin heading
     [1mHnE         [22mend heading
     [1mLK          [22memit automatically collected links
     [1mHR          [22mproduce a horizontal rule
     [1mNHR         [22msuppress automatic generation of rules
     [1mHTL         [22mrecord document title as HTML metadata only
     [1mHEAD        [22madd data to <head> block
     [1mULS         [22munordered list begin
     [1mULE         [22munordered list end
     [1mOLS         [22mordered list begin
     [1mOLE         [22mordered list end
     [1mDLS         [22mdefinition list begin
     [1mDLE         [22mdefinition list end
     [1mLI          [22minsert a list item
     [1mDC          [22mgenerate a drop capital
     [1mHTML        [22mtransmit raw HTML to output driver
     [1mCDS         [22mcode example begin
     [1mCDE         [22mcode example end
     [1mALN         [22mplace links on left of main text
     [1mLNS         [22mstart two-column table with links on the left
     [1mLNE         [22mend two-column table started with [1m.LNS[0m
     [1mLINKSTYLE   [22minitialize default URL attributes

[1mMacros[0m
     [1mJOBNAME [4m[22mfile-name-stem[0m
              Split output into multiple HTML files.  In [4mms[24m documents, a file is
              split  whenever  an [1m.SH [22mor “[1m.NH 1[22m” call is encountered.  Its argu‐
              ment is the file name stem used for output files.  This option  is
              equivalent to [4mgrohtml[24m's [1m-j [22moption.

     [1mHX [4m[22mn[24m     Set  section heading level above which [4mgrohtml[24m is not to automati‐
              cally generate links to  [4mn.[24m   For  example,  when  used  with  the
              ]8;;man:groff_ms(7)\[4mgroff_ms[24m(7)]8;;\  package, “[1m.HX 2[22m” causes [4mgrohtml[24m to generate a list of
              links for [4mms[24m macro calls “[1m.NH 1[22m” and “[1m.NH 2[22m” but not for “[1m.NH  3[22m”,
              whereas “[1m.HX 0[22m” generates no hyperlinks to section headings.  Giv‐
              ing [4mgroff[24m the option “[1m-P -l[22m” disables automatic heading linkage.

     [1mBCL [4m[22mforeground[24m [4mbackground[24m [4mactive[24m [4mnot-visited[24m [4mvisited[0m
              Configure  colours  used for page foreground, page background, ac‐
              tive hypertext link, hypertext links not yet visited, and  visited
              hypertext links.

     [1mBGIMG [4m[22mfile[0m
              Set the background image to [4mfile.[0m

     [1mURL [4m[22murl[24m [[4mlink-text[24m [[4mpost[24m]]
              Generate a hyperlink to [4murl[24m with optional [4mlink-text[24m followed imme‐
              diately by non-linked text [4mpost.[0m

              If  [4mlink-text[24m  is  absent, [4murl[24m is formatted as the link text.  Hy‐
              phenation is disabled while  formatting  a  URL;  insert  explicit
              break points with the [1m\: [22mescape sequence.

     [1mMTO [4m[22maddress[24m [[4mlink-text[24m [[4mpost[24m]]
              Generate  an  email  hyperlink  to [4maddress[24m with optional [4mlink-text[0m
              followed immediately by non-linked text [4mpost.[0m

              If [4mlink-text[24m is absent, [4maddress[24m is formatted  as  the  link  text.
              Hyphenation  is  disabled  while formatting a URL; insert explicit
              break points with the [1m\: [22mescape sequence.

     [1mTAG [4m[22mname[0m
              Generate an anchor [4mname[24m marking its location in the document as  a
              target for hyperlinks.

     [1mIMG [4m[22mfile-name[24m [[1m-C[22m|[1m-L[22m|[1m-R[22m] [[4mwidth[24m [[4mheight[24m]]
              Insert  graphical  image  [4mfile-name.[24m  The optional second argument
              aligns the image to the center ([1m-C[22m; default), left ([1m-L[22m), or  right
              ([1m-R[22m).  The optional [4mwidth[24m defaults to 100 units (in the context of
              the HTML renderer) and the optional [4mheight[24m to the same measurement
              as [4mwidth[24m [4m.[0m

     [1mPIMG [22m[[1m-C[22m|[1m-L[22m|[1m-R[22m] [4mfile-name[24m [[4mwidth[24m [[4mheight[24m]]
              Insert  graphical  image  [4mfile-name,[24m  assumed to be in PNG format.
              Compared to [1mIMG[22m, this macro has the advantage of working with both
              PostScript and HTML devices since it converts [4mfile-name[24m  into  EPS
              format  using ]8;;man:pngtopnm(1)\[4mpngtopnm[24m(1)]8;;\, ]8;;man:pnmcrop(1)\[4mpnmcrop[24m(1)]8;;\, and ]8;;man:pnmtops(1)\[4mpnmtops[24m(1)]8;;\.  [4mheight[24m and
              [4mwidth[24m may be given as percentages (of the line length  [1m\n[.l]  [22mand
              page length [1m\n[.p][22m, respectively).

              If  the document isn't processed with “[1m-T html[22m” or “[1m-T xhtml[22m”, you
              must use ]8;;man:groff(1)\[4mgroff[24m(1)]8;;\'s [1m-U [22moption.

     [1mMPIMG [22m[[1m-L[22m|[1m-R[22m] [[1m-G [4m[22mgap[24m] [4mfile-name[24m [[4mwidth[24m [[4mheight[24m]]
              As [1mPIMG[22m, but place the image at a margin and wrap text around  it.
              The  image  is aligned the to the left ([1m-L[22m, default) or right ([1m-R[22m)
              margin.  [1m-G [4m[22mgap[24m imposes horizontal space of [4mgap[24m pixels between the
              picture and the text that wraps around it.   The  default  [4mgap[24m  is
              zero.

     [1mHnS [4m[22mn[24m    Begin heading at level [4mn.[0m

     [1mHnE      [22mEnd heading text.

     [1mLK       [22mDirect  [4mgrohtml[24m to emit the list of automatically generated hyper‐
              links at this location.

     [1mHR       [22mGenerate a full-width horizontal rule when used with “[1m-T html[22m”  or
              “[1m-T xhtml[22m”.

     [1mNHR      [22mSuppress  the  horizontal  rules  at the document's top and bottom
              that [4mgrohtml[24m emits by default.

     [1mHTL      [22mGenerate an HTML title only.  This differs from  ]8;;man:groff_ms(7)\[4mgroff_ms[24m(7)]8;;\'s  [1mTL[0m
              macro,  which  generates  both  an HTML title and an <H1> heading.
              Use it to provide an HTML title as document metadata  but  not  as
              formatted  text.   The  title  ends when vertical space ([1m.sp[22m) or a
              break ([1m.br[22m) is seen.

     [1mHEAD     [22mAdd arbitrary data to the HTML <head>  element.   Ignored  if  not
              processed with “[1m-T html[22m” or “[1m-T xhtml[22m”.

     [1mHTML     [22mAll  text after this macro is treated as raw HTML.  Ignored if not
              processed with “[1m-T html[22m” or “[1m-T xhtml[22m”.

     [1mDC [4m[22mL[24m [4mtext[24m [[4mcolor[24m]
              Format a “drop cap”——a large character [4mL[24m (usually a  capital  let‐
              ter) at a larger size and with a lower text baseline than the fol‐
              lowing [4mtext,[24m such that the cap-heights of [4mL[24m and [4mtext[24m align, in the
              specified [4mcolor[24m (default: black).

     [1mCDS      [22mBegin  code  display; a monospaced font is selected and filling is
              disabled.

     [1mCDE      [22mEnd code display.

     [1mALN [22m[[4mcolor[24m [[4mwidth-percentage[24m]]
              Enable a “navigation pane” containing links to  section  headings,
              aligned  to  the left of running text, and configure its rendering
              parameters.  Columnation is achieved with an  HTML  table.   [4mcolor[0m
              indicates  an  HTML  background color to be used in the navigation
              column; the default is [1m#eeeeee[22m.   [4mwidth-percentage[24m  allocates  the
              given  percentage  of  the navigation pane's table column; the de‐
              fault is [1m30[22m.  Call this macro at most once, at  the  beginning  of
              the document.

     [1mLNS      [22mBegin text indexed by the navigation pane configured by [1mALN[22m.

     [1mLNE      [22mEnd text indexed by navigation pane started by [1mLNS[22m.

     [1mLINKSTYLE [4m[22mcolor[24m [[4mfont-style[24m [[4mopen-glyph[24m [4mclose-glyph[24m]]
              Configure  rendering  of  formatted  hyperlink targets for devices
              other than [1mhtml [22mand [1mxhtml[22m; render targets in [4mcolor[24m (default: blue)
              using the typeface [4mfont-style[24m (default: [1mCR[22m) bracketed  with  [4mopen-[0m
              [4mglyph[24m and [4mclose-glyph[24m (defaults: [1m\[la] [22mand [1m\[ra][22m, respectively).

[1mSection heading links[0m
     By default [4mgrohtml[24m generates links to all section headings and places these
     at  the  top  of the HTML document.  Configure this behavior with [1mHX [22mand/or
     [1mLK[22m.

[1mLimitations of [4mgrohtml[0m
     ]8;;man:tbl(1)\[4mtbl[24m(1)]8;;\ tables are rendered as PNG images.

     All URLs currently are treated as consuming  no  textual  space  in  [4mgroff[24m.
     This  could  be considered as a bug since it causes some problems.  To cir‐
     cumvent this, [4mwww.tmac[24m inserts a zero-width character which  expands  to  a
     harmless space (only if run with [1m-Thtml [22mor [1m-Txhtml[22m).

     Some  of  the  macros, like [1mALN[22m, [1mLNS[22m, and [1mLNE[22m, are integrated only with the
     ]8;;man:groff_ms(7)\[4mgroff_ms[24m(7)]8;;\ package.

[1mFiles[0m
     [4m/usr/share/groff/1.24.0/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.0                       2025-12-18                       [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 Mergenthaler Linotron 202, Kernighan undertook a revision
     and rewrite of [4mtroff[24m to generalize its design.  To implement  this  revised
     architecture, he developed the font and device description file formats and
     the page description language that remain in use today.  He described these
     novelties  in the article “A Typesetter-independent TROFF”, last revised in
     1982, and like the [4mtroff[24m manual itself, 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 view‐
     graphs and slides, and the [4mideal[24m preprocessor, which produces diagrams from
     mathematical constraints).  Beyond that, it has  added  numerous  features;
     see  ]8;;man:groff_diff(7)\[4mgroff_diff[24m(7)]8;;\.   Since  its  inception  and for at least the following
     three decades, it has been used by practically all GNU/Linux and BSD  oper‐
     ating 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 processors 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.0                       2026-01-05                            [4mroff[24m(7)
