[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 addi‐
       tional font metric information required by GNU  [4mgtroff[24m(1),  and  writes
       the  combined  result to the standard output.  The information added is
       derived from the font’s existing parameters and assumptions about  tra‐
       ditional  [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 corresponding parameters in the [4mDESC[24m file.
       [4mfont[24m is the name of the file describing 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
       information; 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 [4mgroff_font[24m(5).

       [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 un‐
       specified  parameters.   If  a  parameter is not specified, the default
       will be used.  The defaults are chosen to produce reasonable values for
       a Times font.

[1mSee also[0m
       [4mgroff_font[24m(5), [4mgroff[24m(1), [4mgroff_char[24m(7)

groff 1.23.0                      2 July 2023                     [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
       output

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

       [1mafmtodit --help[0m

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

[1mDescription[0m
       [4mafmtodit[24m  adapts  an Adobe Font Metric file, [4mafm‐file[24m, for use with the
       [1mps [22mand [1mpdf [22moutput devices of [4mgtroff[24m(1).  [4mmap‐file[24m  associates  a  [4mgroff[0m
       ordinary  or special character name with a PostScript glyph name.  Out‐
       put is written in [4mgroff_font[24m(5) format to [4mfont‐description‐file,[24m 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[0m
       ordinary  (if  of unit length) or special (if longer) character identi‐
       fier.  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 [4mdevps/generate[24m subdirectory of the default font di‐
       rectory.

       If a PostScript glyph is not mentioned in [4mmap‐file[24m, and a [4mgroff[24m charac‐
       ter  name  can’t be deduced using the Adobe Glyph List (AGL, built into
       [4mafmtodit[24m), then [4mafmtodit[24m puts the PostScript glyph into the [4mgroff[24m  font
       description  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 con‐
       taining one or more periods are mapped to unnamed entities.  Unless  [1m-e[0m
       is  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[24m [4mtroff[24m, the [4mgroff[24m Texinfo manual, or
       [4mgroff_char[24m(7), which describe how [4mgroff[24m character identifiers are  con‐
       structed.

       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 ac‐
       cess them only via special character identifiers.

       If the font file proper (not just its metrics) is available, listing it
       in  the   files   [4m/usr/pkg/share/groff/1.23.0/font/devps/download[24m   and
       [4m/usr/pkg/share/groff/1.23.0/font/devpdf/download[24m  enables  it to be em‐
       bedded in the output produced by [4mgrops[24m(1) and [4mgropdf[24m(1), respectively.

       If the [1m-i [22moption is used, [4mafmtodit[24m automatically  generates  an  italic
       correction,  a  left  italic correction, and a subscript correction for
       each glyph (the significance of these is explained  in  [4mgroff_font[24m(5));
       they  can  be specified for individual glyphs by adding to the [4mafm‐file[0m
       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  parame‐
       ters are normally needed only for italic (or oblique) fonts.

       The  [1m-s  [22moption  should be given if the font is “special”, meaning that
       [4mgroff[24m should search it whenever a glyph is not  found  in  the  current
       font.  In that case, [4mfont‐description‐file[24m should be listed as an argu‐
       ment  to the [1mfonts [22mdirective in the output device’s [4mDESC[24m file; if it is
       not special, there is no need to do so, since [4mgtroff[24m(1) will  automati‐
       cally mount it when it is first used.

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

       [1m-a [4m[22mslant[0m
              Use [4mslant[24m as the slant (“angle”) parameter in the font  descrip‐
              tion  file; this is used by [4mgroff[24m in the positioning of accents.
              By default [4mafmtodit[24m uses the negative of the [1mItalicAngle  [22mspeci‐
              fied in the AFM file; with true italic fonts it is sometimes de‐
              sirable 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
              PostScript 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 subdi‐
              rectory 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
              [4mgrops[24m(1).  If not found in the current directory, the [4mdevps[24m sub‐
              directory 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[0m
              thousandths 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  un‐
              less option [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 mono‐
              spaced (constant‐width) fonts.

       [1m-m     [22mPrevent negative left italic correction values.   Font  descrip‐
              tion  files for roman styles distributed with [4mgroff[24m were created
              with “[1m-i0 -m[22m” to improve spacing with [4mgeqn[24m(1).

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

       [1m-s     [22mAdd the [1mspecial [22mdirective to the font description file.

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

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

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

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

       [4m/usr/pkg/share/groff/1.23.0/font/devps/download[0m
              lists  fonts available for embedding within the PostScript docu‐
              ment (or download to the device).

       [4m/usr/pkg/share/groff/1.23.0/font/devps/generate/dingbats.map[0m
       [4m/usr/pkg/share/groff/1.23.0/font/devps/generate/dingbats-reversed.map[0m
       [4m/usr/pkg/share/groff/1.23.0/font/devps/generate/slanted-symbol.map[0m
       [4m/usr/pkg/share/groff/1.23.0/font/devps/generate/symbol.map[0m
       [4m/usr/pkg/share/groff/1.23.0/font/devps/generate/text.map[0m
              map names in the Adobe Glyph List  to  [4mgroff[24m  special  character
              identifiers  for  Zapf  Dingbats  ([1mZD[22m),  reversed  Zapf Dingbats
              ([1mZDR[22m), slanted symbol ([1mSS[22m), symbol ([1mS[22m), and text fonts,  respec‐
              tively.   These  [4mmap‐file[24ms are used to produce the font descrip‐
              tion 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
              ignored  AGL  name  contains  four hexadecimal digits [4mXXXX[24m.  The
              Adobe Glyph List (AGL) has its own names for  glyphs;  they  are
              often  different from [4mgroff[24m’s special character names.  [4mafmtodit[0m
              is constructing 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  map‐
              pings.   For  example, if [4mx[24m is [1m*D[22m, [4my[24m is [1mDelta[22m, and [4mz[24m is [1muni0394[22m,
              [4mafmtodit[24m is telling you that the [4mgroff[24m font description that  it
              is  writing  cannot map the [4mgroff[24m 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  map‐
              ping  is  ignored,  a remedy is to craft an alternative [4mmap‐file[0m
              and re‐run [4mafmtodit[24m using it.

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

       [4mgroff[24m(1), [4mgropdf[24m(1), [4mgrops[24m(1), [4mgroff_font[24m(5)

groff 1.23.0                      2 July 2023                      [4mafmtodit[24m(1)
───────────────────────────────────────────────────────────────────────────────
[4mgchem[24m(1)                    General Commands Manual                   [4mgchem[24m(1)

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

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

       [1mgchem -h[0m
       [1mgchem --help[0m

       [1mgchem -v[0m
       [1mgchem --version[0m

[1mDescription[0m
       [4mchem[24m  produces  chemical  structure  diagrams.  Today’s version is best
       suited for organic chemistry (bonds, rings).  The [4mgchem[24m  program  is  a
       [4mgroff[24m preprocessor like [4mgeqn[24m, [4mgpic[24m, [4mgtbl[24m, etc.  It generates [4mpic[24m output
       such  that  all [4mchem[24m parts are translated into diagrams of the [4mpic[24m lan‐
       guage.

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

       The program [4mgchem[24m originates from the Perl  source  file  [4mchem.pl[24m.   It
       tells  [4mgpic[24m to include a copy of the macro file [4mchem.pic[24m.  Moreover the
       [4mgroff[24m 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 [4mgchem[24m, respectively.  In [4mpic[24m context, i.e., after the call of  [1m.PS[22m,
       [4mchem[24m  input  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
       modification;  all  data  between the initialization lines is converted
       into [4mpic[24m 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 [4mgchem[24m followed by
       [4mgroff[24m with the option [1m-p [22mfor the activation of [4mgpic[24m:

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

[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  ig‐
       nored.

       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[24m 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;
              default is 10 point.

   [1mBonds[0m
       This

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

       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 di‐
       rection 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 dotted 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
       support.   [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 di‐
       rection.  So the corners of [1mR1 [22mare [1mR1.V1 [22m(the [4mtop[24m), [1mR1.V2[22m, [1mR1.V3[22m, [1mR1.V4[0m
       (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
       written 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[0m
       is 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 ap‐
       pear  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  sur‐
       rounded 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[24m 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 specify‐
       ing  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 com‐
       mand.  It represents a string  that  should  be  printed  (without  the
       quotes).   Text within quotes [1m"[22m...[1m" [22mis treated more or less like a moi‐
       ety 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 let‐
       ters and numbers is valid:

              [1mFirst: bond[0m
                     [1mbond 30 from First[0m

   [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
       signals 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 [22mhas 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
       label.

       Since [4mgchem[24m is a [4mgpic[24m preprocessor,  it  is  possible  to  include  [4mpic[0m
       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[0m
       command 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 short‐
       hand 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$ [22mcon‐
       struct 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/pkg/share/groff/1.23.0/pic/chem.pic[0m
              A collection of [4mpic[24m macros needed by [4mgchem[24m.

       [4m/usr/pkg/share/groff/1.23.0/tmac/pic.tmac[0m
              A macro file which redefines [1m.PS[22m, [1m.PE[22m, and [1m.PF [22mto center [4mpic[24m di‐
              agrams.

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

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

[1mAuthors[0m
       The GNU version of  [4mchem[24m  was  written  by  Bernd  Warken  ⟨groff-bernd
       .warken-72@web.de⟩.    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
       Laboratories Computing Science Technical Report No. 122

       [4mgroff[24m(1), [4mgpic[24m(1)

groff 1.23.0                      2 July 2023                         [4mgchem[24m(1)
───────────────────────────────────────────────────────────────────────────────
[4mgeqn[24m(1)                     General Commands Manual                    [4mgeqn[24m(1)

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

[1mSynopsis[0m
       [1mgeqn [22m[[1m-CNrR[22m] [[1m-[22md [4mxy[24m] [[1m-f [4m[22mF[24m] [[1m-m [4m[22mn[24m] [[1m-M [4m[22mdir[24m] [[1m-p [4m[22mn[24m] [[1m-s [4m[22mn[24m] [[1m-T [4m[22mdev[24m]
            [[4mfile[24m ...]

       [1mgeqn --help[0m

       [1mgeqn -v[0m
       [1mgeqn --version[0m

[1mDescription[0m
       The GNU implementation of [4meqn[24m is part of the [4mgroff[24m(7) document  format‐
       ting  system.  [4mgeqn[24m is a [4mgtroff[24m(1) preprocessor that translates expres‐
       sions in its own language, embedded in [4mroff[24m(7) input files, into mathe‐
       matical notation typeset by [4mgtroff[24m(1).  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  delim‐
       iters.   Normally,  [4mgeqn[24m  is not executed directly by the user, but in‐
       voked by specifying the [1m-e [22moption to [4mgroff[24m(1).  While GNU  [4meqn[24m’s  input
       syntax  is  highly  compatible  with AT&T [4meqn[24m, the output [4mgeqn[24m produces
       cannot be processed by AT&T [4mtroff[24m; GNU [4mtroff[24m (or a  [4mtroff[24m  implementing
       relevant  GNU  extensions) must be used.  If no [4mfile[24m operands are given
       on the command line, or if [4mfile[24m is “[1m-[22m”, [4mgeqn[24m reads the  standard  input
       stream.

       Unless  the  [1m-R [22moption is used, [4mgeqn[24m searches for the file [4meqnrc[24m in the
       directories   given   with   the   [1m-M    [22moption    first,    then    in
       [4m/usr/pkg/share/groff/site-tmac[24m,  and  finally in the standard macro di‐
       rectory [4m/usr/pkg/share/groff/1.23.0/tmac[24m.  If it exists  and  is  read‐
       able, [4mgeqn[24m processes it before any input files.

       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[24m below; these may safely be ignored if you do not know TeX.

       Three points are worth special 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  base‐
         line,  not  the  three centered dots of AT&T [4meqn[24m.  Set an ellipsis on
         the math axis with the GNU extension macro [1mcdots[22m.

   [1mAnatomy of an equation[0m
       [4meqn[24m input consists of tokens.  Consider a form of Newton’s  second  law
       of motion.  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.

       The  following  input  characters  not only separate tokens, but manage
       their grouping and spacing 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 in‐
       put.  When they occur, they must appear at the outermost lexical scope.
       This roughly means that they can’t appear within braces that are neces‐
       sary to disambiguate the input; [4mgeqn[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 fore‐
       going, or components of an equation.

       [4mPrimitives[24m are fundamental keywords of the [4meqn[24m language.  They can con‐
       figure an aspect  of  the  preprocessor’s  state,  as  when  setting  a
       “global” font selection or type size ([1mgfont [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 after them (as
       with [1mfat[22m, [1mover[22m, [1msqrt[22m, or [1mup[22m).

       Equation [4mcomponents[24m include mathematical variables, constants,  numeric
       literals, and operators.  [4mgeqn[24m remaps some input character sequences to
       [4mgroff[24m  special character escape sequences for economy in equation entry
       and to  ensure  that  glyphs  from  an  unstyled  font  are  used;  see
       [4mgroff_char[24m(7).

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

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

   [1mSpacing and typeface[0m
       GNU [4meqn[24m imputes types to the components of an equation,  adjusting  the
       spacing  between  them  accordingly.   Recognized types are as follows;
       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.

       [4mgeqn[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"    ^~

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

   [1mPrimitives[0m
       [4mgeqn[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
       The  GNU extension primitives “[1mtype[22m” and [1mchartype [22mare discussed in sub‐
       section “Spacing and typeface” above; “[1mset[22m” in  subsection  “Customiza‐
       tion” below; and [1mgrfont [22mand [1mgbfont [22min subsection “Fonts” below.  In the
       following synopses, [4mX[24m can be any character not appearing in the parame‐
       ter thus bracketed.

       [4me1[24m [1maccent [4m[22me2[0m
              Set  [4me2[24m as an accent over [4me1[24m.  [4me2[24m is assumed to be at the appro‐
              priate height for a lowercase letter without an ascender; [4mg[24m  [4meqn[0m
              vertically shifts it depending on [4me1[24m’s height.  For example, [1mhat[0m
              is defined as follows.

                     accent { "^" }

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

       [1mbig [4m[22me[24m  Enlarge the expression [4me[24m; semantics like those  of  CSS  “large”
              are intended.  In [4mgtroff[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 [22mor [1m.EN[22m.  If a relative path name, [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
              expansion; 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
              input “[1mA opprime sub 1[22m”, the “1” is tucked under the prime as  a
              subscript  to  the “A” (as is conventional in mathematical type‐
              setting), 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  primi‐
              tives  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 reduces the type size of [4me1[24m and [4me2[24m, and puts less
              vertical space between [4me1[24m and [4me2[24m and the fraction bar.  The [1mover[0m
              primitive 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
              default  values,  where  [4mn[24m is an integer in hundredths of an em.
              If positive, [4mn[24m increases vertical spacing before  the  equation;
              if negative, it does so after the equation.  This primitive pro‐
              vides  an  interface 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 [4mgpic[24m(1) picture.

       [1mspecial [4m[22mtroff‐macro[24m [4me[0m
              Construct  an  object  by  calling  [4mtroff‐macro[24m on [4me[24m.  The [4mtroff[0m
              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 object an accent over  it  should  be
              placed.)   The  macro  must modify [1m0s [22mso that it outputs the de‐
              sired result, returns the drawing position to the text  baseline
              at  the  beginning  of [4me[24m, and updates the foregoing 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 -
              because they are part of the argument to a [4mgtroff[24m macro, so [4mgeqn[0m
              does not transform them to mathematical glyphs for us.  Here’s a
              more  complicated  construct  that draws a box around an expres‐
              sion; the bottom of the box rests on the text baseline.  We  de‐
              fine the [4meqn[24m macro [1mbox [22mto wrap the call of the [4mgtroff[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
              expansion; it is split up and the spacing between characters ad‐
              justed 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 appro‐
              priate height for a letter without a descender; [4mg[24m [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 unde‐
              fined.

       [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 [4mgeqn[24m ignores  this
              primitive  when  producing that output format.  The built‐in [1msum[0m
              macro 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
       deliberate incompatibility.

       [1mdelim on[0m
              [4mgeqn[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
              effect.   Few  [4meqn[24m  documents are expected to use “o” and “n” as
              left and right delimiters, respectively.  If  yours  does,  con‐
              sider swapping 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) increases the ver‐
              tical spacing between rows, using  [4mgroff[24m’s  [1m\x  [22mescape  sequence
              (the  value  has no effect in MathML mode).  Negative values are
              accepted but have no effect.  If more than one [4mn[24m occurs in a ma‐
              trix or pile, the largest is used.

   [1mCustomization[0m
       When [4mgeqn[24m generates [4mgtroff[24m input, the appearance of equations  is  con‐
       trolled by a large number of parameters.  They have no effect when gen‐
       erating  MathML,  which delegates typesetting to a MathML rendering en‐
       gine.  Configure these parameters with the [1mset [22mprimitive.

       [1mset [4m[22mp[24m [4mn[0m
              assigns parameter [4mp[24m the integer value [4mn[24m;  [4mn[24m  is  interpreted  in
              units of hundredths of an em unless otherwise stated.  For exam‐
              ple,

                     set x_height 45

              says  that  [4mgeqn[24m  should  assume  that  the  font’s  x‐height is
              0.45 ems.

              Available parameters 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
                               overprinting two copies of the  equation  hori‐
                               zontally  offset by this amount ([1m4[22m).  In MathML
                               mode, components to  which  [1mfat_offset  [22mapplies
                               instead 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 denominator; in other words,  it  overhangs
                               the  numerator and denominator by at least this
                               amount ([1m0[22m).

              [1maccent_width     [22mWhen [1mbar [22mor [1munder [22mis applied to a single  char‐
                               acter,  the  line is this long ([1m31[22m).  Normally,
                               [1mbar [22mor [1munder [22mproduces 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[0m
                               and [1mright [22mprimitives have a combined height and
                               depth  of  at  least  this  many thousandths of
                               twice the maximum amount by which the sub‐equa‐
                               tion that the delimiters enclose  extends  away
                               from the axis ([1m900[22m).

              [1mdelimiter_shortfall[0m
                               Extensible  delimiters  produced  with the [1mleft[0m
                               and [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  delimiters  enclose  extends away from the
                               axis and this amount ([1m50[22m).

              [1mnull_delimiter_space[0m
                               This 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
                               after punctuation characters.  It also  config‐
                               ures  the  width of the space produced by the [1m^[0m
                               token ([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.  It  also  config‐
                               ures  the  width of the space produced by the [1m~[0m
                               token ([1m28[22m).

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

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

              [1mdefault_rule_thickness[0m
                               This should be set  to  the  thickness  of  the
                               [1m\[ru] [22mcharacter, 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 denomi‐
                               nator 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  lim‐
                               its  or  numerators  of [1msmallover [22mfractions are
                               shifted up by at least this amount ([1m37[22m).   Con‐
                               ventionally, 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).   Convention‐
                               ally, 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  super‐
                               script,  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 superscript 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 subscript 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
                               below the bottom of the  object  on  which  the
                               limit is set ([1m60[22m).

              [1mbig_op_spacing5  [22mThis much vertical space is added above and be‐
                               low 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
                               bottom 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
                               matrix ([1m100[22m).

              [1mmatrix_side_sep  [22mThis  much space is added at each side of a ma‐
                               trix ([1m17[22m).

              [1mdraw_lines       [22mIf non‐zero, [4mgeqn[24m draws lines using  the  [4mtroff[0m
                               [1m\D  [22mescape  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 devices, otherwise [1m0[22m.

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

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

              [1mnroff            [22mIf non‐zero, then [1mndefine [22mbehaves  like  [1mdefine[0m
                               and  [1mtdefine  [22mis ignored, otherwise [1mtdefine [22mbe‐
                               haves like [1mdefine [22mand [1mndefine [22mis ignored.   The
                               [4meqnrc[24m  file  sets  the  default:  [1m1  [22mon  [1mascii[22m,
                               [1mlatin1[22m, [1mutf8[22m, and [1mcp1047 [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 argu‐
       ments.  In this context only, commas and parentheses also serve as  to‐
       ken  separators.   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 arguments, 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 clas‐
       sical 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 ini‐
       tial capital letter ([1mAlpha[22m) or in full capitals ([1mALPHA[22m) to  obtain  up‐
       percase forms.

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

   [1mFonts[0m
       [4mgeqn[24m  uses  up to three typefaces to set an equation: italic (oblique),
       roman (upright), and bold.  Assign each a [4mgroff[24m typeface with the prim‐
       itives [1mgfont[22m, [1mgrfont[22m, and [1mgbfont.  [22mThe defaults are the  styles  [1mI[22m,  [1mR[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.  This is a GNU extension.

       [1mgfont [4m[22mf[0m
              Select [4mf[24m as the italic font.

       [1mgrfont [4m[22mf[0m
              Select [4mf[24m as the roman font.  This is a GNU extension.

[1mOptions[0m
       [1m--help [22mdisplays a usage message, while [1m-v [22mand  [1m--version  [22mshow  version
       information; 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 [4m[22mxy[24m” statements in the source file override this option.

       [1m-f [4m[22mF[24m   is equivalent to “[1mgfont [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  “Descrip‐
              tion” above.

       [1m-N     [22mProhibit newlines within delimiters.  This option allows [4mgeqn[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.  [4mgeqn[24m normally sets  sub‐  and
              superscripts at 70% of the type size of the surrounding text.

       [1m-r     [22mReduce  the type size of subscripts at most once relative to the
              base type size for the equation.

       [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.  In most cases, the effect of
              this is to define a macro [4mdev[24m with a value of [1m1[22m; [4meqnrc[24m uses this
              to provide definitions appropriate for the device.  However,  if
              the  specified  driver  is “MathML”, the output is MathML markup
              rather than [4mgtroff[24m input, and [4meqnrc[24m is not loaded at  all.   The
              default output device is [1mps[22m.

[1mFiles[0m
       [4m/usr/pkg/share/groff/1.23.0/tmac/eqnrc[0m
              Initialization file.

[1mMathML mode limitations[0m
       MathML  is  designed  on  the  assumption that it cannot know the exact
       physical characteristics of the media and devices on which it  will  be
       rendered.  It does not support control of motions and sizes to the same
       degree [4mgtroff[24m does.

       • [4mgeqn[24m customization parameters have no effect on generated MathML.

       • The  [1mspecial[22m,  [1mup[22m,  [1mdown[22m,  [1mfwd[22m,  and [1mback [22mprimitives cannot be imple‐
         mented, 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 [4mgeqn[24m sets extra large in [4mtroff[24m mode—notably the inte‐
         gral  sign—may  appear  too  small  and need to have their “<mstyle>”
         wrappers adjusted by hand.

       As in its [4mtroff[24m mode, [4mgeqn[24m in MathML mode leaves the [1m.EQ [22mand [1m.EN [22mtokens
       in place, but emits nothing corresponding to  [1mdelim  [22mdelimiters.   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  recog‐
       nized  as  names  of  macros or primitives, or if they are to be inter‐
       preted 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 “[1mgfont[0m
       [1mPI[22m” does not select [4mgroff[24m’s Palatino italic font for the global  italic
       face; you must use “[1mgfont "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 open‐
       ing delimiter.

       Unlike TeX, [4meqn[24m does not inherently distinguish  displayed  and  inline
       equation  styles;  see  the  [1msmallover [22mprimitive above.  However, macro
       packages frequently define [1mEQ [22mand [1mEN  [22mmacros  such  that  the  equation
       within  is displayed.  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  ex‐
       pressions,  or  unintelligible  gibberish.   But there’s no changing it
       now.

       In [4mnroff[24m mode, lowercase Greek letters are rendered in roman instead of
       italic style.

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

       In  MathML  mode, each digit of a numeric literal gets a separate “<mn>
       </mn>” pair, and decimal points are tagged with “<mo></mo>”.   This  is
       allowed by the specification, but inefficient.

[1mExamples[0m
       We first illustrate [4mgeqn[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
       appear 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 illustrates use of fractions  and  radicals,  and
       affords an opportunity to use 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 opera‐
       tor.  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.
       Appendix  G  discusses  many of the parameters from section “Customiza‐
       tion” above in greater detail.

       [4mgroff_char[24m(7), particularly subsections “Logical symbols”,  “Mathemati‐
       cal  symbols”, and “Greek glyphs”, documents a variety of special char‐
       acter escape sequences useful in mathematical typesetting.

       [4mgroff[24m(1), [4mgtroff[24m(1), [4mgpic[24m(1), [4mgroff_font[24m(5)

groff 1.23.0                      2 July 2023                          [4mgeqn[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 [4mgeqn[24m(1) 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 nor‐
       mally precedes it within [4mgroff[24m(1) macros; nor do you need to have  dol‐
       lar‐sign or other delimiters around the equation.

       Arguments  not recognized by [4meqn2graph[24m are passed to the ImageMagick or
       GraphicsMagick program [4mconvert[24m(1).  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  small‐
       est 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
       information; 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 given order to
              determine the directory where temporary files will  be  created.
              If none are set, [4m/tmp[24m is used.

[1mAuthors[0m
       [4meqn2graph[24m  was written by Eric S. Raymond ⟨esr@thyrsus.com⟩, based on a
       recipe for [4mpic2graph[24m(1), by W. Richard Stevens.

[1mSee also[0m
       [4mpic2graph[24m(1), [4mgrap2graph[24m(1), [4mgeqn[24m(1), [4mgroff[24m(1), [4mconvert[24m(1)

groff 1.23.0                      2 July 2023                     [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‐[0m
               [4mcommand[24m] [[1m-D [22m[[1m-B[22m] [[1m-M [4m[22mmark1[24m [4mmark2[24m]] [[1m--[22m] [4mfile1[24m [4mfile2[24m [[4moutput[24m]

       [1mgdiffmk --help[0m

       [1mgdiffmk --version[0m

[1mDescription[0m
       [4mgdiffmk[24m compares two [4mroff[24m(7) documents, [4mfile1[24m and [4mfile2[24m, and creates  a
       [4mroff[24m document consisting of [4mfile2[24m with added margin character ([1m.mc[22m) re‐
       quests indicating output lines that differ from [4mfile1.[24m  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 absent, [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  informa‐
       tion; both exit afterward.

       [1m-a [4m[22madd‐mark[0m
              Use [4madd‐mark[24m for source lines not in [4mfile1[24m but present in [4mfile2[24m.
              Default: “[1m+[22m”.

       [1m-B     [22mBy  default,  the deleted texts marked by the [1m-D [22moption end with
              an added [4mroff[24m break request, [1m.br[22m, to ensure that  the  deletions
              are  marked  properly.   This  is the only way to guarantee that
              deletions and small changes get flagged.   This  option  directs
              the program not to insert these breaks; it makes no sense to use
              it without [1m-D[22m.

       [1m-c [4m[22mchange‐mark[0m
              Use [4mchange‐mark[24m for changed source lines.  Default: “[1m|[22m”.

       [1m-d [4m[22mdelete‐mark[0m
              Use the [4mdelete‐mark[24m for deleted source lines.  Default: “[1m*[22m”.

       [1m-D     [22mShow the deleted portions from changed and deleted text.

       [1m-M [4m[22mmark1[24m [4mmark2[0m
              Change  the  delimiting  marks  for  the [1m-D [22moption.  It makes no
              sense to use this option without [1m-D[22m.  Default delimiting  marks:
              “[1m[[[22m” ... “[1m]][22m”.

       [1m-x [4m[22mdiff‐command[0m
              Use  the [4mdiff‐command[24m command to perform the comparison of [4mfile1[0m
              and [4mfile2[24m.  In particular, [4mdiff‐command[24m should  accept  the  GNU
              [4mdiff[24m(1) [1m-D [22moption.  Default: [1mdiff[22m.

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

[1mBugs[0m
       The  output  is  not necessarily compatible with all macro packages and
       all preprocessors.  A  workaround  that  often  overcomes  preprocessor
       problems  is  to run [4mgdiffmk[24m on the output of all the preprocessors in‐
       stead of the input source.

       [4mgdiffmk[24m relies on the [1m-D [22moption of GNU [4mdiff[24m to make a  merged  “#ifdef”
       output  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 Mike Bianchi ⟨MBianchi@Foveal.com⟩, now retired.
       It is maintained by the [4mgroff[24m developers.

[1mSee also[0m
       [4mgroff[24m(1), [4mnroff[24m(1), [4mgtroff[24m(1), [4mroff[24m(7), [4mdiff[24m(1)

groff 1.23.0                      2 July 2023                       [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 [4m[22mfilename‐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 [4mgroff[24m(7) 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.

[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[0m
       device 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  [4mlilypond[24m(1)  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 useful [4mEPS[24m files are send.  So at last, the temporary direc‐
              tory 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[0m
              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
              temporary directory.  This directory name is used as is  without
              any  extensions.  If this directory does not exist it is be cre‐
              ated.  The temporary directory is created by Perl’s security op‐
              erations directly under this directory.  In this  temporary  di‐
              rectory, the temporary 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
       argument can consist of arbitrary many options without option argument,
       composed 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 argu‐
       ment 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
              argument,  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[0m
              [4msome_dir[24m.

   [1mHandling of long options[0m
       Arguments that start with a double dash [1m-- [22mare so‐called [4mlong[24m [4moptions[24m [4mR[0m
       [4m.[24m  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 [22mis 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
       possible.

       The [4mlong[24m [4moption[24m [1m--keep_all [22mcan be abbreviated from [1m--keep_al [22mup to  [1m--k[0m
       because 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
       abbreviated 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.lily‐[0m
       [1mpond end [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[0m
       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[0m
       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[0m
       [1minclude [22mmay not be used in [4mlilypond[24m [4mmode[24m, i.e. between [1m.lilypond  start[0m
       and  [1m.lilypond  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 tem‐
       porary 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 automati‐
       cally 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 program.

       The  beginning  of  the  names of the temporary files can be set by the
       command‐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
       cannot 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
       This  mode  is  the actual default and can also be chosen by the option
       [1m--pdf2eps[22m.

       In this mode, the [1m.ly [22mfiles are transformed by the [4mlilypond[24m(1)  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 exten‐
       sion [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 [4mpdf2ps[24m(1) 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 [4mps2eps[24m(1) 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[0m
       command
              [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
       extension, its directory is temporary.

       There are many [4mEPS[24m files created.  One having the complete  transformed
       [1mly [22mfile, 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 collec‐
       tion  of  the corresponding [4mEPS[24m page files.  This is done by [4mgroff[24m com‐
       mands
       [1m.PSPIC [4m[22mfile‐name[24m[1m-[4m[22mdigit[24m[1m.eps[0m

[1mGenerated [4mgroff[24m output[0m
       The new [4mgroff[24m(7) structure generated by [4mglilypond[24m is either

       1)     sent to standard output and can there be saved into  a  file  or
              piped into [4mgroff[24m(1) or

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

[1mAuthors[0m
       [4mglilypond[24m was written by Bernd Warken ⟨groff-bernd.warken-72@web.de⟩.

[1mSee also[0m
       [4mgroff[24m(1)
              describes  the  usage of the [4mgroff[24m command and contains pointers
              to further documentation of the [4mgroff[24m system.

       [4mgroff_tmac[24m(5)
              describes the [1m.PSPIC [22mrequest.

       [4mlilypond[24m(1)
              briefly describes the [4mlilypond[24m command and contains pointers  to
              further documentation.

       [4mpdf2ps[24m(1)
              transforms a [4mPDF[24m file into a [4mPostScript[24m format.

       [4mps2eps[24m(1)
              transforms a [4mPS[24m file into an [4mEPS[24m format.

groff 1.23.0                      2 July 2023                     [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 [4mgroff[24m(1).  It allows the use of [4mperl[24m(7) code
       in  [4mgroff[24m(7)  files.   The result of a [4mPerl[24m [4mpart[24m can be stored in groff
       [4mstrings[24m or [4mnumerical[24m [4mregisters[24m based on the arguments at a  final  line
       of a [4mPerl[24m [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  ar‐
       guments  to  be interpreted as [4mfile[24m operands, even if their names start
       with a dash.  [1m-h [22mand [1m--help [22mdisplay a usage  message,  whereas  [1m-v  [22mand
       [1m--version [22mdisplay version information; all exit afterward.

[1mPerl regions[0m
       [4mPerl[24m  parts in [4mgroff[24m [4mfiles[24m are enclosed by two [1m.Perl [22mrequests with dif‐
       ferent 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  re‐
       quest 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
       running [4mPerl[24m [4mpart[24m.  Of course, it would be reasonable to add the  argu‐
       ment [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[0m
       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 sev‐
       eral 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 [22mcommand.  Each argument [1m.ds [22mchanges the mode  into  [4mgroff[24m  [4mstring[0m
       and  [1m.nr  [22mchanges 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
       before the first [1m.nr [22mcommand.  That suits to  [4mgroff[24m(7),  because  every
       output  can be saved as [4mgroff[24m string, but the registers can be very re‐
       strictive.

       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
       argument 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[24m 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  [22mcom‐
              mand.  default.

       [1m.Perl [4m[22mvar_name1[24m [4mvar_name2[0m
              This will store 2 output lines into groff string names [4mvar_name1[0m
              and [4mvar_name2[24m, because the default mode [1m.ds [22mis active, such that
              no [1m.ds [22margument 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 Bernd Warken ⟨groff-bernd.warken-72@web.de⟩.

[1mSee also[0m
       Man pages related to [4mgroff[24m are [4mgroff[24m(1), [4mgroff[24m(7), and [4mgrog[24m(1).

       Documents related to [4mPerl[24m are [4mperl[24m(1), [4mperl[24m(7).

groff 1.23.0                      2 July 2023                         [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 [4mgroff[24m(1) that facilitates use of Hanyu
       Pinyin in [4mgroff[24m(7) files.  Pinyin is a method for writing the  Mandarin
       Chinese  language  with  the Latin alphabet.  Mandarin consists of more
       than four hundred base syllables, each spoken with one of five  differ‐
       ent  tones.  Changing 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[0m
       and [1m--help [22mdisplay 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 character 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
       uppercase.  Within [1m.pinyin [22msections, [4mgpinyin[24m supports the form “ue” for
       lowercase and the forms “Ue” and “UE” for uppercase.

   [1mTones[0m
       Each syllable has exactly one of five [4mtones[24m.  The fifth tone is not ex‐
       plicitly written at all, but each of the first through fourth tones  is
       indicated 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
       transformed  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 Bernd Warken ⟨groff-bernd.warken-72@web.de⟩.

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

       [4mgroff[24m(1) and [4mgrog[24m(1) explain how to view [4mroff[24m documents.

       [4mgroff[24m(7)  and  [4mgroff_char[24m(7)  are comprehensive references covering the
       language elements of GNU [4mtroff[24m and the available glyph repertoire,  re‐
       spectively.

groff 1.23.0                      2 July 2023                       [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 [4mgrap[24m(1) 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 [4mgroff[24m(1) documents.

       Arguments not recognized by [4mgrap2graph[24m are passed to the ImageMagick or
       GraphicsMagick  program  [4mconvert[24m(1).  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 small‐
       est 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
       information; 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
              arbitrary 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 given order to
              determine the directory where temporary files will  be  created.
              If none are set, [4m/tmp[24m is used.

[1mAuthors[0m
       [4mgrap2graph[24m was written by Eric S. Raymond ⟨esr@thyrsus.com⟩, based on a
       recipe for [4mpic2graph[24m(1), by W. Richard Stevens.

[1mSee also[0m
       [4mpic2graph[24m(1), [4meqn2graph[24m(1), [4mgrap[24m(1), [4mgpic[24m(1), [4mgroff[24m(1), [4mconvert[24m(1)

groff 1.23.0                      2 July 2023                    [4mgrap2graph[24m(1)
───────────────────────────────────────────────────────────────────────────────
[4mggrn[24m(1)                     General Commands Manual                    [4mggrn[24m(1)

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

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

       [1mggrn -?[0m
       [1mggrn --help[0m

       [1mggrn -v[0m
       [1mggrn --version[0m

[1mDescription[0m
       [4mggrn[24m  is a preprocessor for including [4mgremlin[24m pictures in [4mgtroff[24m(1) in‐
       put.  [4mggrn[24m writes to standard output, processing only input  lines  be‐
       tween  two  that start with [1m.GS [22mand [1m.GE[22m.  Those lines must contain [4mggrn[0m
       commands (see below).  These macros request a [4mgremlin[24m file; the picture
       in that file is converted and placed in the [4mgtroff[24m input  stream.   [1m.GS[0m
       may  be  called  with a [1mC[22m, [1mL[22m, or [1mR [22margument to center, left‐, or right‐
       justify 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 pic‐
       ture, the position on the page is the bottom of  the  [4mgremlin[24m  picture.
       If  the  [4mggrn[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.

       [4mggrn[24m produces drawing escape sequences that use  [4mgroff[24m’s  color  scheme
       extension ([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 [4mggrn[24m command.  Com‐
       mands consist of one or two strings separated by white space, the first
       string being the command and the second its operand.  Commands  may  be
       upper‐ or lowercase 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
       environment  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
              default 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 [4mgtroff[24m’s font
              [4mf[24m (either a name or number).  The default is R (I, B, and S, re‐
              spectively).

       [1ml [4m[22mf[0m
       [1mstipple [4m[22mf[0m
              Set the stipple font to [4mgtroff[24m’s stipple font [4mf[24m  (name  or  num‐
              ber).   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
              compile  time).  The default is 1.0 (3.0 and 5.0, respectively),
              which corresponds to 0.15pt (0.45pt and  0.75pt,  respectively).
              A  thickness  value  of zero selects the smallest available line
              thickness.  Negative values cause the line thickness to be  pro‐
              portional 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 [4mgtroff[24m’s limitations, of course).  An  operand  of  any‐
              thing but [1moff [22mwill turn text scaling on.

       [1mdefault[0m
              Reset  the  picture  environment defaults to the settings in the
              current picture.  This is meant to be used as a global parameter
              setting mechanism at the beginning of the [4mgtroff[24m input file, 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 scal‐
              ing 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
              factors.   If  both  [1mwidth [22mand [1mheight [22mare specified, the tighter
              constraint will determine the scale of the picture.  [1mheight  [22mand
              [1mwidth  [22mcommands  are  not  saved with a “[1mdefault[22m” command.  They
              will, however, 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 mul‐
              tiple [1mfile [22mcommands are given, the last one controls.   If  [4mname[0m
              doesn’t  exist, an error message is reported and processing con‐
              tinues from the [1m.GE [22mline.

   [1mUsage with [4mgroff[0m
       Since [4mggrn[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 [4mgtroff[24m input can be placed between  the  [1m.GS  [22mand  [1m.GE[0m
       macros.   However,  [4mgremlin[24m text elements are subsequently processed by
       [4mgtroff[24m, so anything valid in a single line of [4mgtroff[24m input is valid  in
       a  line  of  [4mgremlin[24m 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 en‐
       closed by previously defined delimiters (e.g., “$$”).

       When using [4mggrn[24m along with other  preprocessors,  it  is  best  to  run
       [4mgtbl[24m(1)  before  [4mggrn[24m, [4mgpic[24m(1), and/or [4mideal[24m to avoid overworking [4mgtbl[24m.
       [4mgeqn[24m(1) should always be run last.   [4mgroff[24m(1)  will  automatically  run
       preprocessors in the correct order.

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

       [4mggrn[24m uses [4mgtroff[24m’s registers [1mg1 [22mthrough [1mg9 [22mand sets registers [1mg1 [22mand [1mg2[0m
       to  the width and height of the [4mgremlin[24m figure (in device units) before
       entering 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 coordi‐
       nates is [4mnot[24m compatible with the AED version.  As  long  as  a  [4mgremlin[0m
       file  does not contain negative coordinates, either format will be read
       correctly by either version of [4mgremlin[24m or [4mggrn[24m.  The  other  difference
       in  Sun/X11 format is the use of names for picture objects (e.g., [1mPOLY‐[0m
       [1mGON[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 “[1mgrem‐[0m
         [1mlinfile[22m” (AED) or “[1msungremlinfile[22m” (Sun/X11).

       • The  second line of the file contains an orientation and [4mx[24m and [4my[24m val‐
         ues for a positioning point, separated by spaces.   The  orientation,
         either [1m0 [22mor [1m1[22m, is ignored by the Sun/X11 version.  [1m0 [22mmeans that [4mgrem‐[0m
         [4mlin[24m  will  display  things in horizontal format (a drawing area wider
         than it is tall, with a menu across the top).  [1m1 [22mmeans  that  [4mgremlin[0m
         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 positioning point to be used when this file  is  read
         into  another file.  The stuff on this line really isn’t all that im‐
         portant; a value of “[1m1 0.00 0.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 giv‐
         ing 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        [22mbottom‐left‐justified text
                    [1m1       BOTRIGHT       [22mbottom‐right‐justified text
                    [1m2       CENTCENT       [22mcenter‐justified text
                    [1m3       VECTOR         [22mvector
                    [1m4       ARC            [22marc
                    [1m5       CURVE          [22mcurve
                    [1m6       POLYGON        [22mpolygon
                    [1m7       BSPLINE        [22mb‐spline
                    [1m8       BEZIER         [22mBézier
                   [1m10       TOPLEFT        [22mtop‐left‐justified text
                   [1m11       TOPCENT        [22mtop‐center‐justified text
                   [1m12       TOPRIGHT       [22mtop‐right‐justified text
                   [1m13       CENTLEFT       [22mleft‐center‐justified text
                   [1m14       CENTRIGHT      [22mright‐center‐justified text
                   [1m15       BOTCENT        [22mbottom‐center‐justified text

       • After the object type comes a variable number of lines, each specify‐
         ing a point used to display the element.  Each line contains an x‐co‐
         ordinate and a y‐coordinate in floating‐point  format,  separated  by
         spaces.   The  list  of points is terminated by a line containing 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,  one  more value, 0, is valid.  It specifies a polygon
         with an invisible border.  For text, the brush selects a font as fol‐
         lows.

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

         If you’re using [4mggrn[24m to run your pictures through [4mgroff[24m, the font  is
         really  just a starting font.  The text string can contain formatting
         sequences 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  be‐
         tween  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 vicinity.  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 [4mprintf[24m(3) format “%f1.2”; it’s
       probably a good idea to use the same format if you want to  modify  the
       [4mggrn[24m code.

   [1mSun/X11 coordinates[0m
       There  is no restriction on the range of coordinates used to create ob‐
       jects in the Sun/X11 version of [4mgremlin[24m.  However, files with  negative
       coordinates [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 ver‐
       sion information; all exit afterward.

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

       [1m-F [4m[22mdir[24m Search [4mdir[24m for subdirectories [4mdev[24mname ([4mname[24m is the name  of  the
              output  driver) for the [4mDESC[24m file before the default font direc‐
              tories                           [4m/usr/pkg/share/groff/site-font[24m,
              [4m/usr/pkg/share/groff/1.23.0/font[24m, and [4m/usr/lib/font[24m.

       [1m-M [4m[22mdir[24m Prepend  [4mdir[24m  to the search path for [4mgremlin[24m files.  The default
              search path  is  the  current  directory,  the  home  directory,
              [4m/usr/pkg/share/groff/site-tmac[24m,                              and
              [4m/usr/pkg/share/groff/1.23.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 [4mgroff[24m(1) for a list of valid devices.

[1mFiles[0m
       [4m/usr/pkg/share/groff/1.23.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 Werner Lemberg modified it for [4mgroff[24m.

[1mSee also[0m
       [4mgremlin[24m(1), [4mgroff[24m(1), [4mgpic[24m(1), [4mideal[24m(1)

groff 1.23.0                      2 July 2023                          [4mggrn[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 [4mgtroff[24m(1)  into
       TeX  DVI format.  Normally, [4mgrodvi[24m is invoked by [4mgroff[24m(1) when the lat‐
       ter is given the “[1m-T dvi[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  [4mgrodvi[24m.   If no [4mfile[24m arguments are given, or if [4mfile[24m is “-”,
       [4mgrodvi[24m reads the standard input stream.  Output is written to the stan‐
       dard output stream.

       The DVI file generated by [4mgrodvi[24m can interpreted by any correctly writ‐
       ten DVI driver.  [4mtroff[24m drawing primitives are  implemented  using  [4mtpic[0m
       version  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  [22mmacro.   [4mpspic.tmac[24m  is  loaded  automatically by [4mdvi.tmac[24m.  See
       [4mgroff_tmac[24m(5).

       The default color used by the [1m\m [22mand  [1m\M  [22mescape  sequences  is  black.
       Currently,  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  ac‐
       cess 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.   Instead,  [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 accordingly.  If either the page
       width or length is not positive, no [1mpapersize [22mspecial is output.

       A device control escape sequence [1m\X'[4m[22manything[24m[1m' [22mis translated to the same
       DVI file instructions as would be  produced  by  [1m\special{[4m[22manything[24m[1m}  [22min
       TeX; [4manything[24m cannot contain a newline.

   [1mTypefaces[0m
       [4mgrodvi[24m  supports  the  standard  four  styles: [1mR [22m(roman), [1mI [22m([4mitalic[24m), [1mB[0m
       ([1mbold[22m), and [1mBI [22m([4m[1mbold‐italic[24m[22m).  Fonts are grouped into families [1mT [22mand  [1mH[0m
       having members 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(cm‐
       tex10, 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
       available as special fonts [1mSA [22m(msam10) and [1mSB [22m(msbm10).  They  are  are
       not mounted by default.

       The  [4mgtroff[24m  option [1m-mec [22mloads the [4mec.tmac[24m macro file, employing the EC
       and TC fonts instead of CM.  These are designed similarly to  the  Com‐
       puter  Modern  fonts;  further,  they  provide Euro [1m\[Eu] [22mand per mille
       [1m\[%0] [22mglyphs.  [4mec.tmac[24m must  be  loaded  before  any  language‐specific
       macro  files  because  it does not set up the codes necessary for auto‐
       matic hyphenation.

   [1mFont description files[0m
       Use [4mtfmtodit[24m(1) to create [4mgroff[24m font description files  from  TFM  (TeX
       font metrics) files.  The font description file should contain the fol‐
       lowing additional 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 draw‐
              ing  position, and the diagonally opposite corner at the drawing
              position +([4mdh[24m,[4mdv[24m), which becomes the new drawing position after‐
              ward.  This command produces a rule in the DVI file and  so  can
              be  printed  even  with a driver that does not support [4mtpic[24m spe‐
              cials, unlike the other [1m\D [22mcommands.

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

       [1m-d     [22mDo  not  use [4mtpic[24m specials to implement drawing commands.  Hori‐
              zontal and vertical lines are implemented by rules.  Other draw‐
              ing commands are ignored.

       [1m-F [4m[22mdir[24m Prepend directory dir[4m/dev[24mname to the search path  for  font  and
              device  description  files; [4mname[24m is the name of the device, usu‐
              ally [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[0m
              file.   [4mpaper‐format[24m  can  be  any  argument  accepted  by   the
              [1mpapersize [22mdirective; see [4mgroff_font[24m(5).

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

[1mEnvironment[0m
       [4mGROFF_FONT_PATH[0m
              lists directories in which to search for [4mdevdvi[24m, [4mgrodvi[24m’s direc‐
              tory of device and font description files.   See  [4mgtroff[24m(1)  and
              [4mgroff_font[24m(5).

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

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

       [4m/usr/pkg/share/groff/1.23.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/pkg/share/groff/1.23.0/tmac/ec.tmac[0m
              configures the [1mdvi [22moutput device to use the EC and TC font fami‐
              lies 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 resolu‐
       tion 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
       “What are the EC fonts?”   ⟨https://texfaq.org/FAQ-ECfonts⟩;  TeX  FAQ:
       Frequently Asked Question List for TeX

       [4mtfmtodit[24m(1),    [4mgroff[24m(1),   [4mgtroff[24m(1),   [4mgroff_out[24m(5),   [4mgroff_font[24m(5),
       [4mgroff_char[24m(7), [4mgroff_tmac[24m(5)

groff 1.23.0                      2 July 2023                        [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‐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‐[0m
             [4mexpression[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 ...]

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

       A reimplementation and extension of  the  typesetter  from  AT&T  Unix,
       [4mgroff[24m  is  present  on most POSIX systems owing to its long association
       with Unix manuals (including man pages).  It and  its  predecessor  are
       notable for their production of several best‐selling software engineer‐
       ing texts.  [4mgroff[24m is capable of producing typographically sophisticated
       documents while consuming minimal system resources.

       The  [4mgroff[24m  command  orchestrates  the  execution of preprocessors, the
       transformation of input documents into a  device‐independent  page  de‐
       scription 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 [4mgtroff[24m(1) formatter, the two programs share a set of options.  How‐
       ever, [4mgroff[24m has some options that [4mgtroff[24m does  not  share,  and  others
       which  [4mgroff[24m  interprets  differently.  At the same time, not all valid
       [4mgtroff[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  inter‐
       preted differently by [4mgroff[24m.

       [1m-D [4m[22menc[24m Set  fallback  input encoding used by [4mpreconv[24m(1) to [4menc[24m; implies
              [1m-k[22m.

       [1m-e     [22mRun [4mgeqn[24m(1) preprocessor.

       [1m-g     [22mRun [4mggrn[24m(1) preprocessor.

       [1m-G     [22mRun [4mgrap[24m(1) preprocessor; implies [1m-p[22m.

       [1m-I [4m[22mdir[24m Works as [4mgtroff[24m’s option (see below), but also  implies  [1m-g  [22mand
              [1m-s[22m.   It is passed to [4mgsoelim[24m(1) and the output driver, and [4mggrn[0m
              is passed an [1m-M [22moption with [4mdir[24m as its argument.

       [1m-j     [22mRun [4mgchem[24m(1) preprocessor; implies [1m-p[22m.

       [1m-k     [22mRun [4mpreconv[24m(1) preprocessor.  Refer to its man page for its  be‐
              havior 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 [4mpreconv[24m(1) 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 [4mgroff_font[24m(5).  If no such directive is
              present for the output device, output is piped to  [4mlpr[24m(1).   See
              options [1m-L [22mand [1m-X[22m.

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

       [1m-M     [22mWorks  as  [4mgtroff[24m’s  option  (see  below), but is also passed to
              [4mgeqn[24m(1), [4mgrap[24m(1), and [4mggrn[24m(1).

       [1m-N     [22mProhibit newlines between [4meqn[24m delimiters: pass [1m-N [22mto [4mgeqn[24m(1).

       [1m-p     [22mRun [4mgpic[24m(1) 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
              option dash to [4marg[24m before passing it to the postprocessor.

       [1m-R     [22mRun [4mgrefer[24m(1) preprocessor.  No mechanism is provided for  pass‐
              ing arguments to [4mgrefer[24m because most [4mgrefer[24m options have equiva‐
              lent  language  elements  that can be specified within the docu‐
              ment.

       [1m-s     [22mRun [4mgsoelim[24m(1) preprocessor.

       [1m-S     [22mOperate in “safer” mode; see [1m-U [22mbelow for its opposite.  For se‐
              curity reasons, safer mode is enabled by default.

       [1m-t     [22mRun [4mgtbl[24m(1) preprocessor.

       [1m-T [4m[22mdev[24m Direct [4mgtroff[24m to format the input for  the  output  device  [4mdev[24m.
              [4mgroff[24m  then calls an output driver to convert [4mgtroff[24m’s output to
              a form appropriate for [4mdev[24m; see subsection “Output devices”  be‐
              low.

       [1m-U     [22mOperate in unsafe mode: pass the [1m-U [22moption to [4mgpic[24m and [4mgtroff[24m.

       [1m-v[0m
       [1m--version[0m
              Write  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,  but  do not execute it.  If given more than once, [4mgroff[0m
              both writes and runs the pipeline.

       [1m-X     [22mUse [4mgxditview[24m(1) instead of the usual postprocessor to (pre)view
              a document on an X11 display.  Combining this option  with  [1m-Tps[0m
              uses  the  font  metrics  of  the PostScript device, whereas the
              [1m-TX75 [22mand [1m-TX100 [22moptions use the metrics of X11 fonts.

       [1m-Z     [22mDisable postprocessing.  [4mgtroff[24m output will appear on the  stan‐
              dard output stream (unless suppressed with [1m-z[22m); see [4mgroff_out[24m(5)
              for a description of this format.

   [1mTransparent options[0m
       The  following  options  are  passed  as‐is  to  the  formatter program
       [4mgtroff[24m(1) 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[22mcs[0m
       [1m-d [4m[22mname[24m[1m=[4m[22mstring[0m
              Define string.

       [1m-E     [22mInhibit [4mgtroff[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 direc‐
              tory 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[22mname[0m
              Process name[4m.tmac[24m before input files.

       [1m-M [4m[22mdir[24m Search directory [4mdir[24m for macro files.

       [1m-n [4m[22mnum[24m Number the first page [4mnum[24m.

       [1m-o [4m[22mlist[0m
              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-w [4m[22mname[0m
       [1m-W [4m[22mname[0m
              Enable ([1m-w[22m) or inhibit ([1m-W[22m) emission  of  warnings  in  category
              [4mname[24m.

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

[1mUsage[0m
       The  architecture  of the GNU [4mroff[24m system follows that of other device‐
       independent [4mroff[24m implementations, comprising preprocessors, macro pack‐
       ages, output drivers (or “postprocessors”), a suite of  utilities,  and
       the  formatter  [4mgtroff[24m at its heart.  See [4mroff[24m(7) 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 summa‐
       rizes the constituent parts of the GNU  [4mroff[24m  system.   It  complements
       [4mroff[24m(7) with [4mgroff[24m‐specific information.

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

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

       We used a [4msed[24m 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.html[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
       verify one’s understanding of the formatter’s behavior and/or the  syn‐
       tax 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
       In  GNU [4mroff[24m, the page dimensions for the formatter [4mgtroff[24m and for out‐
       put devices are handled separately.  In  the  formatter,  requests  are
       used  to  set the page length ([1m.pl[22m), page offset (or left margin, [1m.po[22m),
       and line length ([1m.ll[22m).  The right margin is not explicitly  configured;
       the combination of page offset and line length provides the information
       necessary  to  derive  it.   The [4mpapersize[24m macro package, automatically
       loaded by [4mgtroff[24m, provides an interface for configuring page dimensions
       by convenient names, like “letter” or  “A4”;  see  [4mgroff_tmac[24m(5).   The
       formatter’s default in this installation is “[1mA4[22m”.

       It  is  up to each macro package to respect the page dimensions config‐
       ured in this way.  Some offer alternative mechanisms.

       For each output device, the size of the output medium can be set in its
       [4mDESC[24m file.  Most output drivers also recognize a command‐line option [1m-p[0m
       to override the default dimensions and an option [1m-l  [22mto  use  landscape
       orientation.   See [4mgroff_font[24m(5) for a description of the [1mpapersize [22mdi‐
       rective, which takes an argument of the same form as  [1m-p[22m.   The  output
       driver’s  man  page, such as [4mgrops[24m(1), may also be helpful.  [4mgroff[24m uses
       the command‐line option [1m-P [22mto pass options to output devices; for exam‐
       ple, use the following for PostScript output on A4 paper  in  landscape
       orientation.

              groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps

   [1mFront end[0m
       The [4mgroff[24m program is a wrapper around the [4mgtroff[24m(1) program.  It allows
       one to specify preprocessors via command‐line options and automatically
       runs the appropriate postprocessor for the selected output device.  Do‐
       ing so, the manual construction of pipelines or management of temporary
       files  required of users of traditional [4mroff[24m(7) systems can be avoided.
       Use the [4mgrog[24m(1) program 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 family of languages we also call [4mroff[24m; see  [4mroff[24m(7)  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 [4mgroff[24m(7).  GNU [4mroff[24m extensions to the AT&T [4mtroff[24m lan‐
       guage, a common subset of [4mroff[24m dialects extant today, are  detailed  in
       [4mgroff_diff[24m(7).

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

              [4mgtbl[24m        lays out tables;
              [4mgeqn[24m        typesets mathematics;
              [4mgpic[24m        draws diagrams;
              [4mgrefer[24m      processes bibliographic references;
              [4mgsoelim[24m     preprocesses “sourced” input files;
              [4mggrn[24m        renders [4mgremlin[24m(1) diagrams;
              [4mgchem[24m       draws chemical structural formulæ using [4mpic[24m;
              [4mgperl[24m       populates [4mgroff[24m registers and strings using [4mperl[24m(1);
              [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 [4mpreconv[24m(1), which converts various
       input 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 to‐
       kens.   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 [4mgtroff[24m.   The  [4mgideal[24m  preprocessor  is  not  yet
       available in [4mgroff[24m.

                ┌──────────────┬─────────────────┬────────────────┐
                │ preprocessor │ starting token  │  ending token  │
                ├──────────────┼─────────────────┼────────────────┤
                │    gchem     │     .cstart     │     .cend      │
                │     geqn     │       .EQ       │      .EN       │
                │     grap     │       .G1       │      .G2       │
                │     ggrn     │       .GS       │      .GE       │
                │    gideal    │       .IS       │      .IE       │
                │              │                 │      .IF       │
                │     gpic     │       .PS       │      .PE       │
                │              │                 │      .PF       │
                │              │                 │      .PY       │
                │    grefer    │       .R1       │      .R2       │
                │     gtbl     │       .TS       │      .TE       │
                ├──────────────┼─────────────────┼────────────────┤
                │  glilypond   │ .lilypond start │ .lilypond stop │
                │    gperl     │   .Perl start   │   .Perl stop   │
                │   gpinyin    │  .pinyin start  │  .pinyin stop  │
                └──────────────┴─────────────────┴────────────────┘

   [1mMacro packages[0m
       Macro  files  are  [4mroff[24m input files designed to produce no output them‐
       selves 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.

       Macro packages can be loaded prior to any [4mroff[24m input documents with the
       [1m-m [22moption.  The GNU [4mroff[24m system implements most well‐known macro  pack‐
       ages  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 econ‐
       omy in early Unix culture, a laconic approach that led to many  of  the
       packages being identified in general usage with the [4mnroff[24m and [4mtroff[24m op‐
       tion  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”
       packages, adopting responsibility for page layout among other fundamen‐
       tal tasks, and defining their own lexicon of macros for document compo‐
       sition; 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 Ver‐
              sion 7 Unix (1979); see [4mgroff_man[24m(7).  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 [4mgroff_mdoc[24m(7).  It can be  specified  on
              the command line as [1m-mdoc[22m.

       [4me[24m      is the Berkeley general‐purpose macro suite, developed as an al‐
              ternative  to AT&T’s [4ms[24m; see [4mgroff_me[24m(7).  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 [4mgroff_mm[24m(7).
              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 [4mmom[24m HTML man‐
              ual   ⟨file:///usr/pkg/share/doc/groff-1.23.0/html/mom/toc.html⟩
              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
              [4mgroff_ms[24m(7).  It can be specified on the command line as [1m-ms[22m.

       Others are supplemental.  For instance, [4mandoc[24m is a wrapper package spe‐
       cific  to  GNU [4mroff[24m that recognizes whether a document uses [4mman[24m or [4mmdoc[0m
       format and loads the corresponding macro package.  It can be  specified
       on  the  command  line  as [1m-mandoc[22m.  A [4mman[24m(1) librarian program 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 de‐
       scribed, along with details of macro  file  naming  and  placement,  in
       [4mgroff_tmac[24m(5).

   [1mFormatters[0m
       The  formatter,  the  program  that  interprets [4mroff[24m language input, is
       [4mgtroff[24m(1).  It provides the features of the AT&T [4mtroff[24m and  [4mnroff[24m  pro‐
       grams  as well as many extensions.  The command‐line option [1m-C [22mswitches
       [4mgtroff[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 system.

       A shell script, [4mgnroff[24m(1), emulates the behavior of AT&T [4mnroff[24m.  It at‐
       tempts 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 subsection.

       GNU  [4mtroff[24m generates output in a device‐independent, but not device‐ag‐
       nostic, page description language detailed in [4mgroff_out[24m(5).

   [1mOutput devices[0m
       [4mgtroff[24m output is formatted for a particular  [4moutput[24m  [4mdevice[24m,  typically
       specified by the [1m-T [22moption to the formatter or a front end.  If neither
       this  option nor the [4mGROFF_TYPESETTER[24m environment variable is used, the
       default output device is [1mps[22m.  An output device may be any of  the  fol‐
       lowing.

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

       [1mcp1047   [22mfor  terminals  using the IBM code page 1047 character set and
                encoding.

       [1mdvi      [22mfor TeX DVI format.

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

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

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

       [1mlj4      [22mfor  HP LaserJet4‐compatible (or other PCL5‐compatible) print‐
                ers.

       [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  pre‐
       pare a document for viewing or printing.  Postprocessors for other pur‐
       poses,  such as page resequencing or statistical measurement of a docu‐
       ment, are conceivable.

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

       [4mgrodvi[24m(1)
              provides [1mdvi[22m.

       [4mgrohtml[24m(1)
              provides [1mhtml [22mand [1mxhtml[22m.

       [4mgrolbp[24m(1)
              provides [1mlbp[22m.

       [4mgrolj4[24m(1)
              provides [1mlj4[22m.

       [4mgropdf[24m(1)
              provides [1mpdf[22m.

       [4mgrops[24m(1)
              provides [1mps[22m.

       [4mgrotty[24m(1)
              provides [1mascii[22m, [1mcp1047[22m, [1mlatin1[22m, and [1mutf8[22m.

       [4mgxditview[24m(1)
              provides  [1mX75[22m,  [1mX75-12[22m,  [1mX100[22m, and [1mX100-12[22m, and additionally can
              preview [1mps[22m.

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

       [4mgdiffmk[24m(1)
              marks differences between a pair of [4mroff[24m input files.

       [4mgrog[24m(1)
              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.

       [4maddftinfo[24m(1)
              adds information to AT&T [4mtroff[24m font description files to  enable
              their use with GNU [4mtroff[24m.

       [4mafmtodit[24m(1)
              creates font description files for PostScript Type 1 fonts.

       [4mpfbtops[24m(1)
              translates a PostScript Type 1 font in PFB (Printer Font Binary)
              format  to  PFA  (Printer  Font ASCII), which can then be inter‐
              preted by [4mafmtodit[24m.

       [4mhpftodit[24m(1)
              creates font description files for the HP LaserJet 4  family  of
              printers.

       [4mtfmtodit[24m(1)
              creates font description files for the TeX DVI device.

       [4mxtotroff[24m(1)
              creates font description files for X Window System core fonts.

       A  trio of tools transform material constructed using [4mroff[24m preprocessor
       languages into graphical image files.

       [4meqn2graph[24m(1)
              converts an [4meqn[24m equation into a cropped image.

       [4mgrap2graph[24m(1)
              converts a [4mgrap[24m diagram into a cropped image.

       [4mpic2graph[24m(1)
              converts a [4mpic[24m diagram into a cropped image.

       Another set of programs works with the bibliographic data files used by
       the [4mrefer[24m(1) preprocessor.

       [4mgindxbib[24m(1)
              makes inverted indices  for  bibliographic  databases,  speeding
              lookup operations on them.

       [4mlkbib[24m(1)
              searches the databases.

       [4mglookbib[24m(1)
              interactively searches the databases.

[1mExit status[0m
       [4mgroff[24m  exits  with  a failure status if there was a problem parsing its
       arguments and a successful status if either of the options [1m-h [22mor [1m--help[0m
       was specified.  Otherwise, [4mgroff[24m runs a pipeline to process its  input;
       if all commands within the pipeline exit successfully, [4mgroff[24m does like‐
       wise.   If  not,  [4mgroff[24m’s exit status encodes a summary of problems en‐
       countered, setting bit 0 if a command exited  with  a  failure  status,
       bit 1 if a command was terminated with a signal, and bit 2 if a command
       could  not  be  executed.  (Thus, if all three misfortunes befell one’s
       pipeline, [4mgroff[24m would exit with status 2^0 + 2^1 + 2^2 =  1+2+4  =  7.)
       To  troubleshoot  pipeline  problems,  you may wish to re‐run the [4mgroff[0m
       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
       Normally, the path separator in environment variables ending with  [4mPATH[0m
       is the colon; this may vary depending on the operating system.  For ex‐
       ample, Windows uses a semicolon instead.

       [4mGROFF_BIN_PATH[0m
              This  search  path, followed by [4mPATH[24m, is used to locate commands
              executed by [4mgroff[24m.  If it is not set, the installation directory
              of the GNU [4mroff[24m executables, [4m/usr/pkg/bin[24m,  is  searched  before
              [4mPATH[24m.

       [4mGROFF_COMMAND_PREFIX[0m
              GNU  [4mroff[24m can be configured at compile time to apply a prefix to
              the names of the programs it provides that had a counterpart  in
              AT&T  [4mtroff[24m,  so  that  name collisions are avoided at run time.
              The default prefix is empty.

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

       [4mGROFF_ENCODING[0m
              The value of this variable is  passed  to  the  [4mpreconv[24m(1)  pre‐
              processor’s  [1m-e [22moption to select the character encoding of input
              files.  This variable’s existence implies the [4mgroff[24m  option  [1m-k[22m.
              If  set  but  empty,  [4mgroff[24m  calls [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
              description  files  in  this list of directories.  See [4mgtroff[24m(1)
              and [4mgroff_font[24m(5).

       [4mGROFF_TMAC_PATH[0m
              Seek macro files in this list of directories.  See [4mgtroff[24m(1) and
              [4mgroff_tmac[24m(5).

       [4mGROFF_TMPDIR[0m
              Create temporary files in this directory.  If not set,  but  the
              environment  variable [4mTMPDIR[24m is set, temporary files are created
              there 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  created  in
              [4m/tmp[24m.  The [4mgrefer[24m(1), [4mgrohtml[24m(1), and [4mgrops[24m(1) commands use tem‐
              porary 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
              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 [4mlocaltime[24m(3)
              when the formatter starts up and stored in registers  usable  by
              documents and macro packages.

       [4mTZ[24m     The  time zone to use when converting the current time (or value
              of [4mSOURCE_DATE_EPOCH[24m) to human‐readable form; see [4mtzset[24m(3).

[1mExamples[0m
       [4mroff[24m systems are best known for formatting man pages.   Once  a  [4mman[24m(1)
       librarian  program  has located a man page, it may execute a [4mgroff[24m com‐
       mand much like the following.
              groff -t -man -Tutf8 /usr/share/man/man1/groff.1
       The librarian will also pipe the output through a  pager,  which  might
       not  interpret  the SGR terminal escape sequences [4mgroff[24m emits for bold‐
       face, underlining, or italics; see section “Limitations” below.

       To process a [4mroff[24m input file using the preprocessors [4mgtbl[24m and [4mgpic[24m  and
       the  [4mme[24m  macro package in the way to which AT&T [4mtroff[24m users were accus‐
       tomed, one would type (or script) a pipeline.

              gpic foo.me | gtbl | gtroff -me -Tutf8 | grotty

       Using [4mgroff[24m, this pipe can be shortened to an equivalent command.

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

       An even easier way to do this is to use [4mgrog[24m(1) to guess the preproces‐
       sor and macro options and execute the result by using the command  sub‐
       stitution feature of the shell.

              $(grog -Tutf8 foo.me)

       Each  command‐line option to a postprocessor must be specified with any
       required leading dashes “[1m-[22m” because [4mgroff[24m passes the arguments as‐is to
       the postprocessor; this permits arbitrary arguments to be  transmitted.
       For  example, 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, [1mcp1047[22m,  [1mlatin1[22m,  and  [1mutf8  [22mdevices,
       programs  like  [4mmore[24m(1) and [4mless[24m(1) may require command‐line options to
       correctly handle some terminal escape sequences; see [4mgrotty[24m(1).

       On EBCDIC hosts such as OS/390  Unix,  the  output  devices  [1mascii  [22mand
       [1mlatin1  [22maren’t  available.  Conversely, the output device [1mcp1047 [22mis not
       available on systems based on the ISO 646 or ISO 8859 character  encod‐
       ing standards.

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

       [4m/usr/pkg/lib/X11/app-defaults[0m
              Application defaults directory for [4mgxditview[24m(1).

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

       [4m/usr/pkg/share/groff/1.23.0/eign[0m
              List of common words for [4mindxbib[24m(1).

       [4m/usr/pkg/share/groff/1.23.0[0m
              Directory for data files.

       [4m/usr/share/dict/papers/Ind[0m
              Default index for [4mlkbib[24m(1) and [4mrefer[24m(1).

       [4m/usr/pkg/share/doc/groff-1.23.0[0m
              Documentation directory.

       [4m/usr/pkg/share/doc/groff-1.23.0/examples[0m
              Example directory.

       [4m/usr/pkg/share/groff/1.23.0/font[0m
              Font directory.

       [4m/usr/pkg/share/doc/groff-1.23.0/html[0m
              HTML documentation directory.

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

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

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

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

       [4m/usr/pkg/share/groff/1.23.0/oldfont[0m
              Font directory for compatibility with old versions of [4mgroff[24m; see
              [4mgrops[24m(1).

       [4m/usr/pkg/share/doc/groff-1.23.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/pkg/share/groff/1.23.0/tmac[24m for the installation corresponding  to
       this  document.  As a rule, multiple directories are searched for macro
       files; see [4mgtroff[24m(1).  For a catalog of macro files GNU [4mroff[24m  provides,
       see [4mgroff_tmac[24m(5).

   [4m[1mgroff[24m device and font description directory[0m
       Device  and font description files supplied with GNU [4mroff[24m are stored in
       [4m/usr/pkg/share/groff/1.23.0/font[24m for the installation corresponding  to
       this document.  As a rule, multiple directories are searched for device
       and  font  description  files; see [4mgtroff[24m(1).  For the formats of these
       files, see [4mgroff_font[24m(5).

[1mAvailability[0m
       Obtain links to [4mgroff[24m releases for  download,  its  source  repository,
       discussion  mailing lists, a support ticket tracker, and further infor‐
       mation from the [4mgroff[24m page  of  the  GNU  website  ⟨http://www.gnu.org/
       software/groff⟩.

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

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

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

       Introduction, history, and further reading:
              [4mroff[24m(7)

       Viewer for [4mgroff[24m (and AT&T device‐independent [4mtroff[24m) documents:
              [4mgxditview[24m(1)

       Preprocessors:
              [4mgchem[24m(1), [4mgeqn[24m(1), [4mgneqn[24m(1), [4mglilypond[24m(1), [4mggrn[24m(1),  [4mpreconv[24m(1),
              [4mgperl[24m(1), [4mgpic[24m(1), [4mgpinyin[24m(1), [4mgrefer[24m(1), [4mgsoelim[24m(1), [4mgtbl[24m(1)

       Macro packages and package‐specific utilities:
              [4mgroff_hdtbl[24m(7), [4mgroff_man[24m(7), [4mgroff_man_style[24m(7), [4mgroff_mdoc[24m(7),
              [4mgroff_me[24m(7),      [4mgroff_mm[24m(7),     [4mgroff_mmse[24m(7),     [4mmmroff[24m(1),
              [4mgroff_mom[24m(7),    [4mpdfmom[24m(1),    [4mgroff_ms[24m(7),    [4mgroff_rfc1345[24m(7),
              [4mgroff_trace[24m(7), [4mgroff_www[24m(7)

       Bibliographic database management tools:
              [4mgindxbib[24m(1), [4mlkbib[24m(1), [4mglookbib[24m(1)

       Language, conventions, and GNU extensions:
              [4mgroff[24m(7),     [4mgroff_char[24m(7),    [4mgroff_diff[24m(7),    [4mgroff_font[24m(5),
              [4mgroff_tmac[24m(5)

       Intermediate output language:
              [4mgroff_out[24m(5)

       Formatter program:
              [4mgtroff[24m(1)

       Formatter wrappers:
              [4mgnroff[24m(1), [4mpdfroff[24m(1)

       Postprocessors for output devices:
              [4mgrodvi[24m(1),   [4mgrohtml[24m(1),   [4mgrolbp[24m(1),   [4mgrolj4[24m(1),    [4mgropdf[24m(1),
              [4mgrops[24m(1), [4mgrotty[24m(1)

       Font support utilities:
              [4maddftinfo[24m(1), [4mafmtodit[24m(1), [4mhpftodit[24m(1), [4mpfbtops[24m(1), [4mtfmtodit[24m(1),
              [4mxtotroff[24m(1)

       Graphics conversion utilities:
              [4meqn2graph[24m(1), [4mgrap2graph[24m(1), [4mpic2graph[24m(1)

       Difference‐marking utility:
              [4mgdiffmk[24m(1)

       “groff guess” utility:
              [4mgrog[24m(1)

groff 1.23.0                      2 July 2023                         [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[[1m--run[22m] [[1m--ligatures[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 [4mgroff[24m(1) options are needed to
       render it.  If no operands are given, or if [4mfile[24m is “[1m-[22m”, [4mgrog[24m reads the
       standard input stream.  The corresponding  [4mgroff[24m  command  is  normally
       written  to the standard output stream.  With the option [1m--run[22m, the in‐
       ferred command is written to the standard error stream  and  then  exe‐
       cuted.

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

       [1m--ligatures[0m
              includes  the  arguments [1m-P-y -PU [22min the inferred [4mgroff[24m command.
              These are supported only by the [1mpdf [22moutput device.

       [1m--run  [22mwrites the inferred command to the  standard  error  stream  and
              then executes it.

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

[1mDetails[0m
       [4mgrog[24m reads each [4mfile[24m operand, pattern‐matching strings that are statis‐
       tically likely to be characteristic of [4mroff[24m(7) 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  in‐
       ferred [4mgroff[24m 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[0m
       to  select a non‐default output device.  If the input is not encoded in
       US‐ASCII, ISO 8859‐1, or IBM code page 1047, specification of  a  [4mgroff[0m
       option  to  run the [4mpreconv[24m(1) preprocessor is advised; see the [1m-D[22m, [1m-k[22m,
       and [1m-K [22moptions of [4mgroff[24m(1).  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[0m
       will infer a [4mgroff[24m 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 con‐
       tinuation 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
       will  conceal  the use of the [4mms[24m macros [1mNH [22mand [1mSH [22mfrom [4mgrog[24m.  Such con‐
       structions 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 example, requires [1mPS[22m, [1mPE[22m, and [1mPF [22mcalls to imme‐
       diately follow the default control character  at  the  beginning  of  a
       line.

       Detection  of the [1m-s [22moption (the [4mgsoelim[24m(1) preprocessor) is tricky; to
       correctly infer its necessity would require [4mgrog[24m  to  recursively  open
       all  files  given as arguments to the [1m.so [22mrequest under the same condi‐
       tions that [4mgsoelim[24m itself does so;  see  its  man  page.   Recall  that
       [4mgsoelim[24m  is  necessary  only  if sourced files need to be preprocessed.
       Therefore, as a workaround, you may  want  to  run  the  input  through
       [4mgsoelim[24m  manually, piping it to [4mgrog[24m, and compare the output to running
       [4mgrog[24m on the input directly.  If the “[4mgsoelim[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
              $ [1mgsoelim 1.roff | grog[0m
              groff -t -ms -

       In  the  foregoing  example, we see that this procedure enabled [4mgrog[24m to
       detect [4mgtbl[24m(1) macros, so we would add [1m-s [22mas well as  the  detected  [1m-t[0m
       option 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 error status [1m1 [22mif a macro package appears to be in use
       by the input 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.  (If the [1m--run [22moption is specified, [4mgroff[24m’s exit  status
       is  discarded.)  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/pkg/share/doc/groff-1.23.0/meintro.me[0m
       at the command line results in
              groff -me /usr/pkg/share/doc/groff-1.23.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/pkg/share/doc/groff-1.23.0/pic.ms[0m
       outputs
              groff -e -p -t -ms /usr/pkg/share/doc/groff-1.23.0/pic.ms
       on  the other hand.  Besides discerning the [4mms[24m macro package, [4mgrog[24m rec‐
       ognizes that the file [4mpic.ms[24m additionally needs the combination  of  [1m-t[0m
       for [4mtbl[24m, [1m-e [22mfor [4meqn[24m, and [1m-p [22mfor [4mpic[24m.

       Consider  a  file [4mdoc/grnexampl.me[24m, which uses the [4mggrn[24m preprocessor to
       include a [4mgremlin[24m(1) 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 errors that [4mgtroff[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/pkg/share/doc/groff-1.23.0[24m if you’d like to try this example your‐
       self.)

[1mAuthors[0m
       [4mgrog[24m was originally written in Bourne shell by James Clark.   The  cur‐
       rent  implementation  in  Perl was written by Bernd Warken ⟨groff-bernd
       .warken-72@web.de⟩  and  heavily  revised  by   G.   Branden   Robinson
       ⟨g.branden.robinson@gmail.com⟩.

[1mSee also[0m
       [4mgroff[24m(1)

groff 1.23.0                      2 July 2023                          [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[0m
                   [4mresolution[24m] [[1m-I [4m[22mimage‐stem[24m] [[1m-o [4m[22mimage‐vertical‐offset[24m] [[1m-x[0m
                   [4mhtml‐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-s[0m
                    [4mbase‐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  trans‐
       late  [4mroff[24m(7)  documents to HTML.  Because a preprocessor is (uniquely)
       required for this output driver, users should invoke  [4mgrohtml[24m  via  the
       [4mgroff[24m(1)  command with the [1m-Thtml [22mor [1m-Txhtml [22moptions.  (In this instal‐
       lation, [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  input  stream.   Output  is
       written 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  Post‐
       Script format using the [1mps [22moutput device.  In the second pass, the out‐
       put driver [4mpost-grohtml[24m translates the output of [4mgtroff[24m(1) to HTML.

       [4mgrohtml[24m  writes  output encoded in UTF‐8 and has built‐in HTML entities
       for all non‐composite Unicode characters.  In spite of this, [4mgroff[24m  may
       issue  warnings about unknown special characters if they can’t be found
       during the first pass.  Such warnings can be safely ignored 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[0m
       ([1mbold[22m), and [1mBI [22m([4m[1mbold‐italic[24m[22m).  Fonts are grouped into families [1mT [22mand  [1mC[0m
       having members 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
       expect it to always be available.

   [1mFont description files[0m
       The font description files used with  [4mgrohtml[24m  expose  the  same  glyph
       repertoire in their [1mcharset [22msections.  See [4mgroff_font[24m(5).

   [1mDependencies[0m
       [4mpre-grohtml[24m  generates  an image whenever an [4mgeqn[24m equation, [4mgtbl[24m table,
       or [4mgpic[24m picture is encountered in the input.  [4mgrohtml[24m therefore may run
       several commands as part of its operation.  These  include  the  Netpbm
       tools  [4mpnmcrop[24m, [4mpnmcut[24m, and [4mpnmtopng[24m; Ghostscript ([4mgs[24m); and the PSUtils
       tool [4mpsselect[24m.

[1mOptions[0m
       [1m--help [22mdisplays a usage message, while [1m-v [22mand  [1m--version  [22mshow  version
       information; 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[0m
              are  also  valid.   Your system’s version of [4mgs[24m must support the
              [1m-dTextAlphaBits [22moption in  order  to  exploit  antialiasing.   A
              value  of  [1m0 [22mstops [4mgrohtml[24m 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‐[0m
              [4mdirectory[24m.

       [1m-e     [22mDirect [4mgeqn[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[0m
              option.

       [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 de‐
              vice, usually [1mhtml[22m.

       [1m-g [4m[22manti‐aliasing‐graphic‐bits[0m
              Number of bits of antialiasing information to be used by  graph‐
              ics  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 increas‐
              ing 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 ap‐
              pended to the stem to separate it from the following image  num‐
              ber.

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

       [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  head‐
              ing  is  found.  Without the option the anchor value is the tex‐
              tual heading.  This can cause problems when a heading contains a
              “?” on older versions of some browsers.  This feature  is  auto‐
              matically 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 increase 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
              default 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[0m
              should generate 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[0m
              option.

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

[1mEnvironment[0m
       [4mGROFF_FONT_PATH[0m
              lists directories in which to search for [4mdevhtml[24m, [4mgrohtml[24m’s  di‐
              rectory of device and font description files.  See [4mgtroff[24m(1) and
              [4mgroff_font[24m(5).

       [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 [4mctime[24m(3) and
              recorded in an HTML comment.

       [4mTZ[24m     The time zone to use when converting the current time (or  value
              of [4mSOURCE_DATE_EPOCH[24m) to human‐readable form; see [4mtzset[24m(3).

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

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

       [4m/usr/pkg/share/groff/1.23.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 se‐
              lected.

       [4m/usr/pkg/share/groff/1.23.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
              devices is selected.

       [4mgrohtml[24m uses temporary files.  See [4mgroff[24m(1)  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
       hyphenating long input lines, which can appear in HTML  output  with  a
       hyphenated word followed by a space but no line break.

[1mSee also[0m
       [4mgroff[24m(1), [4mgtroff[24m(1), [4mgroff_font[24m(5)

groff 1.23.0                      2 July 2023                       [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‐format[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‐format[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 [4mgtroff[24m(1) into a
       CaPSL and VDM format suitable for Canon LBP‐4 and LBP‐8 printers.  Nor‐
       mally, [4mgrolbp[24m is invoked by [4mgroff[24m(1)  when  the  latter  is  given  the
       “[1m-T  lbp[22m”  option.  (In this installation, [1mps [22mis the default output de‐
       vice.)  Use [4mgroff[24m’s [1m-P [22moption  to  pass  any  options  shown  above  to
       [4mgrolbp[24m.   If  no  [4mfile[24m  arguments  are given, or if [4mfile[24m is “-”, [4mgrolbp[0m
       reads the standard input stream.  Output is  written  to  the  standard
       output stream.

   [1mTypefaces[0m
       The  driver  supports the Dutch, Swiss, and Swiss‐Narrow scalable type‐
       faces, each in the regular, bold, italic, and bold‐italic styles.   Ad‐
       ditionally,  the  bitmapped, monospaced Courier and Elite typefaces are
       available in regular, 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 access 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 over‐
       rides 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[0m
       directive accepting one mandatory argument, [1mportrait [22mor [1mlandscape[22m.  The
       first  valid  orientation  directive encountered controls.  The [1m-l[22m, [1m-o[22m,
       and [1m--orientation [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
       [4mgroff_font[24m(5), [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 en‐
       coded as follows.

       For bitmapped fonts, [4mprinter‐font_name[24m has the form
              N⟨[4mbase‐font‐name[24m⟩⟨[4mfont‐style[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
       roman, 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
              lbpname NeliteI
       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 list‐
       ing as “Swiss-BoldOblique”,
              lbpname Swiss-BoldOblique
       is the required directive, and this is what we find in the  [4mgroff[24m  font
       description file [4mHBI[24m for the [1mlbp [22mdevice.

   [1mDrawing commands[0m
       For  compatibility  with  [4mgrolj4[24m(1),  an  additional drawing command is
       available.

       [1m\D'R [4m[22mdh[24m [4mdv[24m[1m'[0m
              Draw a rule (solid black rectangle) with one corner at the draw‐
              ing 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 ver‐
       sion 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  de‐
              vice, usually [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  pa‐
              per 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).

[1mEnvironment[0m
       [4mGROFF_FONT_PATH[0m
              lists directories in which to seek the selected output  device’s
              directory  of  device and font description files.  See [4mgtroff[24m(1)
              and [4mgroff_font[24m(5).

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

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

       [4m/usr/pkg/share/groff/1.23.0/tmac/lbp.tmac[0m
              defines macros for use with the [1mlbp [22moutput device.  It is  auto‐
              matically  loaded  by  [4mtroffrc[24m when the [1mlbp [22moutput device is se‐
              lected.

[1mSee also[0m
       [4mgroff[24m(1), [4mgtroff[24m(1), [4mgroff_out[24m(5), [4mgroff_font[24m(5), [4mgroff_char[24m(7)

groff 1.23.0                      2 July 2023                        [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‐[0m
              [4mformat[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 [4mgtroff[24m(1)  into  a
       PCL5 format suitable for an HP LaserJet 4 printer.  Normally, [4mgrolj4[24m is
       invoked  by [4mgroff[24m(1) 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[0m
       option 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.
       Output is written to the standard output stream.

   [1mTypefaces[0m
       [4mgrolj4[24m supports the standard four styles:  [1mR  [22m(roman),  [1mI  [22m([4mitalic[24m),  [1mB[0m
       ([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.

              [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 [22m(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 de‐
       scription 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 [4mgroff_font[24m(5).

       [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 de‐
              fault is 0.

       [1mpclproportional [4m[22mn[0m
              Set the proportional spacing Boolean flag to [4mn[24m, which can be ei‐
              ther 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
       documented in [4mgroff[24m(7).

       [1m\D'R [4m[22mdh[24m [4mdv[24m[1m'[0m
              Draw a rule (solid black rectangle) with one corner at the draw‐
              ing position, and the diagonally opposite corner at the  drawing
              position  +([4mdh[24m,[4mdv[24m), at which the drawing position will be after‐
              ward.  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, all Hewlett‐Packard LaserJet  4‐series  and  newer  printers
       have  the  same  internal  fonts:  45  scalable fonts and one bitmapped
       Lineprinter font.  The scalable fonts are available  in  sizes  between
       0.25   points   and   999.75  points,  in  0.25‐point  increments;  the
       Lineprinter font is available only in 8.5‐point size.

       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 scal‐
       able fonts; the remaining 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 dif‐
       fers  slightly  between  Intellifont and TrueType fonts (generally, the
       TrueType fonts include more glyphs), and there are some  minor  differ‐
       ences in glyph metrics.  Differences among printer models are described
       in  the  [4mPCL[24m [4m5[24m [4mComparison[24m [4mGuide[24m and the [4mPCL[24m [4m5[24m [4mComparison[24m [4mGuide[24m [4mAddendum[0m
       (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,  [4mhpftodit[24m(1)
       searches a list of symbol sets, and selects the first set that contains
       the  glyph.  The printing 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 [4mgroff_font[24m(5) for a complete descrip‐
       tion of the font file format; symbol sets are described in greater  de‐
       tail in the [4mPCL[24m [4m5[24m [4mPrinter[24m [4mLanguage[24m [4mTechnical[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[0m
       is 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 specified.

       Font metrics for Intellifont fonts were provided by Tagged Font  Metric
       (TFM)  files  originally developed by Agfa/Compugraphic.  The TFM files
       provided 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 Laser‐
       Jet 4000 printer was introduced, most developers had migrated to  other
       means of obtaining font metrics, and support for new TFM files was very
       limited.   The  TFM files provided for the TrueType fonts in the Laser‐
       Jet 4000 support only the Latin 2 (ISO 8859‐2) symbol set, and  include
       no  kerning information; consequently, they are of little value for any
       but the most rudimentary documents.

       Because the Intellifont TFM files contain  considerably  more  informa‐
       tion,  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  Intellifont fonts of the same names.  Although most output us‐
       ing the Intellifont metrics with the newer printers  is  quite  accept‐
       able,  a  few glyphs may fail to print as expected.  The differences in
       glyph metrics may be particularly noticeable with  composite  parenthe‐
       ses,  brackets,  and  braces  used  by  [4meqn[24m(1).   A  script, located in
       [4m/usr/pkg/share/groff/1.23.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 Uni‐
       code standard was available.  Consequently,  many  glyphs  lacking  as‐
       signed  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.  Con‐
       sequently, two different mapping 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
       information; 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  de‐
              vice, 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 pa‐
              per 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).

[1mEnvironment[0m
       [4mGROFF_FONT_PATH[0m
              lists  directories in which to seek the selected output device’s
              directory of device and font description files.   See  [4mgtroff[24m(1)
              and [4mgroff_font[24m(5).

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

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

       [4m/usr/pkg/share/groff/1.23.0/tmac/lj4.tmac[0m
              defines  macros for use with the [1mlj4 [22moutput device.  It is auto‐
              matically loaded by [4mtroffrc[24m when the [1mlj4 [22moutput  device  is  se‐
              lected.

[1mBugs[0m
       Small dots.

[1mSee also[0m
       [4mHP[24m  [4mPCL/PJL[24m  [4mReference:[24m [4mPCL[24m [4m5[24m [4mPrinter[24m [4mLanguage[24m [4mTechnical[24m [4mReference[24m [4mMan‐[0m
       [4mual,[24m [4mPart[24m [4mI[24m ⟨http://www.hp.com/ctg/Manual/bpl13210.pdf⟩

       [4mhpftodit[24m(1),   [4mgroff[24m(1),   [4mgtroff[24m(1),   [4mgroff_out[24m(5),    [4mgroff_font[24m(5),
       [4mgroff_char[24m(7)

groff 1.23.0                      2 July 2023                        [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-dels[22m] [[1m-F [4m[22mfont‐directory[24m] [[1m-I [4m[22minclusion‐directory[24m] [[1m-p [4m[22mpaper‐[0m
              [4mformat[24m] [[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 [4mgtroff[24m(1) into
       Portable Document Format.  Normally, [4mgropdf[24m is invoked by [4mgroff[24m(1) when
       the latter is given the “[1m-T pdf[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 [4mgropdf[24m.  If no [4mfile[24m arguments are given, or if  [4mfile[24m  is
       “-”,  [4mgropdf[24m reads the standard input stream.  Output is written 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
       information; 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-F [4m[22mdir[24m Prepend directory [4mdir[24m/dev[4mname[24m to the search path for  font,  and
              device  description  files; [4mname[24m is the name of the device, usu‐
              ally [1mpdf[22m.

       [1m-I [4m[22mdir[24m Search the directory [4mdir[24m for files named in [1m\X'pdf: pdfpic'  [22mde‐
              vice control commands.  [1m-I [22mmay be specified more than once; each
              [4mdir[24m is searched in the given order.  To search the current work‐
              ing directory before others, add “[1m-I .[22m” at the desired place; it
              is otherwise 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 over‐
              rides the [1mpapersize[22m, [1mpaperlength[22m, and [1mpaperwidth  [22mdirectives  in
              the  [4mDESC[24m  file;  it accepts the same arguments as the [1mpapersize[0m
              directive.  See [4mgroff_font[24m(5) for details.

       [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
              using  [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-y [4m[22mfoundry[0m
              Set the foundry to use for selecting fonts of the same name.

[1mUsage[0m
       The input to [4mgropdf[24m must be in the format output by [4mgtroff[24m(1).  This is
       described in [4mgroff_out[24m(5).  In addition, the device and  font  descrip‐
       tion files for the device used must meet certain requirements: The res‐
       olution must be an integer multiple of 72 times the [1msizescale[22m.  The [1mpdf[0m
       device uses a resolution of 72000 and a sizescale of 1000.

       The  device  description  file  must  contain a valid paper format; see
       [4mgroff_font[24m(5).  [4mgropdf[24m uses the same Type 1 Adobe PostScript  fonts  as
       the  [1mgrops  [22mdevice driver.  Although the PDF Standard allows the use of
       other font types (like TrueType) this implementation only  accepts  the
       Type  1  PostScript font.  Fewer Type 1 fonts are supported natively in
       PDF documents than the standard 35 fonts supported  by  [1mgrops  [22mand  all
       PostScript  printers,  but  all the fonts are available since any which
       aren’t supported natively are automatically embedded in the PDF.

       [4mgropdf[24m supports the concept of foundries, that is different versions of
       basically the same font.  During install a [4mFoundry[24m file controls  where
       fonts  are  found and builds [4mgroff[24m fonts from the files it discovers on
       your system.

       Each font description file must contain a command

              [1minternalname [4m[22mpsname[0m

       which says that the PostScript name  of  the  font  is  [4mpsname[24m.   Lines
       starting with [1m# [22mand blank lines are ignored.  The code for each charac‐
       ter  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  [22mescape  se‐
       quence in [1mtroff [22mto select the character, even if the character does not
       have  a [4mgroff[24m name.  Every character in the font file must exist in the
       PostScript font, and the widths given in the font file must  match  the
       widths used in the PostScript font.

       Note that [4mgropdf[24m is currently only able to display the first 256 glyphs
       in any font.  This restriction will be lifted in a later version.

       [4mgropdf[24m  can  automatically  include the downloadable fonts necessary to
       print the document.  Fonts may be in PFA or PFB format.

       Any downloadable fonts which should,  when  required,  be  included  by
       [4mgropdf[24m  must  be  listed  in the file [4m/usr/pkg/share/groff/1.23.0/font/[0m
       [4mdevpdf/download[24m; this should consist of lines of the form

              [4mfoundry[24m [4mfont[24m [4mfilename[0m

       where [4mfoundry[24m is the foundry name or blank  for  the  default  foundry.
       [4mfont[24m  is  the  PostScript name of the font, and [4mfilename[24m is the name of
       the file containing the font; lines beginning with [1m#  [22mand  blank  lines
       are ignored; fields must be separated by tabs (spaces are [1mnot [22mallowed);
       [4mfilename[24m  is  searched  for  using  the same mechanism that is used for
       [4mgroff[24m font metric files.  The [4mdownload[24m 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 default foundry.  This de‐
       fault uses the same fonts as [4mghostscript[24m uses when it embeds fonts in a
       PDF file.

       In the default setup there are styles called [1mR[22m, [1mI[22m, [1mB[22m, and [1mBI [22mmounted at
       font positions 1 to 4.  The fonts are grouped into families [1mA[22m,  [1mBM[22m,  [1mC[22m,
       [1mH[22m, [1mHN[22m, [1mN[22m, [1mP[22m, and [1mT [22mhaving 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

       There is also the following font which is not a member of a family:

              [1mZCMI   [22mZapfChancery‐MediumItalic

       There are also some special fonts called [1mS [22mfor the PS Symbol font.  The
       lower  case  greek  characters  are automatically slanted (to match the
       SymbolSlanted font (SS) available to  PostScript).   Zapf  Dingbats  is
       available  as  [1mZD[22m;  the “hand pointing left” glyph ([1m\[lh][22m) is available
       since it has been defined using the [1m\X'pdf: xrev' [22mdevice  control  com‐
       mand, which reverses the direction of letters within words.

       The default color for [1m\m [22mand [1m\M [22mis black.

       [4mgropdf[24m  understands  some  of  the device control commands supported by
       [4mgrops[24m(1).

       [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[0m
       [1mexch translate'[0m
              where [4mn[24m is the angle of rotation.  This is to support the  [1malign[0m
              command in [4mgpic[24m(1).

       [1m\X'ps: exec grestore'[0m
              Used by [4mgpic[24m(1) 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

       [1m\X'ps: [22m... [1mpdfmark'[0m
              All the [4mpdfmark[24m macros installed by using [4m-m[24m [4mpdfmark[24m or [4m-m[24m [4mmspdf[0m
              (see  documentation  in  [4mpdfmark.pdf[24m).  A subset of these macros
              are installed automatically when you use [1m-Tpdf [22mso you should not
              need to use “[1m-m pdfmark[22m” to access most PDF functionality.

       [4mgropdf[24m  also  supports  a  subset  of  the   commands   introduced   in
       [4mpresent.tmac[24m.  Specifically it supports:‐

              PAUSE
              BLOCKS
              BLOCKE

       Which  allows  you to create presentation type 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
              using the current [1mBLOCK [22mtransition setting (see “[1m\X'pdf: transi‐[0m
              [1mtion'[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‐presentation    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
       [4mpresentps[24m(1) since the output will already be a presentation PDF.

       All other [1mps: [22mtags are silently ignored.

       One [1m\X [22mdevice control command used by the DVI  driver  is  also  recog‐
       nised.

       [1m\X'papersize=[4m[22mpaper‐format[24m[1m'[0m
              where  the [4mpaper‐format[24m parameter is the same as that to the [1mpa‐[0m
              [1mpersize [22mdirective.  See [4mgroff_font[24m(5).  This means that you  can
              alter the page size at will within the PDF file being created by
              [4mgropdf[24m.   If  you do want to change the paper format, it must be
              done before you start creating the page.

       [4mgropdf[24m supports several more device control  features  using  the  [1mpdf:[0m
       tag.  Some have counterpart [4mconvenience[24m [4mmacros[24m that take the same argu‐
       ments and behave equivalently.

       [1m\X'pdf: pdfpic [4m[22mfile[24m [4malignment[24m [4mwidth[24m [4mheight[24m [4mline‐length[24m'
              Place an image of the specified [4mwidth[24m containing the PDF drawing
              from file [4mfile[24m of desired [4mwidth[24m and [4mheight[24m (if [4mheight[24m is missing
              or  zero  then it is scaled proportionally).  If [4malignment[24m is [1m-L[0m
              the 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[24m is specified as zero then the width is scaled  in  propor‐
              tion to the height.

       [1m\X'pdf: xrev'[0m
              Toggle  the  reversal  of  glyph  direction.  This feature works
              “letter by letter”, that is, each letter in a word  is  reversed
              left‐to‐right,  not the entire word.  One application is the re‐
              versal of glyphs in the Zapf Dingbats font.  To restore the nor‐
              mal glyph orientation, repeat the command.

       [1m\X'pdf: markstart [4m[22m/ANN‐definition[24m[1m'[0m
       [1m\X'pdf: markend'[0m
              Macros that support PDF bookmarks use these calls internally  to
              start  and  stop  (respectively) the placement of the bookmark’s
              [4mhot[24m [4mspot;[24m the user will have called “[1m.pdfhref L[22m” with  the  text
              of  the  hot  spot.   Normally, these are never used except from
              within the [4mpdfmark[24m macros.

       [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
              commands if a PDF [4mhot[24m [4mspot[24m crosses a  trap  boundary;  otherwise
              any  text  output  by the trap will be marked as part of the hot
              spot.  To prevent this error, place these  device  control  com‐
              mands  or their corresponding convenience macros [1m.pdfmarksuspend[0m
              and [1m.pdfmarkrestart [22mat the start and end of the trap macro,  re‐
              spectively.

       [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’.  The convenience macro for this  com‐
              mand is [1m.pdfpagename[22m.

       [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’[0m
              position  within  the  document  (see  pagename  command above).
              [4m‘when’[24m can be either ‘[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  eso‐
              teric uses are possible.  The convenience macro for this command
              is [1m.pdfswitchtopage[22m.

       [1m\X'pdf: transition [4m[22mfeature[24m [4mmode[24m [4mduration[24m [4mdimension[24m [4mmotion[24m [4mdirection[0m
       [4mscale[24m [4mbool[24m[1m'[0m
              where  [4mfeature[24m  can  be either SLIDE or BLOCK.  When it is SLIDE
              the transition is used when a new slide  is  introduced  to  the
              screen, if BLOCK then this transition is used for the individual
              blocks which make 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[0m
                     entries, respectively.
                     [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 verti‐
                     cal, 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[24m 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  [4mdi‐[0m
                     [4mrection[24m entry, revealing the new page.
                     [1mDissolve [22m‐ The old page dissolves gradually to reveal the
                     new one.
                     [1mGlitter  [22m‐  Similar  to  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 speci‐
                     fied by the [4mdirection[24m entry.
                     [1mR [22m‐ The new page simply replaces the old one with no spe‐
                     cial transition effect; the [4mdirection[24m entry shall be  ig‐
                     nored.
                     [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  [4mdirec‐[0m
                     [4mtion[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 oc‐
              cur: [1mH [22mHorizontal, or [1mV [22mVertical.

              [4mmotion[24m (Optional; [1mSplit[22m, [1mBox [22mand [1mFly [22mtransition styles only) The
              direction of motion for the specified transition effect:  [1mI  [22mIn‐
              ward 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
              transition effect shall moves,  expressed  in  degrees  counter‐
              clockwise 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  start‐
              ing or ending scale at which the changes shall be drawn.  If [4mmo‐[0m
              [4mtion[24m  specifies  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 transition

              [4mbool[24m (Optional; PDF 1.5; [1mFly [22mtransition style only) If [1mtrue[22m, the
              area that shall be flown in is rectangular and opaque.

              This command can be used by calling the macro [1m.pdftransition [22mus‐
              ing the parameters described above.  Any of the  parameters  may
              be replaced with a "." which signifies the parameter retains its
              previous  value,  also  any  trailing missing parameters are ig‐
              nored.

              [1mNote: [22mnot all PDF Readers support any or all these transitions.

       [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
              produces a background rectangle on the page, where

              [4mcmd[24m    is the command, which can be any  of  “[1mpage[22m|[1mfill[22m|[1mbox[22m”  in
                     combination.   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).  “[1mbox‐[0m
                     [1mfill[22m”,  on  the other hand, requires the given dimensions
                     to place the box.  Including “[1mfill[22m” in the  command  will
                     paint the rectangle with the current fill colour (as with
                     [1m\M[][22m)  and including “[1mbox[22m” will give the rectangle a bor‐
                     der in the current stroke colour (as with [1m\m[][22m).

                     [4mcmd[24m may also be “[1moff[22m” on its own,  which  will  terminate
                     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 will  replace  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” command with no  other  boxes
                     open.

                     Finally,  [4mcmd[24m  may  be “[1mfootnote[22m” followed by a new value
                     for [4mbottom[24m, which will be 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  mul‐
                     tiple  footnotes,  for instance).  (If the value is nega‐
                     tive, 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 coor‐
                     dinates  are  the  minimum and maximum for the box, since
                     the actual 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 bot‐
                     tom coordinates 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  in‐
                     cluded in the command.

              The  convenience  macro  for  this  escape sequence is [1m.pdfback‐[0m
              [1mground[22m.   An  [4msboxes[24m  macro  file   is   also   available;   see
              [4mgroff_tmac[24m(5).

   [1mMacros[0m
       [4mgropdf[24m’s  support  macros in [4mpdf.tmac[24m define the convenience macros de‐
       scribed above.  Some features have no  direct  device  control  command
       counterpart.

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

   [1mImporting graphics[0m
       [4mgropdf[24m supports only the inclusion of other PDF files  for  inline  im‐
       ages.  Such a PDF file may, however, contain any of the graphic formats
       supported  by  the  PDF standard, such as JPEG/JFIF, PNG, and GIF.  Any
       application that outputs PDF can thus be used to prepare files for  em‐
       bedding in documents processed by [4mgroff[24m and [4mgropdf[24m.

       The  PDF  file you wish to insert must be a single page and the drawing
       must just fit inside the media size of the PDF file.  In [4minkscape[24m(1) or
       [4mgimp[24m(1), 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 [4mpdftk[24m(1) 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
       The following is a step‐by‐step font installation guide for [4mgropdf.[0m

       • Convert your font to something [4mgroff[24m understands.  This  is  a  Post‐
         Script  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‐print‐
         ing  bytes.   In  the  following  steps,  we will consider the use of
         CTAN’s    BrushScriptX‐Italic    ⟨https://ctan.org/tex-archive/fonts/
         brushscr⟩ font in PFA format.

       • Convert  the  AFM  file  to  a  [4mgroff[24m  font description file with the
         [4mafmtodit[24m(1) program.  For instance,
                $ [1mafmtodit BrushScriptX-Italic.afm text.map BSI[0m
         converts the Adobe Font Metric file  [4mBrushScriptX-Italic.afm[24m  to  the
         [4mgroff[24m 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, 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  [4mdevpdf[24m  subdirectory
         in  the search path that [4mgroff[24m uses for device and font file descrip‐
         tions.  See the [4mGROFF_FONT_PATH[24m entry  in  section  “Environment”  of
         [4mgtroff[24m(1) for the current value of the font search path.  While [4mgroff[0m
         doesn’t  directly  use  AFM  files,  it  is a good idea to store them
         alongside its font description 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[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 [4mgropdf[24m is  stored  in  the  [1minternalname[0m
         field in the [4mgroff[24m font description file.  (This name does not neces‐
         sarily  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

[1mEnvironment[0m
       [4mGROFF_FONT_PATH[0m
              A  list  of directories in which to seek the selected output de‐
              vice’s directory of device and font description files.   If,  in
              the  [4mdownload[24m file, the font file has been specified with a full
              path,  no  directories  are   searched.    See   [4mgtroff[24m(1)   and
              [4mgroff_font[24m(5).

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

       [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
              [4mlocaltime()[24m function and recorded in a PDF comment.

       [4mTZ[24m     The time zone to use when converting the current time (or  value
              of [4mSOURCE_DATE_EPOCH[24m) to human‐readable form; see [4mtzset[24m(3).

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

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

       [4m/usr/pkg/share/groff/1.23.0/font/devpdf/U-[24mF
              describes  the  font  from the URW foundry (versus the Adobe de‐
              fault) known as [4mF[24m on device [1mpdf[22m.

       [4m/usr/pkg/share/groff/1.23.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/pkg/share/groff/1.23.0/font/devpdf/Foundry[0m
              is  a  data  file used by the [4mgroff[24m build system to locate Post‐
              Script Type 1 fonts.

       [4m/usr/pkg/share/groff/1.23.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/pkg/share/groff/1.23.0/tmac/pdf.tmac[0m
              defines macros for use with the [1mpdf [22moutput device.  It is  auto‐
              matically  loaded  by  [4mtroffrc[24m when the [1mpdf [22moutput device is se‐
              lected.

       [4m/usr/pkg/share/groff/1.23.0/tmac/pdfpic.tmac[0m
              defines the [1mPDFPIC [22mmacro for embedding images in a document; see
              [4mgroff_tmac[24m(5).  It is automatically loaded by [4mtroffrc.[0m

[1mAuthors[0m
       [4mgropdf[24m was written and is maintained  by  Deri  James  ⟨deri@chuzzlewit
       .myzen.co.uk⟩.

[1mSee also[0m
       [4m/usr/pkg/share/doc/groff-1.23.0/sboxes/msboxes.ms[0m
       [4m/usr/pkg/share/doc/groff-1.23.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  [4mgpresent[24m  ⟨https://bob.diertens.org/corner/useful/
              gpresent/⟩, a software package by Bob Diertens that  works  with
              [4mgroff[24m to produce presentations (“foils”, or “slide decks”).

       [4mafmtodit[24m(1), [4mgroff[24m(1), [4mgtroff[24m(1), [4mgroff_font[24m(5), [4mgroff_out[24m(5)

groff 1.23.0                      2 July 2023                        [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
       [4mgtroff[24m(1) into PostScript.  Normally, [4mgrops[24m is invoked by [4mgroff[24m(1) 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 standard input stream.  Output is written 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 concatenated output, it is necessary to deacti‐
       vate 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
       information; all exit afterward.

       [1m-b [4m[22mn[24m   Work around problems with spoolers, previewers, and older print‐
              ers.    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
              TranScript that get confused by anything between the [1m%%EndProlog[0m
              comment and the first [1m%%Page [22mcomment.

              Add  2  to omit lines in included files beginning with [1m%![22m, which
              confuse 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  com‐
              mand).  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
              device  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: import' [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  de‐
              sired 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[0m
              file.   [4mfmt[24m can be any argument accepted by the [1mpapersize [22mdirec‐
              tive; see [4mgroff_font[24m(5).

       [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 [4mgtroff[24m(1), described
       in  [4mgroff_out[24m(5).   In  addition, the device and font description files
       for the device used must meet certain requirements.  The device resolu‐
       tion must be an integer multiple of 72 times the [1msizescale[22m.  The device
       description file must contain a valid paper format; see  [4mgroff_font[24m(5).
       Each font description 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 en‐
       coding 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
       position  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 correspond 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 reencoded.  This code can be used with the [1m\N  [22mescape  se‐
       quence  in  [4mgtroff[24m  to select 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 descrip‐
       tion file must match the widths used in the PostScript font.  [4mgrops[24m as‐
       sumes  that  a  character with a [4mgroff[24m 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 encod‐
       ing 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[24m 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
       [4mpfbtops[24m(1) 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; lines beginning with [1m# [22mand blank  lines  are
       ignored; fields may be separated by tabs or spaces.  [4mfile[24m is sought us‐
       ing  the  same mechanism as that for [4mgroff[24m font description files.  The
       [4mdownload[24m file itself is also sought using  this  mechanism;  currently,
       only  the  first matching file found in the device and font description
       search path is used.

       If the file containing a downloadable font or  imported  document  con‐
       forms  to the Adobe Document Structuring Conventions, then [4mgrops[24m inter‐
       prets any comments in the files sufficiently to  ensure  that  its  own
       output  is conforming.  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 be‐
       fore 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%%Document‐[0m
       [1mNeededResources[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%%Begin‐[0m
       [1mFont[22m, and [1m%%EndFont [22mcomments) should be used.

       The  default stroke and fill color is black.  For colors defined in the
       “rgb” color space, [1msetrgbcolor [22mis used; for “cmy” and “cmyk”,  [1msetcmyk‐[0m
       [1mcolor[22m;   and   for  “gray”,  [1msetgray[22m.   [1msetcmykcolor  [22mis  a  PostScript
       LanguageLevel 2 command 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 hav‐
       ing 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  [22m(slanted  symbol),  which contains oblique forms of lowercase Greek
       letters derived from Symbol; [1mEURO[22m, which offers a Euro  glyph  for  use
       with  old  devices lacking it; and [1mZDR[22m, a reversed version of ZapfDing‐
       bats (with symbols flipped about the vertical axis).   Most  glyphs  in
       these  fonts are unnamed and must be accessed using [1m\N[22m.  The last three
       are not standard PostScript fonts, but supplied by [4mgroff[24m and  therefore
       included in the default [4mdownload[24m file.

   [1mDevice control commands[0m
       [4mgrops[24m  recognizes device control commands produced by the [1m\X [22mescape se‐
       quence, 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[0m
              escape sequence is interpreted before executing [4mcode[24m.  The  ori‐
              gin  is  at  the  top left corner of the page; [4mx[24m coordinates in‐
              crease to the right, and [4my[24m coordinates down the page.  A  proce‐
              dure [1mu [22mis defined that converts [4mgroff[24m basic units to the coordi‐
              nate  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  allo‐
              cate  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  [22mes‐
              cape  sequence with an argument that names a macro, [4mcode[24m can ex‐
              tend over multiple lines.  For example,
                     .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  di‐
              mension “[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,
              nothing more.  In particular, it doesn’t start and end  the  in‐
              serted  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 de‐
              finitions  can  be  split over several [1m\X [22mcommands; all the [4mcode[0m
              arguments are simply joined together separated by newlines.  The
              definitions are placed in a dictionary  which  is  automatically
              pushed on the dictionary stack when an [1mexec [22mcommand is executed.
              If  you use the [1m\Y [22mescape 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[24m  needs  to know how many definitions [4mcode[24m contains so that
              it can create 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
              PostScript coordinate system.  They should all be integers:  [4mllx[0m
              and  [4mlly[24m 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  up‐
              per  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  lo‐
              cated 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 [4mgtroff[24m, so
              vertical 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  Struc‐
              turing  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  [4mgroff_tmac[24m(5)  for  a  description of the [1mPSPIC [22mmacro which
              provides 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
              bracketed with these [1m\X [22mcommands.  These commands  are  intended
              for  use  when  output  from  [4mgtroff[24m  is  previewed before being
              processed with [4mgrops[24m; if the previewer is unable to display cer‐
              tain characters or other constructs, then other substitute char‐
              acters 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][0m
              character because the standard X11 fonts do not provide it; this
              problem can be overcome by executing 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 control command, it is executed at the beginning of
       every page (before anything is drawn or written by [4mgroff[24m).   For  exam‐
       ple, to underlay the page contents with the word “DRAFT” in light gray,
       you might use

              .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
              .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  uncon‐
       nected).

   [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
       TrueType fonts can be used with [4mgrops[24m if converted  first  to  Type  42
       format,  a PostScript wrapper equivalent to the PFA format described in
       [4mpfbtops[24m(1).  Several methods exist to generate a Type 42 wrapper;  some
       of  them  involve  the  use  of a PostScript interpreter such as Ghost‐
       script—see [4mgs[24m(1).

       One approach is to use FontForge ⟨https://fontforge.org/⟩, a font  edi‐
       tor  that  can convert most outline font formats.  Here’s an example of
       using the Roboto Slab Serif font with  [4mgroff[24m.   Several  variables  are
       used so that you can more easily adapt it into your own script.

           MAP=/usr/pkg/share/groff/1.23.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 generate warnings depending on the attrib‐
       utes of the font.  The test procedure is simple.

           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 environ‐
       ment  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
       The following is a step‐by‐step font installation guide for [4mgrops.[0m

       • Convert your font to something [4mgroff[24m understands.  This  is  a  Post‐
         Script  Type  1  font in PFA format or a PostScript Type 42 font, to‐
         gether 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‐print‐
         ing  bytes.   If  your  font is in PFB format, use [4mgroff[24m’s [4mpfbtops[24m(1)
         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 True‐
         Type font interpreter).  In the following steps, we will consider the
         use  of  CTAN’s  BrushScriptX‐Italic   ⟨https://ctan.org/tex-archive/
         fonts/brushscr⟩ font in PFA format.

       • Convert  the  AFM  file  to  a  [4mgroff[24m  font description file with the
         [4mafmtodit[24m(1) program.  For instance,
                $ [1mafmtodit BrushScriptX-Italic.afm text.map BSI[0m
         converts the Adobe Font Metric file  [4mBrushScriptX-Italic.afm[24m  to  the
         [4mgroff[24m 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,  re‐
         spectively,  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 abbrevi‐
         ated 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  descrip‐
         tions.   See  the  [4mGROFF_FONT_PATH[24m  entry in section “Environment” of
         [4mgtroff[24m(1) for the current value of the font search path.  While [4mgroff[0m
         doesn’t directly use AFM files, it is  a  good  idea  to  store  them
         alongside its font description files.

       • Register  fonts in the [4mdevps/download[24m file so they can be located for
         embedding in PostScript files [4mgrops[24m generates.  Only the first  [4mdown‐[0m
         [4mload[24m  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[0m
         field in the [4mgroff[24m font description file.  (This name does not neces‐
         sarily  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 -P -e >hello.ps
                see hello.pdf

[1mOld fonts[0m
       [4mgroff[24m versions 1.19.2 and earlier contained descriptions of a  slightly
       different set of the base 35 PostScript level 2 fonts defined by Adobe.
       The  older  set  has  229 glyphs and a larger set of kerning pairs; the
       newer one has 314 glyphs and includes the Euro  glyph.   For  backwards
       compatibility,  these  old  font descriptions are also installed in the
       [4m/usr/pkg/share/groff/1.23.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/pkg/share/groff/1.23.0/oldfont [22m...
       or add the directory to [4mgroff[24m’s font and device description search path
       environment variable,
              $ [1mGROFF_FONT_PATH=/usr/pkg/share/groff/1.23.0/oldfont \[0m
                     [1mgroff -Tps [22m...
       when the command runs.

[1mEnvironment[0m
       [4mGROFF_FONT_PATH[0m
              A list of directories in which to seek the selected  output  de‐
              vice’s  directory  of  device  and  font description files.  See
              [4mgtroff[24m(1) and [4mgroff_font[24m(5).

       [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 [22moverrides 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 [4mctime[24m(3)  and
              recorded in a PostScript comment.

       [4mTZ[24m     The  time zone to use when converting the current time (or value
              of [4mSOURCE_DATE_EPOCH[24m) to human‐readable form; see [4mtzset[24m(3).

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

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

       [4m/usr/pkg/share/groff/1.23.0/font/devps/download[0m
              lists fonts available for embedding within the PostScript  docu‐
              ment (or download to the device).

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

       [4m/usr/pkg/share/groff/1.23.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/pkg/share/groff/1.23.0/tmac/ps.tmac[0m
              defines macros for use with the [1mps [22moutput device.  It  is  auto‐
              matically  loaded  by  [4mtroffrc[24m  when the [1mps [22moutput device is se‐
              lected.

       [4m/usr/pkg/share/groff/1.23.0/tmac/pspic.tmac[0m
              defines the [1mPSPIC [22mmacro for embedding images in a document;  see
              [4mgroff_tmac[24m(5).  It is automatically loaded by [4mtroffrc.[0m

       [4m/usr/pkg/share/groff/1.23.0/tmac/psold.tmac[0m
              provides  replacement  glyphs  for text fonts that lack complete
              coverage 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.

       [4mgrops[24m creates temporary files using  the  template  “[4mgrops[24mXXXXXX”;  see
       [4mgroff[24m(1) for details on their storage location.

[1mSee also[0m
       PostScript  Language  Document  Structuring  Conventions  Specification
       ⟨http://partners.adobe.com/public/developer/en/ps/5001.DSC_Spec.pdf⟩

       [4mafmtodit[24m(1),   [4mgroff[24m(1),    [4mgtroff[24m(1),    [4mpfbtops[24m(1),    [4mgroff_char[24m(7),
       [4mgroff_font[24m(5), [4mgroff_out[24m(5), [4mgroff_tmac[24m(5)

groff 1.23.0                      2 July 2023                         [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-dfho[22m] [[1m-i[22m|[1m-r[22m] [[1m-F [4m[22mdir[24m] [[4mfile[24m ...]

       [1mgrotty -c [22m[[1m-bBdfhouU[22m] [[1m-F [4m[22mdir[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
       [4mgtroff[24m(1) into a form suitable for typewriter‐like  devices,  including
       terminal  emulators.   Normally, [4mgrotty[24m is invoked by [4mgroff[24m(1) when the
       latter is given one of  the  “[1m-T  ascii[22m”,  “[1m-T  latin1[22m”,  [1m-Tlatin1[22m,  or
       “[1m-T utf8[22m” options on systems using ISO character encoding standards, or
       with  “[1m-T cp1047[22m” or “[1m-T utf8[22m” on EBCDIC‐based hosts.  (In this instal‐
       lation, [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.  Out‐
       put is written 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,  under‐
       line, reverse video [“negative image”] and colors).  Devices supporting
       the appropriate sequences can view [4mroff[24m documents using eight different
       background  and  foreground  colors.  Following ISO 6429, the following
       colors are defined in [4mtty.tmac[24m: black, white, red, green, blue, yellow,
       magenta, and cyan.  Unrecognized  colors  are  mapped  to  the  default
       color,  which  is dependent on the settings of the terminal.  OSC 8 hy‐
       perlinks are produced for these devices.

       In keeping with long‐standing practice and the rarity of terminals (and
       emulators) that support oblique or italic  fonts,  italicized  text  is
       represented with underlining by default—but see the [1m-i [22moption below.

   [1mSGR and OSC support in pagers[0m
       When  paging  [4mgrotty[24m’s  output with [4mless[24m(1), the latter program must be
       instructed to pass SGR and OSC sequences through to the device; its  [1m-R[0m
       option  is  one  way  to achieve this ([4mless[24m version 566 or later is re‐
       quired for OSC 8 support).  Consequently,  programs  like  [4mman[24m(1)  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 pa‐
       per 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  se‐
       quences  are  not  emitted; bold, italic, and underlining character at‐
       tributes are thus not manipulated.  Instead, [4mgrotty[24m overstrikes, repre‐
       senting a bold character [4mc[24m with the sequence “[4mc[24m BACKSPACE [4mc[24m”, an italic
       character [4mc[24m with the sequence “[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 emula‐
       tor) by piping [4mgrotty[24m’s output through [4mul[24m(1),  which  may  render  bold
       italics  as  reverse  video.   Some implementations of [4mmore[24m(1) are also
       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 re‐
       quiring options.  In contrast to the terminal output  drivers  of  some
       other  [4mroff[24m  implementations,  [4mgrotty[24m never outputs reverse line feeds.
       There is therefore no need to filter its output through [4mcol[24m(1).

   [1mDevice control commands[0m
       [4mgrotty[24m understands one device control function produced by the [4mroff[24m  [1m\X[0m
       escape sequence in a document.

       [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.
              Specifying [4muri[24m starts hyperlinked text, and omitting it ends the
              hyperlink.  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” di‐
       rective, [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 [4mgroff_font[24m(5).

       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, then  the  font  is
       treated  as an italic font; if the 02 bit is set, then it is treated as
       a bold font.

   [1mTypefaces[0m
       [4mgrotty[24m supports the standard four styles:  [1mR  [22m(roman),  [1mI  [22m([4mitalic[24m),  [1mB[0m
       ([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.

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

       [1m-b     [22mSuppress the use of overstriking for bold characters  in  legacy
              output format.

       [1m-B     [22mUse  only overstriking for bold‐italic characters in legacy out‐
              put 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 [1m\D [22mdrawing escape sequences in  the  input.   By  de‐
              fault,  [4mgrotty[24m  renders  [1m\D'l[22m...[1m'  [22mescape sequences that have at
              least one zero argument (and so are either horizontal or  verti‐
              cal)  using Unicode box drawing characters (for the [1mutf8 [22mdevice)
              or the [1m-[22m, [1m|[22m, and [1m+ [22mcharacters (for all other  devices).   [4mgrotty[0m
              handles [1m\D'p[22m...[1m' [22mescape sequences that consist entirely of hori‐
              zontal and vertical lines similarly.

       [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
              device description files; [4mname[24m  describes  the  output  device’s
              character encoding, one of [1mascii[22m, [1mlatin1[22m, [1mutf8[22m, or [1mcp1047[22m.

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

       [1m-i     [22mRender oblique‐styled fonts ([1mI [22mand [1mBI[22m) with  the  SGR  attribute
              for  italic  text  rather  than underlined text.  Many terminals
              don’t  support  this   attribute;   however,   [4mxterm[24m(1),   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
              characters when the legacy output format is in use).

       [1m-r     [22mRender oblique‐styled fonts ([1mI [22mand [1mBI[22m) with  the  SGR  attribute
              for  reverse video text rather than underlined text.  Ignored if
              [1m-c [22mor [1m-i [22mis also specified.

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

[1mEnvironment[0m
       [4mGROFF_FONT_PATH[0m
              A  list  of directories in which to seek the selected output de‐
              vice’s directory of device  and  font  description  files.   See
              [4mgtroff[24m(1) and [4mgroff_font[24m(5).

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

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

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

       [4m/usr/pkg/share/groff/1.23.0/font/devcp1047/DESC[0m
              describes the [1mcp1047 [22moutput device.

       [4m/usr/pkg/share/groff/1.23.0/font/devcp1047/[24mF
              describes the font known as [4mF[24m on device [1mcp1047[22m.

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

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

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

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

       [4m/usr/pkg/share/groff/1.23.0/tmac/tty.tmac[0m
              defines  macros for use with the [1mascii[22m, [1mcp1047[22m, [1mlatin1[22m, and [1mutf8[0m
              output devices.  It is automatically loaded by [4mtroffrc[24m when  any
              of those output devices is selected.

       [4m/usr/pkg/share/groff/1.23.0/tmac/tty-char.tmac[0m
              defines fallback characters for use with [4mgrotty.[24m  See [4mnroff[24m(1).

[1mLimitations[0m
       [4mgrotty[24m is intended only for simple documents.

       • There is no support for fractional horizontal or vertical motions.

       • [4mroff[24m [1m\D [22mescape sequences producing anything other than horizontal and
         vertical lines are not supported.

       • Characters above the first line (that is, with a vertical drawing po‐
         sition of 0) cannot be rendered.

       • Color handling differs from other output drivers.  The [4mgroff[24m requests
         and  escape sequences that set the stroke and fill colors instead set
         the foreground and background character cell colors, respectively.

[1mExamples[0m
       The following [4mgroff[24m document exercises several features for which  out‐
       put  device  support  varies:  (1)  bold  style; (2) italic (underline)
       style; (3) bold‐italic style; (4) character composition by overstriking
       (“coöperate”); (5) foreground color; (6) background color; and (7) hor‐
       izontal and vertical line‐drawing.

              You might see \f[B]bold\f[] and \f[I]italic\f[].
              Some people see \f[BI]both\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  fol‐
       lowing.

              $ [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
       “Control  Functions  for  Coded  Character Sets” (ECMA‐48) 5th edition,
       Ecma International, June 1991.  A gratis version of ISO 6429, this doc‐
       ument includes a normative description of SGR escape sequences.  Avail‐
       able at  ⟨http://www.ecma-international.org/publications/files/ECMA-ST/
       Ecma-048.pdf⟩.

       “Hyperlinks  in Terminal Emulators” ⟨https://gist.github.com/egmontkob/
       eb114294efbcd5adb1944c9f3cb5feda⟩, Egmont Koblinger.

       [4mgroff[24m(1), [4mgtroff[24m(1), [4mgroff_out[24m(5), [4mgroff_font[24m(5), [4mgroff_char[24m(7), [4mul[24m(1),
       [4mmore[24m(1), [4mless[24m(1), [4mman[24m(1)

groff 1.23.0                      2 July 2023                        [4mgrotty[24m(1)
───────────────────────────────────────────────────────────────────────────────
[4mgxditview[24m(1)                General Commands Manual               [4mgxditview[24m(1)

[1mName[0m
       gxditview - display [4mgroff[24m intermediate output files 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 -version[0m
       [1mgxditview --version[0m

[1mDescription[0m
       [4mgxditview[24m interprets and displays the  intermediate  output  format  of
       [4mgroff[24m(1) on an X11 display.  It uses the standard X11 fonts, so it does
       not  require  access to the server machine for font loading.  There are
       several ways to use [4mgxditview[24m.

       The intermediate output format of [4mgroff[24m, documented in [4mgroff_out[24m(5), is
       produced by [4mgtroff[24m or the [1m-Z [22moption to [4mgroff[24m.  It can be viewed by  ex‐
       plicitly  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.
       The  intermediate  output format of [4mgroff[24m is device‐independent but not
       device‐agnostic.  [4mgxditview[24m can view it for all typesetter devices, but
       the quality 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  [4mgroff[24m’s  [1m-T  [22mop‐
       tion,  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, [4mgroff[24m generates the intermediate output for
       this device and calls [4mgxditview[24m automatically 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[0m
                    Display the previous page.

       [1mSelect Page  [22mSelect  a  particular  numbered page specified by a dialog
                    box.

       [1mPrint        [22mPrint the [4mgroff[24m intermediate output using a command speci‐
                    fied by a dialog box.  The default command initially  dis‐
                    played  is  controlled by the [1mprintCommand [22mapplication re‐
                    source, and by the [1m-printCommand [22moption.

       [1mOpen         [22mOpen for display a new file specified  by  a  dialog  box.
                    The file should contain [4mgroff[24m intermediate output.  If the
                    filename  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
       [1mPreviousPage [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
       current file, and redisplays the current page; if the current file is a
       command, 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[24m output device specify the length and width in  machine  units  of
       the virtual page displayed by [4mgxditview[24m; see [4mgroff_font[24m(5).

   [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: firstly the [4mgroff[24m font
              name,  and  secondly the XLFD (X Logical Font Description).  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  in‐
       dented 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-version [22mand [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 [4mgroff[24m intermediate output window can
              take a perceiptible 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‐store‐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[0m
              menu entry will be [4mcommand[24m.

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

       [1m-filename [4m[22mstring[0m
              The  default  filename  displayed in the dialog box for the [1mOpen[0m
              menu entry will be [4mstring[24m.  This can be either a filename, 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 sur‐
              rounding the window.

       [1m-fg [4m[22mcolor[0m
              This option specifies the color to use for displaying text.  The
              default 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.

[1mEnvironment[0m
       [4mGROFF_FONT_PATH[0m
              A  list  of directories in which to seek the selected output de‐
              vice’s directory of device  and  font  description  files.   See
              [4mgtroff[24m(1) and [4mgroff_font[24m(5).

[1mFiles[0m
       [4m/usr/pkg/lib/X11/app-defaults/GXditview[0m
       [4m/usr/pkg/lib/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 [4mappres[24m(1) and [4mxrdb[24m(1).

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

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

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

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

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

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

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

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

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

       [4m/usr/pkg/share/groff/1.23.0/tmac/Xps.tmac[0m
              sets up [4mgtroff[24m to use [4mgxditview[24m as a previewer for  device‐inde‐
              pendent  output targeting the [1mps [22moutput device.  It is automati‐
              cally loaded by [4mtroffrc[24m when [4mgtroff[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
       display 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 (Berke‐
       ley),  Malcolm  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
       “X  Logical  Font Description Conventions” ⟨https://www.x.org/releases/
       X11R7.6/doc/xorg-docs/specs/XLFD/xlfd.html⟩, by Jim Flowers and Stephen
       Gildea.

       [4mX[24m(7), [4mxrdb[24m(1), [4mxditview[24m(1), [4mgroff[24m(1), [4mgroff_out[24m(5)

groff 1.23.0                      2 July 2023                     [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 with the [4mgrolj4[24m(1)  output  driver
       of [4mgroff[24m(1), using data from an HP tagged font metric (TFM) file.  [4mtfm‐[0m
       [4mfile[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 [4mgroff_char[24m(7) 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[24m 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 [4mgroff_diff[24m(1) 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[0m
       name, it must appear first in a list of [4mgroff[24m names if a comment is in‐
       cluded, 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.

       Output is written in [4mgroff_font[24m(5) format to [4mfont‐description,[24m  a  file
       named  for  the  intended  [4mgroff[24m font name; if this operand is “[1m-[22m”, the
       font description is written to the standard output stream.

       If the [1m-i [22moption is  used,  [4mhpftodit[24m  automatically  will  generate  an
       italic correction, a left italic correction, and a subscript correction
       for  each  glyph  (the significance of these parameters is explained in
       [4mgroff_font[24m(5)).

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

       [1m-a     [22mInclude  glyphs  in  the  TFM file that are not included in [4mmap‐[0m
              [4mfile[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  Pri‐
              vate  Use  Area  (0xE000–0xF8FF)  is also included as an unnamed
              glyph.

              This option provides a simple means of adding Unicode‐named  and
              unnamed 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  pres‐
              ence or absence 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 selective—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 in‐
              cludes  the  values  of important TFM tags and a listing (by MSL
              number for Intellifont TFM files or by Unicode value  for  True‐
              Type  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 Intellifont fonts, and 2048 de‐
              sign units per em for TrueType fonts.  Note that the accessibil‐
              ity 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 ap‐
              pear in any supported symbol set and cannot be printed.

              With the [1m-d [22moption, [4mmap‐file[24m is optional, and [4moutput‐font[24m is ig‐
              nored 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.  If a negative italic correc‐
              tion would result, 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 a subscript correction greater than the italic
              correction 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, affect‐
              ing the order in which HP symbol  sets  are  searched  for  each
              glyph.  Without this option, the “text” sets are searched before
              the  “mathematical”  symbol  sets.  With it, the search order is
              reversed.

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

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

       [4m/usr/pkg/share/groff/1.23.0/font/devlj4/generate/Makefile[0m
              is a [4mmake[24m(1) script that uses [4mhpftodit[24m(1) to prepare  the  [4mgroff[0m
              font description files above from HP TFM data; in can be used to
              regenerate them in the event the TFM files are updated.

       [4m/usr/pkg/share/groff/1.23.0/font/devlj4/generate/special.awk[0m
              is  an  [4mawk[24m(1) script that corrects the Intellifont‐based height
              metrics for several glyphs in the [1mS [22m(special) font for  TrueType
              CG Times used in the HP LaserJet 4000 and later.

       [4m/usr/pkg/share/groff/1.23.0/font/devlj4/generate/special.map[0m
       [4m/usr/pkg/share/groff/1.23.0/font/devlj4/generate/symbol.map[0m
       [4m/usr/pkg/share/groff/1.23.0/font/devlj4/generate/text.map[0m
       [4m/usr/pkg/share/groff/1.23.0/font/devlj4/generate/wingdings.map[0m
              map  MSL indices and HP Unicode PUA assignments to [4mgroff[24m special
              character identifiers.

[1mSee also[0m
       [4mgroff[24m(1), [4mgroff_diff[24m(1), [4mgrolj4[24m(1), [4mgroff_font[24m(5)

groff 1.23.0                      2 July 2023                      [4mhpftodit[24m(1)
───────────────────────────────────────────────────────────────────────────────
[4mgindxbib[24m(1)                 General Commands Manual                [4mgindxbib[24m(1)

[1mName[0m
       gindxbib - make inverted index for bibliographic databases

[1mSynopsis[0m
       [1mgindxbib [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 ...]

       [1mgindxbib --help[0m

       [1mgindxbib -v[0m
       [1mgindxbib --version[0m

[1mDescription[0m
       [4mgindxbib[24m makes an inverted index for  the  bibliographic  databases  in
       each [4mfile[24m for use with [4mgrefer[24m(1), [4mglookbib[24m(1), and [4mlkbib[24m(1).  Each cre‐
       ated  index  is named file[4m.i[24m; writing is done to a temporary file which
       is then renamed to this.  If no [4mfile[24m operands are given on the  command
       line  because  the  [1m-f [22moption has been used, and no [1m-o [22moption is given,
       the index will be named [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.

       The values set by the [1m-c[22m, [1m-l[22m, [1m-n[22m, and [1m-t [22moptions are stored in the  in‐
       dex:  when  the index is searched, keys will be discarded and truncated
       in a manner appropriate to these options; the  original  keys  will  be
       used  for verifying that any record found using the index actually con‐
       tains the keys.  This means that a user  of  an  index  need  not  know
       whether  these options were used in the creation of the index, provided
       that not all the keys to be searched for would have been discarded dur‐
       ing indexing and that the user supplies at least the part of  each  key
       that  would  have  remained after being truncated during indexing.  The
       value set by the [1m-i [22moption is also stored in the index and will be used
       in verifying records found using the index.

[1mOptions[0m
       [1m--help [22mdisplays a usage message, while [1m-v [22mand  [1m--version  [22mshow  version
       information; 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/pkg/share/groff/1.23.0/eign[24m.

       [1m-d [4m[22mdir[24m Use [4mdir[24m as the name of the directory to store in the index,  in‐
              stead  of  that returned by [4mgetcwd[24m(2).  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  [22mop‐
              tion 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
              [4mgindxbib[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, [4mgindxbib[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 argu‐
              ment.  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 mini‐
              mum 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 discarded.

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

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

       [4mInd.i[24m  default index name

       [4m/usr/pkg/share/groff/1.23.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.

       [4mgrefer[24m(1), [4mlkbib[24m(1), [4mglookbib[24m(1)

groff 1.23.0                      2 July 2023                      [4mgindxbib[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 containing key‐
       words [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   variable   if   it   is   set,  otherwise  it  is
       [4m/usr/share/dict/papers/Ind[24m.  For each database [4mfile[24m to be searched,  if
       an index file[4m.i[24m created by [4mgindxbib[24m(1) 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
       information; all exit afterward.

       [1m-i [4m[22mstring[0m
              When searching files for which no index exists, ignore the  con‐
              tents 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
              default is 6.

[1mEnvironment[0m
       [4mREFER[24m  Default database.

[1mFiles[0m
       [4m/usr/share/dict/papers/Ind[0m
              Default database to be used if the [4mREFER[24m environment variable is
              not set.

       file[4m.i[24m 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.

       [4mgrefer[24m(1), [4mglookbib[24m(1), [4mgindxbib[24m(1)

groff 1.23.0                      2 July 2023                         [4mlkbib[24m(1)
───────────────────────────────────────────────────────────────────────────────
[4mglookbib[24m(1)                 General Commands Manual                [4mglookbib[24m(1)

[1mName[0m
       glookbib - search bibliographic databases

[1mSynopsis[0m
       [1mglookbib [22m[[1m-i [4m[22mstring[24m] [[1m-t [4m[22mn[24m] [4mfile[24m ...

       [1mglookbib --help[0m

       [1mglookbib -v[0m
       [1mglookbib --version[0m

[1mDescription[0m
       [4mglookbib[24m writes a prompt to the standard error stream (unless the stan‐
       dard input stream is not a terminal), reads from the standard  input  a
       line containing 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 [4mgindxbib[24m(1) 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
       information; all exit afterward.

       [1m-i [4m[22mstring[0m
              When searching files for which no index exists, ignore the  con‐
              tents 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
              default is 6.

[1mFiles[0m
       file[4m.i[24m 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.

       [4mgrefer[24m(1), [4mlkbib[24m(1), [4mgindxbib[24m(1)

groff 1.23.0                      2 July 2023                      [4mglookbib[24m(1)
───────────────────────────────────────────────────────────────────────────────
[4mmmroff[24m(1)                   General Commands Manual                  [4mmmroff[24m(1)

[1mName[0m
       mmroff - cross‐referencing 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  cross  references
       in [4mmm[24m; see [4mgroff_mm[24m(7).  It runs [4mgroff[24m with the [1m-mm [22moption twice, first
       with  [1m-z  [22mand  [1m-rRef=1 [22mto populate cross‐reference and index files with
       their corresponding entries, and then again 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 informa‐
       tion; both exit afterward.

       [1m-x     [22mCreate or update the cross‐reference file and exit.

[1mAuthors[0m
       [4mmmroff[24m was written by Jörgen Hägg ⟨jh@axis.se⟩ of Lund, Sweden.

[1mSee also[0m
       [4mgroff_mm[24m(7),  [4mgroff_mmse[24m(7),  [4mgroff[24m(1),  [4mgtroff[24m(1),  [4mgtbl[24m(1),  [4mgpic[24m(1),
       [4mgeqn[24m(1)

groff 1.23.0                      2 July 2023                        [4mmmroff[24m(1)
───────────────────────────────────────────────────────────────────────────────
[4mgneqn[24m(1)                    General Commands Manual                   [4mgneqn[24m(1)

[1mName[0m
       gneqn - format equations for character‐cell terminal output

[1mSynopsis[0m
       [1mgneqn [22m[[4mgeqn‐argument[24m ...]

[1mDescription[0m
       [4mgneqn[24m invokes the [4mgeqn[24m(1) command with the [1mascii [22moutput device.

       [4mgeqn[24m does not support low‐resolution, typewriter‐like devices, although
       it may work adequately for very simple input.

[1mSee also[0m
       [4mgeqn[24m(1)

groff 1.23.0                      2 July 2023                         [4mgneqn[24m(1)
───────────────────────────────────────────────────────────────────────────────
[4mgnroff[24m(1)                   General Commands Manual                  [4mgnroff[24m(1)

[1mName[0m
       gnroff - format documents with [4mgroff[24m for TTY (terminal) devices

[1mSynopsis[0m
       [1mgnroff [22m[[1m-bcCEhikpRStUVz[22m] [[1m-d [4m[22mctext[24m] [[1m-d [4m[22mstring[24m[1m=[4m[22mtext[24m] [[1m-K [4m[22mfallback‐[0m
              [4mencoding[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‐[0m
              [4mexpression[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 ...]

       [1mgnroff --help[0m

       [1mgnroff -v[0m
       [1mgnroff --version[0m

[1mDescription[0m
       [4mgnroff[24m  formats  documents  written  in the [4mgroff[24m(7) language for type‐
       writer‐like devices such as terminal emulators.  GNU [4mnroff[24m emulates the
       AT&T  [4mnroff[24m  command  using  [4mgroff[24m(1).   [4mgnroff[24m  generates  output  via
       [4mgrotty[24m(1),  [4mgroff[24m’s  terminal  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,  [1mutf8[22m,  and  [1mcp1047[22m;  any
       others  are ignored.  If neither the [4mGROFF_TYPESETTER[24m environment vari‐
       able nor the [1m-T [22mcommand‐line option (which  overrides  the  environment
       variable) specifies a (valid) device, [4mgnroff[24m consults the locale to se‐
       lect  an  appropriate output device.  It first tries the [4mlocale[24m(1) pro‐
       gram, then checks several  locale‐related  environment  variables;  see
       section  “Environment” below.  If all of the foregoing fail, [1m-Tascii [22mis
       implied.

       The [1m-b[22m, [1m-c[22m, [1m-C[22m, [1m-d[22m, [1m-E[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  [22mop‐
       tions  have the effects described in [4mgtroff[24m(1).  [1m-c [22mand [1m-h [22mimply “[1m-P-c[22m”
       and “[1m-P-h[22m”, respectively; [1m-c [22mis also interpreted  directly  by  [4mgtroff[24m.
       In addition, this implementation ignores the AT&T [4mnroff[24m options [1m-e[22m, [1m-q[22m,
       and  [1m-s  [22m(which are not implemented in [4mgroff[24m).  The options [1m-k[22m, [1m-K[22m, [1m-p[22m,
       [1m-P[22m, [1m-R[22m, [1m-t[22m, and [1m-S [22mare documented in [4mgroff[24m(1).   [1m-V  [22mcauses  [4mgnroff[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  [4mgnroff[24m  and  the programs it runs, while [1m--help [22mdisplays a usage
       message; all exit afterward.

[1mExit status[0m
       [4mgnroff[24m exits with error status [1m2 [22mif there was a problem parsing its ar‐
       guments, with status [1m0 [22mif any of the  options  [1m-V[22m,  [1m-v[22m,  [1m--version[22m,  or
       [1m--help [22mwere specified, and with the status of [4mgroff[24m otherwise.

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

       [4mGROFF_BIN_PATH[0m
              is a colon‐separated list of directories in which to search  for
              the  [4mgroff[24m  executable  before  searching  in  [4mPATH[24m.   If unset,
              [4m/usr/pkg/bin[24m is used.

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

[1mFiles[0m
       [4m/usr/pkg/share/groff/1.23.0/tmac/tty-char.tmac[0m
              defines  fallback definitions of [4mroff[24m special characters.  These
              definitions more poorly  optically  approximate  typeset  output
              than those of [4mtty.tmac[24m in favor of communicating semantic infor‐
              mation.  [4mnroff[24m loads it automatically.

[1mNotes[0m
       Pager  programs  like  [4mmore[24m(1) and [4mless[24m(1) may require command‐line op‐
       tions to correctly handle some output sequences; see [4mgrotty[24m(1).

[1mSee also[0m
       [4mgroff[24m(1), [4mgtroff[24m(1), [4mgrotty[24m(1), [4mlocale[24m(1), [4mroff[24m(7)

groff 1.23.0                      2 July 2023                        [4mgnroff[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-Tpdf[22m] [[4mgroff‐options[24m] [[4mfile[24m ...]

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

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

[1mDescription[0m
       [4mpdfmom[24m is a wrapper around [4mgroff[24m(1) that facilitates the production  of
       PDF documents from files formatted with the [4mmom[24m macros.

       [4mpdfmom[24m  prints  to the standard output, so output must usually be redi‐
       rected to a destination file.  The size of the final PDF can be reduced
       by piping the output through [4mps2pdf[24m(1).

       If called  with  the  [1m-Tpdf  [22moption  (which  is  the  default),  [4mpdfmom[0m
       processes files using [4mgroff[24m’s native PDF driver, [4mgropdf[24m(1).  If [1m-Tps [22mis
       given,  processing  is passed over to [4mpdfroff[24m, which uses [4mgroff[24m’s Post‐
       Script 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
       options associated with [4mpdfroff[24m are  accepted  as  well.   When  [4mpdfmom[0m
       calls  [4mpdfroff[24m,  the  options “[1m-mpdfmark -mom --no-toc[22m” options are im‐
       plied 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
       information and exits.

[1mAuthors[0m
       [4mpdfmom[24m  was written by Deri James ⟨deri@chuzzlewit.myzen.co.uk⟩ and Pe‐
       ter Schaffter ⟨peter@schaffter.ca⟩, and is maintained by James.

[1mSee also[0m
       [4m/usr/pkg/share/doc/groff-1.23.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.

       [4mgroff[24m(1), [4mgropdf[24m(1), [4mpdfroff[24m(1), [4mps2pdf[24m(1)

groff 1.23.0                      2 July 2023                        [4mpdfmom[24m(1)
───────────────────────────────────────────────────────────────────────────────
[4mpdfroff[24m(1)                  General Commands Manual                 [4mpdfroff[24m(1)

[1mName[0m
       pdfroff - construct files in Portable Document Format using [4mgroff[0m

[1mSynopsis[0m
       [1mpdfroff [22m[[4mgroff‐option[24m] [[1m--emit-ps[22m] [[1m--no-toc-relocation[22m]
               [[1m--no-kill-null-pages[22m] [[1m--stylesheet=[4m[22mname[24m] [[1m--no-pdf-output[22m]
               [[1m--pdf-output=[4m[22mname[24m] [[1m--no-reference-dictionary[22m]
               [[1m--reference-dictionary=[4m[22mname[24m] [[1m--report-progress[22m]
               [[1m--keep-temporary-files[22m] [[4mfile[24m ...]

       [1mpdfroff -h[0m
       [1mpdfroff --help[0m

       [1mpdfroff -v [22m[[4mgroff‐option[24m ...]
       [1mpdfroff --version [22m[[4mgroff‐option[24m ...]

       [4mgroff‐option[24m  is  any short option supported by [4mgroff[24m(1) except for [1m-h[22m,
       [1m-T[22m, and [1m-v[22m; see section “Usage” below.

[1mDescription[0m
       [4mpdfroff[24m is a wrapper program for the GNU text processing system, [4mgroff[24m.
       It transparently handles the mechanics of multiple pass [4mgroff[24m  process‐
       ing,  when  applied to suitably marked up [4mgroff[24m source files, such that
       tables of contents and body text are formatted separately, and are sub‐
       sequently combined in the correct order, for  final  publication  as  a
       single  PDF  document.   A further optional “style sheet” capability is
       provided; this allows for the definition of content which  is  required
       to precede the table of contents, in the published document.

       For  each  invocation  of  [4mpdfroff[24m, the ultimate [4mgroff[24m output stream is
       post‐processed by the Ghostscript [4mgs[24m(1) interpreter to produce  a  fin‐
       ished PDF document.

       [4mpdfroff[24m makes no assumptions about, and imposes no restrictions on, the
       use of any [4mgroff[24m macro packages which the user may choose to employ, in
       order  to  achieve  a desired document format; however, it [4mdoes[24m include
       specific built in support for the [4mpdfmark[24m  macro  package,  should  the
       user  choose to employ it.  Specifically, if the [4mpdfhref[24m macro, defined
       in the [4mpdfmark.tmac[24m package, is used to define public reference  marks,
       or dynamic links to such reference marks, then [4mpdfroff[24m performs as many
       preformatting  [4mgroff[24m passes as required, up to a maximum limit of [4mfour[24m,
       in order to compile a document reference dictionary, to resolve  refer‐
       ences, and to expand the dynamically defined content of links.

[1mUsage[0m
       The  command  line is parsed in accordance with normal GNU conventions,
       but with one exception—when specifying any short form option  (i.e.,  a
       single character option introduced by a single hyphen), and if that op‐
       tion  expects  an  argument,  then  it  [4mmust[24m be specified independently
       (i.e., it may [4mnot[24m be appended to any group of  other  single  character
       short form options).

       Long  form option names (i.e., those introduced by a double hyphen) may
       be abbreviated to their minimum length unambiguous initial substring.

       Otherwise, [4mpdfroff[24m usage closely mirrors that of [4mgroff[24m itself.  Indeed,
       with the exception of the [1m-h[22m, [1m-v[22m, and [1m-T [4m[22mdev[24m short  form  options,  and
       all  long form options, which are parsed internally by [4mpdfroff[24m, all op‐
       tions and file name arguments specified on the command line are  passed
       on  to  [4mgroff[24m,  to  control the formatting of the PDF document.  Conse‐
       quently, [4mpdfroff[24m accepts all options and  arguments,  as  specified  in
       [4mgroff[24m(1),  which may also be considered as the definitive reference for
       all standard [4mpdfroff[24m options and argument usage.

[1mOptions[0m
       [4mpdfroff[24m accepts all of the short form options (i.e.,  those  introduced
       by  a  single  hyphen), which are available with [4mgroff[24m itself.  In most
       cases, these are simply passed transparently to [4mgroff[24m;  the  following,
       however, are handled specially by [4mpdfroff[24m.

       [1m-h     [22mSame as [1m--help[22m; see below.

       [1m-i     [22mProcess  standard  input, after all other specified input files.
              This is passed transparently to  [4mgroff[24m,  but,  if  grouped  with
              other  options,  it  [4mmust[24m  be the first in the group.  Hiding it
              within a group breaks standard input processing, in  the  multi‐
              ple‐pass [4mgroff[24m processing context of [4mpdfroff[24m.

       [1m-T [4m[22mdev[24m Only  [1m-T ps  [22mis supported by [4mpdfroff[24m.  Attempting to specify any
              other device causes [4mpdfroff[24m to abort.

       [1m-v     [22mSame as [1m--version[22m; see below.

       See [4mgroff[24m(1) for a description of all other short form  options,  which
       are transparently passed through [4mpdfroff[24m to [4mgroff[24m.

       All  long  form options (i.e., those introduced by a double hyphen) are
       interpreted locally by [4mpdfroff[24m; they are [4mnot[24m passed on to [4mgroff[24m, unless
       otherwise stated below.

       [1m--help [22mCauses [4mpdfroff[24m to display a summary of the its usage syntax, and
              supported options, and then exit.

       [1m--emit-ps[0m
              Suppresses the final output conversion step, causing [4mpdfroff[24m  to
              emit  PostScript  output  instead of PDF.  This may be useful to
              capture intermediate PostScript output when using a  specialised
              postprocessor, such as [4mgpresent[24m for example, in place of the de‐
              fault Ghostscript PDF writer.

       [1m--keep-temporary-files[0m
              Suppresses  the  deletion of temporary files, which normally oc‐
              curs after [4mpdfroff[24m has completed PDF document  formatting;  this
              may be useful when debugging formatting problems.

              See  section  “Files”  below  for a description of the temporary
              files used by [4mpdfroff[24m.

       [1m--no-pdf-output[0m
              May be used with  the  [1m--reference-dictionary=[4m[22mname[24m  option  (de‐
              scribed  below) to eliminate the overhead of PDF formatting when
              running [4mpdfroff[24m to create a reference dictionary for  use  in  a
              different document.

       [1m--no-reference-dictionary[0m
              May  be  used  to eliminate the overhead of creating a reference
              dictionary, when it is known that the target PDF  document  con‐
              tains no public references, created by the [1mpdfhref [22mmacro.

       [1m--no-toc-relocation[0m
              May  be used to eliminate the extra [4mgroff[24m processing pass, which
              is required to generate a table of contents, and relocate it  to
              the  start  of  the  PDF  document, when processing any document
              which lacks an automatically generated table of contents.

       [1m--no-kill-null-pages[0m
              While preparing for simulation of  the  manual  collation  step,
              which  is traditionally required to relocate a [4mtable[24m [4mof[24m [4mcontents[0m
              to the start of a document,  [4mpdfroff[24m  accumulates  a  number  of
              empty  page descriptions into the intermediate PostScript output
              stream.  During the final collation step, these empty pages  are
              normally  discarded  from  the  finished  document;  this option
              forces [4mpdfroff[24m to leave them in place.

       [1m--pdf-output=[4m[22mname[0m
              Specifies the name to be used for the resultant PDF document; if
              unspecified, the PDF output is written to  standard  output.   A
              future  version  of  [4mpdfroff[24m  may use this option, to encode the
              document name in a generated reference dictionary.

       [1m--reference-dictionary=[4m[22mname[0m
              Specifies the name to be used for the generated  reference  dic‐
              tionary  file;  if unspecified, the reference dictionary is cre‐
              ated in a temporary file, which is  deleted  when  [4mpdfroff[24m  com‐
              pletes  processing of the current document.  This option [4mmust[24m be
              specified, if it is desired to save  the  reference  dictionary,
              for use in references placed in other PDF documents.

       [1m--report-progress[0m
              Causes  [4mpdfroff[24m  to display an informational message on standard
              error, at the start of each [4mgroff[24m processing pass.

       [1m--stylesheet=[4m[22mname[0m
              Specifies the name of an [4minput[24m [4mfile[24m, to be used as a style sheet
              for formatting of content, which is to be placed [4mbefore[24m the  ta‐
              ble of contents, in the formatted PDF document.

       [1m--version[0m
              Causes [4mpdfroff[24m to display a version identification message.  The
              entire  command line is then passed transparently to [4mgroff[24m, in a
              [4mone[24m pass operation [4monly[24m, in  order  to  display  the  associated
              [4mgroff[24m version information, before exiting.

[1mEnvironment[0m
       The following environment variables may be set, and exported, to modify
       the behaviour of [4mpdfroff[24m.

       [4mPDFROFF_COLLATE[0m
              Specifies  the  program to be used for collation of the finished
              PDF document.

              This collation step may be required to move [4mtables[24m  [4mof[24m  [4mcontents[0m
              to  the start of the finished PDF document, when formatting with
              traditional macro packages, which print them at the  end.   How‐
              ever, users should not normally need to specify [4mPDFROFF_COLLATE[24m,
              (and  indeed,  are  not  encouraged  to do so).  If unspecified,
              [4mpdfroff[24m uses [4msed[24m(1) by default, which normally suffices.

              If [4mPDFROFF_COLLATE[24m [4mis[24m specified, then it must act as  a  filter,
              accepting a list of file name arguments, and write its output to
              the   standard   output  stream,  whence  it  is  piped  to  the
              [4mPDFROFF_POSTPROCESSOR_COMMAND[24m, to produce the finished PDF  out‐
              put.

              When  specifying  [4mPDFROFF_COLLATE[24m,  it  is normally necessary to
              also specify [4mPDFROFF_KILL_NULL_PAGES[24m.

              [4mPDFROFF_COLLATE[24m is ignored,  if  [4mpdfroff[24m  is  invoked  with  the
              [1m--no-kill-null-pages [22moption.

       [4mPDFROFF_KILL_NULL_PAGES[0m
              Specifies options to be passed to the [4mPDFROFF_COLLATE[24m program.

              It    should    not    normally    be   necessary   to   specify
              [4mPDFROFF_KILL_NULL_PAGES[24m.   The  internal  default  is  a  [4msed[24m(1)
              script,  which is intended to remove completely blank pages from
              the collated output stream, and which should be  appropriate  in
              most  applications  of  [4mpdfroff[24m.  However, if any alternative to
              [4msed[24m(1) is specified for [4mPDFROFF_COLLATE[24m, then it is likely  that
              a      corresponding      alternative      specification     for
              [4mPDFROFF_KILL_NULL_PAGES[24m is required.

              As in the case of  [4mPDFROFF_COLLATE[24m,  [4mPDFROFF_KILL_NULL_PAGES[24m  is
              ignored, if [4mpdfroff[24m is invoked with the [1m--no-kill-null-pages [22mop‐
              tion.

       [4mPDFROFF_POSTPROCESSOR_COMMAND[0m
              Specifies  the command to be used for the final document conver‐
              sion from PostScript intermediate output to PDF.  It must behave
              as a filter, writing its output to the standard  output  stream,
              and must accept an arbitrary number of [4mfiles[24m [4m...[24m arguments, with
              the special case of “[1m-[22m” representing the standard input stream.

              If unspecified, [4mPDFROFF_POSTPROCESSOR_COMMAND[24m defaults to
                   gs -dBATCH -dQUIET -dNOPAUSE -dSAFER -sDEVICE=pdfwrite \
                        -sOutputFile=-

       [4mGROFF_TMPDIR[0m
              Identifies  the  directory in which [4mpdfroff[24m should create tempo‐
              rary files.  If [4mGROFF_TMPDIR[24m is [4mnot[24m specified,  then  the  vari‐
              ables  [4mTMPDIR[24m,  [4mTMP[24m  and [4mTEMP[24m are considered in turn as possible
              temporary file repositories.  If none of  these  are  set,  then
              temporary files are created in the current directory.

       [4mGROFF_GHOSTSCRIPT_INTERPRETER[0m
              Specifies  the program to be invoked when [4mpdfroff[24m converts [4mgroff[0m
              PostScript output to PDF.  If  [4mPDFROFF_POSTPROCESSOR_COMMAND[24m  is
              specified,  then the command name it specifies is [4mimplicitly[24m as‐
              signed to [4mGROFF_GHOSTSCRIPT_INTERPRETER[24m, overriding any explicit
              setting     specified     in      the      environment.       If
              [4mGROFF_GHOSTSCRIPT_INTERPRETER[24m  is  not  specified,  then [4mpdfroff[0m
              searches the process [4mPATH[24m, looking for a program with any of the
              well known names for the Ghostscript interpreter; if  no  Ghost‐
              script interpreter can be found, [4mpdfroff[24m aborts.

       [4mGROFF_AWK_INTERPRETER[0m
              Specifies  the  program to be invoked when [4mpdfroff[24m is extracting
              reference dictionary entries from a [4mgroff[24m  intermediate  message
              stream.  If [4mGROFF_AWK_INTERPRETER[24m is not specified, then [4mpdfroff[0m
              searches the process [4mPATH[24m, looking for any of the preferred pro‐
              grams,  [4mgawk[24m,  [4mmawk[24m,  [4mnawk[24m,  and  [4mawk[24m, in that order; if none of
              these are found, [4mpdfroff[24m issues a warning message, and  continue
              processing;  however,  in  this case, no reference dictionary is
              created.

       [4mOSTYPE[24m Typically defined automatically by the operating system,  [4mOSTYPE[0m
              is  used  on Microsoft Win32/MS‐DOS platforms [4monly[24m, to infer the
              default [4mPATH_SEPARATOR[24m character, which is used when parsing the
              process [4mPATH[24m to search for external helper programs.

       [4mPATH_SEPARATOR[0m
              If set, [4mPATH_SEPARATOR[24m overrides the default  separator  charac‐
              ter,  (‘:’  on  POSIX/Unix  systems, inferred from [4mOSTYPE[24m on Mi‐
              crosoft Win32/MS‐DOS), which is used when  parsing  the  process
              [4mPATH[24m to search for external helper programs.

       [4mSHOW_PROGRESS[0m
              If this is set to a non‐empty value, then [4mpdfroff[24m always behaves
              as  if  the [1m--report-progress [22moption is specified on the command
              line.

[1mFiles[0m
       Input and output files for [4mpdfroff[24m may be named according to  any  con‐
       vention  of the user’s choice.  Typically, input files may be named ac‐
       cording to the choice of the principal normatting macro package,  e.g.,
       file[4m.ms[24m  might  be  an  input  file  for formatting using the [4mms[24m macros
       ([4ms.tmac[24m); normally, the final output file should be named file[4m.pdf[24m.

       Temporary files created by [4mpdfroff[24m are placed in the file system  hier‐
       archy,  in  or  below  the directory specified by environment variables
       (see section “Environment” above).  If [4mmktemp[24m(1) is  available,  it  is
       invoked  to  create  a  private subdirectory of the nominated temporary
       files directory, (with subdirectory  name  derived  from  the  template
       [4mpdfroff-XXXXXXXXXX[24m);  if this subdirectory is successfully created, the
       temporary files will be placed within it, otherwise they will be placed
       directly in the directory nominated in the environment.

       All temporary files themselves are named according  to  the  convention
       [4mpdf[24m$$[4m.[24m*,  where  [4m$$[24m  is  the  standard  shell variable representing the
       process identifier of the [4mpdfroff[24m process itself, and [4m*[24m represents  any
       of  the  extensions used by [4mpdfroff[24m to identify the following temporary
       and intermediate files.

       [4mpdf[24m$$[4m.tmp[0m
              A scratch pad file, used to capture reference  data  emitted  by
              [4mgroff[24m, during the [4mreference[24m [4mdictionary[24m compilation phase.

       [4mpdf[24m$$[4m.ref[0m
              The  [4mreference[24m  [4mdictionary[24m, as compiled in the last but one pass
              of the [4mreference[24m [4mdictionary[24m compilation phase; (at the start  of
              the  first  pass,  this  file  is  created  empty; in successive
              passes, it contains the [4mreference[24m [4mdictionary[24m  entries,  as  col‐
              lected in the preceding pass).

              If the [1m--reference-dictionary[22m=[4mname[24m option is specified, this in‐
              termediate  file  becomes  permanent,  and is named [4mname[24m, rather
              than [4mpdf[24m$$[4m.ref[24m.

       [4mpdf[24m$$[4m.cmp[0m
              Used to collect [4mreference[24m [4mdictionary[24m entries during  the  active
              pass  of the [4mreference[24m [4mdictionary[24m compilation phase.  At the end
              of any pass, when the content of [4mpdf[24m$$[4m.cmp[24m compares as identical
              to  [4mpdf[24m$$[4m.ref[24m,  (or  the  corresponding  file   named   by   the
              [1m--reference-dictionary[22m=[4mname[24m  option),  then [4mreference[24m [4mdictionary[0m
              compilation is terminated, and the [4mdocument[24m [4mreference[24m [4mmap[24m is ap‐
              pended to this intermediate file, for  inclusion  in  the  final
              formatting passes.

       [4mpdf[24m$$[4m.tc[0m
              An  intermediate  [4mPostScript[24m  file, in which “Table of Contents”
              entries are collected, to facilitate relocation before the  body
              text, on ultimate output to the [4mGhostscript[24m postprocessor.

       [4mpdf[24m$$[4m.ps[0m
              An  intermediate [4mPostScript[24m file, in which the body text is col‐
              lected prior to ultimate output to the  [4mGhostscript[24m  postproces‐
              sor, in the proper sequence, [4mafter[24m [4mpdf[24m$$[4m.tc[24m.

[1mAuthors[0m
       [4mpdfroff[24m  was written by Keith Marshall ⟨keith.d.marshall@ntlworld.com⟩,
       who maintains it at  his  [4mgroff‐pdfmark[24m  OSDN  site  ⟨https://osdn.net/
       users/keith/pf/groff‐pdfmark/wiki/FrontPage⟩.   [4mgroff[24m’s  version may be
       withdrawn in a future release.

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

       Since [4mpdfroff[24m provides a superset of all [4mgroff[24m capabilities, the  above
       manual,  or  its terser reference page, [4mgroff[24m(7) may also be considered
       definitive references to all [4mstandard[24m  capabilities  of  [4mpdfroff[24m,  with
       this document providing the reference to [4mpdfroff[24m’s extended features.

       While  [4mpdfroff[24m  imposes neither any restriction on, nor any requirement
       for, the use of any specific [4mgroff[24m macro package, a number of  supplied
       macro  packages,  and  in  particular those associated with the package
       [4mpdfmark.tmac[24m, are best suited for use with  [4mpdfroff[24m  as  the  preferred
       formatter.

       [4m/usr/pkg/share/doc/groff-1.23.0/pdf/pdfmark.pdf[0m
              “Portable  Document  Format Publishing with GNU [4mTroff[24m”, by Keith
              Marshall, offers detailed documentation  on  the  use  of  these
              packages.   This  file, together with its source, [4mpdfmark.ms[24m, is
              part of the [4mgroff[24m distribution.

groff 1.23.0                      2 July 2023                       [4mpdfroff[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 supplied 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 [4mafmtodit[24m(1).

       The [1m--help [22moption displays a usage message, while [1m-v [22mand [1m--version [22mshow
       version information; all exit afterward.

[1mSee also[0m
       [4mgrops[24m(1), [4mgropdf[24m(1)

groff 1.23.0                      2 July 2023                       [4mpfbtops[24m(1)
───────────────────────────────────────────────────────────────────────────────
[4mgpic[24m(1)                     General Commands Manual                    [4mgpic[24m(1)

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

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

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

       [1mgpic --help[0m

       [1mgpic -v[0m
       [1mgpic --version[0m

[1mDescription[0m
       The GNU implementation of [4mpic[24m is part of the [4mgroff[24m(1) document  format‐
       ting system.  [4mgpic[24m is a [4mgtroff[24m(1) preprocessor that translates descrip‐
       tions  of  diagrammatic pictures embedded in [4mroff[24m(7) or TeX input files
       into the language understood by TeX or [4mgtroff[24m.  It copies the  contents
       of  each  [4mfile[24m to the standard output stream, except that lines between
       [1m.PS [22mand any of [1m.PE[22m, [1m.PF[22m, or [1m.PY [22mare interpreted as picture descriptions
       in the [4mpic[24m language.  End a [4mgpic[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, [4mgpic[24m is not executed directly by the  user,  but
       invoked  by  specifying the [1m-p [22moption to [4mgroff[24m(1).  If no [4mfile[24m operands
       are given on the command line, or if [4mfile[24m is “[1m-[22m”,  the  standard  input
       stream is read.

       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[0m
       option [1m-mpic[22m; these will center each picture.

       GNU [4mpic[24m supports [1mPY [22mas a synonym of [1mPF [22mto work around a name space col‐
       lision  with  the  [4mmm[24m  macro package, which defines [1mPF [22mas a page footer
       management macro.  Use [1mPF [22mpreferentially unless a similar problem faces
       your document.

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

       [1m-c     [22mBe  more compatible with [4mtpic[24m; implies [1m-t[22m.  Lines beginning with
              [1m\ [22mare not passed through transparently.  Lines beginning with  [1m.[0m
              are  passed through with the initial [1m. [22mchanged to [1m\[22m.  A line be‐
              ginning with [1m.ps [22mis given special treatment:  it  takes  an  op‐
              tional integer argument specifying the line thickness (pen size)
              in  milliinches;  a  missing argument restores the previous line
              thickness; the default line thickness  is  8  milliinches.   The
              line thickness thus specified takes effect only when a non‐nega‐
              tive  line  thickness  has  not  been  specified  by  use of the
              [1mthickness [22mattribute or by setting the [1mlinethick [22mvariable.

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

       [1m-n     [22mDon’t use [4mgroff[24m extensions to the [4mtroff[24m drawing commands.  Spec‐
              ify this option if a postprocessor you’re using doesn’t  support
              these  extensions,  described in [4mgroff_out[24m(5).  This option also
              causes [4mgpic[24m not to use zero‐length lines to draw dots  in  [4mtroff[0m
              mode.

       [1m-S     [22mOperate  in [4msafer[24m [4mmode;[24m [1msh [22mcommands are ignored.  This mode, en‐
              abled by default, can be useful when operating on  untrustworthy
              input.

       [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  is  unnecessary
              because the [4mtroff[24m output generated by GNU [4mpic[24m is device‐indepen‐
              dent.

[1mUsage[0m
       This  section  primarily  discusses the differences between GNU [4mpic[24m and
       the Eighth Edition Research 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 to‐
       day for lending its name to a group of [1m\special  [22mcommands  it  produced
       for TeX.)

       Lines  beginning  with [1m\ [22mare passed through transparently; a [1m% [22mis added
       to the end of the line to avoid unwanted spaces.  You  can  safely  use
       this  feature  to change fonts or the value of [1m\baselineskip[22m.  Anything
       else may well produce undesirable results; use at your  own  risk.   By
       default,  lines  beginning with a dot are not treated specially—but see
       the [1m-c [22moption.

       In TeX mode, [4mgpic[24m will define 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 will produce 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 follow‐
       ing 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  syn‐
       opses  as braces [1m{ }[22m.  Nesting of braces is supported.  Any other char‐
       acters (except a space, tab, or newline) may be used as alternative de‐
       limiters, in which case the members of a given pair must be  identical.
       Strings  are recognized within delimiters of either kind; they may con‐
       tain 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.  If [4mexpr3[24m is prefixed
              by [1m* [22mthen [4mvariable[24m will instead be  multiplied  by  [4mexpr3[24m.   The
              value  of  [4mexpr3[24m can be negative for the additive case; [4mvariable[0m
              is then tested whether it is greater than  or  equal  to  [4mexpr2[24m.
              For  the  multiplicative  case, [4mexpr3[24m must be greater than zero.
              If the constraints aren’t met, the loop isn’t executed.   [4mX[24m  can
              be any character not occurring 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‐false[24m.  [4mX[24m can be any character not occurring in  [4mif‐true[24m.   [4mY[0m
              can be any character not occurring in [4mif‐false[24m.

       [1mprint [4m[22marg[24m ...
              Concatenate  and  write  arguments  to the standard error stream
              followed by a newline.  Each [4marg[24m must be an expression, a  posi‐
              tion, or text.  This is useful for debugging.

       [1mcommand [4m[22marg[24m ...
              Concatenate  arguments  and pass them as a line to [4mtroff[24m or TeX.
              Each [4marg[24m must be an expression, a position,  or  text.   [1mcommand[0m
              allows  the  values of [4mpic[24m variables to be passed to the format‐
              ter.  For example,
                     .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.

       [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[0m
              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, lines
              will  be read only until a line the first word of which is [4mword[24m;
              that line will then be discarded.  [4mX[24m can be  any  character  not
              occurring 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 char‐
              acter is interpreted 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  vari‐
              ables  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 values times the new value of [1mscale[22m.

       [1mplot [4m[22mexpr[24m [[1m"[4m[22mtext[24m[1m"[22m]
              This is a text object which is constructed by using  [4mtext[24m  as  a
              format  string for sprintf with an argument of [4mexpr[24m.  If [4mtext[24m is
              omitted a format string of [1m"%g"  [22mis  used.   Attributes  can  be
              specified  in the same way as for a normal text object.  Be very
              careful that you specify an appropriate format string; [4mgpic[24m does
              only very limited checking of the string.  This is deprecated in
              favour of [1msprintf[22m.

       [4mvar[24m [1m:= [4m[22mexpr[0m
              This syntax resembles variable assignment with [1m= [22mexcept that [4mvar[0m
              must already be defined, and [4mexpr[24m will be assigned to [4mvar[24m  with‐
              out  creating  a  variable local to the current block.  (By con‐
              trast, [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  equiva‐
       lent to [4mdir[24m [4mexpr[24m, where [4mdir[24m is the current direction.  For example

              [1mline 2i[0m

       means  draw a line 2 inches long in the current direction.  The ‘i’ (or
       ‘I’) character is ignored; to use another  measurement  unit,  set  the
       [4mscale[24m variable to an appropriate value.

       The  maximum  width  and height of the picture are taken from the vari‐
       ables [1mmaxpswid [22mand [1mmaxpsht[22m.  Initially, these have values 8.5 and 11.

       Scientific notation is allowed for numbers.  For example

              [1mx = 5e-2[0m

       Text attributes can be compounded.  For example,

              [1m"foo" above ljust[0m

       is valid.

       There is no limit to the depth to which blocks can  be  examined.   For
       example,

              [A: [B: [C: box ]]] with .A.B.C.sw at 1,2
              circle at last [].A.B.C

       is acceptable.

       Arcs  now 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 also.

       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.  This effectively changes the shape of  a
       box  from  a rectangle to an arbitrary parallelogram.  The [1mxslanted [22mand
       [1myslanted [22mattributes specify the x and y offset of the box’s upper right
       corner from its default position.

       The [1m.PS [22mline can have a second argument specifying a maximum height for
       the picture.  If the width of zero is specified the width will  be  ig‐
       nored  in  computing  the scaling factor for the picture.  GNU [4mpic[24m will
       always scale a picture by the same amount vertically as well  as  hori‐
       zontally.  This is different from DWB 2.0 [4mpic[24m which may scale a picture
       by a different amount vertically than horizontally if a height is spec‐
       ified.

       Each  text object has an invisible box associated with it.  The compass
       points of a text object are determined by this box.  The  implicit  mo‐
       tion  associated  with  the object is also determined by this box.  The
       dimensions of this box are taken from the width and height  attributes;
       if  the width attribute is not supplied then the width will be taken to
       be [1mtextwid[22m; if the height attribute is not  supplied  then  the  height
       will  be taken to be the number of text strings associated with the ob‐
       ject times [1mtextht[22m.  Initially, [1mtextwid [22mand [1mtextht [22mhave a value of 0.

       In (almost all) places where a quoted text string can be used,  an  ex‐
       pression of the form

              [1msprintf("[4m[22mformat[24m[1m", [4m[22marg[24m[1m, [22m...[1m)[0m

       can  also  be used; this will produce the arguments formatted according
       to [4mformat[24m, which should be a string as described in [4mprintf[24m(3) appropri‐
       ate for the number of arguments supplied.  Only the modifiers “[1m#[22m”, “[1m-[22m”,
       “[1m+[22m”, and “ ” [space]), a minimum field width,  an  optional  precision,
       and the conversion specifiers [1m%e[22m, [1m%E[22m, [1m%f[22m, [1m%g[22m, [1m%G[22m, and [1m%% [22mare supported.

       The  thickness  of  the lines used to draw objects is controlled by the
       [1mlinethick [22mvariable.  This gives the thickness of lines  in  points.   A
       negative  value  means  use  the default thickness: in TeX output mode,
       this means use a thickness of 8 milliinches; in TeX  output  mode  with
       the  [1m-c  [22moption,  this  means  use  the line thickness specified by [1m.ps[0m
       lines; in [4mtroff[24m output mode, this means use a thickness proportional to
       the pointsize.  A zero value means draw the thinnest possible line sup‐
       ported by the output device.  Initially, it has a value of  -1.   There
       is also a [1mthick[22m[[1mness[22m] attribute.  For example,

              [1mcircle thickness 1.5[0m

       would  draw  a circle using a line with a 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].
       This takes an optional argument of an expression with a value between 0
       and  1; 0 will fill it with white, 1 with black, values in between with
       a proportionally gray shade.  A value greater than 1 can also be  used:
       this means fill with the shade of gray that is currently being used for
       text  and  lines.   Normally this will be black, but output devices may
       provide a mechanism for changing this.  Without an argument,  then  the
       value  of  the  variable  [1mfillval  [22mwill be used.  Initially, this has a
       value of 0.5.  The invisible attribute does not affect the  filling  of
       objects.   Any text associated with a filled object will be added after
       the object has been filled, so that the text will not  be  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[24m  declare  color  names; you can define additional ones with the
       [1mdefcolor [22mrequest (see [4mgroff[24m(7)).

       To change the name of the vbox in TeX  mode,  set  the  pseudo‐variable
       [1mfigname  [22m(which  is  actually a specially parsed command) within a pic‐
       ture.  Example:

              [1m.PS[0m
              [1mfigname = foobar;[0m
              [1m...[0m
              [1m.PE[0m

       The picture is then available in the box [1m\foobar[22m.

       [4mgpic[24m assumes that at the beginning of a picture  both  glyph  and  fill
       color are set to the default value.

       Arrow  heads will be drawn as solid triangles if the variable [1marrowhead[0m
       is non‐zero and either TeX mode is enabled or the  [1m-n  [22moption  has  not
       been  given.  Initially, [1marrowhead [22mhas a value of 1.  Solid arrow heads
       are always filled with the current outline color.

       The [4mtroff[24m output of [4mgpic[24m  is  device‐independent.   The  [1m-T  [22moption  is
       therefore  redundant.   All  numbers are taken to be in inches; numbers
       are never interpreted to be in [4mtroff[24m machine units.

       Objects can have an [1maligned [22mattribute.  This  will  only  work  if  the
       postprocessor  is  [4mgrops[24m(1)  or [4mgropdf[24m(1).  Any text associated with an
       object having the [1maligned [22mattribute will be rotated about the center of
       the object so that it is aligned in the direction from the start  point
       to  the end point of the object.  This attribute will have 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
       single  token: no space is allowed between the apostrophe and the “[1mth[22m”.
       For example,

              for i = 1 to 4 do {
                 line from 'i'th box.nw to 'i+1'th box.se
              }

[1mConversion[0m
       To obtain a stand‐alone picture from a [4mgpic[24m file, enclose your [4mpic[24m code
       with [1m.PS [22mand [1m.PE [22mrequests; [4mroff[24m configuration commands may be added  at
       the beginning of the file, but no [4mroff[24m text.

       It  is  necessary  to feed this file into [4mgroff[24m without adding any page
       information, so you must check which [1m.PS [22mand [1m.PE [22mrequests are  actually
       called.  For example, the [4mmm[24m macro package adds a page number, which is
       very annoying.  At the moment, calling standard [4mgroff[24m without any macro
       package  works.  Alternatively, you can define your own requests, e.g.,
       to do nothing:

              .de PS
              ..
              .de PE
              ..

       [4mgroff[24m itself does not provide direct  conversion  into  other  graphics
       file  formats.  But there are lots of possibilities if you first trans‐
       form your picture into PostScript® format using the [4mgroff[24m option  [1m-Tps[22m.
       Since  this [4mps[24m‐file lacks BoundingBox information it is not very useful
       by itself, but it may be fed into other  conversion  programs,  usually
       named  [1mps2[4m[22mother[24m or [1mpsto[4m[22mother[24m or the like.  Moreover, the PostScript in‐
       terpreter Ghostscript ([4mgs[24m(1)) has built‐in graphics conversion  devices
       that are called with the option

              [1mgs -sDEVICE=[4m[22m<devname>[0m

       Call

              [1mgs --help[0m

       for a list of the available devices.

       An  alternative  may be to use the [1m-Tpdf [22moption to convert your picture
       directly into [1mPDF [22mformat.  The MediaBox of the  file  produced  can  be
       controlled by passing a [1m-P-p [22mpapersize to [4mgroff[24m.

       As the Encapsulated PostScript File Format [1mEPS [22mis getting more and more
       important,  and  the conversion wasn’t regarded trivial in the past you
       might be interested to know that  there  is  a  conversion  tool  named
       [4mps2eps[24m  which  does  the  right  job.   It is much better than the tool
       [4mps2epsi[24m packaged with [4mgs[24m.

       For bitmapped graphic formats, you should use  [4mpstopnm[24m;  the  resulting
       (intermediate)  [4mpnm[24m(5)  file  can  be  then  converted to virtually any
       graphics format using the tools of the [1mnetpbm [22mpackage.

[1mFiles[0m
       [4m/usr/pkg/share/groff/1.23.0/tmac/pic.tmac[0m
              offers simple definitions of the [1mPS[22m, [1mPE[22m, [1mPF[22m, and [1mPY [22mmacros.

[1mBugs[0m
       Characters that are invalid as input to GNU [4mtroff[24m (see the  [4mgroff[24m  Tex‐
       info manual or [4mgroff_char[24m(7) for a list) are rejected even in TeX mode.

       The  interpretation  of  [1mfillval  [22mis incompatible with the [4mpic[24m in Tenth
       Edition Research Unix, which interprets 0 as black and 1 as white.

[1mSee also[0m
       [4m/usr/pkg/share/doc/groff-1.23.0/pic.ps[0m
              “Making Pictures with GNU pic”, by Eric S. Raymond.  This  file,
              together with its source, [4mpic.ms[24m, is part of the [4mgroff[24m distribu‐
              tion.

       “PIC—A  Graphics  Language  for  Typesetting: User Manual”, by Brian W.
       Kernighan, 1984 (revised 1991), AT&T Bell Laboratories  Computing  Sci‐
       ence Technical Report No. 116

       [4mps2eps[24m  is  available  from  CTAN  mirrors,  e.g., ⟨ftp://ftp.dante.de/
       tex-archive/support/ps2eps/⟩

       W. Richard Stevens, [4mTurning[24m [4mPIC[24m [4minto[24m [4mHTML[24m ⟨http://www.kohala.com/start/
       troff/pic2html.html⟩

       W. Richard Stevens,  [4mExamples[24m  [4mof[24m  pic  [4mMacros[24m  ⟨http://www.kohala.com/
       start/troff/pic.examples.ps⟩

       [4mgtroff[24m(1),   [4mgroff_out[24m(5),   [4mtex[24m(1),   [4mgs[24m(1),   [4mps2eps[24m(1),  [4mpstopnm[24m(1),
       [4mps2epsi[24m(1), [4mpnm[24m(5)

groff 1.23.0                      2 July 2023                          [4mgpic[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 [4mgpic[24m(1) program from the standard input and writes an
       image file, by default in Portable Network Graphics  (PNG)  format,  to
       the  standard output.  It furthermore translates [4mgeqn[24m(1) constructs, so
       it can be used for generating images of mathematical formulae.

       The input PIC code should [4mnot[24m be  wrapped  with  the  [1m.PS  [22mand  [1m.PE[22m/[1m.PF[0m
       macros that normally guard it within [4mgroff[24m(1) documents.

       Arguments  not recognized by [4mpic2graph[24m are passed to the ImageMagick or
       GraphicsMagick program [4mconvert[24m(1).  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  small‐
       est 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
       information; all exit afterward.

       [1m-eqn [4m[22mdelimiters[0m
              Use [4mdelimiters[24m as the opening and closing  characters  that  de‐
              limit [4mgeqn[24m directives; the default is “$$”.  The option argument
              [4mdelimiters[24m should be a two‐character string, but an empty string
              ("") is accepted as a directive to disable [4mgeqn[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
              arbitrary 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 given order to
              determine the directory where temporary files will  be  created.
              If none are set, [4m/tmp[24m is used.

[1mAuthors[0m
       [4mpic2graph[24m  was written by Eric S. Raymond ⟨esr@thyrsus.com⟩, based on a
       recipe by W. Richard Stevens.

[1mSee also[0m
       W. Richard Stevens, [4mTurning[24m [4mPIC[24m [4minto[24m [4mHTML[24m ⟨http://www.kohala.com/start/
       troff/pic2html.html⟩

       [4meqn2graph[24m(1), [4mgrap2graph[24m(1), [4mgpic[24m(1), [4mgeqn[24m(1), [4mgroff[24m(1), [4mconvert[24m(1)

groff 1.23.0                      2 July 2023                     [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
       [4mgtroff[24m(1)  can  interpret,  and sends the result to the standard output
       stream.  Currently, this means that code points in the range 0–127  (in
       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
       beginning  of  each  [4mfile[24m, identifying it for the benefit of later pro‐
       cessing (including 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[0m
       operands are given on the command line, or if [4mfile[24m is “[1m-[22m”, the standard
       input stream is read.

       [4mpreconv[24m  tries to find the 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,  determine  the
           encoding as UTF‐8, UTF‐16, or UTF‐32 accordingly.

       3.  If  the  input stream is seekable, check the first and second input
           lines for a recognized GNU Emacs  file‐local  variable  identifying
           the  character  encoding,  here referred to as the “coding tag” for
           brevity.  If found, use it.

       4.  If the input stream is seekable, and if  the  [4muchardet[24m  library  is
           available 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 Latin‐1
           (ISO 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 files 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  locale  appropriately.   [4mgroff[24m  also  supports  a
       [4mGROFF_ENCODING[24m  environment variable, which can be overridden by its [1m-K[0m
       option.  Valid values for (or parameters to) all of these  are  enumer‐
       ated 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 are reliable 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 regions 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 file.  Both “\"” and “\#” com‐
       ment forms are recognized, but the control (or no‐break control)  char‐
       acter  must be the default and must begin the line.  Similarly, the es‐
       cape 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

       Trailing “-dos”, “-unix”, and “-mac” suffixes on coding tags (which in‐
       dicate the end‐of‐line convention used in the file) are disregarded for
       the purpose of comparison with the above tags.

   [4m[1miconv[24m support[0m
       While [4mpreconv[24m recognizes all of the coding tags listed above, it is ca‐
       pable  on  its  own of interpreting only three encodings: Latin‐1, code
       page 1047, and UTF‐8.  If [4miconv[24m support is configured at  compile  time
       and available at run time, all others are passed to [4miconv[24m library func‐
       tions,  which may recognize many additional encoding strings.  The com‐
       mand “[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 fol‐
       lowing  examples using the input “café” (note the “e” with an acute ac‐
       cent), which due to its short length challenges inference of the encod‐
       ing 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[24m 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 repre‐
       sentable character in the declared 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.
       Examples include files that are interpolated by preprocessors that  run
       subsequently,  including  [4mgsoelim[24m(1);  files  included by [4mgtroff[24m itself
       through “[1mso[22m” and similar requests; and  string  definitions  passed  to
       [4mgtroff[24m through its [1m-d [22mcommand‐line option.

       [4mpreconv[24m  assumes  that  its  input uses the default escape character, a
       backslash [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 ver‐
       sion information; all exit afterward.

       [1m-d     [22mEmit debugging messages to the standard error stream.

       [1m-D [4m[22mfallback‐encoding[0m
              Report [4mfallback‐encoding[24m if all detection methods fail.

       [1m-e [4m[22mencoding[0m
              Skip detection and assume [4mencoding[24m; see [4mgroff[24m’s [1m-K [22moption.

       [1m-r     [22mWrite files “raw”; do not add [1m.lf [22mrequests.

[1mSee also[0m
       [4mgroff[24m(1), [4miconv[24m(3), [4mlocale[24m(7)

groff 1.23.0                      2 July 2023                       [4mpreconv[24m(1)
───────────────────────────────────────────────────────────────────────────────
[4mgrefer[24m(1)                   General Commands Manual                  [4mgrefer[24m(1)

[1mName[0m
       grefer - process bibliographic references for [4mgroff[0m

[1mSynopsis[0m
       [1mgrefer [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 ...]

       [1mgrefer --help[0m

       [1mgrefer -v[0m
       [1mgrefer --version[0m

[1mDescription[0m
       The GNU implementation of [4mrefer[24m is part of the [4mgroff[24m(1)  document  for‐
       matting  system.   [4mgrefer[24m  is  a  [4mgtroff[24m(1)  preprocessor that prepares
       bibilographic citations by looking up keywords specified in  a  [4mroff[24m(7)
       input  document,  obviating the need to type such annotations, and per‐
       mitting the citation style in formatted output to be  altered  indepen‐
       dently  and systematically.  It copies the contents of each [4mfile[24m to the
       standard output stream, except that it interprets lines between [1m.[  [22mand
       [1m.]  [22mas  citations  to be translated into [4mgroff[24m input, and lines between
       [1m.R1  [22mand  [1m.R2  [22mas  instructions  regarding  how  citations  are  to  be
       processed.   Normally, [4mgrefer[24m is not executed directly by the user, but
       invoked by specifying the [1m-R [22moption to [4mgroff[24m(1).  If no  [4mfile[24m  operands
       are  given  on  the command line, or if [4mfile[24m is “[1m-[22m”, the standard input
       stream is read.

       Each citation specifies a reference.  The citation can specify a refer‐
       ence that is contained in a bibliographic database by giving a  set  of
       keywords that only that reference contains.  Alternatively it can spec‐
       ify a reference by supplying a database record in the citation.  A com‐
       bination of these alternatives is also possible.

       For  each  citation,  [4mgrefer[24m can produce a mark in the text.  This mark
       consists of some label which can be separated from the  text  and  from
       other  labels  in  various  ways.   For  each reference it also outputs
       [4mgroff[24m(7) language commands that can be used by a macro package to  pro‐
       duce  a  formatted  reference  for each citation.  The output of [4mgrefer[0m
       must therefore be processed using a suitable macro package, such as [4mme[24m,
       [4mmm[24m, [4mmom[24m, or [4mms[24m.  The commands to format a citation’s reference  can  be
       output immediately after the citation, or the references may be accumu‐
       lated,  and the commands output at some later point.  If the references
       are accumulated, then multiple citations of  the  same  reference  will
       produce a single formatted reference.

       The  interpretation  of lines between [1m.R1 [22mand [1m.R2 [22mas prepreocessor com‐
       mands is a feature of GNU [4mrefer[24m.  Documents making use of this  feature
       can still be processed by AT&T [4mrefer[24m just by adding the lines
              .de R1
              .ig R2
              ..
       to  the beginning of the document.  This will cause [4mgtroff[24m(1) to ignore
       everything between [1m.R1 [22mand [1m.R2[22m.  The effect of some commands  can  also
       be achieved by options.  These options are supported mainly for compat‐
       ibility  with  AT&T  [4mrefer[24m.   It is usually more convenient to use com‐
       mands.

       [4mgrefer[24m generates [1m.lf [22mrequests so that file names and  line  numbers  in
       messages  produced by commands that read [4mgrefer[24m output will be correct;
       it also interprets lines beginning with [1m.lf [22mso that file names and line
       numbers in the messages and [1m.lf [22mlines that it produces will be accurate
       even  if  the  input  has  been  preprocessed  by  a  command  such  as
       [4mgsoelim[24m(1).

   [1mBibliographic databases[0m
       The  bibliographic  database is a text file consisting of records sepa‐
       rated by one or more blank lines.  Within each record fields start with
       a [1m% [22mat the beginning of a line.  Each field has a  one  character  name
       that immediately follows the [1m%[22m.  It is best to use only upper and lower
       case  letters for the names of fields.  The name of the field should be
       followed by exactly one space, and then by the contents of  the  field.
       Empty fields are ignored.  The conventional meaning of each field is as
       follows:

       [1m%A     [22mThe  name  of  an author.  If the name contains a suffix such as
              “Jr.”, it should be separated from the last  name  by  a  comma.
              There can be multiple occurrences of the [1m%A [22mfield.  The order is
              significant.   It is a good idea always to supply an [1m%A [22mfield or
              a [1m%Q [22mfield.

       [1m%B     [22mFor an article that is part of a book, the title of the book.

       [1m%C     [22mThe place (city) of publication.

       [1m%D     [22mThe date of publication.  The year should be specified in  full.
              If  the  month  is specified, the name rather than the number of
              the month should be used, but only the first three  letters  are
              required.  It is a good idea always to supply a [1m%D [22mfield; if the
              date  is  unknown,  a  value  such as [1min press [22mor [1munknown [22mcan be
              used.

       [1m%E     [22mFor an article that is part of a book, the name of an editor  of
              the  book.  Where the work has editors and no authors, the names
              of the editors should be given as [1m%A [22mfields  and  “[1m,  (ed.)[22m”  or
              “[1m, (eds.)[22m” should be appended to the last author.

       [1m%G     [22mU.S. government ordering number.

       [1m%I     [22mThe publisher (issuer).

       [1m%J     [22mFor an article in a journal, the name of the journal.

       [1m%K     [22mKeywords to be used for searching.

       [1m%L     [22mLabel.

       [1m%N     [22mJournal issue number.

       [1m%O     [22mOther  information.   This  is usually printed at the end of the
              reference.

       [1m%P     [22mPage number.  A range of pages can be specified as [4mm[24m[1m-[4m[22mn[24m.

       [1m%Q     [22mThe name of the author, if the author is  not  a  person.   This
              will  only be used if there are no [1m%A [22mfields.  There can only be
              one [1m%Q [22mfield.

       [1m%R     [22mTechnical report number.

       [1m%S     [22mSeries name.

       [1m%T     [22mTitle.  For an article in a book or journal, this should be  the
              title of the article.

       [1m%V     [22mVolume number of the journal or book.

       [1m%X     [22mAnnotation.

       For  all  fields except [1m%A [22mand [1m%E[22m, if there is more than one occurrence
       of a particular field in a record, only the last  such  field  will  be
       used.

       If  accent strings are used, they should follow the character to be ac‐
       cented.  This means that an [4mms[24m document must call the [1m.AM [22mmacro when it
       initializes.  Accent strings should not be quoted:  use  one  [1m\  [22mrather
       than  two.   Accent strings are an obsolescent feature of the [4mme[24m and [4mms[0m
       macro packages; modern documents should use [4mgroff[24m special character es‐
       cape sequences instead; see [4mgroff_char[24m(7).

   [1mCitations[0m
       Citations have a characteristic format.
              [1m.[[4m[22mopening‐text[0m
              [4mflags[24m [4mkeywords[0m
              [4mfields[0m
              [1m.][4m[22mclosing‐text[0m

       The [4mopening‐text[24m, [4mclosing‐text[24m,  and  [4mflags[24m  components  are  optional.
       Only one of the [4mkeywords[24m and [4mfields[24m components need be specified.

       The [4mkeywords[24m component says to search the bibliographic databases for a
       reference  that  contains all the words in [4mkeywords[24m.  It is an error if
       more than one reference is found.

       The [4mfields[24m components specifies additional fields to replace or supple‐
       ment those specified in the reference.  When references are being accu‐
       mulated and the [4mkeywords[24m component is non‐empty, then additional fields
       should be specified only on the first occasion that a particular refer‐
       ence is cited, and will apply to all citations of that reference.

       The [4mopening‐text[24m and [4mclosing‐text[24m components specify strings to be used
       to bracket the label instead of those in the [1mbracket-label [22mcommand.  If
       either of these components is non‐empty, the strings specified  in  the
       [1mbracket-label  [22mcommand  will  not be used; this behavior can be altered
       using the [1m[ [22mand [1m] [22mflags.  Leading and trailing spaces  are  significant
       for these components.

       The  [4mflags[24m  component  is a list of non‐alphanumeric characters each of
       which modifies the treatment of this particular citation.   AT&T  [4mrefer[0m
       will  treat these flags as part of the keywords and so will ignore them
       since they are non‐alphanumeric.  The  following  flags  are  currently
       recognized.

       [1m#      [22mUse  the  label specified by the [1mshort-label [22mcommand, instead of
              that specified by the [1mlabel [22mcommand.  If no short label has been
              specified, the normal label will be used.  Typically  the  short
              label  is  used with author‐date labels and consists of only the
              date and possibly a disambiguating letter; the “[1m#[22m”  is  supposed
              to be suggestive of a numeric type of label.

       [1m[      [22mPrecede  [4mopening‐text[24m  with  the  first  string specified in the
              [1mbracket-label [22mcommand.

       [1m]      [22mFollow [4mclosing‐text[24m with the  second  string  specified  in  the
              [1mbracket-label [22mcommand.

       An  advantage  of  using  the  [1m[  [22mand [1m] [22mflags rather than including the
       brackets in [4mopening‐text[24m and [4mclosing‐text[24m is that you  can  change  the
       style   of   bracket   used  in  the  document  just  by  changing  the
       [1mbracket-label [22mcommand.  Another is that sorting and  merging  of  cita‐
       tions will not necessarily be inhibited if the flags are used.

       If  a label is to be inserted into the text, it will be attached to the
       line preceding the [1m.[ [22mline.  If there is no such line,  then  an  extra
       line will be inserted before the [1m.[ [22mline and a warning will be given.

       There  is  no special notation for making a citation to multiple refer‐
       ences.  Just use a sequence  of  citations,  one  for  each  reference.
       Don’t put anything between the citations.  The labels for all the cita‐
       tions  will  be attached to the line preceding the first citation.  The
       labels may also be sorted or merged.  See the description of the [1m<> [22mla‐
       bel    expression,    and    of    the     [1msort-adjacent-labels     [22mand
       [1mabbreviate-label-ranges  [22mcommands.   A  label will not be merged if its
       citation has a non‐empty [4mopening‐text[24m or  [4mclosing‐text[24m.   However,  the
       labels for a citation using the [1m] [22mflag and without any [4mclosing‐text[24m im‐
       mediately followed by a citation using the [1m[ [22mflag and without any [4mopen‐[0m
       [4ming‐text[24m  may  be  sorted  and  merged even though the first citation’s
       [4mopening‐text[24m or the second citation’s [4mclosing‐text[24m is  non‐empty.   (If
       you wish to prevent this, use the dummy character escape sequence [1m\& [22mas
       the first citation’s [4mclosing‐text[24m.)

   [1mCommands[0m
       Commands are contained between lines starting with [1m.R1 [22mand [1m.R2[22m.  Recog‐
       nition  of  these  lines can be prevented by the [1m-R [22moption.  When a [1m.R1[0m
       line is recognized any accumulated references are flushed out.  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)
       introduces  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) dou‐
       ble quote ([1m"[22m) extends to the next double quote that is not followed  by
       another  double  quote.  If there is no such double quote, the word ex‐
       tends to the end of the line.  Pairs of double quotes in a word  begin‐
       ning  with a double quote collapse to one double quote.  Neither a num‐
       ber sign nor a semicolon is recognized inside double  quotes.   A  line
       can  be  continued by ending it with a backslash “[1m\[22m”; this works every‐
       where except after a number sign.

       Each command [4mname[24m that is marked with * has an associated negative com‐
       mand [1mno-[4m[22mname[24m that undoes the effect of [4mname[24m.  For example, the  [1mno-sort[0m
       command  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[0m
       is used for a single upper or lower case letter naming a field;  [4mfields[0m
       is used for a sequence of such letters; [4mm[24m and [4mn[24m are used for a non‐neg‐
       ative numbers; [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 last
              name 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 hyphenated 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 refer‐
              ences will be abbreviated to a label consisting of the first la‐
              bel, followed by [4mstring[24m, followed by the last  label.   This  is
              mainly useful with numeric labels.  If [4mstring[24m is omitted, it de‐
              faults 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
              whenever 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
              omitted it will default to [1mX[22m.  Only one field can be an  annota‐
              tion.

       [1marticles [4m[22mstring[24m ...
              Each  [4mstring[24m  is a definite or indefinite article, and should be
              ignored 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
              database [4mfile[24m.  This command should  come  last  in  an  [1m.R1[22m/[1m.R2[0m
              block.

       [1mbracket-label [4m[22mstring1[24m [4mstring2[24m [4mstring3[0m
              In  the  text,  bracket each label with [4mstring1[24m and [4mstring2[24m.  An
              occurrence of [4mstring2[24m immediately followed by  [4mstring1[24m  will  be
              turned into [4mstring3[24m.  The default behavior is as follows.
                     [1mbracket-label \*([. \*(.] ", "[0m

       [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  [4mgindxbib[24m(1)  exists, then it will be
              searched instead; 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 sub‐
              section “Label expressions” below for a description of label ex‐
              pressions.  This command is useful if you do not  want  explicit
              labels  in  the  reference  list, but instead want to handle any
              necessary disambiguation 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,
                     [1mdate-as-label D.+yD.y%a*D.-y[0m
              would  attach  a disambiguating letter to the year part of the [1mD[0m
              field in the reference.

       [1mdefault-database[22m*
              The default database should be searched.  This  is  the  default
              behavior,  so  the negative version of this command is more use‐
              ful.  [4mgrefer[24m 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[0m
              are [1mXYZ[22m.

       [1met-al[22m* [4mstring[24m [4mm[24m [4mn[0m
              Control  use of [1met al. [22min the evaluation of [1m@ [22mexpressions in la‐
              bel expressions.  If the number of authors needed  to  make  the
              author sequence unambiguous is [4mu[24m and the total number of authors
              is  [4mt[24m  then the last [4mt[24m-[4mu[24m authors will be replaced by [4mstring[24m pro‐
              vided 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.
                     [1met-al " et al" 2 3[0m
              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 ex‐
              actly 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
              reference’s label.  This is the default behavior, so  the  nega‐
              tive 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
              negative version of this command is more useful.

       [1mlabel [4m[22mstring[0m
              [4mstring[24m is a label expression describing how to label each refer‐
              ence.

       [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 descrip‐
              tion of the [1m<> [22mlabel expression.

       [1mmove-punctuation[22m*
              In  the  text,  move any punctuation at the end of line past the
              label.  It is usually a good idea to give  this  command  unless
              you are using superscripted numbers as labels.

       [1mreverse[22m* [4mstring[0m
              Reverse  the  fields whose names are in [4mstring[24m.  Each field name
              can be followed by a number which  says  how  many  such  fields
              should be reversed.  If no number is given for a field, all such
              fields will be reversed.

       [1msearch-ignore[22m* [4mfields[0m
              While searching for keys in databases for which no index exists,
              ignore  the  contents  of [4mfields[24m.  Initially, fields [1mXYZ [22mare ig‐
              nored.

       [1msearch-truncate[22m* [4mn[0m
              Only require the first [4mn[24m characters of keys to be given.  In ef‐
              fect when searching for a given key words in  the  database  are
              truncated  to  the maximum of [4mn[24m and the length of the key.  Ini‐
              tially, [4mn[24m is 6.

       [1mshort-label[22m* [4mstring[0m
              [4mstring[24m is a label expression that specifies an alternative (usu‐
              ally 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  au‐
              thors from the label.  The [1mshort-label [22mcommand will typically be
              used  to  specify  a label containing just a date and possibly a
              disambiguating letter.

       [1msort[22m* [4mstring[0m
              Sort references according to [4mstring[24m.  References will  automati‐
              cally  be  accumulated.  [4mstring[24m should be a list of field names,
              each followed 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 (ten‐
              tative) label.  (Subsection “Label expressions” below  describes
              the concept of a tentative label.)

       [1msort-adjacent-labels[22m*
              Sort labels that are adjacent in the text according to their po‐
              sition  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 will
              have no effect unless references are being accumulated.

   [1mLabel expressions[0m
       Label expressions can be evaluated both normally and tentatively.   The
       result  of  normal evaluation is used for output.  The result of tenta‐
       tive evaluation, called the [4mtentative[24m [4mlabel[24m, is used to gather the  in‐
       formation  that normal evaluation needs to disambiguate the label.  La‐
       bel 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 applies to normal evaluation, except where other‐
       wise specified.

       [4mfield[0m
       [4mfield[24m [4mn[0m
              The [4mn[24m‐th 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 the authors joined as specified by the [1mjoin-authors [22mcommand.
              The  whole  of each author’s name will be used.  However, if the
              references are sorted by author (that is, the sort specification
              starts with “[1mA+[22m”), then authors’ last names  will  be  used  in‐
              stead, provided that this does not introduce ambiguity, and also
              an initial subsequence of the authors may be used instead of all
              the authors, again provided that this does not introduce ambigu‐
              ity.   The use of only the last name for the [4mi[24m‐th author of some
              reference is considered to be ambiguous if there is  some  other
              reference, such that the first [4mi[24m-1 authors of the references are
              the  same,  the  [4mi[24m‐th authors are not the same, but the [4mi[24m‐th au‐
              thors last names are 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 sub‐
              sequence.   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 additional require‐
              ments  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
              purpose will 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
              character  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 tenta‐
              tively 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  dig‐
              its  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 to‐
              wards 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 last name 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 evalu‐
              ated.  Thus [1m.a [22mis useful only when you want a field to be abbre‐
              viated 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 last name 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 concatenation 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 ad‐
              jacent two‐part labels which have the same first  part  will  be
              merged by appending the second part of the second label onto the
              first   label   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& [22mand [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 se‐
       ries  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  charac‐
       ter).   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  clas‐
       sified  as  type  1,  otherwise  if  it  contains a [1mB [22mfield, it will be
       type 3, otherwise if it contains a [1mG [22mor [1mR [22mfield it will be type 4, oth‐
       erwise 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 ref‐
       erences  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
       information; all exit afterward.

       [1m-R     [22mDon’t recognize lines beginning with [1m.R1[22m/[1m.R2[22m.

       Other options are equivalent to [4mgrefer[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 argu‐
       ments 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

[1mEnvironment[0m
       [4mREFER[24m  If set, overrides the default database.

[1mFiles[0m
       [4m/usr/share/dict/papers/Ind[0m
              Default database.

       file[4m.i[24m Index files.

       [4m/usr/pkg/share/groff/1.23.0/tmac/refer.tmac[0m
              defines  macros  and strings facilitating integration with macro
              packages that wish to support [4mgrefer[24m.

       [4mgrefer[24m uses temporary files.  See the [4mgroff[24m(1) man page for details  of
       where such files are created.

[1mBugs[0m
       In  label  expressions, [1m<> [22mexpressions are ignored inside [1m.[4m[22mchar[24m expres‐
       sions.

[1mExamples[0m
       We can illustrate the operation of [4mgrefer[24m with a  sample  bibliographic
       database  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 [4mgrefer[24m (a) produces a label “1”; (b) brack‐
       ets 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 bibliographic data for the reference; (e) calls a macro “[1m][[22m”;
       and (f) uses the [1mlf [22mrequest to restore the line numbers of the original
       input.  As discussed in subsection “Macro interface” above, it is up to
       the document or a macro package to employ and format  this  information
       usefully.  Let us see how we might turn [4mgroff_ms[24m(7) 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 [4mgrefer[24m’s
       label numbering, so we have manually specified a  (superscripted)  sym‐
       bolic footnote for our non‐bibliographic aside.

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

       [4mgindxbib[24m(1), [4mglookbib[24m(1), [4mlkbib[24m(1)

groff 1.23.0                      2 July 2023                        [4mgrefer[24m(1)
───────────────────────────────────────────────────────────────────────────────
[4mgsoelim[24m(1)                  General Commands Manual                 [4mgsoelim[24m(1)

[1mName[0m
       gsoelim - recursively interpolate source requests in [4mroff[24m or other text
       files

[1mSynopsis[0m
       [1mgsoelim [22m[[1m-Crt[22m] [[1m-I [4m[22mdir[24m] [[4minput‐file[24m ...]

       [1mgsoelim --help[0m

       [1mgsoelim -v[0m
       [1mgsoelim --version[0m

[1mDescription[0m
       GNU  [4msoelim[24m is a preprocessor for the [4mgroff[24m(7) document formatting sys‐
       tem.  [4mgsoelim[24m works as a filter to eliminate source requests in [4mroff[24m(7)
       input files; that is, it replaces lines of the form “[1m.so [4m[22mincluded‐file[24m”
       within each text [4minput‐file[24m with the contents of [4mincluded‐file[24m,  recur‐
       sively.   By  default, it writes [1mlf [22mrequests as well to record the name
       and line number of each [4minput‐file[24m and [4mincluded‐file[24m, so that any diag‐
       nostics 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[0m
       arguments, [4mgsoelim[24m reads the standard input stream.  Output is  written
       to the standard output stream.

       If the name of a [4mmacro‐file[24m contains a backslash, use [1m\\ [22mor [1m\e [22mto embed
       it.  To embed a space, write “[1m\ [22m” (backslash followed by a space).  Any
       other  escape  sequence  in  [4mmacro‐file[24m,  including  “[1m\[rs][22m”,  prevents
       [4mgsoelim[24m from replacing the source request.

       The dot must be at the beginning of a line and must be followed by “[1mso[22m”
       without intervening spaces or tabs for [4mgsoelim[24m to handle it.  This con‐
       vention allows source requests to be  “protected”  from  processing  by
       [4mgsoelim[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 [4mmacro‐file[0m
       argument.  The [1m-C [22moption overrides this requirement.

       The foregoing is the limit of [4mgsoelim[24m’s understanding of the [4mroff[24m  lan‐
       guage; 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, [4mgsoelim[0m
       can  be used to process text files in general, to flatten a tree of in‐
       put documents.

       [4msoelim[24m was designed to handle situations where the  target  of  a  [4mroff[0m
       source  request  requires  a  preprocessor  such  as  [4mgeqn[24m(1), [4mgpic[24m(1),
       [4mgrefer[24m(1), or [4mgtbl[24m(1).  The usual processing sequence of [4mgroff[24m(1) is as
       follows.  In the diagrams below, the traditional names for  [4msoelim[24m  and
       [4mtroff[24m  are  used;  on  this  system,  the GNU versions are installed as
       [4mgsoelim[24m and [4mgtroff[24m.

                 input        sourced
                 file          file
                   ⎪             ⎪
                   ↓             ↓
               preprocessor ⎯→ troff ⎯→ postprocessor
                                             ⎪
                                             ↓
                                          output
                                           file

       That is, files sourced with “[1mso[22m” are normally read [4monly[24m by the  format‐
       ter, [4mgtroff[24m.  [4mgsoelim[24m is [4mnot[24m required for [4mgtroff[24m to source files.

       If a file to be sourced should also be preprocessed, it must already be
       read  [4mbefore[24m  the input file passes through the preprocessor.  [4mgsoelim[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
       information; 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 path for [4minput‐[24m and [4mincluded‐files.[24m  [1m-I[0m
              may 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-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  pur‐
              pose.

       If both [1m-r [22mand [1m-t [22mare given, the last one specified controls.

[1mSee also[0m
       [4mgroff[24m(1)

groff 1.23.0                      2 July 2023                       [4mgsoelim[24m(1)
───────────────────────────────────────────────────────────────────────────────
[4mgtbl[24m(1)                     General Commands Manual                    [4mgtbl[24m(1)

[1mName[0m
       gtbl - prepare tables for [4mgroff[24m documents

[1mSynopsis[0m
       [1mgtbl [22m[[1m-C[22m] [[4mfile[24m ...]

       [1mgtbl --help[0m

       [1mgtbl -v[0m
       [1mgtbl --version[0m

[1mDescription[0m
       The  GNU implementation of [4mtbl[24m is part of the [4mgroff[24m(1) document format‐
       ting system.  [4mgtbl[24m is a [4mgtroff[24m(1) preprocessor that translates descrip‐
       tions of tables embedded in [4mroff[24m(7) input files into the  language  un‐
       derstood  by  [4mgtroff[24m.  It copies the contents of each [4mfile[24m to the stan‐
       dard output stream, except that lines between [1m.TS [22mand  [1m.TE  [22mare  inter‐
       preted  as  table descriptions.  While GNU [4mtbl[24m’s input syntax is highly
       compatible 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 ex‐
       tensions  employed)  must  be used.  Normally, [4mgtbl[24m is not executed di‐
       rectly by the  user,  but  invoked  by  specifying  the  [1m-t  [22moption  to
       [4mgroff[24m(1).   If  no  [4mfile[24m  operands are given on the command line, or if
       [4mfile[24m is “[1m-[22m”, [4mgtbl[24m reads the standard input stream.

   [1mOverview[0m
       [4mgtbl[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 [4mtable[24m [4mregion[24m en‐
       closes  one  or  more table descriptions.  Within a table region, table
       descriptions beyond 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 subse‐
       quent pages (see below).

       (Experienced [4mroff[24m users should observe that [4mgtbl[24m is not a [4mroff[24m language
       interpreter: the default control character must be used, and no  spaces
       or tabs are permitted between the control character and the macro name.
       These  [4mgtbl[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[0m
       macros  to handle issues of table placement on the page.  [4mgtbl[24m produces
       [4mgroff[24m code to define these macros as empty if their definitions do  not
       exist when the formatter 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[0m
       [4mspecification[24m  followed  by  one or more input lines (rows) of [4mentries.[0m
       These entries comprise the [4mtable[24m [4mdata.[0m

   [1mRegion options[0m
       The line immediately following the [1m.TS [22mtoken  may  specify  region  op‐
       tions,  keywords  that influence the interpretation or rendering of the
       region as a whole or all  table  entries  within  it  indiscriminately.
       They  must be separated by commas, spaces, or tabs.  Those that require
       a parenthesized argument permit spaces and tabs  between  the  option’s
       name and the opening parenthesis.  Options accumulate and cannot be un‐
       set  within a region once declared; if an option that takes a parameter
       is repeated, the last occurrence controls.  If present, the set of  re‐
       gion options must be terminated with a semicolon ([1m;[22m).

       Any  of  the  [1mallbox[22m, [1mbox[22m, [1mdoublebox[22m, [1mframe[22m, and [1mdoubleframe [22mregion op‐
       tions 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.  As a  GNU  extension,
              the alternative option name [1mframe [22mis also recognized.

       [1mcenter [22mCenter  the table region with respect to the current indentation
              and line length; the default is to left‐align it.  As a GNU  ex‐
              tension, the alternative option name [1mcentre [22mis also recognized.

       [1mdecimalpoint([4m[22mc[24m[1m)[0m
              Recognize  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)[0m
              Recognize  characters  [4mx[24m  and [4my[24m as start and end delimiters, re‐
              spectively, for [4mgeqn[24m(1) input, and ignore input between them.  [4mx[0m
              and [4my[24m need not be distinct.

       [1mdoublebox[0m
              Enclose the entire table region in a double  box;  implies  [1mbox[22m.
              As  a  GNU extension, the alternative option name [1mdoubleframe [22mis
              also recognized.

       [1mexpand [22mSpread the table horizontally to fill the available space  (line
              length  minus indentation) by increasing column separation.  Or‐
              dinarily, a table is made only as wide as necessary to  accommo‐
              date  the  widths  of  its  entries  and  its column separations
              (whether specified or default).  When [1mexpand [22mapplies to a  table
              that  exceeds  the available horizontal space, column separation
              is reduced as far as necessary (even to  zero).   [4mgtbl[24m  produces
              [4mgroff[24m input that issues a diagnostic if such compression occurs.
              The column modifier [1mx [22m(see below) overrides this option.

       [1mlinesize([4m[22mn[24m[1m)[0m
              Draw  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 is ignored on terminal devices.

       [1mnokeep [22mDon’t use [4mroff[24m diversions to manage page breaks.  Normally, [4mgtbl[0m
              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[0m
              Ignore leading and trailing spaces in table entries.  This is  a
              GNU extension.

       [1mnowarn [22mSuppress  diagnostic  messages  produced  at document formatting
              time when the line or page lengths are 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
       typeset.   The  format specification is a series of column [4mdescriptors.[0m
       Each descriptor encodes a [4mclassifier[24m followed by  zero  or  more  [4mmodi‐[0m
       [4mfiers.[24m   Classifiers  are  letters  (recognized  case‐insensitively) or
       punctuation symbols; modifiers consist of or begin with letters or  nu‐
       merals.  Spaces, tabs, newlines, and commas separate descriptors.  New‐
       lines and commas are special; they apply the descriptors following them
       to  a subsequent row of the table.  (This enables 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[0m
       [4mdefinition.[24m   Within  a  row  definition, separation between column de‐
       scriptors (by spaces or tabs) is often optional; only  some  modifiers,
       described below, make separation necessary.

       Each  column descriptor begins with a mandatory [4mclassifier,[24m a character
       that selects from one of several arrangements.  Some determine the  po‐
       sitioning  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  classi‐
       fier  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 con‐
       clude with a dot “[1m.[22m” followed by a newline.  Each row definition is ap‐
       plied  in turn to one row of the table.  The last row definition is ap‐
       plied to rows of table data in excess of the row definitions.

       For clarity in this document’s examples, we shall 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  bold‐
       faced;  the  second  and any further rows’ first and second columns are
       left‐ and right‐aligned, respectively.

       The row definition with the most column descriptors determines the num‐
       ber of columns in the table; any row definition with fewer  is  implic‐
       itly  extended  on the right‐hand side with [1mL [22mclassifiers as many times
       as necessary 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  en‐
              tries in the column with respect to the centered entry, then in‐
              dent  all  entries  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.  [4mgtbl[24m aligns columns of
              numbers vertically at the units place.  If multiple decimal sep‐
              arators are adjacent to a digit, it uses the rightmost  one  for
              vertical  alignment.   If  there  is  no  decimal separator, the
              rightmost digit is used for vertical alignment; otherwise,  [4mgtbl[0m
              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, the left‐
              most is used for alignment.

              If [1mN[22m‐classified entries share a column with [1mL [22mor [1mR [22mentries, [4mgtbl[0m
              centers the widest [1mN [22mentry with respect to the widest [1mL [22mor [1mR [22men‐
              try, preserving the alignment of [1mN [22mentries with respect to  each
              other.

              The appearance of [4mgeqn[24m equations within [1mN[22m‐classified columns can
              be  troublesome  due to the foregoing textual scan for a decimal
              separator.  Use the [1mdelim [22mregion option to make [4mgtbl[24m ignore  the
              data within [4meqn[24m delimiters for that purpose.

       [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.  An empty table  en‐
              try  is  expected  to correspond to this classifier; if data are
              found there, [4mgtbl[24m issues a diagnostic message.

       [1m=      [22mReplace table entry with a double horizontal rule.  An empty ta‐
              ble entry is expected to correspond to this classifier; if  data
              are found there, [4mgtbl[24m issues a diagnostic message.

       [1m|      [22mPlace a vertical rule (line) on the corresponding row of the ta‐
              ble  (if  two  of  these  are adjacent, a double vertical rule).
              This classifier 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 [4mgtbl[24m region, use the [1m.T& [22mtoken at
       the start of a line.  It is followed by a format specification and  ta‐
       ble data, but [4mnot[24m region options.  The quantity of columns in a new ta‐
       ble format thus introduced cannot increase relative to the previous ta‐
       ble  format;  in that case, you must end the table region and start an‐
       other.  If that will not serve because the region 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.

       Attempting  to horizontally span in the first column or vertically span
       on the first row is an error.  Non‐rectangular span areas are also  not
       supported.

   [1mColumn modifiers[0m
       Any  number  of modifiers can follow a column classifier.  Arguments to
       modifiers, where accepted, are case‐sensitive.  If the same modifier is
       applied to a column specifier more than once, or if  conflicting  modi‐
       fiers are applied, only the last occurrence has effect.  The modifier [1mx[0m
       is  mutually  exclusive  with  [1me [22mand [1mw[22m, but [1me [22mis not mutually exclusive
       with [1mw[22m; if these are used in combination, [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”),
              instead of the center, of its range.  This is a GNU extension.

       [1me[22m, [1mE   [22mEqualize the widths of columns with this modifier.   The  column
              with the largest width controls.  This modifier sets the default
              line length used in a text block.

       [1mf[22m, [1mF   [22mSelect  the typeface for the table entry.  This modifier must be
              followed by 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.
              The last form is a GNU extension.  (The parameter corresponds to
              that accepted by the [4mtroff[24m [1mft [22mrequest.)  A  one‐character  argu‐
              ment  not in parentheses must be separated by one or more spaces
              or tabs from what follows.

       [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  subsec‐
              tion “Text blocks” below).  This is a GNU extension.  This modi‐
              fier  must  be followed by a macro name of one or two characters
              or a name of any length in parentheses.  A  one‐character  macro
              name  not in parentheses must be separated by one or more spaces
              or tabs from what follows.  The named macro must be defined  be‐
              fore the table region containing this column modifier is encoun‐
              tered.   The  macro should contain only simple [4mgroff[24m 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 for the table entry.  This  modifier  must  be
              followed  by an integer [4mn[24m with an optional leading sign.  If un‐
              signed, the type size is set to [4mn[24m scaled points.  Otherwise, the
              type size is incremented or decremented per the sign by [4mn[24m scaled
              points.  The use of a signed multi‐digit number is a GNU  exten‐
              sion.   (The parameter corresponds to that accepted by the [4mtroff[0m
              [1mps [22mrequest.)  If a type size modifier is followed  by  a  column
              separation  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 GNU extension.

       [1mv[22m, [1mV   [22mSet the vertical spacing to be used in a text block.  This modi‐
              fier must be followed by an integer [4mn[24m with an  optional  leading
              sign.   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 num‐
              ber is a GNU extension.  (This parameter corresponds to that ac‐
              cepted by the [4mtroff[24m [1mvs [22mrequest.)  If a vertical spacing modifier
              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.  This modifier must be followed
              by a number, which is either a unitless integer, or a [4mroff[24m hori‐
              zontal measurement in parentheses.  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,  distrib‐
              ute  any  remaining  line length evenly over all columns bearing
              this modifier.  Applying 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
              calculation  purposes; that is, compute the column’s width using
              only the information in its descriptor.

       [4mn[24m      A numeric suffix on a column descriptor sets the separation dis‐
              tance (in ens) from the succeeding column; the  default  separa‐
              tion 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 di‐
              agnostic from [4mgtbl[24m.

   [1mTable data[0m
       The table data come after the format specification.   Each  input  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,  discussed below, also spread table entries across multiple in‐
       put lines.)  Table entries within a row are separated in the input by a
       tab character by default; see the [1mtab [22mregion option above.  Excess  en‐
       tries  in  a row of table data (those that have no corresponding column
       descriptor, not even an implicit one arising from rectangularization of
       the table) are discarded with a diagnostic message.  [4mroff[24m control lines
       are accepted between rows of table data and within text blocks.  If you
       wish to visibly mark an empty table entry in the document source, popu‐
       late it with the [1m\& [4m[22mroff[24m dummy character.  The table  data  are  inter‐
       rupted  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,  bro‐
       ken,  hyphenated, adjusted, or populated with additional inter‐sentence
       space.  [4mgtbl[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 [22mmodifier applies to the column, 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 se‐
       lection or vertical spacing, do not persist between entries.

       Several forms of table entry are interpreted specially.

       • If a table row contains only an underscore or equals sign ([1m_ [22mor [1m=[22m), a
         single  or  double  horizontal  rule  (line),  respectively, is drawn
         across the table at that point.

       • A table entry containing only [1m_ [22mor [1m= [22mon an otherwise populated row is
         replaced by a single or double horizontal rule, respectively, joining
         its neighbors.

       • Prefixing a lone underscore or equals sign with a backslash also  has
         meaning.   If a table entry consists only of [1m\_ [22mor [1m\= [22mon an otherwise
         populated row, it is replaced by a single or double horizontal  rule,
         respectively, that does [4mnot[24m (quite) join its neighbors.

       • A table entry consisting of [1m\R[4m[22mx[24m, where [4mx[24m is any [4mroff[24m ordinary or spe‐
         cial character, is replaced by enough repetitions of the glyph corre‐
         sponding  to  [4mx[24m to fill the column, albeit without joining its neigh‐
         bors.

       • 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 escape 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 recognized.  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
       table,  excessively wide; the table then exceeds the line length of the
       page, and becomes ugly or is exposed to truncation by  the  output  de‐
       vice.   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

       [4mgtbl[24m  interprets a table entry beginning with “[1mT{[22m” at the end of an in‐
       put line not as table data, but as a token starting a text block.  Sim‐
       ilarly, “[1mT}[22m” at the start of an input line ends a text block;  it  must
       also  end  the  table entry.  Text block tokens can share an input line
       with other table data (preceding [1mT{ [22mand following [1mT}[22m).  Input lines be‐
       tween 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  alter its adjustment distinctly from other text in the docu‐
       ment.  As with other table entries, when a text block ends, any  alter‐
       ations to formatting parameters are discarded.  They do not affect sub‐
       sequent 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  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.  Be‐
       cause a diversion is used to format the  text  block,  its  height  and
       width  are  subsequently  available in the registers [1mdn [22mand [1mdl[22m, respec‐
       tively.

   [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[0m
       token  is output so that a [4mgroff[24m macro named [1mTE [22mcan make use of it.  [1mT.[0m
       is a Boolean‐valued register indicating whether the bottom of the table
       is being processed.  The [1m#T [22mregister marks the top of the table.  Avoid
       using these names for any other purpose.

       [4mgtbl[24m also defines a macro [1mT# [22mto produce the bottom and side lines of  a
       boxed  table.   While  [4mgtbl[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
       beginning with the numeral [1m3[22m.  A document to be preprocessed  with  GNU
       [4mtbl[24m should not use any such identifiers.

   [1mInteraction with [4mgeqn[0m
       [4mgtbl[24m  should  always be called before [4mgeqn[24m(1).  ([4mgroff[24m(1) 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 [4mgtbl[24m will recognize them.

   [1mGNU [4mtbl[24m enhancements[0m
       In  addition to extensions noted above, GNU [4mtbl[24m removes constraints en‐
       dured 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.

       • All  table  rows are considered when deciding column widths, not just
         those occurring in the first 200 input lines of a region.  Similarly,
         table continuation ([1m.T&[22m) tokens are  recognized  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
       [4mgtbl[24m  writes  its  own macro definitions at the beginning of each table
       region, it is necessary to call end macros instead of ending macro def‐
       initions with “[1m..[22m”.  Additionally, the escape character  must  be  dis‐
       abled.

       Not all [4mgtbl[24m features can be exercised from such macros because [4mgtbl[24m is
       a  [4mroff[24m  preprocessor: it sees the input earlier than [4mgtroff[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 [4mgtbl[24m itself, which sees only [1m\$1[22m,  [1m\$2[22m,  and  so  on,  and
       therefore  can’t  recognize a decimal separator that only appears later
       when [4mgtroff[24m interpolates a macro or string definition.

       Using [4mgtbl[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
       subsequent  diagnostics.   [4mgtbl[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 [4mgtbl[24m injects to re‐
       store the source line number cannot take effect.  Consider copying  the
       input  line counter register [1mc. [22mand 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
       information; all exit afterward.

       [1m-C     [22mEnable  AT&T compatibility mode: recognize [1m.TS [22mand [1m.TE [22meven when
              followed by a character other than space or  newline.   Further‐
              more, interpret the uninterpreted leader escape sequence [1m\a[22m.

[1mLimitations[0m
       Multi‐page  tables,  if  boxed and/or if you want their column headings
       repeated after page breaks, require support at the time the document is
       formatted.  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  [22margument.   Then, within the table data, call the [1mTH[0m
       macro; 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 repeating 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  demon‐
       stration.

       Double  horizontal  rules  are not supported by [4mgrotty[24m(1); single rules
       are used instead.  [4mgrotty[24m also ignores half‐line motions, so the [1mu [22mcol‐
       umn modifier has no effect.  On terminal devices (“[4mnroff[24m mode”),  hori‐
       zontal rules and box borders occupy a full vee of space; this amount is
       doubled for [1mdoublebox [22mtables.  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 be‐
       tween  columns in [4mnroff[24m mode; using double vertical rules and/or reduc‐
       ing the column separation below the default can make them ugly or over‐
       strike 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,  ex‐
       cept  in  compatibility mode.  This is correct behavior: [1m\a [22mis an [4munin‐[0m
       [4mterpreted[24m leader.  You can still use the [4mroff[24m  leader  character  (Con‐
       trol+A)  or  define a string to use [1m\a [22mas it was designed: to be inter‐
       preted 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  and/or  trailing  [1m|  [22min  a  format  specification,  such  as
       “[1m|LCR|.[22m”,  produces an en space between the vertical rules and the con‐
       tent of the adjacent columns.  If no such space is desired (so that the
       rule abuts the content), you can introduce “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; unfor‐
       tunately 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
       formal 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 obligate carnivores tomato‐based fruit salads
              .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 obligate carnivores tomato‐based fruit salads │
       └────────────────────────────────────────────────────────────────────┘

       The [1mA [22mand [1mN [22mcolumn classifiers can be easier to grasp in visual render‐
       ing 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  [4mgtbl[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 Janu‐
       ary  1979),  AT&T  Bell Laboratories Computing Science Technical Report
       No. 49.

       The spanning example above was taken from [4mmandoc[24m’s man page for its [4mtbl[0m
       implementation ⟨https://man.openbsd.org/tbl.7⟩.

       [4mgroff[24m(1), [4mgtroff[24m(1)

groff 1.23.0                      2 July 2023                          [4mgtbl[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  [4mgroff[24m(1)’s  [1mdvi[0m
       output  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 identi‐
       fiers 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[0m
       through [4mcn[24m are glyph identifiers in the form used  by  [4mgroff[24m  font  de‐
       scriptions.   If  a glyph has no [4mgroff[24m names but exists in [4mtfm‐file,[24m it
       is put in the [4mgroff[24m font description file as an unnamed glyph.   Output
       is  written  in  [4mgroff_font[24m(5) 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‐description[24m in the [1mfonts [22mdirective in  the  output  device’s  [4mDESC[0m
       file.

       To do a good job of math typesetting, [4mgroff[24m requires font metric infor‐
       mation  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 ad‐
       ditional information required by [4mgroff[24m is given by the two arguments to
       the [1mmath_fit [22mmacro 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 after [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;
       consider 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
       “special”  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
       information; all exit afterward.

       [1m-g [4m[22mgf‐file[0m
              Use the [4mgf‐file[24m produced by Metafont  containing  “[1mspecial[22m”  and
              “[1mnumspecial[22m”  commands to obtain additional font metric informa‐
              tion.

       [1m-k [4m[22mskew‐char[0m
              The skew character of this font is at position [4mskew‐char.[24m  [4mskew‐[0m
              [4mchar[24m 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 second component is [4mskew‐char[24m are ignored.

       [1m-s     [22mAdd the [1mspecial [22mdirective to the font description file.

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

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

       [4m/usr/pkg/share/groff/1.23.0/font/devdvi/generate/ec.map[0m
       [4m/usr/pkg/share/groff/1.23.0/font/devdvi/generate/msam.map[0m
       [4m/usr/pkg/share/groff/1.23.0/font/devdvi/generate/msbm.map[0m
       [4m/usr/pkg/share/groff/1.23.0/font/devdvi/generate/tc.map[0m
       [4m/usr/pkg/share/groff/1.23.0/font/devdvi/generate/texb.map[0m
       [4m/usr/pkg/share/groff/1.23.0/font/devdvi/generate/texex.map[0m
       [4m/usr/pkg/share/groff/1.23.0/font/devdvi/generate/texi.map[0m
       [4m/usr/pkg/share/groff/1.23.0/font/devdvi/generate/texitt.map[0m
       [4m/usr/pkg/share/groff/1.23.0/font/devdvi/generate/texmi.map[0m
       [4m/usr/pkg/share/groff/1.23.0/font/devdvi/generate/texr.map[0m
       [4m/usr/pkg/share/groff/1.23.0/font/devdvi/generate/texsy.map[0m
       [4m/usr/pkg/share/groff/1.23.0/font/devdvi/generate/textex.map[0m
       [4m/usr/pkg/share/groff/1.23.0/font/devdvi/generate/textt.map[0m
              map glyph indices in TeX fonts to  [4mgroff[24m  ordinary  and  special
              character  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[0m
              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[24m for [1mCW[22m.

[1mSee also[0m
       [4mgroff[24m(1), [4mgrodvi[24m(1), [4mgroff_font[24m(5)

groff 1.23.0                      2 July 2023                      [4mtfmtodit[24m(1)
───────────────────────────────────────────────────────────────────────────────
[4mgtroff[24m(1)                   General Commands Manual                  [4mgtroff[24m(1)

[1mName[0m
       gtroff - GNU [4mroff[24m typesetter and document formatter

[1mSynopsis[0m
       [1mgtroff [22m[[1m-abcCEiRUz[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‐directory[24m] [[1m-I [4m[22minclusion‐directory[24m] [[1m-m [4m[22mmacro‐package[24m]
              [[1m-M [4m[22mmacro‐directory[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‐category[24m] [[1m-W [4m[22mwarning‐category[24m]
              [[4mfile[24m ...]

       [1mgtroff --help[0m

       [1mgtroff -v[0m
       [1mgtroff --version[0m

[1mDescription[0m
       GNU [4mtroff[24m transforms [4mgroff[24m(7) language input into  the  device‐indepen‐
       dent  output format described in [4mgroff_out[24m(5); [4mgtroff[24m is thus the heart
       of the GNU [4mroff[24m document formatting system.  If no  [4mfile[24m  operands  are
       given on the command line, or if [4mfile[24m is “[1m-[22m”, the standard input stream
       is read.

       GNU [4mtroff[24m is functionally compatible with the AT&T [4mtroff[24m typesetter and
       features  numerous  extensions.  Many people prefer to use the [4mgroff[24m(1)
       command, 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 ver‐
       sion 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 ex‐
                ample, “<beginning of page>”.

              • Lines are broken where they would be in the formatted output.

              • A horizontal motion of any size is represented as  one  space.
                Adjacent  horizontal motions are not combined.  Inter‐sentence
                space nodes (those arising from the second argument to the [1m.ss[0m
                request) are not represented.

              • Vertical motions are not represented.

              • Special characters are rendered in angle brackets;  for  exam‐
                ple, the default soft hyphen character 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 [4mgtroff[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,
              because [4mgtroff[24m’s idea of line numbers can  be  confused  by  re‐
              quests that append to macros.

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

       [1m-C     [22mEnable   AT&T   [4mtroff[24m   compatibility  mode;  implies  [1m-c[22m.   See
              [4mgroff_diff[24m(7).

       [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  one  charac‐
              ter; [4mstring[24m can be of arbitrary length.  Such string assignments
              happen  before  any  macro file is loaded, including the startup
              file.  Due to  [4mgetopt_long[24m(3)  limitations,  [4mc[24m  cannot  be,  and
              [4mstring[24m  cannot  contain,  an  equals sign, even though that is a
              valid character in a [4mroff[24m identifier.

       [1m-E     [22mInhibit [4mgtroff[24m error messages; implies [1m-Ww[22m.   This  option  does
              [4mnot[24m suppress messages sent to the standard error stream by docu‐
              ments 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 direc‐
              tory of device and font description files.  See the  description
              of  [4mGROFF_FONT_PATH[24m  in  section “Environment” below for the de‐
              fault 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:  im‐[0m
              [1mport'[22m”, “[1m\X'ps: file'[22m”, and “[1m\X'pdf: pdfpic'[22m” device control es‐
              cape  sequences).   [1m-I [22mmay be specified more than once; each [4mdir[0m
              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-I [22mworks similarly to,  and  is  named
              for, the “include” option of Unix C compilers.

       [1m-m [4m[22mname[0m
              Process  the  file  name[4m.tmac[24m  prior to any input files.  If not
              found, [4mtmac.[24mname is attempted.  [4mname[24m (in both  arrangements)  is
              presumed   to   be   a   macro  file;  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[0m
              Output  only  pages  in [4mlist,[24m which is a comma‐separated list of
              inclusive 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.  [4mgtroff[24m stops processing and exits after format‐
              ting 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.[0m
              [4mc[24m  must  be  a  one‐character name; [4mregister[24m can be of arbitrary
              length.  Such register assignments happen before any macro  file
              is  loaded,  including  the startup file.  Due to [4mgetopt_long[24m(3)
              limitations, [4mc[24m cannot be, and [4mregister[24m cannot contain, an equals
              sign, even though that is a valid character in  a  [4mroff[24m  identi‐
              fier.

       [1m-R     [22mDon’t load [4mtroffrc[24m and [4mtroffrc-end[24m.

       [1m-T [4m[22mdev[24m Prepare output for device [4mdev.[24m  The default is [1mps[22m; see [4mgroff[24m(1).

       [1m-U     [22mOperate  in  [4munsafe[24m [4mmode,[24m enabling the [1mopen[22m, [1mopena[22m, [1mpi[22m, [1mpso[22m, and
              [1msy [22mrequests, which are disabled by default because they allow an
              untrusted input document to write to arbitrary  file  names  and
              run  arbitrary  commands.  This option also adds the current di‐
              rectory to the macro package search path; see the [1m-m [22mand [1m-M  [22mop‐
              tions above.

       [1m-w [4m[22mname[0m
       [1m-W [4m[22mname[0m
              Enable ([1m-w[22m) or inhibit ([1m-W[22m) warnings in category [4mname.[24m  See sec‐
              tion “Warnings” below.

       [1m-z     [22mSuppress formatted output.

[1mWarnings[0m
       Warning  diagnostics emitted by [4mgtroff[24m are divided into named, numbered
       categories.  The name associated with each warning category is used  by
       the  [1m-w [22mand [1m-W [22moptions.  Each category is also assigned a power of two;
       the sum of enabled category codes is used by the [1mwarn [22mrequest  and  the
       [1m.warn  [22mregister.  Warnings of each category are produced under the fol‐
       lowing circumstances.

              ┌───────────────────────┬─────────────────────────────┐
              │ Bit   Code   Category │ Bit    Code      Category   │
              ├───────────────────────┼─────────────────────────────┤
              │   0      [4m1[24m   [1mchar     [22m│  10      [4m1024[24m   [1mreg         [22m│
              │   1      [4m2[24m   [1mnumber   [22m│  11      [4m2048[24m   [1mtab         [22m│
              │   2      [4m4[24m   [1mbreak    [22m│  12      [4m4096[24m   [1mright-brace [22m│
              │   3      [4m8[24m   [1mdelim    [22m│  13      [4m8192[24m   [1mmissing     [22m│
              │   4     [4m16[24m   [1mel       [22m│  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 the output line length
                           [1m\n[.l][22m.  This category is enabled by default.

       [1mchar            [22m1   No mounted font defines a glyph for  the  requested
                           character.  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 component in a color defin‐
                           ition  was  encountered,  or an attempt was made to
                           redefine a default color.

       [1mdelim           [22m8   The closing delimiter in  an  escape  sequence  was
                           missing or mismatched.

       [1mdi            [22m256   A  [1mdi[22m, [1mda[22m, [1mbox[22m, or [1mboxa [22mrequest was invoked without
                           an argument when there was no current diversion.

       [1mel             [22m16   The [1mel [22mrequest was encountered with no prior corre‐
                           sponding [1mie [22mrequest.

       [1mescape      [22m32768   An unsupported escape sequence was encountered.

       [1mfile      [22m1048576   An attempt was made to load a file  that  does  not
                           exist.  This category is enabled by default.

       [1mfont       [22m131072   A  non‐existent font was selected, or the selection
                           was ignored because a  font  selection  escape  se‐
                           quence  was used after the output line continuation
                           escape sequence on an input line.  This category is
                           enabled by default.

       [1mig         [22m262144   An invalid escape sequence occurred  in  input  ig‐
                           nored  using the [1mig [22mrequest.  This warning category
                           diagnoses a condition that is an error when it  oc‐
                           curs in non‐ignored 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, at most one warning  is  given
                           for each.

                           This  warning  is  also  emitted upon an attempt to
                           move an unplanted trap macro.  In such  cases,  the
                           unplanted  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 ab‐
                           sent.

       [1mnumber          [22m2   An  invalid  numeric  expression  was  encountered.
                           This category is enabled by default.

       [1mrange          [22m64   A  numeric expression was out of range for its con‐
                           text.

       [1mreg          [22m1024   An undefined register was used.  When an  undefined
                           register  is  dereferenced, it is automatically de‐
                           fined with a value of 0.  So, unless  it  is  later
                           deleted, at most one warning is given for each.

       [1mright-brace  [22m4096   A  right  brace  escape sequence [1m\} [22mwas encountered
                           where a number was expected.

       [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 un‐
                           defined name longer than two characters is  encoun‐
                           tered and the first two characters of the name con‐
                           stitute  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 oc‐
                           curs in compatibility mode.

       [1msyntax        [22m128   A  self‐contradictory  hyphenation  mode  was   re‐
                           quested;  an empty or incomplete numeric expression
                           was encountered; an operand to a  numeric  operator
                           was missing; an attempt was made to define a recur‐
                           sive,  empty,  or nonsensical character class; or a
                           [4mgroff[24m extension conditional expression operator was
                           used while in compatibility mode.

       [1mtab          [22m2048   A tab character was encountered where a number  was
                           expected,  or  appeared  in an unquoted macro argu‐
                           ment.

       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  descen‐
              dants, 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.

[1mEnvironment[0m
       [4mGROFF_FONT_PATH[24m and [4mGROFF_TMAC_PATH[24m each accept a search path of direc‐
       tories;  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  de‐
              vice’s  directory  of device and font description files.  [4mgtroff[0m
              will scan directories given as arguments to any specified [1m-F [22mop‐
              tions  before  these,  then   in   a   site‐specific   directory
              ([4m/usr/pkg/share/groff/site-font[24m),     a     standard    location
              ([4m/usr/pkg/share/groff/1.23.0/font[24m), and a  compatibility  direc‐
              tory ([4m/usr/lib/font[24m) after them.

       [4mGROFF_TMAC_PATH[0m
              A  list  of  directories  in  which  to  search for macro files.
              [4mgtroff[24m 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 direc‐
              tory ([4m/usr/pkg/share/groff/site-tmac[24m), and a  standard  location
              ([4m/usr/pkg/share/groff/1.23.0/tmac[24m) after them.

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

       [4mSOURCE_DATE_EPOCH[0m
              A  timestamp  (expressed as seconds since the Unix epoch) to use
              as the output creation timestamp in place of the  current  time.
              The  time is converted to human‐readable form using [4mlocaltime[24m(3)
              when the formatter starts up and stored in registers  usable  by
              documents and macro packages.

       [4mTZ[24m     The  timezone  to use when converting the current time (or value
              of [4mSOURCE_DATE_EPOCH[24m) to human‐readable form; see [4mtzset[24m(3).

[1mFiles[0m
       [4m/usr/pkg/share/groff/1.23.0/tmac/troffrc[0m
              is an initialization macro file loaded before any macro packages
              specified with [1m-m [22moptions.

       [4m/usr/pkg/share/groff/1.23.0/tmac/troffrc-end[0m
              is an initialization macro file loaded after all macro  packages
              specified with [1m-m [22moptions.

       [4m/usr/pkg/share/groff/1.23.0/tmac/[24mname[4m.tmac[0m
              are macro files distributed with [4mgroff[24m.

       [4m/usr/pkg/share/groff/1.23.0/font/dev[24mname[4m/DESC[0m
              describes the output device [4mname[24m.

       [4m/usr/pkg/share/groff/1.23.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
       directory by default for security reasons, even if  the  [1m-U  [22moption  is
       specified.  Use the [1m-M [22mcommand‐line option or the [4mGROFF_TMAC_PATH[24m envi‐
       ronment  variable to add these directories to the search path if neces‐
       sary.

[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
       Werner  Lemberg  ⟨wl@gnu.org⟩,  Bernd Warken ⟨groff-bernd.warken-72@web
       .de⟩, and G. Branden Robinson ⟨g.branden.robinson@gmail.com⟩.

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

       [4mgroff[24m(1)
              offers an overview of the GNU  [4mroff[24m  system  and  describes  its
              front end executable.

       [4mgroff[24m(7)
              details  the [4mgroff[24m language, including a short but complete ref‐
              erence of all predefined requests,  registers,  and  escape  se‐
              quences.

       [4mgroff_char[24m(7)
              explains the syntax of [4mgroff[24m special character escape sequences,
              and lists all special characters predefined by the language.

       [4mgroff_diff[24m(7)
              enumerates the differences between AT&T device‐independent [4mtroff[0m
              and [4mgroff[24m.

       [4mgroff_font[24m(5)
              covers the format of [4mgroff[24m device and font description files.

       [4mgroff_out[24m(5)
              describes the format of [4mgtroff[24m’s output.

       [4mgroff_tmac[24m(5)
              includes information about macro files that ship with [4mgroff[24m.

       [4mroff[24m(7)
              supplies background on [4mroff[24m systems in general, including point‐
              ers to further related documentation.

groff 1.23.0                      2 July 2023                        [4mgtroff[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 [4mgroff[24m(1) font description files from
       X11 fonts.  Each line in [4mfont‐map[24m consists of  a  series  of  lines  of
       paired  [4mgroff[24m font names and X font names as X Logical Font Description
       (XLFD) patterns, with the pair members separated by spaces and/or tabs.
       For example, an input [4mfont‐map[24m file consisting 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
       catalog, and aborts if it cannot.  If necessary, the wildcards  in  the
       XLFD  patterns  are  populated  with the arguments to the [1m-r [22mand [1m-s [22mop‐
       tions.  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 directory (or that  specified  by  the  [1m‐d  [22moption)
       named for each [4mgroff[24m font, and reports the mapping to the standard out‐
       put stream.

[1mOptions[0m
       [1m--help  [22mdisplays  a  usage message, while [1m-v [22mand [1m--version [22mshow version
       information; 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.

[1mFiles[0m
       [4m/usr/pkg/share/groff/1.23.0/font/FontMap-X11[0m
              is the font mapping file used to produce the pre‐generated  font
              description files, supplied with [4mgroff[24m, of X11 core fonts corre‐
              sponding 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
       “X Logical Font Description  Conventions”  ⟨https://www.x.org/releases/
       X11R7.6/doc/xorg-docs/specs/XLFD/xlfd.html⟩, by Jim Flowers and Stephen
       Gildea.

       [4mX[24m(7), [4mgroff[24m(1), [4mgxditview[24m(1), [4mtroff[24m(1), [4mgroff_font[24m(5)

groff 1.23.0                      2 July 2023                      [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 exten‐
       sions 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 [4mde‐[0m
       [4mv[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,[0m
       where [4mf[24m is usually an abbreviation of a font’s name and/or style.   For
       example,  the  [1mps  [22m(PostScript) device 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 terminal emulators)  has  only  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, [4mgtroff[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 [22mdirec‐
       tive must precede any [1mpapersize [22mdirective; and (2) the  [1mcharset  [22mdirec‐
       tive  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.  Comments 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[0m
              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
              quantities are rounded 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 [4mgs[24m(1), but under other systems (no‐
              tably Cygwin) it might be set to another name.   The  [4mgrohtml[24m(1)
              driver uses this directive.

       [1mpaperlength [4m[22mn[0m
              The  vertical  dimension  of  the output medium is [4mn[24m basic units
              (deprecated: use [1mpapersize [22minstead).

       [1mpapersize [4m[22mformat‐or‐dimension‐pair‐or‐file‐name[24m ...
              The dimensions of the output medium are as according to the  ar‐
              gument,  which  is either a standard paper format, a pair of di‐
              mensions, 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  enve‐
              lope  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 pi‐
              cas.  Example: “[1m12c,235p[22m”.  An argument that starts with a digit
              is always 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
              attempted against each other form.  No comment  syntax  is  sup‐
              ported.

              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 [4mgtroff[24m  to  emit  the  name  of  the  source  file  being
              processed.   This  is achieved with the intermediate output com‐
              mand “[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  de‐
              vices 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
              default 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
              commands.

       [1municode[0m
              The output device  supports  the  complete  Unicode  repertoire.
              This  directive is useful only for devices which produce charac‐
              ter entities 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 descrip‐
              tion file’s [1mcharset [22msection, they either  override  the  default
              mappings  for  those  particular  characters or add new mappings
              (normally for composite characters).

              The [1mutf8[22m, [1mhtml[22m, and [1mxhtml [22moutput devices use this directive.

       [1munitwidth [4m[22mn[0m
              Quantities in the font description files are in basic units  for
              fonts whose type size is [4mn[24m scaled points.

       [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
              [4mgtroff[24m should encode named glyphs  inside  device  control  com‐
              mands.  The [4mgrohtml[24m driver uses this directive.

       [1mvert [4m[22mn[24m The  vertical motion quantum is [4mn[24m basic units.  Vertical quanti‐
              ties are rounded to multiples of [4mn.[0m

       [1mcharset[0m
              This directive and the rest of the file are ignored.  It is rec‐
              ognized for compatibility with other [4mtroff[24m implementations.   In
              GNU  [4mtroff[24m,  character set repertoire is described on a per‐font
              basis.

       [4mgtroff[24m recognizes  but  ignores  the  directives  [1mspare1[22m,  [1mspare2[22m,  and
       [1mbiggestfont[22m.

       The  [1mres[22m,  [1munitwidth[22m, [1mfonts[22m, and [1msizes [22mlines are mandatory.  Directives
       not listed above are ignored by [4mgtroff[24m but may be used  by  postproces‐
       sors to obtain further information about the device.

[1mFont description file format[0m
       On typesetting output devices, each font is typically available at mul‐
       tiple  sizes.   While paper measurements in the device description file
       are in absolute units, measurements applicable to fonts must be propor‐
       tional to the type size.  [4mgroff[24m achieves this using the  precedent  set
       by  AT&T  device‐independent  [4mtroff[24m: one font size is chosen as a norm,
       and all others are scaled linearly relative to that basis.   The  “unit
       width” is the number of basic units per point when the font is rendered
       at this nominal size.

       For  instance,  [4mgroff[24m’s  [1mlbp [22mdevice uses a [1munitwidth [22mof 800.  Its Times
       roman font (“[1mTR[22m”) has a [1mspacewidth [22mof 833; this is also  the  width  of
       its  comma,  period,  centered period, and mathematical asterisk, while
       its “M” is 2,963 basic units.  Thus, an “M” on the [1mlbp [22mdevice is  2,963
       basic  units  wide  at  a notional type size of 800 points.  (800‐point
       type is not practical for most purposes, but using it enables the quan‐
       tities in the font description files to be expressed as integers.)

       A font description file has two sections.  The first is a  sequence  of
       directives,  and  is parsed similarly to the [4mDESC[24m file described above.
       Except for the directive names that begin the second section, their or‐
       dering is immaterial.  Later directives of the same name override  ear‐
       lier  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[0m
              requests  and escape sequences interpret non‐negative font names
              as mounting positions instead.  Further, a font named “[1m0[22m” cannot
              be automatically 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 basic units.

       The directives above must appear in the first section; those below  are
       optional.

       [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 imple‐
              mentations,  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 a  glyph  is  requested  that  is  not
              present  in  the current font, it is sought in any mounted fonts
              that bear this property.

       Other directives in this section are ignored by [4mgtroff[24m, but may be used
       by postprocessors to obtain further information about the font.

       The second section contains one or two subsections.  These  can  appear
       in  either  order;  the first one encountered commences the second sec‐
       tion.  Each starts with a directive on a line  by  itself.   A  [1mcharset[0m
       subsection  is  mandatory  unless the associated [4mDESC[24m file contains the
       [1municode [22mdirective.  Another subsection, [1mkernpairs[22m, is optional.

       The directive [1mcharset [22mstarts the character set subsection.  (For  type‐
       setter  devices,  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 [4mcode[24m [[4mentity‐name[24m] [[1m-- [4m[22mcomment[24m]

       [4mname[24m identifies the glyph: if [4mname[24m is a printable character [4mc[24m, it  cor‐
       responds to the [4mtroff[24m ordinary character [4mc[24m.  If [4mname[24m is a multi‐charac‐
       ter sequence not beginning with [1m\[22m, it corresponds to the GNU [4mtroff[24m spe‐
       cial  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 [22mand similar  re‐
       quests.  The [4mname[24m “[1m\-[22m” defines the minus sign glyph.  Finally, [4mname[24m can
       be the horizontal motion escape sequences, [1m\| [22mand [1m\^ [22m(“thin” and “hair”
       spaces,  respectively),  in  which case only the width metric 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]]]]]]]]]]

       There  must  not  be  any  spaces, tabs, or newlines between these [4msub‐[0m
       [4mfields,[24m which are in basic units expressed as  decimal  integers.   Un‐
       specified  subfields default to [1m0[22m.  Since there is no associated binary
       format, these values are not required to fit into the C  language  data
       type [1mchar [22mas 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 (upwards is positive); if  a  glyph  does
       not extend above the baseline, it should be given a zero height, rather
       than  a  negative  height.   The  [4mdepth[24m subfield gives the depth of the
       glyph, that is, the distance below the baseline to which the glyph  ex‐
       tends  (downwards  is  positive);  if a glyph does not extend below the
       baseline, it should be given a  zero  depth,  rather  than  a  negative
       depth.   Italic corrections are relevant to glyphs in italic or oblique
       styles.  The [4mitalic‐correction[24m is the amount of space  that  should  be
       added  after  an oblique glyph to be followed immediately by an upright
       glyph.  The [4mleft‐italic‐correction[24m is the amount of space  that  should
       be  added  before an oblique glyph to be preceded immediately by an up‐
       right glyph.  The [4msubscript‐correction[24m is  the  amount  of  space  that
       should  be  added after an oblique glyph to be followed by a subscript;
       it should be less than the italic correction.

       For fonts used with typesetting devices, the [4mtype[24m field gives  a  feat‐
       ural  description  of the glyph: it is a bit mask recording whether the
       glyph is an ascender, descender, both, or neither.  When  a  [1m\w  [22mescape
       sequence  is  interpolated, these values are bitwise or‐ed together for
       each glyph and stored in the [1mct [22mregister.   In  font  descriptions  for
       terminal  devices,  all glyphs might have a type of zero, regardless of
       their appearance.

       0      means the glyph lies entirely between the baseline and  a  hori‐
              zontal 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 [4mcode[24m field gives a numeric identifier that the  postprocessor  uses
       to  render  the  glyph.  The glyph can be specified to [4mtroff[24m using this
       code by means of the [1m\N [22mescape sequence.  The code can be  any  integer
       (that  is,  any  integer parsable by the C standard library’s [4mstrtol[24m(3)
       function).

       The [4mentity‐name[24m field defines an identifier  for  the  glyph  that  the
       postprocessor  uses  to print the [4mgtroff[24m glyph [4mname[24m.  This field is op‐
       tional; it was introduced so that the [4mgrohtml[24m output driver  could  en‐
       code 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 di‐
       rectly into [4mgrohtml[24m.  [4mgrops[24m 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.

       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 preced‐
       ing line.  Such aliases can be chained.

       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 formatted 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.   Most  kerning
       pairs should have a negative value for [4mn[24m.

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

       [4m/usr/pkg/share/groff/1.23.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
       Lemberg, 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 output
       format 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 addi‐
       tional insights into the device and font description file  formats  and
       device‐independent output format.

       [4mgroff[24m(1), subsection “Utilities”, lists programs available for describ‐
       ing  fonts  in  a variety of formats such that [4mgroff[24m output drivers can
       use them.

       [4mgtroff[24m(1) documents the default device and font description file search
       path.

       [4mgroff_out[24m(5), [4maddftinfo[24m(1)

groff 1.23.0                      2 July 2023                    [4mgroff_font[24m(5)
───────────────────────────────────────────────────────────────────────────────
[4mgroff_out[24m(5)                  File Formats Manual                 [4mgroff_out[24m(5)

[1mName[0m
       groff_out - GNU [4mroff[24m intermediate output format

[1mDescription[0m
       The fundamental operation of the [4mgtroff[24m(1) formatter is the translation
       of the [4mgroff[24m(7) input language into a series of instructions  concerned
       primarily  with  placing  glyphs or geometric objects at specific posi‐
       tions on a rectangular page.  In the  following  discussion,  the  term
       [4mcommand[24m  refers  to  this  intermediate  output  language, never to the
       [4mgroff[24m(7) language intended for use by document  authors.   Intermediate
       output commands comprise several categories: glyph output; font, color,
       and text size selection; motion of the printing position; page advance‐
       ment;  drawing  of geometric primitives; and device control commands, a
       catch‐all for other operations.  The last includes directives to  start
       and stop output, identify the intended output device, and embed URL hy‐
       perlinks in supported output formats.

       Because  the front‐end command [4mgroff[24m(1) is a wrapper that normally runs
       the [4mgtroff[24m formatter to generate intermediate output and an output dri‐
       ver (“postprocessor”) to consume it, users normally  do  not  encounter
       this  language.   The [4mgroff[24m program’s [1m-Z [22moption inhibits postprocessing
       such that this intermediate output  is  sent  to  the  standard  output
       stream as when [4mgtroff[24m is run manually.

       [4mgroff[24m’s  intermediate output facilitates the development of output dri‐
       vers and other postprocessors by offering a common  programming  inter‐
       face.  It is an extension of the page description language developed by
       Brian  Kernighan for AT&T device‐independent [4mtroff[24m circa 1980.  Where a
       distinction is necessary, we will say “[4mgtroff[24m output” to  describe  the
       output  of  GNU [4mtroff[24m, and “intermediate output” to denote the language
       accepted by the parser implemented in [4mgroff[24m’s internal C++ library used
       by most of its output drivers.

[1mLanguage concepts[0m
       During the run of [4mgtroff[24m, the [4mroff[24m input is cracked down to the  infor‐
       mation  on  what has to be printed at what position on the intended de‐
       vice.  So the language of the [4mintermediate[24m [4moutput[24m format can  be  quite
       small.   Its  only elements are commands with or without arguments.  In
       this document, the term “command” always  refers  to  the  [4mintermediate[0m
       [4moutput[24m  language,  never to the [4mroff[24m language used for document format‐
       ting.  There are commands for positioning and text writing,  for  draw‐
       ing, and for device controlling.

   [1mSeparation[0m
       [4mClassical[24m  [4mtroff[24m  [4moutput[24m  had  strange requirements on whitespace.  The
       [4mgroff[24m output parser, however, is smart about whitespace  by  making  it
       maximally  optional.   The whitespace characters, i.e., the [4mtab[24m, [4mspace[24m,
       and [4mnewline[24m characters, always have a syntactical  meaning.   They  are
       never printable because spacing within the output is always done by po‐
       sitioning commands.

       Any  sequence of [4mspace[24m or [4mtab[24m characters is treated as a single [4msyntac‐[0m
       [4mtical[24m [4mspace[24m.  It separates commands and arguments, but is only required
       when there would occur a clashing between the command code and the  ar‐
       guments  without  the  space.   Most  often, this happens when variable
       length command names, arguments, argument lists,  or  command  clusters
       meet.   Commands  and  arguments with a known, fixed length need not be
       separated by [4msyntactical[24m [4mspace[24m.

       A line break is a syntactical element, too.  Every command argument can
       be followed by whitespace, a comment, or a newline character.   Thus  a
       [4msyntactical[24m  [4mline[24m  [4mbreak[24m  is defined to consist of optional [4msyntactical[0m
       [4mspace[24m that is optionally followed by a comment, and a  newline  charac‐
       ter.

       The  normal commands, those for positioning and text, consist of a sin‐
       gle letter taking a fixed number of arguments.  For historical reasons,
       the parser allows stacking of such commands on the same line, but  for‐
       tunately, in [4mgroff[24m [4mintermediate[24m [4moutput[24m, every command with at least one
       argument  is  followed  by a line break, thus providing excellent read‐
       ability.

       The other commands — those for drawing and device controlling — have  a
       more complicated structure; some recognize long command names, and some
       take  a variable number of arguments.  So all [1mD [22mand [1mx [22mcommands were de‐
       signed to request a [4msyntactical[24m [4mline[24m [4mbreak[24m after their  last  argument.
       Only  one  command, ‘[1mx X[22m’ has an argument that can stretch over several
       lines, all other commands must have all of their arguments on the  same
       line  as  the  command,  i.e., the arguments may not be split by a line
       break.

       Lines containing only spaces and/or a comment are treated as empty  and
       ignored.

   [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 “[1mz[22m”
       (scaled points); These are defined by the parameters specified  in  the
       device’s  [4mDESC[24m  file; see [4mgroff_font[24m(5) and, for more on scaling units,
       [4mgroff[24m(7) 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 always 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
       argument  is  already terminated by the next non‐digit character, which
       then is regarded as the first character of the next  argument  or  com‐
       mand.

   [1mDocument parts[0m
       A  correct [4mintermediate[24m [4moutput[24m document consists of two parts, the [4mpro‐[0m
       [4mlogue[24m and the [4mbody[24m.

       The task of the [4mprologue[24m is to set the general device parameters  using
       three  exactly specified commands.  The [4mgroff[24m [4mprologue[24m is guaranteed to
       consist of the following three lines (in that order):

              [1mx T [4m[22mdevice[0m
              [1mx res [4m[22mn[24m [4mh[24m [4mv[0m
              [1mx init[0m

       with the arguments set as outlined in subsection “Device  Control  Com‐
       mands”  below.   However, the parser for the [4mintermediate[24m [4moutput[24m format
       is able to swallow additional whitespace and comments as well.

       The [4mbody[24m is the main section for processing the document data.  Syntac‐
       tically, it is a sequence of any commands different from the ones  used
       in  the [4mprologue[24m.  Processing is terminated as soon as the first [1mx stop[0m
       command is encountered; the last line of any [4mgroff[24m [4mintermediate[24m  [4moutput[0m
       always contains such a command.

       Semantically,  the  [4mbody[24m  is page oriented.  A new page is started by a
       [1mp [22mcommand.  Positioning, writing, and drawing commands are always  done
       within  the  current page, so they cannot occur before the first [1mp [22mcom‐
       mand.  Absolute positioning (by the [1mH [22mand [1mV [22mcommands) is done  relative
       to the current page, all other positioning is done relative to the cur‐
       rent location within this page.

[1mCommand reference[0m
       This  section describes all [4mintermediate[24m [4moutput[24m commands, the classical
       commands as well as the [4mgroff[24m extensions.

   [1mComment command[0m
       [1m#[4m[22manything[24m⟨line‐break⟩
              A comment.  Ignore any characters from the [1m# [22mcharacter up to the
              next newline.  Each comment can be preceded by arbitrary [4msyntac‐[0m
              [4mtical[24m [4mspace[24m; 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 whitespace.  Optionally, [4msyntactical[24m [4mspace[24m can  be  inserted  be‐
       fore,  after, and between the command letter and its arguments.  All of
       these commands are stackable, i.e., they can be preceded by other  sim‐
       ple  commands or followed by arbitrary other commands on the same line.
       A separating [4msyntactical[24m [4mspace[24m is necessary only when two integer argu‐
       ments would clash or if the preceding argument ends with a string argu‐
       ment.

       [1mC [4m[22mid[24m⟨white‐space⟩
              Typeset the glyph of the special character [4mid[24m.  Trailing syntac‐
              tical space is necessary to allow special character names of ar‐
              bitrary length.  The drawing position is not advanced.

       [1mc [4m[22mc[24m    Typeset the glyph of the ordinary character  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 al‐
              lowed negative [4mn;[24m GNU [4mtroff[24m does not produce  such  values,  but
              [4mgroff[24m’s output 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 be‐
                     tween 0 (black) and 65536 (white).

              [1mmk [4m[22mcyan[24m [4mmagenta[24m [4myellow[24m [4mblack[0m
                     Use  the CMYK color scheme with components cyan, magenta,
                     yellow, 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 nor‐
              mally a non‐negative integer.  The drawing position is  not  ad‐
              vanced.   The [1mhtml [22mand [1mxhtml [22mdevices use this command with nega‐
              tive [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[0m
              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 ignores it.  See [1mv [22mand [1mV[22m.

       [1mp [4m[22mn[24m    Begin  a  new page, setting its number to [4mn[24m.  Each page is inde‐
              pendent, even from those using the same  number.   The  vertical
              drawing  position  is  set  to 0.  All positioning, writing, and
              drawing commands 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[24m used unscaled points ([1mp[22m) instead; see section “Compatibil‐
              ity” 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 op‐
              tional second integer argument is ignored (this allows the  for‐
              matter  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 horizon‐
              tal motion quantum.  Use the [1mC [22mcommand to emplace glyphs of spe‐
              cial characters.  The [1mt [22mcommand is a [4mgroff[24m extension and is out‐
              put  only  for devices whose [4mDESC[24m file contains the [1mtcommand [22mdi‐
              rective; see [4mgroff_font[24m(5).

       [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 horizon‐
              tally by [4mn[24m basic units.  The [1mu [22mcommand is a [4mgroff[24m extension  and
              is output only for devices whose [4mDESC[24m file contains the [1mtcommand[0m
              directive; see [4mgroff_font[24m(5).

       [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  al‐
              lowed  negative  [4mn;[24m  GNU [4mtroff[24m does not produce such values, but
              [4mgroff[24m’s output driver library handles them.

       [1mw      [22mIndicate an inter‐word space.  No action is performed; the  com‐
              mand is present to make the output more easily parsed.  Only ad‐
              justable,  breakable inter‐word spaces are thus described; those
              resulting from [1m\~ [22mor horizontal motion escape sequences are not.
              GNU [4mtroff[24m issues this command but [4mgroff[24m’s output driver  library
              ignores it.  See [1mh [22mand [1mH[22m.

   [1mGraphics commands[0m
       Each graphics or drawing command in the [4mintermediate[24m [4moutput[24m starts with
       the  letter  [1mD [22mfollowed by one or two characters that specify a subcom‐
       mand; this is followed by a fixed or variable number of  integer  argu‐
       ments  that are separated by a single space character.  A [1mD [22mcommand may
       not be followed by another command on the same line (apart from a  com‐
       ment), so each [1mD [22mcommand is terminated by a [4msyntactical[24m [4mline[24m [4mbreak[24m.

       [4mgtroff[24m  output  follows  the  classical spacing rules (no space between
       command and subcommand, all arguments are preceded by  a  single  space
       character),  but  the  parser allows optional space between the command
       letters 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,  negative  left.  The [4mv[24m arguments stand for vertical dis‐
       tances where positive means down, negative up.  All these distances are
       offsets relative to the current location.

       Unless indicated otherwise, each graphics command directly  corresponds
       to a similar [4mgroff[24m [1m\D [22mescape sequence; see [4mgroff[24m(7).

       Unknown  [1mD  [22mcommands  are assumed to be device‐specific.  Its arguments
       are parsed as strings; the whole information is then sent to the  post‐
       processor.

       In  the  following  command  reference, the syntax element [4m⟨line‐break⟩[0m
       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
              offset ([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
              position;  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 argu‐
              ments).  This command is a [4mgroff[24m 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
              position 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
              diameter of [4mh[24m and a vertical diameter of [4mv[24m (both integers in ba‐
              sic  units  [1mu[22m)  with the leftmost point at the current position;
              then move to the rightmost point of the ellipse.   This  command
              is a [4mgroff[24m extension.

       [1mDe [4m[22mh[24m [4mv[24m⟨line‐break⟩
              Draw  an  outlined ellipse with a horizontal diameter of [4mh[24m and a
              vertical diameter of [4mv[24m (both integers in basic units [1mu[22m) with the
              leftmost 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 components 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 gener‐
              ated by the [4mgroff[24m escape sequences [1m\D'F [22m...[1m’  [22mand  [1m\M  [22m(with  no
              other corresponding graphics commands).  This command is a [4mgroff[0m
              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,  ma‐
                     genta, and yellow.

              [1mDFd [22m⟨line‐break⟩
                     Set  fill  color for solid drawing objects to the default
                     fill color value (black in most cases).  No component ar‐
                     guments.

              [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, ma‐
                     genta, 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 is obsoleted by command
                     [1mDFg[22m.

              [4mn[24m<0 or [4mn[24m>1000
                     Set  the filling color to the color that is currently be‐
                     ing used for the text and the  outline,  see  command  [1mm[22m.
                     For example, the command sequence

                            mg 0 0 65536
                            Df -1

                     sets all colors to blue.

              This command is a [4mgroff[24m 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 rea‐
              sons, the position is changed by adding the sum of all arguments
              with odd index to the current horizontal position and  the  even
              ones to the vertical position.  Although this doesn’t make sense
              it  is  kept  for compatibility.  This command is a [4mgroff[24m exten‐
              sion.

       [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 ar‐
              guments, 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 [4mgroff[24m 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 com‐
              patibility.  This command is a [4mgroff[24m extension.

   [1mDevice control commands[0m
       Each device control command starts with the  letter  [1mx  [22mfollowed  by  a
       space  character  (optional or arbitrary space/tab in [4mgroff[24m) and a sub‐
       command letter or word; each argument (if any) must be  preceded  by  a
       [4msyntactical[24m [4mspace[24m.  All [1mx [22mcommands are terminated by a [4msyntactical[24m [4mline[0m
       [4mbreak[24m;  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  readabil‐
       ity,  it can be written as a word, i.e., an arbitrary sequence of char‐
       acters terminated by the next tab, space, or  newline  character.   All
       characters  of  the  subcommand  word but the first are simply ignored.
       For example, [4mgtroff[24m outputs the initialization command  [1mx i  [22mas  [1mx init[0m
       and   the   resolution   command  [1mx r  [22mas  [1mx res[22m.   But  writings  like
       [1mx i_like_groff [22mand [1mx roff_is_groff [22mare accepted as  well  to  mean  the
       same commands.

       In  the  following, the syntax element [4m⟨line‐break⟩[24m means a [4msyntactical[0m
       [4mline[24m [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  re‐
              ports.   This  is  useful for remembering the original file name
              when [4mgroff[24m uses an internal piping mechanism.  The input file is
              not changed by this command.  This command is a [4mgroff[24m 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[0m
              (a text word); see [4mgroff_font[24m(5).

       [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 “Compatibility” below.

       [1mxi [22m⟨line‐break⟩
              ([4minit[24m control command)
              Initialize device.  This is the third command of the [4mprologue[24m.

       [1mxp [22m⟨line‐break⟩
              ([4mpause[24m control command)
              Parsed but ignored.  The classical documentation reads [4mpause[24m [4mde‐[0m
              [4mvice,[24m [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[0m
              the minimal vertical motion possible with this device; all argu‐
              ments are positive integers in basic units [1mu [22mper inch.  This  is
              the second command of the [4mprologue[24m.

       [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 any [4mintermediate[24m [4mgtroff[24m [4moutput[24m.

       [1mxt [22m⟨line‐break⟩
              ([4mtrailer[24m control command)
              Generate trailer information, if any.  In [1mgroff[22m,  this  is  cur‐
              rently 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‐
              whitespace characters terminated by  whitespace.   The  possible
              names  correspond  to  those  of [4mgroff[24m’s [1m-T [22moption.  This is the
              first command of the prologue.

       [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 [1mgnroff [22mmode and is  ignored  other‐
              wise.  This command is a [4mgroff[24m extension.

       [1mxX [4m[22manything[24m⟨line‐break⟩
              ([4mX‐escape[24m control command)
              Send  string  [4manything[24m uninterpreted to the device.  If the line
              following this command starts with a [1m+ [22mcharacter  this  line  is
              interpreted  as a continuation line in the following sense.  The
              [1m+ [22mis ignored, but a newline character is sent instead to the de‐
              vice, the rest of the line is sent uninterpreted.  The same  ap‐
              plies to all following lines until the first character of a line
              is  not  a  [1m+ [22mcharacter.  This command is generated by the [4mgroff[0m
              escape sequence [1m\X[22m.  The line‐continuing feature is a [4mgroff[24m  ex‐
              tension.

   [1mObsolete command[0m
       In [4mclassical[24m [4mtroff[24m output, emitting a single glyph was mostly done by a
       very  strange  command that combined a horizontal move and the printing
       of a glyph.  It didn’t have a command code, but  is  represented  by  a
       3‐character argument consisting of exactly 2 digits and a character.

       [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 sep‐
              arating space is obligatory.  In [4mclassical[24m [4mtroff[24m, large clusters
              of these and other commands were used,  mostly  without  spaces;
              this made such output almost unreadable.

       For  modern  high‐resolution  devices, this command does not make sense
       because the width of the glyphs can become much larger than two decimal
       digits.  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 [22mprovide  greater
       functionality and superior troubleshooting capacity.

[1mPostprocessing[0m
       The  [4mroff[24m  postprocessors  are programs that have the task to translate
       the [4mintermediate[24m [4moutput[24m into actions that are sent to a device.  A  de‐
       vice  can  be  some  piece of hardware such as a printer, or a software
       file format suitable for graphical or text processing.  The [4mgroff[24m  sys‐
       tem  provides  powerful  means  that make the programming of such post‐
       processors an easy task.

       There is a library function that parses  the  [4mintermediate[24m  [4moutput[24m  and
       sends  the  information  obtained  to the device via methods of a class
       with a common interface for each device.  So a [4mgroff[24m postprocessor must
       only redefine the methods of this class.  For details, see  the  refer‐
       ence in section “Files” below.

[1mExample[0m
       This  section  presents the [4mintermediate[24m [4moutput[24m generated from the same
       input for three different devices.  The  input  is  the  sentence  [4mhell[0m
       [4mworld[24m fed into [4mgroff[24m on the command line.

       • High‐resolution device [4mps[0m

         shell> [1mecho "hell world" | groff -Z -T ps[0m

         x T ps
         x res 72000 1 1
         x init
         p1
         x font 5 TR
         f5
         s10000
         V12000
         H72000
         thell
         wh2500
         tw
         H96620
         torld
         n12000 0
         x trailer
         V792000
         x stop

       This  output can be fed into the postprocessor [4mgrops[24m(1) to get its rep‐
       resentation as a PostScript file, or [4mgropdf[24m(1) to  output  directly  to
       PDF.

       • Low‐resolution device [4mlatin1[0m

         This  is  similar to the high‐resolution device except that the posi‐
         tioning is done at a minor scale.  Some comments (lines starting with
         [4m#[24m) were added for clarification; they were not generated by the  for‐
         matter.

         [1mshell> [22m"hell world" | groff -Z -T latin1

         [4m#[24m [4mprologue[0m
         x T latin1
         x res 240 24 40
         x init
         [4m#[24m [4mbegin[24m [4ma[24m [4mnew[24m [4mpage[0m
         p1
         [4m#[24m [4mfont[24m [4msetup[0m
         x font 1 R
         f1
         s10
         [4m#[24m [4minitial[24m [4mpositioning[24m [4mon[24m [4mthe[24m [4mpage[0m
         V40
         H0
         [4m#[24m [4mwrite[24m [4mtext[24m [4m'hell'[0m
         thell
         [4m#[24m [4minform[24m [4mabout[24m [4ma[24m [4mspace,[24m [4mand[24m [4mdo[24m [4mit[24m [4mby[24m [4ma[24m [4mhorizontal[24m [4mjump[0m
         wh24
         [4m#[24m [4mwrite[24m [4mtext[24m [4m'world'[0m
         tworld
         [4m#[24m [4mannounce[24m [4mline[24m [4mbreak,[24m [4mbut[24m [4mdo[24m [4mnothing[24m [4mbecause[24m [4m...[0m
         n40 0
         [4m#[24m [4m...[24m [4mthe[24m [4mend[24m [4mof[24m [4mthe[24m [4mdocument[24m [4mhas[24m [4mbeen[24m [4mreached[0m
         x trailer
         V2640
         x stop

       This  output  can be fed into the postprocessor [4mgrotty[24m(1) to get a for‐
       matted text document.

       • Classical style output

         As a computer monitor has a very low resolution  compared  to  modern
         printers  the [4mintermediate[24m [4moutput[24m for the X devices can use the jump‐
         and‐write command with its 2‐digit displacements.

         [1mshell> [22m"hell world" | groff -Z -T X100

         x T X100
         x res 100 1 1
         x init
         p1
         x font 5 TR
         f5
         s10
         V16
         H100
         [4m#[24m [4mwrite[24m [4mtext[24m [4mwith[24m [4mold‐style[24m [4mjump‐and‐write[24m [4mcommand[0m
         ch07e07l03lw06w11o07r05l03dh7
         n16 0
         x trailer
         V1100
         x stop

       This  output  can  be  fed  into  the  postprocessor  [4mxditview[24m(1x)   or
       [4mgxditview[24m(1) for displaying in X.

       Due  to  the  obsolete jump‐and‐write command, the text clusters in the
       classical output are almost unreadable.

[1mCompatibility[0m
       The [4mintermediate[24m [4moutput[24m language of the [4mclassical[24m [4mtroff[24m was first docu‐
       mented in [CSTR #97].  The [4mgroff[24m [4mintermediate[24m [4moutput[24m format is compati‐
       ble with this specification except for the following features.

       • The classical quasi device independence is not yet implemented.

       • The old hardware was very different from what we use today.   So  the
         [4mgroff[24m devices are also fundamentally different from the ones in [4mclas‐[0m
         [4msical[24m [4mtroff[24m.  For example, the classical PostScript device was called
         [4mpost[24m and had a resolution of 720 units per inch, while [4mgroff[24m’s [4mps[24m de‐
         vice  has a resolution of 72000 units per inch.  Maybe, by implement‐
         ing some rescaling mechanism similar to the  classical  quasi  device
         independence, these could be integrated into modern [4mgroff[24m.

       • The B‐spline command [1mD~ [22mis correctly handled by the [4mintermediate[24m [4mout‐[0m
         [4mput[24m  parser,  but  the drawing routines aren’t implemented in some of
         the postprocessor programs.

       • The argument of the commands [1ms [22mand [1mx H [22mhas the implicit  unit  scaled
         point [1mz [22min [4mgroff[24m, while [4mclassical[24m [4mtroff[24m had point ([1mp[22m).  This isn’t an
         incompatibility,  but a compatible extension, for both units coincide
         for all devices without a [4msizescale[24m parameter, including all  classi‐
         cal  and  the  [4mgroff[24m  text  devices.   The  few  [4mgroff[24m devices with a
         sizescale parameter either did not exist, had a  different  name,  or
         seem to have had a different resolution.  So conflicts with classical
         devices are very unlikely.

       • The position changing after the commands [1mDp[22m, [1mDP[22m, and [1mDt [22mis illogical,
         but as old versions of groff used this feature it is kept for compat‐
         ibility reasons.

       The  differences  between  [4mgroff[24m  and [4mclassical[24m [4mtroff[24m are documented in
       [4mgroff_diff[24m(7).

[1mFiles[0m
       [4m/usr/pkg/share/groff/1.23.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 output
       format and that of  GNU  [4mroff[24m.   The  present  version  was  completely
       rewritten in 2001 by Bernd Warken ⟨groff-bernd.warken-72@web.de⟩.

[1mSee also[0m
       [4mGroff:[24m  [4mThe[24m  [4mGNU[24m [4mImplementation[24m [4mof[24m [4mtroff[24m, by Trent A. Fisher and Werner
       Lemberg, 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 output
       format 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 addi‐
       tional insights into the device and font description file  formats  and
       device‐independent output format.

       [4mgroff[24m(1)
              documents  the  [1m-Z [22moption and contains pointers to further [4mgroff[0m
              documentation.

       [4mgroff[24m(7)
              describes the [4mgroff[24m language, including its escape sequences and
              system of units.

       [4mgroff_font[24m(5)
              details the device scaling parameters of device [4mDESC[24m files.

       [4mgtroff[24m(1)
              generates the device‐independent intermediate output  documented
              here.

       [4mroff[24m(7)
              presents  historical  aspects  and the general structure of [4mroff[0m
              systems.

       [4mgroff_diff[24m(7)
              enumerates differences between the intermediate output  produced
              by AT&T [4mtroff[24m and that of [4mgroff[24m.

       [4mgxditview[24m(1)
              is a viewer for intermediate output.

       [4mRoff.js[0m
              ⟨https://github.com/Alhadis/Roff.js/⟩ is a viewer for intermedi‐
              ate output written in JavaScript.

       [4mgrodvi[24m(1),  [4mgrohtml[24m(1),  [4mgrolbp[24m(1), [4mgrolj4[24m(1), [4mgropdf[24m(1), [4mgrops[24m(1), and
       [4mgrotty[24m(1) are [4mgroff[24m postprocessors.

groff 1.23.0                      2 July 2023                     [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 [4mroff[24m(7) doc‐
       ument 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[24m document; only its purpose distinguishes it.
       When a macro file is installed 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.  Macro packages can be loaded by supplying
       the [1m-m [22moption to [4mgtroff[24m(1) or a [4mgroff[24m front end.

       Each macro package stores its macro, string, and  register  definitions
       in  one or more [4mtmac[24m files.  This name originated in early Unix culture
       as an abbreviation of “[4mtroff[24m macros”.

       A macro file must have a name in the form name[4m.tmac[24m (or [4mtmac.[24mname)  and
       be  placed in a “[4mtmac[24m directory” to be loadable with the [1m-m[4m[22mname[24m option.
       Section “Environment” of [4mgtroff[24m(1) lists these  directories.   Alterna‐
       tively,  a  [4mgroff[24m  document requiring a macro file can load it with the
       [1mmso [22m(“macro source”) request.

       Like any other [4mroff[24m document, a macro file can  use  the  “[1mso[22m”  request
       (“source”) to load further files relative to its own location.

       Macro  files  are  named  for  their most noteworthy application, but a
       macro file need not define any  macros.   It  can  restrict  itself  to
       defining  registers  and  strings or invoking other [4mgroff[24m requests.  It
       can even be empty.

[1mMacro packages[0m
       Macro packages come in two varieties; those which assume responsibility
       for page layout and other critical  functions  (“major”  or  “full‐ser‐
       vice”)  and  those  which  do not (“supplemental” or “auxiliary”).  GNU
       [4mroff[24m provides most major macro packages found in AT&T and BSD Unix sys‐
       tems, an additional full‐service package, and many  supplemental  pack‐
       ages.   Multiple full‐service macro packages cannot be used by the same
       document.  Auxiliary packages can generally 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 was a significant challenge in AT&T
       [4mtroff[24m; [4mgroff[24m’s support for arbitrarily long identifiers affords few ex‐
       cuses for name collisions, apart from attempts  at  compatibility  with
       the demands of historical documents.

   [1mMan pages[0m
       [4man[0m
       [4mman[24m    [4man[24m  is  used  to  compose man pages in the format originating in
              Version 7 Unix (1979).  It has a small macro  interface  and  is
              widely used; see [4mgroff_man[24m(7).

       [4mdoc[0m
       [4mmdoc[24m   [4mdoc[24m  is  used  to compose man pages in the format originating in
              4.3BSD‐Reno (1990).  It provides many more features than [4man[24m, but
              is also larger, more complex, and not  as  widely  adopted;  see
              [4mgroff_mdoc[24m(7).

       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[0m
       [4mmandoc[24m This macro file, specific to [4mgroff[24m, recognizes whether  a  docu‐
              ment  uses  [4mman[24m or [4mmdoc[24m format and loads the corresponding macro
              package.  Multiple man pages, in either format, can be  handled;
              [4mandoc[24m reloads each macro package as necessary.

   [1mFull‐service packages[0m
       The packages in this section provide a complete set of macros for writ‐
       ing  documents  of  any  kind,  up to whole books.  They are similar in
       functionality; it is a matter of taste which one to use.

       [4mme[24m     The classical [4mme[24m macro package; see [4mgroff_me[24m(7).

       [4mmm[24m     The semi‐classical [4mmm[24m macro package; see [4mgroff_mm[24m(7).

       [4mmom[24m    The [4mmom[24m macro package, only available in groff.  As this was not
              based on other packages, it was freely designed as quite a nice,
              modern macro package.  See [4mgroff_mom[24m(7).

       [4mms[24m     The classical [4mms[24m macro package; see [4mgroff_ms[24m(7).

   [1mLocalization packages[0m
       For Western languages, the localization file sets the hyphenation  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 additional inter‐sentence
       space.  For Eastern languages, the localization file defines  character
       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 en‐
              coding 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  en‐
              coding to Latin‐1 by loading [4mlatin1.tmac[24m.

              [4mde.tmac[24m  selects  hyphenation patterns for traditional orthogra‐
              phy, and [4mden.tmac[24m does the same for the new orthography (“Recht‐
              schreibreform”).

       [4men[24m     English.

       [4mfr[24m     French; localizes [4mman[24m, [4mme[24m, [4mmm[24m, [4mmom[24m, and [4mms[24m.  Sets the input  en‐
              coding to Latin‐9 by loading [4mlatin9.tmac[24m.

       [4mit[24m     Italian; localizes [4mman[24m, [4mme[24m, [4mmm[24m, [4mmom[24m, and [4mms[24m.

       [4mja[24m     Japanese.

       [4msv[24m     Swedish; localizes [4mman[24m, [4mme[24m, [4mmm[24m, [4mmom[24m, and [4mms[24m.  Sets the input en‐
              coding to Latin‐1 by loading [4mlatin1.tmac[24m.  Some of the localiza‐
              tion of the [4mmm[24m package is handled separately; see [4mgroff_mmse[24m(7).

       [4mzh[24m     Chinese.

   [1mInput encodings[0m
       [4mlatin1[0m
       [4mlatin2[0m
       [4mlatin5[0m
       [4mlatin9[24m are  various  ISO  8859  input encodings supported by [4mgroff[24m.  On
              systems using ISO character encodings, [4mgroff[24m  loads  [4mlatin1.tmac[0m
              automatically   at  startup.   A  document  that  uses  Latin‐2,
              Latin‐5, or Latin‐9 can specify one of these alternative  encod‐
              ings.

       [4mcp1047[24m provides  support for EBCDIC‐based systems.  On those platforms,
              [4mgroff[24m loads [4mcp1047.tmac[24m automatically at startup.

       Because different input character codes constitute valid GNU [4mtroff[24m  in‐
       put  on ISO and EBCDIC systems, the [4mlatin[24m macro files cannot be used on
       EBCDIC systems, and [4mcp1047[24m cannot be used on ISO systems.

   [1mAuxiliary 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  [4mgtbl[24m(1).   It works only with the [1mps [22mand [1mpdf [22moutput
              devices.  See [4mgroff_hdtbl[24m(7).

       [4mpapersize[0m
              enables the paper format to be set on the command line by giving
              a “[1m-d paper=[4m[22mformat[24m” option to [4mgtroff[24m.  Possible values for  [4mfor‐[0m
              [4mmat[24m  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 en‐
              velopes, are in portrait orientation: the length measurement  is
              vertical.  Appending “l” (ell) to any of these denotes landscape
              orientation  instead.  This macro file assumes one‐inch horizon‐
              tal margins, and sets registers recognized  by  the  [4mgroff[24m  [4mman[24m,
              [4mmdoc[24m,  [4mmm[24m,  [4mmom[24m,  and [4mms[24m packages to configure them accordingly.
              If you want different margins, you will need to use those  pack‐
              ages’  facilities,  or  [4mgtroff[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, re‐
              spectively, defined in its [4mDESC[24m file; see subsection “Paper for‐
              mat” of [4mgroff[24m(1).  This macro file is normally loaded at startup
              by the [4mtroffrc[24m file when formatting  for  a  typesetting  device
              (but not a terminal).

       [4mpdfpic[24m provides  a  single macro, [1mPDFPIC[22m, to include a PDF graphic in a
              document using features of the [1mpdf  [22moutput  driver.   For  other
              output  devices, [1mPDFPIC [22mcalls [1mPSPIC[22m, with which it shares an in‐
              terface (see below).  This macro  file  is  normally  loaded  at
              startup by the [4mtroffrc[24m file.

       [4mpic[24m    supplies  definitions  of the macros [1mPS[22m, [1mPE[22m, and [1mPF[22m, usable with
              the [4mgpic[24m(1) 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 [4mptx[24m(1) program.  If your formatting needs dif‐
              fer, copy the macro into your document  and  adapt  it  to  your
              needs.

       [4mrfc1345[0m
              defines  special  character escape sequences named for the glyph
              mnemonics specified in RFC 1345 and the digraph table of the Vim
              text editor.  See [4mgroff_rfc1345[24m(7).

       [4msboxes[24m offers an interface to the “[1mpdf: background[22m” device control com‐
              mand supported by [4mgropdf[24m(1).  Using this package, [4mgroff[24m [4mms[24m docu‐
              ments 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 which 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 [4mgroff_ms[24m(7) 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   “Using   PDF   boxes   with   [4mgroff[24m  and  the  [4mms[24m  macros”
              ⟨file:///usr/pkg/share/doc/groff-1.23.0/msboxes.pdf⟩    for    a
              demonstration.

       [4mtrace[24m  aids  the  debugging  of [4mgroff[24m documents by tracing macro calls.
              See [4mgroff_trace[24m(7).

       [4mwww[24m    defines   macros   corresponding   to   HTML   elements.     See
              [4mgroff_www[24m(7).

[1mNaming[0m
       AT&T  [4mnroff[24m  and  [4mtroff[24m  were implemented before the conventions of the
       modern C [4mgetopt[24m(3) call evolved, and used a  naming  scheme  for  macro
       packages  that looks odd to modern eyes.  Macro packages were typically
       loaded using the [1m-m [22moption to the formatter; when directly followed  by
       its  argument without an intervening space, this looked like a long op‐
       tion preceded 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.

       [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 sur‐
       prise 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 accommodates different users’ expectations by supplying
       wrapper macro files that load  the  desired  file  with  [1mmso  [22mrequests.
       Thus, all of “[1mgroff -m s[22m”, “[1mgroff -m ms[22m”, “[1mgroff -ms[22m”, and “[1mgroff -mms[22m”
       serve to load the manuscript macros.

       Wrappers  are  not  provided  for packages of more recent vintage, like
       [4mwww.tmac[24m.

       As noted in passing above, AT&T [4mtroff[24m named macro  files  in  the  form
       [4mtmac.[24mname.   It  has  since become conventional in operating systems to
       use a suffixed file name extension to suggest a file type or format.

[1mInclusion[0m
       The traditional method of employing a macro package is to  specify  the
       [1m-m  [4m[22mpackage[24m  option  to the formatter, which then reads [4mpackage[24m’s macro
       file prior to any input files.  Historically, [4mpackage[24m was sought  in  a
       file  named  [4mtmac.[24mpackage  (that is, with a “[1mtmac.[22m” prefix).  GNU [4mtroff[0m
       searches for package[4m.tmac[24m in the macro path; if not found, it looks for
       [4mtmac.[24mpackage instead, and vice versa.

       Alternatively, one could include a macro file by using the request “[1m.so[0m
       [4mfile‐name[24m” in the document; [4mfile‐name[24m is resolved relative to the loca‐
       tion of the input document.  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; however,
       as a convenience, if opening it fails, [1mmso [22mstrips any such  suffix  and
       tries again with a “[1mtmac.[22m” prefix, and vice versa.

       If  a  sourced  file requires preprocessing, for example if it includes
       [4mtbl[24m tables or [4meqn[24m equations, the preprocessor [4mgsoelim[24m(1) must be  used.
       This can be achieved with a pipeline or, in [4mgroff[24m, by specifying the [1m-s[0m
       option to the formatter (or front end).  [4mman[24m(1) librarian programs gen‐
       erally  call  [4mgsoelim[24m automatically.  (Macro packages themselves gener‐
       ally do not require preprocessing.)

[1mWriting macros[0m
       A [4mroff[24m(7) document is a text file that is enriched by  predefined  for‐
       matting  constructs,  such  as requests, escape sequences, strings, nu‐
       meric registers, and macros from a macro package.  These  elements  are
       described in [4mroff[24m(7).

       To  give  a  document a personal style, it is most useful to extend the
       existing 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 [4mgroff[24m(7).

   [1mDraft mode[0m
       Writing groff macros is easy when the escaping mechanism is temporarily
       disabled.  In groff, this is done by enclosing the macro  definition(s)
       within a pair of [1m.eo [22mand [1m.ec [22mrequests.  Then the body in the macro def‐
       inition  is  just like a normal part of the document — text enhanced by
       calls of requests, macros, strings, registers, etc.  For  example,  the
       code above can be written in a simpler way by

              .eo
              .ds midpart was called with the following
              .de print_args
              \f[I]\$0\f[] \*[midpart] \n[.$] arguments:
              \$*
              ..
              .ec

       Unfortunately,  draft  mode cannot be used universally.  Although it is
       good enough for defining normal macros, draft mode fails with  advanced
       applications,  such  as indirectly defined strings, registers, etc.  An
       optimal way is to define and test all macros in draft mode and then  do
       the backslash doubling as a final step; do not forget to remove the [4m.eo[0m
       request.

   [1mTips for macro definitions[0m
       •      Start every line with a dot, for example, by using the groff re‐
              quest  [1m.nop [22mfor text lines, or write your own macro that handles
              also text lines with a leading dot.

                     .de Text
                     .  if (\\n[.$] == 0) \
                     .    return
                     .  nop \)\\$*\)
                     ..

       •      Write a comment macro that works both for copy and draft  modes;
              since  the  escape character is off in draft mode, trouble might
              occur when comment escape sequences are used.  For example,  the
              following  macro  just  ignores its arguments, so it acts like a
              comment line:

                     .de c
                     ..
                     .c This is like a comment line.

       •      In long macro definitions, make ample use of  comment  lines  or
              almost‐empty  lines (this is, lines which have a leading dot and
              nothing else) for a better structuring.

       •      To increase readability, use groff’s  indentation  facility  for
              requests and macro calls (arbitrary whitespace after the leading
              dot).

   [1mDiversions[0m
       Diversions  can  be  used  to implement quite advanced programming con‐
       structs.  They are comparable to pointers to large data  structures  in
       the C programming language, but their usage is quite different.

       In  their  simplest form, diversions are multi‐line strings, but diver‐
       sions get their power when used dynamically within macros.   The  (for‐
       matted)  information  stored in a diversion can be retrieved by calling
       the diversion just like a macro.

       Most of the problems arising with diversions can be avoided if you  re‐
       member  that  diversions always store complete lines.  Using diversions
       when the line buffer has not been flushed produces strange results; not
       knowing this, many people get desperate about  diversions.   To  ensure
       that  a  diversion  works,  add line breaks at the right places.  To be
       safe, enclose everything that has to do with diversions within  a  pair
       of  line  breaks;  for example, by explicitly using [1m.br [22mrequests.  This
       rule should be applied to diversion definition, both  inside  and  out‐
       side,  and  to all calls of diversions.  This is a bit of overkill, but
       it works nicely.

       (If you really need diversions which should ignore the current  partial
       line,  use environments to save the current partial line and/or use the
       [1m.box [22mrequest.)

       The most powerful feature using diversions  is  to  start  a  diversion
       within a macro definition and end it within another macro.  Then every‐
       thing  between each call of this macro pair is stored within the diver‐
       sion and can be manipulated from within the macros.

[1mAuthors[0m
       This document was written by  Bernd  Warken  ⟨groff-bernd.warken-72@web
       .de⟩,  Werner  Lemberg ⟨wl@gnu.org⟩, and G. Branden Robinson ⟨g.branden
       .robinson@gmail.com⟩.

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

       The Filesystem  Hierarchy  Standard  ⟨https://wiki.linuxfoundation.org/
       lsb/fhs⟩ is maintained by the Linux Foundation.

       [4mgroff[24m(1)
              is an overview of the [4mgroff[24m system.

       [4mgroff_man[24m(7),
       [4mgroff_mdoc[24m(7),
       [4mgroff_me[24m(7),
       [4mgroff_mm[24m(7),
       [4mgroff_mom[24m(7),
       [4mgroff_ms[24m(7),
       [4mgroff_rfc1345[24m(7),
       [4mgroff_trace[24m(7),
               and
       [4mgroff_www[24m(7)
              are [4mgroff[24m macro packages.

       [4mgroff[24m(7)
              summarizes the language recognized by GNU [4mtroff[24m.

       [4mtroff[24m(1)
              documents the default macro file search path.

groff 1.23.0                      2 July 2023                    [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 de‐
       vice‐independent [4mtroff[24m typesetting system.  See [4mroff[24m(7) for a survey of
       and background on [4mroff[24m systems.

       This document is intended as a reference.  The  primary  [4mgroff[24m  manual,
       [4mGroff:[24m  [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  discussion.  It is written in Texinfo; you can browse it in‐
       teractively with “info groff”.   Additional  formats,  including  plain
       text,     HTML,     DVI,    and    PDF,    may    be    available    in
       [4m/usr/pkg/share/doc/groff-1.23.0[24m.

       [4mgroff[24m is also a name for an extended dialect of the [4mroff[24m language.   We
       use  “roff”  to denote features that are universal, or nearly so, among
       implementations of this family.  We apply the term “groff” to the  lan‐
       guage  documented  here,  the GNU implementation of the overall system,
       the project that develops that system, and the command of that name.

       GNU [4mtroff[24m, installed on this system as [4mgtroff[24m(1), is the  [4mformatter:[24m  a
       program that reads device and font descriptions ([4mgroff_font[24m(5)), inter‐
       prets  the [4mgroff[24m language expressed in text input files, and translates
       that input into a device‐independent output format ([4mgroff_out[24m(5))  that
       is  usually  then  post‐processed  by an output driver to produce Post‐
       Script, PDF, HTML, DVI, or terminal output.

[1mInput format[0m
       Input to GNU [4mtroff[24m is organized into lines separated by the  Unix  new‐
       line  character (U+000A), and must be in one of two character encodings
       it can recognize: IBM code page 1047 on EBCDIC systems, and ISO Latin‐1
       (8859‐1) otherwise.  Use of ISO 646‐1991:IRV (“US‐ASCII”)  or  (equiva‐
       lently)  the  “Basic  Latin”  subset of ISO 10646 (“Unicode”) is recom‐
       mended; see  [4mgroff_char[24m(7).   The  [4mpreconv[24m(1)  preprocessor  transforms
       other encodings, including UTF‐8, to satisfy [4mgtroff[24m’s requirements.

[1mSyntax characters[0m
       Several input characters are syntactically significant to [4mgroff[24m.

       .   A dot at the beginning of an input line marks it as a [4mcontrol[24m [4mline.[0m
           It  can also follow the [1m.el [22mand [1m.nop [22mrequests, and the condition in
           [1m.if[22m, [1m.ie[22m, and [1m.while [22mrequests.  The control character  invokes  re‐
           quests  and  calls macros by the name that follows it.  The [1m.cc [22mre‐
           quest can change the control character.

       '   The neutral apostrophe is the [4mno‐break[24m  [4mcontrol[24m  [4mcharacter,[24m  recog‐
           nized  where  the  control character is.  It suppresses the (first)
           break implied by the [1m.bp[22m, [1m.cf[22m, [1m.fi[22m, [1m.fl[22m, [1m.in[22m, [1m.nf[22m, [1m.rj[22m,  [1m.sp[22m,  [1m.ti[22m,
           and  [1m.trf  [22mrequests.   The  requested operation takes effect at the
           next break.  It makes [1m.br [22mnilpotent.  The no‐break control  charac‐
           ter  can  be changed with the [1m.c2 [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  characters.  In the [1m.ds[22m, [1m.ds1[22m, [1m.as[22m, and [1m.as1 [22mrequests, an ini‐
           tial neutral double quote in the second argument is stripped off to
           allow embedding of leading spaces.  To include a double  quote  in‐
           side  a quoted argument, use the [1m\[dq] [22mspecial character escape se‐
           quence (which also serves to typeset the glyph in text).

       \   A backslash introduces an escape sequence.   The  escape  character
           can  be  changed with the [1m.ec [22mrequest; [1m.eo [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 cur‐
           rent escape character.

       (   An opening parenthesis is special only in certain escape sequences;
           when recognized, it introduces an argument of exactly  two  charac‐
           ters.  [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 including 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 white space characters are significant to [4mgroff,[24m but  trail‐
       ing spaces on text lines are ignored.

       [4mspace[24m   Space  characters  separate  arguments  in request invocations,
               macro calls, and string interpolations.  In text, they separate
               words.  Multiple adjacent space characters in text cause  [4mgroff[0m
               to attempt end‐of‐sentence detection on the preceding word (and
               trailing  punctuation).   The amount of space between words and
               sentences is controlled by the [1m.ss [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  ex‐
               panded 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 In  text,  a  newline  puts an inter‐word space onto the output
               and, if filling is enabled, triggers  end‐of‐sentence  recogni‐
               tion  on  the  preceding text.  See section “Line continuation”
               below.

       [4mtab[24m     A tab character in text causes the drawing position to  advance
               to the next defined tab stop.

[1mTabs and leaders[0m
       The  formatter  interprets input horizontal tab characters (“tabs”) and
       Control+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  mea‐
       sured  from  the drawing position corresponding to the beginning of the
       input line; see section “Page geometry” of [4mroff[24m(7).  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, respectively.

[1mLine continuation[0m
       When  filling is enabled, input and output line breaks generally do not
       correspond.  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  in
       the  middle  of  a  request invocation, macro call, or escape sequence.
       Input line continuation is invisible to the formatter, with two  excep‐
       tions: the [1m| [22moperator recognizes the new input line, and the input line
       counter register [1m.c [22mis incremented.

       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[0m
       is treated as a new input line, so a control character is recognized at
       its  beginning.   The  visual  results depend on whether filling is en‐
       abled.  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 [22mcontains a positive value if the last output  line  was  continued
       with [1m\c[22m; this datum 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
       limited.  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 objects like circles and polygons are  drawn,  and  the  [4mfill[0m
       [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[0m
       escape  sequences; and [1m.color[22m, [1m.m[22m, and [1m.M [22mregisters exercise color sup‐
       port.

       Each output device has a color named “[1mdefault[22m”, which cannot  be  rede‐
       fined.   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, [4mgtroff[0m
       automatically loads a macro file defining many color names at  startup.
       By the same mechanism, the devices supported by [4mgrotty[24m(1) recognize the
       eight  standard  ISO  6429/ECMA‐48  color names (also known vulgarly as
       “ANSI colors”).

[1mMeasurements[0m
       Numeric parameters that specify measurements are expressed as  integers
       or decimal fractions with an optional [4mscaling[24m [4munit[24m suffixed.  A scaling
       unit  is  a letter that immediately follows the last digit of a number.
       Digits after the decimal point are optional.

       Measurements are scaled by the scaling unit and stored 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.
       The only constraint on the basic unit is that it is at least  as  small
       as any other unit.

       [1mu      [22mBasic 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.
       [1ms[22m, [1mz   [22mScaled   points   and  multiplication  by  the  output  device’s
              [4msizescale[24m parameter, respectively.
       [1mf      [22mMultiplication by 65,536; scales decimal fractions in the inter‐
              val [0, 1] to 16‐bit unsigned integers.

       The magnitudes of other scaling units depend on the text formatting pa‐
       rameters in effect.

       [1mm      [22mEm; an em is equal to the current type size in points.
       [1mn      [22mEn; an en is one‐half em.
       [1mv      [22mVee; distance between text baselines.
       [1mM      [22mHundredth of an em.

   [1mMotion quanta[0m
       An output device’s basic unit [1mu [22mis not  necessarily  its  smallest  ad‐
       dressable  length;  [1mu  [22mcan  be  smaller  to avoid problems with integer
       roundoff.  The minimum distances that a device can  work  with  in  the
       horizontal and vertical directions are termed its [4mmotion[24m [4mquanta,[24m stored
       in  the [1m.H [22mand [1m.V [22mregisters, respectively.  Measurements are rounded 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 basic units if interpreted in a measurement context.  But it is con‐
       venient for many requests and escape sequences to infer a scaling  unit
       for  an  argument  if none is specified.  An explicit scaling unit (not
       after a closing parenthesis) can override an undesirable default.   Ef‐
       fectively,  the default unit is suffixed to the expression if a scaling
       unit is not already present.  GNU [4mtroff[24m’s  use  of  integer  arithmetic
       should also be kept in mind; see below.

[1mNumeric expressions[0m
       A  [4mnumeric[24m [4mexpression[24m evaluates to an integer.  The following operators
       are recognized.

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

       [4mgtroff[24m provides a set of mathematical and logical operators familiar to
       programmers—as well as some  unusual  ones—but  supports  only  integer
       arithmetic.   (Provision is made for interpreting and reporting decimal
       fractions in certain cases.)  The internal data type used for computing
       results is usually a 32‐bit signed integer, which suffices to represent
       magnitudes within a range of ±2 billion.  (If that’s  not  enough,  see
       [4mgroff_tmac[24m(5) for the [4m62bit.tmac[24m macro package.)

       Arithmetic  infix  operators  perform a function on the numeric expres‐
       sions to their left and right; they are [1m+ [22m(addition), [1m-  [22m(subtraction),
       [1m* [22m(multiplication), [1m/ [22m(truncating division), and [1m% [22m(modulus).  [4mTruncat‐[0m
       [4ming[24m  [4mdivision[24m rounds to the integer nearer to zero, no matter how large
       the fractional portion.  Overflow and division (or 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 follow‐
       ing property: given a dividend [4ma[24m and a divisor [4mb[24m, a quotient  [4mq[24m  formed
       by “[1m(a / b)[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[0m
       also  provides  a  pair  of  operators  to  compute  the extrema 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).   [1m==  [22mis  a
       synonym for [1m=[22m.  When evaluated, a comparison is replaced with “[1m0[22m” if it
       is  false  and  “[1m1[22m” if true.  In the [4mroff[24m language, positive values are
       true, others false.

       We can operate on truth values with the logical  operators  [1m&  [22m(logical
       conjunction or “and”) and [1m: [22m(logical disjunction or “or”).  They evalu‐
       ate  as comparison operators do.  A logical complementation (“not”) op‐
       erator, [1m!, [22mworks only within “[1mif[22m”, “[1mie[22m”, and  “[1mwhile[22m”  requests.   Fur‐
       thermore, [1m! [22mis recognized only at the beginning of a numeric expression
       not  contained  by another numeric expression.  In other words, it must
       be the “outermost” operator.  Including it elsewhere in the  expression
       produces  a  warning  in the “[1mnumber[22m” category (see [4mgtroff[24m(1)), and its
       expression evaluates false.  This unfortunate limitation maintains com‐
       patibility with AT&T [4mtroff[24m.  Test a numeric expression for  falsity  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 ex‐
       pression.   They  then  indicate a motion relative to the drawing posi‐
       tion: positive is down in vertical contexts, right in horizontal ones.

       [1m+ [22mand [1m- [22mare also treated differently by the following requests and  es‐
       cape  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  operators, respectively.  To negate an expression, sub‐
       tract 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 po‐
       sition  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 move‐
       ments 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 ex‐
       pression.

       A register interpolated as an operand in a numeric expression must have
       an Arabic format; luckily, this is the default.

       Due to the way arguments are parsed, spaces are not allowed in  numeric
       expressions unless the (sub)expression containing them is surrounded by
       parentheses.

[1mIdentifiers[0m
       An [4midentifier[24m labels a GNU [4mtroff[24m datum such as a register, name (macro,
       string,  or  diversion),  typeface, color, special character, character
       class, environment, or stream.  Valid identifiers  consist  of  one  or
       more  ordinary characters.  An [4mordinary[24m [4mcharacter[24m is an input character
       that is not the escape character, a leader, tab, newline, or invalid as
       GNU [4mtroff[24m input.

       Invalid input characters are subset of  control  characters  (from  the
       sets  “C0 Controls” and “C1 Controls” as Unicode describes them).  When
       [4mgtroff[24m encounters one in an identifier, it produces a warning in  cate‐
       gory  “[1minput[22m”  (see section “Warnings” in [4mgtroff[24m(1)).  They are removed
       during interpretation: an identifier  “foo”,  followed  by  an  invalid
       character and then “bar”, is processed as “foobar”.

       On a machine using the ISO 646, 8859, or 10646 character encodings, in‐
       valid  input characters are [1m0x00[22m, [1m0x08[22m, [1m0x0B[22m, [1m0x0D[22m–[1m0x1F[22m, and [1m0x80[22m–[1m0x9F[22m.
       On an EBCDIC host, they are [1m0x00[22m–[1m0x01[22m,  [1m0x08[22m,  [1m0x09[22m,  [1m0x0B[22m,  [1m0x0D[22m–[1m0x14[22m,
       [1m0x17[22m–[1m0x1F[22m, and [1m0x30[22m–[1m0x3F[22m.  Some of these code points are used by [4mgtroff[0m
       internally, making it non‐trivial to extend the program to accept UTF‐8
       or other encodings that use characters from these ranges.

       An  identifier  with  a  closing bracket (“]”) in its name can’t be ac‐
       cessed with bracket‐form escape sequences that expect an identifier  as
       a  parameter.   Similarly, the identifier “(” can’t be interpolated [4mex‐[0m
       [4mcept[24m with bracket forms.

       If you begin a macro, string, or diversion  name  with  either  of  the
       characters “[” or “]”, you foreclose use of the [4mgrefer[24m(1) preprocessor,
       which recognizes “.[” and “.]” as bibliographic reference delimiters.

       The  escape  sequence  [1m\A [22mtests its argument for validity as an identi‐
       fier.

       How GNU [4mtroff[24m handles the interpretation of an undefined identifier de‐
       pends on the context.  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, [4mgtroff[24m emits a warning
       in category “[1mmac[22m”, defines it as empty, and interpolates  nothing.   If
       the  identifier is interpreted as a register, [4mgtroff[24m emits a warning in
       category “[1mreg[22m”, initializes it to zero, and  interpolates  that  value.
       See section “Warnings” in [4mgtroff[24m(1), and subsection “Interpolating reg‐
       isters”  and  section  “Strings” below.  Attempting to use an undefined
       typeface, style, special character, color,  character  class,  environ‐
       ment, or stream generally 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
       Control characters are recognized only at the  beginning  of  an  input
       line, or at the beginning of the branch of a control structure request;
       see section “Control structures” below.

       A few requests cause a break implicitly; use the no‐break control char‐
       acter  to  prevent the break.  Break suppression is its sole behavioral
       distinction.  Employing the no‐break control character  to  invoke  re‐
       quests that don’t cause breaks is harmless but poor style.

       The control character “[1m.[22m” and the no‐break control character “[1m'[22m” can be
       changed with the [1mcc [22mand [1mc2 [22mrequests, respectively.  Within a macro def‐
       inition, 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 un‐
       recognized request is interpreted as a macro call.   Defining  a  macro
       with  the  same name as a request replaces the request.  Deleting a re‐
       quest name with the [1mrm [22mrequest makes it unavailable.  The  [1mals  [22mrequest
       can  alias requests, permitting them to be wrapped or non‐destructively
       replaced.  See section “Strings” below.

       There is no inherent limit on argument length or  quantity.   Most  re‐
       quests  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 be‐
       tween arguments is necessary; any excess is ignored.   GNU  [4mtroff[24m  does
       not allow tabs for argument separation.

       Generally, a space [4mwithin[24m a request argument is not relevant, not mean‐
       ingful, or is supported by bespoke provisions, as with the [1mtl [22mrequest’s
       delimiters.   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.
       Commonly, authors structure the source of documents or macro files with
       them.

[1mCalling macros[0m
       If  a  macro of the desired name does not exist when called, it is cre‐
       ated, assigned an empty definition, and a warning in category “[1mmac[22m”  is
       emitted.  Calling an undefined 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 neu‐
       tral double quotes ‘[1m"[22m’.  Horizontal motion escape sequences  are  some‐
       times a better 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
       literals.  In GNU [4mtroff[24m, the special character  escape  sequence  [1m\[rs][0m
       produces a backslash and [1m\[dq] [22ma neutral double quote.

       In  GNU [4mtroff[24m’s AT&T compatibility mode, these characters remain avail‐
       able 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 [4mgroff_font[24m(5).  If even that is  not  feasible,  see
       the  “Calling  Macros” section of the [4mgroff[24m Texinfo manual for the com‐
       plex macro argument quoting rules of AT&T [4mtroff[24m.

[1mUsing escape sequences[0m
       Whereas requests must occur on control lines, escape sequences can  oc‐
       cur  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 function.

       Escape  sequences vary in length.  Some take an argument, and of those,
       some have different syntactical forms for a one‐character,  two‐charac‐
       ter,  or  arbitrary‐length  argument.  Others accept [4monly[24m an arbitrary‐
       length argument.  In the former scheme, a one‐character  argument  fol‐
       lows the function character immediately, an opening parenthesis “[1m([22m” in‐
       troduces a two‐character argument (no closing parenthesis is used), and
       an  argument  of arbitrary length is enclosed in brackets “[1m[][22m”.  In the
       latter scheme, the user selects a delimiter character.   A  few  escape
       sequences  are idiosyncratic, and support both of the foregoing conven‐
       tions ([1m\s[22m), designate their own termination sequence ([1m\?[22m), consume  in‐
       put until the next newline ([1m\![22m, [1m\"[22m, [1m\#[22m), or support an additional modi‐
       fier character ([1m\s [22magain, and [1m\n[22m).

       If  an  escape character is followed by a character that does not iden‐
       tify a defined operation, the escape character is ignored (producing  a
       diagnostic  of  the  “[1mescape[22m” warning category, which is not enabled by
       default) and the following character is processed normally.

       Escape sequence interpolation is of higher precedence than  escape  se‐
       quence argument interpretation.  This rule affords flexibility in using
       escape sequences to construct parameters to other escape sequences.

       The escape character can be interpolated ([1m\e[22m).  Requests permit the es‐
       cape mechanism to be deactivated ([1meo[22m) and restored, or the escape char‐
       acter changed ([1mec[22m), and to save and restore it ([1mecs [22mand [1mecr[22m).

[1mDelimiters[0m
       Some escape sequences that require parameters use delimiters.  The neu‐
       tral  apostrophe [1m' [22mis a popular choice and shown in this document.  The
       neutral double quote [1m" [22mis also commonly seen.  Letters,  numerals,  and
       leaders can be used.  Punctuation characters are likely better choices,
       except for those defined as infix operators in numeric expressions; see
       below.

       The  following  escape  sequences don’t take arguments and thus are al‐
       lowed 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.
       However,  using  them  this way is discouraged; they can make the input
       confusing to read.

       A few escape sequences, [1m\A[22m, [1m\b[22m, [1m\o[22m, [1m\w[22m, [1m\X[22m, and [1m\Z[22m, accept a newline as
       a delimiter.  Newlines that serve as delimiters continue to  be  recog‐
       nized  as input line terminators.  Use of newlines as delimiters in es‐
       cape sequences is also discouraged.

       Finally, 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 [22mprohibit many delimiters.

              • 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 complex and flexible primarily for historical  rea‐
       sons; the foregoing restrictions need be kept in mind mainly when using
       [4mgroff[24m in AT&T compatibility mode.  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  argu‐
       ments  you input, not any that result from interpolation.  Typically, [1m'[0m
       works fine.  See section “Implementation differences” in [4mgroff_diff[24m(7).

[1mDummy characters[0m
       As discussed in [4mroff[24m(7), 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 rendering a glyph to the output.   [1m\&  [22minterpolates  a
       dummy  character,  which  is constitutive of output but invisible.  Its
       presence alters the interpretation context of a subsequent input  char‐
       acter, and enjoys several applications: preventing the insertion of ex‐
       tra space after an end‐of‐sentence character, preventing interpretation
       of  a  control  character at the beginning of an input line, preventing
       kerning between two glyphs, and permitting the [1mtr [22mrequest  to  remap  a
       character  to  “nothing”.  [1m\) [22mworks as [1m\& [22mdoes, except that it does not
       cancel a pending end‐of‐sentence state.

[1mControl structures[0m
       [4mgroff[24m has “if” and “while” control  structures  like  other  languages.
       However,  the  syntax for grouping multiple input lines in the branches
       or bodies of these structures is unusual.

       They have a common form: the request name is (except  for  [1m.el  [22m“else”)
       followed  by  a  conditional expression [4mcond‐expr[24m; the remainder of the
       line, [4manything[24m, is interpreted as if it were an input line.  Any  quan‐
       tity  of  spaces  between arguments to requests serves only to separate
       them; leading spaces in [4manything[24m are therefore not seen.  [4manything[24m  ef‐
       fectively  [4mcannot[24m  be  omitted;  if  [4mcond‐expr[24m  is true and [4manything[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 a combination of the  forego‐
       ing.   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 subse‐
       quent to the request’s conditional expression.  [1m\} [22mshould appear  on  a
       line  with  other  occurrences  of  itself as necessary to match [1m\{ [22mse‐
       quences.  It can be preceded by a control character, spaces, and  tabs.
       Input  after any quantity of [1m\} [22msequences on the same line is processed
       only if all the preceding conditions to which they correspond are true.
       Furthermore, a [1m\} [22mclosing the body of a [1m.while [22mrequest must be the last
       such escape sequence on an input line.

   [1mConditional expressions[0m
       The [1m.if[22m, [1m.ie[22m, and [1m.while [22mrequests test the truth values of numeric  ex‐
       pressions.  They also support several additional Boolean operators; the
       members  of  this  expanded  class  are termed [4mconditional[24m [4mexpressions[24m;
       their truth values are as shown below.

       [4m[1mcond‐expr[24m[22m...   [1m...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 glyph [4mg[24m is available.
                [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 [1m.if[22m, [1m.ie[22m, or [1m.while [22mrequest begins  with  a
       non‐alphanumeric  character  apart  from  [1m! [22m(see below); it performs an
       [4moutput[24m [4mcomparison[24m [4mtest.[24m  Shown first in the  table  above,  the  [4moutput[0m
       [4mcomparison[24m  [4moperator[24m  interpolates  a true value if formatting its com‐
       parands [4ms1[24m and [4ms2[24m produces the same output commands.  Other  delimiters
       can be used in place of the neutral apostrophes.  [4mgtroff[24m formats [4ms1[24m and
       [4ms2[24m  in  separate environments; after the comparison, the resulting data
       are discarded.  The resulting glyph properties, including font  family,
       style,  size,  and  slant, must match, but not necessarily the requests
       and/or escape sequences used to obtain them.   Motions  must  match  in
       orientation and magnitude to within the applicable horizontal or verti‐
       cal 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 comparands protected with [1m\? [22mare
       read  in  copy mode, they need not even be valid [4mgroff[24m syntax.  The es‐
       cape 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 expres‐
       sion.   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 conditional evaluates true.  (This bizarre behavior
       maintains compatibility with AT&T [4mtroff[24m.)

[1mSyntax reference conventions[0m
       In the following request and escape sequence specifications, most argu‐
       ment names were chosen to be descriptive.  A few  denotations  may  re‐
       quire introduction.

              [4mc[24m         denotes a single input character.
              [4mfont[24m      a  font  either  specified as a font name or a numeric
                        mounting position.
              [4manything[24m  all characters up to the end of the line, to the  end‐
                        ing  delimiter  for  the escape sequence, or within [1m\{[0m
                        and [1m\}[22m.  Escape sequences may generally be used freely
                        in [4manything[24m, except when it is read in copy mode.
              [4mmessage[24m   is a character sequence to be emitted on the  standard
                        error  stream.  Special character escape sequences are
                        [4mnot[24m interpreted.
              [4mn[24m         is a numeric expression that evaluates to a  non‐nega‐
                        tive integer.
              [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
                        output,  as  do control lines containing requests like
                        [1m.tl [22mor escape sequences like [1m\D[22m.  Macro calls are  not
                        themselves productive, but their interpolated contents
                        can be.
              [4m±N[24m        is  a  numeric  expression with a meaning dependent on
                        its sign.

       If a numeric expression presented as [4m±N[24m starts with a ‘[1m+[22m’ sign, an  in‐
       crement in the amount of of [4mN[24m is applied to the value applicable to the
       request  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  ex‐
       isting  value.   A  leading  minus sign in [4mN[24m is always interpreted as a
       decrementation operator, not an algebraic sign.  To assign a register a
       negative value or the negated value of  another  register,  enclose  it
       with  its  operand in parentheses or subtract it from zero.  If a prior
       value does not exist (the register  was  undefined),  an  increment  or
       decrement is applied as if to 0.

[1mRequest short reference[0m
       Not  all  details of request behavior are outlined here.  See the [4mgroff[0m
       Texinfo manual or, for features new to GNU [4mtroff[24m, [4mgroff_diff[24m(7).

       [1m.ab       [22mAbort processing; exit with failure status.
       [1m.ab [4m[22mmessage[0m
                 Abort processing; write [4mmessage[24m to the standard error  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[22mregister[24m [4mc[0m
                 Assign  format  [4mc[24m to [4mregister[24m, where [4mc[24m is “[1mi[22m”, “[1mI[22m”, “[1ma[22m”, “[1mA[22m”,
                 or a sequence of decimal digits whose  quantity  denotes  the
                 minimum  width  in digits to be used when the register is in‐
                 terpolated.  “[1mi[22m” and “[1ma[22m” indicate Roman  numerals  and  basic
                 Latin alphabetics, respectively, in the lettercase specified.
                 The default is [1m0[22m.
       [1m.aln [4m[22mnew[24m [4mold[0m
                 Create  alias  (additional  name)  [4mnew[24m  for existing register
                 named [4mold[24m.
       [1m.als [4m[22mnew[24m [4mold[0m
                 Create alias (additional  name)  [4mnew[24m  for  existing  request,
                 string, macro, or diversion [4mold[24m.
       [1m.am [4m[22mmacro[24m Append to [4mmacro[24m until [1m.. [22mis encountered.
       [1m.am [4m[22mmacro[24m [4mend[0m
                 Append to [4mmacro[24m until [1m.[4m[22mend[24m is called.
       [1m.am1 [4m[22mmacro[0m
                 Same  as  [1m.am [22mbut with compatibility mode switched off during
                 macro expansion.
       [1m.am1 [4m[22mmacro[24m [4mend[0m
                 Same as [1m.am [22mbut with compatibility mode switched  off  during
                 macro expansion.
       [1m.ami [4m[22mmacro[0m
                 Append to a macro whose name is contained in the string [4mmacro[0m
                 until [1m.. [22mis encountered.
       [1m.ami [4m[22mmacro[24m [4mend[0m
                 Append  to  a  macro  indirectly.   [4mmacro[24m and [4mend[24m are strings
                 whose contents are interpolated for the macro  name  and  the
                 end macro, respectively.
       [1m.ami1 [4m[22mmacro[0m
                 Same  as [1m.ami [22mbut with compatibility mode switched off during
                 macro expansion.
       [1m.ami1 [4m[22mmacro[24m [4mend[0m
                 Same as [1m.ami [22mbut with compatibility mode switched off  during
                 macro expansion.
       [1m.as [4m[22mname[24m  Create  string [4mname[24m with empty contents; no operation if [4mname[0m
                 already exists.
       [1m.as [4m[22mname[24m [4mcontents[0m
                 Append [4mcontents[24m to string [4mname[24m.
       [1m.as1 [4m[22mstring[0m
       [1m.as1 [4m[22mstring[24m [4mcontents[0m
                 As [1m.as[22m, but with compatibility mode  disabled  when  [4mcontents[0m
                 interpolated.
       [1m.asciify [4m[22mdiversion[0m
                 Unformat  ASCII characters, spaces, and some escape sequences
                 in [4mdiversion[24m.
       [1m.backtrace[0m
                 Write the state of the input  stack  to  the  standard  error
                 stream.  See the [1m-b [22moption of [4mgroff[24m(1).
       [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.
       [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[22mname[24m Set blank line macro (trap) to [4mname[24m.
       [1m.box      [22mStop  directing output to current diversion; any pending out‐
                 put line is discarded.
       [1m.box [4m[22mname[24m Direct output to diversion [4mname[24m, omitting  a  partially  col‐
                 lected line.
       [1m.boxa     [22mStop  appending output to current diversion; any pending out‐
                 put line is discarded.
       [1m.boxa [4m[22mname[0m
                 Append output to diversion [4mname[24m, omitting  a  partially  col‐
                 lected 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 output line; adjust if applicable.
       [1m.break    [22mBreak out of a while 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
                 without 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  Copy contents of [4mfile[24m without formatting to  the  (top‐level)
                 diversion.
       [1m.cflags [4m[22mn[24m [4mc1[24m [4mc2[24m ...
                 Assign  properties  encoded by [4mn[24m to characters [4mc1[24m, [4mc2[24m, and so
                 on.
       [1m.ch [4m[22mname[24m  Unplant page location trap [4mname[24m.
       [1m.ch [4m[22mname[24m [4mvpos[0m
                 Change page location trap [4mname[24m planted by [1m.wh [22mby  moving  its
                 location to [4mvpos[24m (default scaling unit [1mv[22m).
       [1m.char [4m[22mc[24m [4mcontents[0m
                 Define ordinary or special character [4mc[24m as [4mcontents[24m.
       [1m.chop [4m[22mobject[0m
                 Remove  the  last character from the macro, string, or diver‐
                 sion named [4mobject[24m.
       [1m.class [4m[22mname[24m [4mc1[24m [4mc2[24m ...
                 Define a (character) class [4mname[24m comprising the characters  or
                 range expressions [4mc1[24m, [4mc2[24m, and so on.
       [1m.close [4m[22mstream[0m
                 Close the [4mstream[24m.
       [1m.color    [22mEnable output of color‐related device‐independent output com‐
                 mands.
       [1m.color [4m[22mn[24m  If [4mn[24m is zero, disable output of color‐related device‐indepen‐
                 dent output commands; otherwise, enable them.
       [1m.composite [4m[22mfrom[24m [4mto[0m
                 Map  glyph  name  [4mfrom[24m  to glyph name [4mto[24m while constructing a
                 composite glyph name.
       [1m.continue [22mFinish the current iteration of a while loop.
       [1m.cp       [22mEnable compatibility mode.
       [1m.cp [4m[22mn[24m     If [4mn[24m is zero, disable compatibility  mode,  otherwise  enable
                 it.
       [1m.cs [4m[22mfont[24m [4mn[24m [4mm[0m
                 Set  constant  character width mode for [4mfont[24m to [4mn[24m/36 ems with
                 em [4mm[24m.
       [1m.cu       [22mContinuously underline the output of the next productive  in‐
                 put line.
       [1m.cu [4m[22mnpl[24m   Continuously  underline the output of the next [4mnpl[24m productive
                 input lines.  If [4mnpl[24m=0, stop continuously underlining.
       [1m.da       [22mStop appending output to current diversion.
       [1m.da [4m[22mname[24m  Append output to diversion [4mname[24m.
       [1m.de [4m[22mmacro[24m Define or redefine [4mmacro[24m until “[1m..[22m” occurs at the start of  a
                 control line in the current conditional block.
       [1m.de [4m[22mmacro[24m [4mend[0m
                 Define  or  redefine  [4mmacro[24m until [4mend[24m is invoked or called at
                 the start of a control line in the current conditional block.
       [1m.de1 [4m[22mmacro[0m
                 As [1m.de[22m, but disable compatibility mode  during  macro  expan‐
                 sion.
       [1m.de1 [4m[22mmacro[24m [4mend[0m
                 As  “[1m.de  [4m[22mmacro[24m  [4mend[24m”,  but disable compatibility mode during
                 macro expansion.
       [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 syn‐
                 onym  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).   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.
       [1m.dei [4m[22mmacro[0m
                 Define  macro  indirectly.   As [1m.de[22m, but use interpolation of
                 string [4mmacro[24m as the name of the defined macro.
       [1m.dei [4m[22mmacro[24m [4mend[0m
                 Define macro indirectly.  As [1m.de[22m, but use  interpolations  of
                 strings  [4mmacro[24m  and  [4mend[24m  as the names of the defined and end
                 macros.
       [1m.dei1 [4m[22mmacro[0m
                 As [1m.dei[22m, but disable compatibility mode during  macro  expan‐
                 sion.
       [1m.dei1 [4m[22mmacro[24m [4mend[0m
                 As  [1m.dei  [4m[22mmacro[24m  [4mend[24m,  but  disable compatibility mode during
                 macro expansion.
       [1m.device [4m[22manything[0m
                 Write [4manything[24m, read in copy mode, to [4mgtroff[24m output as a  de‐
                 vice  control  command.   An  initial neutral double quote is
                 stripped to allow embedding of leading spaces.
       [1m.devicem [4m[22mname[0m
                 Write contents of macro or string [4mname[24m to [4mgtroff[24m output as  a
                 device control command.
       [1m.di       [22mStop directing output to current diversion.
       [1m.di [4m[22mname[24m  Direct output to diversion [4mname[24m.
       [1m.do [4m[22mname[24m ...
                 Interpret  the  string,  request,  diversion,  or  macro [4mname[0m
                 (along with any arguments) with compatibility mode  disabled.
                 Compatibility  mode  is restored (only if it was active) when
                 the [4mexpansion[24m of [4mname[24m is interpreted.
       [1m.ds [4m[22mname[24m  Create empty string [4mname[24m.
       [1m.ds [4m[22mname[24m [4mcontents[0m
                 Create a string [4mname[24m containing [4mcontents[24m.
       [1m.ds1 [4m[22mname[0m
       [1m.ds1 [4m[22mname[24m [4mcontents[0m
                 As [1m.ds[22m, but with compatibility mode  disabled  when  [4mcontents[0m
                 interpolated.
       [1m.dt       [22mClear diversion trap.
       [1m.dt [4m[22mvertical‐position[24m [4mname[0m
                 Set  the  diversion  trap  to macro [4mname[24m at [4mvertical‐position[0m
                 (default 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 [1m.ecs[22m.
       [1m.ecs      [22mSave the escape character.
       [1m.el [4m[22manything[0m
                 Interpret [4manything[24m as if it were an input line if the  condi‐
                 tional expression of the corresponding [1m.ie [22mrequest was false.
       [1m.em [4m[22mname[24m  Call macro [4mname[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.
       [1m.evc [4m[22menv[24m  Copy environment [4menv[24m to the current one.
       [1m.ex       [22mExit with successful status.
       [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[22ma[24m     Set field delimiter to [4ma[24m and pad glyph to space.
       [1m.fc [4m[22ma[24m [4mb[24m   Set field delimiter to [4ma[24m and pad glyph to [4mb[24m.
       [1m.fchar [4m[22mc[24m [4mcontents[0m
                 Define fallback character (or glyph) [4mc[24m as [4mcontents[24m.
       [1m.fcolor   [22mRestore previous fill color.
       [1m.fcolor [4m[22mc[24m Set fill color to [4mc[24m.
       [1m.fi       [22mEnable filling of output lines; a pending output line is bro‐
                 ken.  Sets [1m\n[.u][22m.
       [1m.fl       [22mFlush output buffer.
       [1m.fp [4m[22mpos[24m [4mid[0m
                 Mount font with font description file name [4mid[24m at non‐negative
                 position [4mn[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 [4mn[24m.
       [1m.fschar [4m[22mf[24m [4mc[24m [4manything[0m
                 Define  fallback  character (or glyph) [4mc[24m for font [4mf[24m as string
                 [4manything[24m.
       [1m.fspecial [4m[22mfont[0m
                 Reset list of special fonts for [4mfont[24m to be empty.
       [1m.fspecial [4m[22mfont[24m [4ms1[24m [4ms2[24m ...
                 When the current font is [4mfont[24m, then the fonts [4ms1[24m, [4ms2[24m, ... are
                 special.
       [1m.ft[0m
       [1m.ft P     [22mSelect previous font mounting  position  (abstract  style  or
                 font); same as [1m\f[] [22mor [1m\fP[22m.
       [1m.ft [4m[22mfont[24m  Select  typeface  [4mfont,[24m which can be a mounting position, ab‐
                 stract style, or font name; same as [1m\f[[4m[22mfont[24m[1m] [22mescape sequence.
                 [4mfont[24m cannot be [1mP[22m.
       [1m.ftr [4m[22mfont1[24m [4mfont2[0m
                 Translate [4mfont1[24m to [4mfont2[24m.
       [1m.fzoom [4m[22mfont[0m
       [1m.fzoom [4m[22mfont[24m [1m0[0m
                 Stop magnifying [4mfont[24m.
       [1m.fzoom [4m[22mfont[24m [4mz[0m
                 Set zoom factor for  [4mfont[24m  to  [4mz[24m  (in  thousandths;  default:
                 1000).
       [1m.gcolor   [22mRestore previous stroke color.
       [1m.gcolor [4m[22mc[24m Set stroke color to [4mc[24m.
       [1m.hc       [22mReset the hyphenation character to [1m\% [22m(the default).
       [1m.hc [4m[22mchar[24m  Change the hyphenation character to [4mchar[24m.
       [1m.hcode [4m[22mc1[24m [4mcode1[24m [[4mc2[24m [4mcode2[24m] ...
                 Set the hyphenation code of character [4mc1[24m to [4mcode1[24m, that of [4mc2[0m
                 to [4mcode2[24m, and so on.
       [1m.hla [4m[22mlang[24m Set the hyphenation language to [4mlang[24m.
       [1m.hlm [4m[22mn[24m    Set  the  maximum quantity of consecutive hyphenated lines to
                 [4mn[24m.
       [1m.hpf [4m[22mpattern‐file[0m
                 Read hyphenation patterns from [4mpattern‐file[24m.
       [1m.hpfa [4m[22mpattern‐file[0m
                 Append hyphenation patterns from [4mpattern‐file[24m.
       [1m.hpfcode [4m[22ma[24m [4mb[24m [[4mc[24m [4md[24m] ...
                 Define mappings for character codes  in  hyphenation  pattern
                 files read with [1m.hpf [22mand [1m.hpfa[22m.
       [1m.hw [4m[22mword[24m ...
                 Define  hyphenation overrides for each [4mword;[24m a hyphen “[1m-[22m” in‐
                 dicates a hyphenation point.
       [1m.hy       [22mSet automatic hyphenation mode to [1m1[22m.
       [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.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  the  line can be justified with the addition of up to [4mhy‐[0m
                 [4mphenation‐space[24m to each  inter‐word  space  (default  scaling
                 unit [1mm[22m).
       [1m.ie [4m[22mcond‐expr[24m [4manything[0m
                 If [4mcond‐expr[24m is true, interpret [4manything[24m as if it were an in‐
                 put line, otherwise skip to a corresponding [1m.el [22mrequest.
       [1m.if [4m[22mcond‐expr[24m [4manything[0m
                 If  [4mcond‐expr[24m  is true, then interpret [4manything[24m as if it were
                 an input line.
       [1m.ig       [22mIgnore input (except for side effects of  [1m\R  [22mon  auto‐incre‐
                 menting  registers)  until “[1m..[22m” occurs at the start of a con‐
                 trol line in the current conditional block.
       [1m.ig [4m[22mend[24m   Ignore input (except for side effects of  [1m\R  [22mon  auto‐incre‐
                 menting  registers)  until  [1m.[4m[22mend[24m  is called at the start of a
                 control line in the current conditional block.
       [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 [4mname[0m
                 Set (or replace) an input line trap in the environment, call‐
                 ing macro [4mname[24m, after the next  [4mnpl[24m  productive  input  lines
                 have  been  read.   Lines  interrupted with the [1m\c [22mescape se‐
                 quence are counted separately.
       [1m.itc      [22mCancel any pending input line trap.
       [1m.itc [4m[22mnpl[24m [4mname[0m
                 As [1m.it[22m, except that input lines interrupted with the  [1m\c  [22mes‐
                 cape sequence are not counted.
       [1m.kern     [22mEnable pairwise kerning.
       [1m.kern [4m[22mn[24m   If [4mn[24m is zero, disable pairwise kerning, otherwise enable it.
       [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 [4manything[0m
                 Compute  the  number  of characters of [4manything[24m and store the
                 count in the register [4mreg[24m.
       [1m.linetabs [22mEnable line‐tabs mode (calculate tab  positions  relative  to
                 beginning of output line).
       [1m.linetabs 0[0m
                 Disable line‐tabs mode.
       [1m.lf [4m[22mn[24m     Set number of next input line to [4mn[24m.
       [1m.lf [4m[22mn[24m [4mfile[0m
                 Set  number  of  next  input line to [4mn[24m and input file name to
                 [4mfile[24m.
       [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  han‐
                 dling of lines with leading spaces.
       [1m.lsm [4m[22mname[24m Set the leading space macro (trap) to [4mname[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 scal‐
                 ing 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.
       [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[22mregister[0m
                 Mark vertical drawing position in [4mregister[24m.
       [1m.mso [4m[22mfile[24m As [1m.so[22m, except that [4mfile[24m is sought in the [4mtmac[24m directories.
       [1m.msoquiet [4m[22mfile[0m
                 As [1m.mso[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
                 broken.  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,[24m writing numbers every [4mm[24m lines, 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 to be numbered
                 with [1mnm[22m.
       [1m.nn [4m[22mn[24m     Suppress numbering of the next [4mn[24m output lines to be  numbered
                 with [1mnm[22m.  If [4mn[24m=0, cancel suppression.
       [1m.nop [4m[22manything[0m
                 Interpret [4manything[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.
       [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 [22mprimitive is output.  See [1m.rs[22m.
       [1m.nx       [22mImmediately jump to end of current file.
       [1m.nx [4m[22mfile[24m  Stop formatting current file and begin reading [4mfile.[0m
       [1m.open [4m[22mstream[24m [4mfile[0m
                 Open [4mfile[24m for writing and associate the stream  named  [4mstream[0m
                 with it.  Unsafe request; disabled by default.
       [1m.opena [4m[22mstream[24m [4mfile[0m
                 As  [1m.open[22m,  but  append to [4mfile.[24m  Unsafe request; disabled by
                 default.
       [1m.os       [22mOutput vertical distance that was saved by the [1m.sv [22mrequest.
       [1m.output [4m[22mcontents[0m
                 Emit [4mcontents[24m directly to intermediate output, allowing lead‐
                 ing whitespace if [4mstring[24m starts with  [1m"  [22m(which  is  stripped
                 off).
       [1m.pc       [22mReset page number character to ‘[1m%[22m’.
       [1m.pc [4m[22mc[24m     Page number character.
       [1m.pev      [22mReport  the state of the current environment followed by that
                 of all other environments to the standard error stream.
       [1m.pi [4m[22mprogram[0m
                 Pipe output to [4mprogram[24m ([4mnroff[24m only).   Unsafe  request;  dis‐
                 abled 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.pm       [22mReport, to the standard error stream, the names and sizes  in
                 bytes of defined macros, strings, and diversions.
       [1m.pn [4m[22m±N[24m    Next page number [4mN[24m.
       [1m.pnr      [22mWrite  the names and contents of all defined registers 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    Page offset [4mN[24m.
       [1m.ps       [22mReturn to 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[22mfile[0m
                 Retrieve  the  bounding  box of the PostScript image found in
                 [4mfile,[24m which must conform to Adobe’s Document Structuring Con‐
                 ventions (DSC).  See registers [1mllx[22m, [1mlly[22m, [1murx[22m, [1mury[22m.
       [1m.pso [4m[22mcommand‐line[0m
                 Execute [4mcommand‐line[24m with [4mpopen[24m(3) and interpolate  its  out‐
                 put.  Unsafe request; disabled by default.
       [1m.ptr      [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
                 scaling unit [1mp[22m).
       [1m.rchar [4m[22mc1[24m [4mc2[24m ...
                 Remove  definition  of each ordinary or special character [4mc1[24m,
                 [4mc2[24m, ... defined by a [1m.char[22m, [1m.fchar[22m, or [1m.schar [22mrequest.
       [1m.rd [4m[22mprompt[0m
                 Read insertion.
       [1m.return   [22mReturn from a macro.
       [1m.return [4m[22manything[0m
                 Return twice, namely from the macro at the current level  and
                 from the macro one level higher.
       [1m.rfschar [4m[22mf[24m [4mc1[24m [4mc2[24m ...
                 Remove  the  font‐specific  definitions of glyphs [4mc1[24m, [4mc2[24m, ...
                 for font [4mf[24m.
       [1m.rj [4m[22mnpl[24m   Break, 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 in‐
                 put lines without filling, then break again.   If  [4mnpl[24m  ≤  0,
                 stop right‐aligning.
       [1m.rm [4m[22mname[24m  Remove 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[22mident[24m Remove register [4mident[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 [4mcontents[0m
                 Define global fallback character (or glyph) [4mc[24m as [4mcontents[24m.
       [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 [4m[22mn[24m  In a macro definition, left‐shift arguments by [4mn[24m positions.
       [1m.sizes [4m[22ms1[24m [4ms2[24m ... [4msn[24m [[1m0[22m]
                 Set  available type sizes similarly to the [1msizes [22mdirective in
                 a [4mDESC[24m file.  Each [4ms[24mi  is  interpreted  in  units  of  scaled
                 points ([1mz[22m).
       [1m.so [4m[22mfile[24m  Replace the request’s control line with the contents of [4mfile[24m,
                 “sourcing” it.
       [1m.soquiet [4m[22mfile[0m
                 As [1m.so[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 un‐
                 til springing a page location trap.
       [1m.sp [4m[22mdist[24m  Break  and move the next text baseline down by [4mdist[24m, or until
                 springing a page location trap (default scaling unit  [1mv[22m).   A
                 negative  [4mdist[24m will not reduce the position of the text base‐
                 line below zero.  Prefixing [4mdist[24m with the [1m| [22moperator moves to
                 a position relative to the page top for positive [4mN[24m,  and  the
                 bottom  if [4mN[24m is negative; in all cases, one line height (vee)
                 is added to [4mdist[24m.  [4mdist[24m is ignored inside a diversion.
       [1m.special  [22mReset global list of special fonts to be empty.
       [1m.special [4m[22ms1[24m [4ms2[24m ...
                 Fonts [4ms1[24m, [4ms2[24m, etc. are special and are  searched  for  glyphs
                 not in the current font.
       [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  scaling  unit is [1mm[22m.  At startup, [1m.spreadwarn [22mis
                 inactive and [4mN[24m is 3 m[1m.[0m
       [1m.ss [4m[22mn[24m     Set minimal inter‐word spacing to [4mn[24m 12ths of  current  font’s
                 space width.
       [1m.ss [4m[22mn[24m [4mm[24m   As  “[1m.ss  [4m[22mn[24m”,  and  set  additional  inter‐sentence  space to
                 [4mm[24m 12ths of current font’s space width.
       [1m.stringdown [4m[22mstringvar[0m
                 Replace each byte in the string named [4mstringvar[24m with its low‐
                 ercase version.
       [1m.stringup [4m[22mstringvar[0m
                 Replace each byte in the string named [4mstringvar[24m with its  up‐
                 percase version.
       [1m.sty [4m[22mn[24m [4mstyle[0m
                 Associate abstract [4mstyle[24m with font position [4mn[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
                 backwards from the end of the string.
       [1m.sv       [22mAs [1m.ne[22m, but save 1 v for output with [1m.os [22mrequest.
       [1m.sv [4m[22md[24m     As [1m.ne[22m, but save distance [4md[24m for later output with [1m.os [22mrequest
                 (default scaling unit [1mv[22m).
       [1m.sy [4m[22mcommand‐line[0m
                 Execute [4mcommand‐line[24m with [4msystem[24m(3).   Unsafe  request;  dis‐
                 abled by default.
       [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 de‐
                 fault), “[1mC[22m” for centered, and “[1mR[22m” for right‐aligned.
       [1m.tag[0m
       [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 [4m[22mmessage[0m
                 Write  [4mmessage,[24m  followed by a newline, to the standard error
                 stream.
       [1m.tm1 [4m[22mmessage[0m
                 As [1m.tm[22m, but an initial neutral double quote in [4mmessage[24m is re‐
                 moved, allowing it to contain leading spaces.
       [1m.tmc [4m[22mmessage[0m
                 As [1m.tm1[22m, without emitting 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 Transparently  output  the contents of [4mfile.[24m  Unlike [1m.cf[22m, in‐
                 valid input characters in [4mfile[24m are rejected.
       [1m.trin [4m[22mabcd[24m...
                 As [1m.tr[22m, except that [1m.asciify [22mignores the translation  when  a
                 diversion is interpolated.
       [1m.trnt [4m[22mabcd[24m...
                 As  [1m.tr[22m, except that translations are suppressed in the argu‐
                 ment to [1m\![22m.
       [1m.troff    [22mMake the conditional expressions [1mt [22mtrue and [1mn [22mfalse.
       [1m.uf [4m[22mfont[24m  Set underline font used by [1m.ul [22mto [4mfont.[0m
       [1m.ul       [22mUnderline (italicize in [4mtroff[24m mode) the output  of  the  next
                 productive input line.
       [1m.ul [4m[22mnpl[24m   Underline  (italicize  in  [4mtroff[24m mode) the output of the next
                 [4mnpl[24m productive input line.  If [4mnpl[24m=0, stop underlining.
       [1m.unformat [4m[22mdiversion[0m
                 Unformat space characters and tabs in  [4mdiversion[24m,  preserving
                 font information.
       [1m.vpt      [22mEnable vertical position traps.
       [1m.vpt 0    [22mDisable vertical position traps.
       [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
                 [4mgtroff[24m(1).
       [1m.warnscale [4m[22msu[0m
                 Set scaling unit used in certain warnings to [4msu[24m (one of [1mu[22m, [1mi[22m,
                 [1mc[22m, [1mp[22m, or [1mP[22m; default: [1mi[22m).
       [1m.wh [4m[22mvpos[24m  Remove visible page location trap at  [4mvpos[24m  (default  scaling
                 unit [1mv[22m).
       [1m.wh [4m[22mvpos[24m [4mname[0m
                 Plant macro [4mname[24m as page location trap at [4mvpos[24m (default scal‐
                 ing unit [1mv[22m), removing any visible trap already there.
       [1m.while [4m[22mcond‐expr[24m [4manything[0m
                 Repeatedly execute [4manything[24m unless and until [4mcond‐expr[24m evalu‐
                 ates false.
       [1m.write [4m[22mstream[24m [4manything[0m
                 Write [4manything[24m to the stream named [4mstream[24m.
       [1m.writec [4m[22mstream[24m [4manything[0m
                 Similar to [1m.write [22mwithout emitting a final newline.
       [1m.writem [4m[22mstream[24m [4mxx[0m
                 Write  contents  of  macro  or  string [4mxx[24m to the stream named
                 [4mstream[24m.

[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[22mnewline[24m are interpreted even in copy mode.

       [1m\"     [22mComment.  Everything up to the end of the line is ignored.
       [1m\#     [22mComment.  Everything up to and including the next newline is ig‐
              nored.
       [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), tak‐
              ing [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 concatenation of all  macro  or  string  parameters,
              separated by spaces.
       [1m\$@    [22mInterpolate  concatenation  of  all  macro or string parameters,
              with each surrounded by double quotes and separated by spaces.
       [1m\$^    [22mInterpolate concatenation of all macro or string  parameters  as
              if they were arguments to the [1m.ds [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\%     [22mControl hyphenation.
       [1m\!     [22mTransparent  line.   The  remainder  of the input line is inter‐
              preted (1) when the current diversion is read; or (2) if in  the
              top‐level diversion, by the postprocessor (if any).
       [1m\?[4m[22manything[24m[1m\?[0m
              Transparently embed [4manything[24m, read in copy mode, in a diversion,
              or  unformatted  as an output comparand in a conditional expres‐
              sion.
       [1m\[4m[22mspace[24m Move right one 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 adja‐
              cent 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
              hyphen glyph).
       [1m\[4m[22mnewline[0m
              Continue current input line on the next.
       [1m\{     [22mBegin conditional input.
       [1m\}     [22mEnd conditional input.
       [1m\([4m[22mgl[24m   Interpolate glyph with two‐character name [4mgl[24m.
       [1m\[[4m[22mglyph[24m[1m][0m
              Interpolate glyph with name [4mglyph[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[22manything[24m[1m'[0m
              Interpolate  1  if  [4manything[24m is a valid identifier, and 0 other‐
              wise.
       [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[22manything[24m[1m'[0m
              Interpolate 1 if [4manything[24m is a valid numeric expression,  and  0
              otherwise.
       [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 ar‐
              bitrarily 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  height  of  current  font  to [4mN[24m scaled points (or specified
              units).
       [1m\k[4m[22mr[24m    Mark horizontal position in one‐character register name [4mr[24m.
       [1m\k([4m[22mrg[24m  Mark horizontal position in two‐character register name [4mrg[24m.
       [1m\k[[4m[22mreg[24m[1m][0m
              Mark horizontal  position  in  register  with  arbitrarily  long
              name [4mreg[24m.
       [1m\l'[4m[22mN[24m[[4mc[24m][1m'[0m
              Draw  horizontal  line  of  length  [4mN[24m with character [1mc [22m(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 [1mc [22m(default: [1m\[br][22m;
              default scaling unit [1mv[22m).
       [1m\m[4m[22mc[24m    Set stroke color to that with one‐character name [4mc[24m.
       [1m\m([4m[22mcl[24m  Set stroke color to that with two‐character name [4mcl[24m.
       [1m\m[[4m[22mcolor[24m[1m][0m
              Set stroke color to that with arbitrarily long name [4mcolor[24m.
       [1m\m[]   [22mRestore previous stroke color.
       [1m\M[4m[22mc[24m    Set fill color to that with one‐character name [4mc[24m.
       [1m\M([4m[22mcl[24m  Set fill color to that with two‐character name [4mcl[24m.
       [1m\M[[4m[22mcolor[24m[1m][0m
              Set fill color to that with arbitrarily long name [4mcolor[24m.
       [1m\M[]   [22mRestore previous fill color.
       [1m\n[4m[22mr[24m    Interpolate contents of register with one‐character name [4mr[24m.
       [1m\n([4m[22mrg[24m  Interpolate contents of register with two‐character name [4mrg[24m.
       [1m\n[[4m[22mreg[24m[1m][0m
              Interpolate contents of register with arbitrarily long name [4mreg[24m.
       [1m\N'[4m[22mn[24m[1m'  [22mInterpolate glyph with index [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 stan‐
              dard error stream the page number, four bounding  box  registers
              enclosing  glyphs written since the previous [1m\O [22mescape sequence,
              the page offset, line length, image file name (if any), horizon‐
              tal 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[0m
              must  be a single digit; 0 restores the previous type size.  (In
              compatibility mode only, a non‐zero  [4mN[24m  must  be  in  the  range
              4–39.)  Otherwise, as [1m.ps [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.  As [1m.ps [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.   As
              [1m.ps [22mrequest.
       [1m\S'[4m[22mN[24m[1m'  [22mSlant  output glyphs by [4mN[24m degrees; the direction of text flow is
              positive.
       [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  contents of environment variable with one‐character
              name [4me[24m.
       [1m\V([4m[22mev[24m  Interpolate contents of environment variable with  two‐character
              name [4mev[24m.
       [1m\V[[4m[22menv[24m[1m][0m
              Interpolate  contents  of  environment variable with arbitrarily
              long name [4menv[24m.
       [1m\w'[4m[22manything[24m[1m'[0m
              Interpolate width of [4manything[24m, formatted in a dummy environment.
       [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[22manything[24m[1m'[0m
              Write  [4manything[24m  to  [4mgtroff[24m  output as a device control command.
              Within [4manything[24m, the escape sequences [1m\&[22m, [1m\)[22m, [1m\%[22m, and [1m\: [22mare ig‐
              nored; [1m\[4m[22mspace[24m and [1m\~ [22mare converted to single  space  characters;
              and  [1m\\  [22mhas  its  escape character stripped.  So that the basic
              Latin subset of the Unicode character set can  be  reliably  en‐
              coded  in  [4manything,[24m  the special character escape sequences [1m\-[22m,
              [1m\[aq][22m, [1m\[dq][22m, [1m\[ga][22m, [1m\[ha][22m, [1m\[rs][22m, and [1m\[ti] [22mare mapped to basic
              Latin characters; see [4mgroff_char[24m(7).  For  this  transformation,
              character translations and special character definitions are ig‐
              nored.
       [1m\Y[4m[22mn[24m    Write contents of macro or string [4mn[24m to [4mgtroff[24m output as a device
              control command.
       [1m\Y([4m[22mnm[24m  Write  contents  of macro or string [4mnm[24m to [4mgtroff[24m output as a de‐
              vice control command.
       [1m\Y[[4m[22mname[24m[1m][0m
              Write contents of macro or string [4mname[24m to [4mgtroff[24m output as a de‐
              vice control command.
       [1m\z[4m[22mc[24m    Format character [4mc[24m with zero width—without advancing the drawing
              position.
       [1m\Z'[4m[22manything[24m[1m'[0m
              Save the drawing position, format [4manything[24m, then restore it.

   [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.  Terminal devices in particular implement almost none.

       Rendering  starts  at  the drawing position; when finished, the drawing
       position is left at the rightmost point of the object, even for  closed
       figures,  except  where  noted.  GNU [4mtroff[24m draws stroked (outlined) ob‐
       jects 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 default 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  always  smaller  than an outlined one because the former is
       drawn only within its defined area, whereas strokes have a line  thick‐
       ness (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 posi‐
              tion 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 bi‐
              sector 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
              position.
       [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 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
              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.
       [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 minimal supported thickness.  A negative  [4mn[0m
              selects  a  thickness proportional to the type size; this is the
              default.

   [1mDevice control commands[0m
       The [1m.device [22mand [1m.devicem [22mrequests, and [1m\X [22mand [1m\Y [22mescape sequences,  en‐
       able  documents to pass information directly to a postprocessor.  These
       are useful for exercising device‐specific capabilities that  the  [4mgroff[0m
       language  does  not  abstract or generalize; such functions include the
       embedding of hyperlinks and image files.  Device‐specific functions are
       documented in each output driver’s man page.

[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,
       without invoking requests or calling any other macros,  one  defines  a
       string instead.  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 [1m.ds [22mrequest creates a string with a specified  name  and  contents.
       If  the  identifier named by [1m.ds [22malready exists as an alias, the target
       of the alias is redefined.  If [1m.ds [22mis called with  only  one  argument,
       the named string becomes empty.  Otherwise, [4mgtroff[24m stores the remainder
       of the control line in copy mode; see subsection “Copy mode” below.

       The  [1m\* [22mescape sequence dereferences a string’s name, interpolating its
       contents.  If the name does not exist, it is defined as empty,  nothing
       is  interpolated, and a warning in category “[1mmac[22m” is emitted.  See sec‐
       tion “Warnings” in [4mgtroff[24m(1).  The bracketed interpolation form accepts
       arguments that are handled as macro arguments are; see section “Calling
       macros” above.  In contrast to  macro  calls,  however,  if  a  closing
       bracket  [1m]  [22moccurs in a string argument, that argument must be enclosed
       in double quotes.  [1m\* [22mis interpreted even in copy mode.  When  defining
       strings,  argument interpolations must be escaped if they are to refer‐
       ence parameters from the calling context; see section “Parameters”  be‐
       low.

       An initial neutral double quote [1m" [22min the string contents is stripped to
       allow  embedding  of leading spaces.  Any other [1m" [22mis interpreted liter‐
       ally, but it is wise to use the special character escape sequence [1m\[dq][0m
       instead if the string might be interpolated as part of  a  macro  argu‐
       ment; 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 newlines.  Care is therefore
       required when interpolating strings while filling is disabled.   It  is
       not possible to embed a newline in a string that will be interpreted as
       such  when  the string is interpolated.  To achieve that effect, use [1m\*[0m
       to interpolate a macro instead.

       The [1m.as [22mrequest is similar to [1m.ds [22mbut appends to a  string  instead  of
       redefining  it.   If [1m.as [22mis called with only one argument, no operation
       is performed (beyond dereferencing the string).

       Because strings are similar to macros, they too can be defined to  sup‐
       press  AT&T  [4mtroff[24m compatibility mode enablement when interpolated; see
       section “Compatibility mode” below.  The [1m.ds1 [22mrequest defines a  string
       that suspends compatibility mode when the string is later interpolated.
       [1m.as1 [22mis likewise similar to [1m.as[22m, with compatibility mode suspended when
       the appended portion of the string is later interpolated.

       [1mCaution:  [22mUnlike  other requests, the second argument to these requests
       consumes the remainder of the input line,  including  trailing  spaces.
       Ending  string  definitions  (and  appendments) with a comment, even an
       empty one, prevents unwanted  space  from  creeping  into  them  during
       source document maintenance.

       Several  requests  exist  to  perform  rudimentary  string  operations.
       Strings can be  queried  ([1m.length[22m)  and  modified  ([1m.chop[22m,  [1m.substring[22m,
       [1m.stringup[22m, [1m.stringdown[22m), and their names can be manipulated through re‐
       naming, removal, and aliasing ([1m.rn[22m, [1m.rm[22m, [1m.als).[0m

       When  a  request, macro, string, or diversion is aliased, redefinitions
       and appendments “write through” alias names.  To replace an alias  with
       a  separately  defined  object, you must use the [1mrm [22mrequest on its name
       first.

[1mRegisters[0m
       In the [4mroff[24m language, numbers can be stored in [4mregisters.[24m  Many  built‐
       in registers exist, supplying anything from the date to details of for‐
       matting  parameters.  You can also define your own.  See section “Iden‐
       tifiers” above for information on constructing a valid name for a  reg‐
       ister.

       Define  registers and update their values with the [1mnr [22mrequest or the [1m\R[0m
       escape sequence.

       Registers can also be incremented or decremented by a configured amount
       at the time they are interpolated.  The value of the increment is spec‐
       ified with a third argument to the [1m.nr [22mrequest, and a special  interpo‐
       lation  syntax,  [1m\n[4m[22m±[24m  is used to alter and then retrieve the register’s
       value.  Together, these features are called [4mauto‐increment[24m.   (A  nega‐
       tive auto‐increment can be considered an “auto‐decrement”.)

       Many  predefined  registers  are available.  In the following presenta‐
       tion, the register interpolation syntax [1m\n[[4m[22mname[24m[1m] [22mis used to refer to  a
       register  [4mname[24m to clearly distinguish it from a string or request [4mname[24m.
       The register name space  is  separate  from  that  used  for  requests,
       macros,  strings,  and  diversions.  Bear in mind that the symbols [1m\n[][0m
       are [4mnot[24m part of the register name.

   [1mRead‐only registers[0m
       Predefined registers whose identifiers start with a dot are  read‐only.
       Many are Boolean‐valued.  Some are string‐valued, meaning that they in‐
       terpolate  text.  A register name (without the dot) is often associated
       with a request of the same name; 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 [4mgtroff[24m [1m-a [22moption.
       \n[[1m.b[22m]         Font emboldening offset; see [1m.bd[22m.
       \n[[1m.br[22m]        The normal control character was used to call  the  cur‐
                      rently interpolated macro (Boolean‐valued).
       \n[[1m.c[22m]         Input line number; see [1m.lf [22mand register “[1mc.[22m”.
       \n[[1m.C[22m]         Compatibility mode is enabled (Boolean‐valued); see [1m.cp[22m.
                      Always false when processing [1m.do[22m; see register [1m.cp[22m.
       \n[[1m.cdp[22m]       Depth  of last glyph formatted in the environment; posi‐
                      tive if glyph extends below the baseline.
       \n[[1m.ce[22m]        Count of output lines remaining to be centered.
       \n[[1m.cht[22m]       Height of last glyph formatted in the environment; posi‐
                      tive if glyph extends above the baseline.
       \n[[1m.color[22m]     Color output is enabled (Boolean‐valued).
       \n[[1m.cp[22m]        Within [1m.do[22m, the saved value of compatibility  mode;  see
                      register [1m.C[22m.
       \n[[1m.csk[22m]       Skew  of  the  last  glyph formatted in the environment;
                      skew is how far to the right of the center  of  a  glyph
                      the  center  of  an  accent  over  that  glyph should be
                      placed.
       \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 [1m.ft [22mand [1m\f[22m.
       \n[[1m.F[22m]         Name of input file (string‐valued); see [1m.lf[22m.
       \n[[1m.fam[22m]       Name of default font family (string‐valued).
       \n[[1m.fn[22m]        Resolved name of selected font (string‐valued); see  [1m.ft[0m
                      and [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]    Font height; 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.hym[22m]       Hyphenation margin in environment.
       \n[[1m.hys[22m]       Hyphenation space adjustment threshold in environment.
       \n[[1m.i[22m]         Indentation amount; see [1m.in[22m.
       \n[[1m.in[22m]        Indentation  amount  applicable  to  the  pending output
                      line; see [1m.ti[22m.
       \n[[1m.int[22m]       Previous output line was “interrupted” or continued with
                      [1m\c [22m(Boolean‐valued).
       \n[[1m.j[22m]         Adjustment mode encoded as an integer; see [1m.ad [22mand  [1m.na[22m.
                      Do not interpret or perform arithmetic on its value.
       \n[[1m.k[22m]         Horizontal drawing position relative to indentation.
       \n[[1m.kern[22m]      Pairwise kerning is enabled (Boolean‐valued).
       \n[[1m.l[22m]         Line length; see [1m.ll[22m.
       \n[[1m.L[22m]         Line spacing; see [1m.ls[22m.
       \n[[1m.lg[22m]        Ligature mode.
       \n[[1m.linetabs[22m]  Line‐tabs mode is enabled (Boolean‐valued).
       \n[[1m.ll[22m]        Line length applicable to the pending output line.
       \n[[1m.lt[22m]        Title length.
       \n[[1m.m[22m]         Stroke color (string‐valued); see [1m.gcolor [22mand [1m\m[22m.  Empty
                      if the stroke color is the default.
       \n[[1m.M[22m]         Fill  color  (string‐valued); see [1m.fcolor [22mand [1m\M[22m.  Empty
                      if the fill color is the default.
       \n[[1m.n[22m]         Length of formatted output on previous output line.
       \n[[1m.ne[22m]        Amount of vertical  space  required  by  last  [1m.ne  [22mthat
                      caused a trap to be sprung; also see register [1m.trunc[22m.
       \n[[1m.nm[22m]        Output line numbering is enabled (Boolean‐valued).
       \n[[1m.nn[22m]        Count  of  output lines remaining to have numbering sup‐
                      pressed.
       \n[[1m.ns[22m]        No‐space mode is enabled (Boolean‐valued).
       \n[[1m.o[22m]         Page offset; see [1m.po[22m.
       \n[[1m.O[22m]         Output suppression nesting level; see [1m\O[22m.
       \n[[1m.p[22m]         Page length; see [1m.pl[22m.
       \n[[1m.P[22m]         The page is selected for  output  (Boolean‐valued);  see
                      [4mgtroff[24m [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]        Type size in scaled points.
       \n[[1m.psr[22m]       Most  recently requested type size in scaled points; see
                      [1m.ps [22mand [1m\s[22m.
       \n[[1m.pvs[22m]       Post‐vertical line spacing.
       \n[[1m.R[22m]         Count of available unused registers;  always  10,000  in
                      GNU [4mtroff[24m.
       \n[[1m.rj[22m]        Count of lines remaining to be right‐aligned.
       \n[[1m.s[22m]         Type  size  in points as a decimal fraction (string‐val‐
                      ued); see [1m.ps [22mand [1m\s[22m.
       \n[[1m.slant[22m]     Slant of font in degrees; see [1m\S[22m.
       \n[[1m.sr[22m]        Most recently requested type size in points as a decimal
                      fraction (string‐valued); see [1m.ps [22mand [1m\s[22m.
       \n[[1m.ss[22m]        Size of minimal inter‐word  space  in  twelfths  of  the
                      space width of the selected font.
       \n[[1m.sss[22m]       Size  of  additional inter‐sentence space in twelfths of
                      the space width of the selected font.
       \n[[1m.sty[22m]       Selected abstract style (string‐valued); see [1m.ft [22mand [1m\f[22m.
       \n[[1m.t[22m]         Distance to next vertical position  trap;  see  [1m.wh  [22mand
                      [1m.ch[22m.
       \n[[1m.T[22m]         An  output  device was explicitly selected (Boolean‐val‐
                      ued); see [4mgtroff[24m [1m-T [22moption.
       \n[[1m.tabs[22m]      Representation of tab settings suitable for use as argu‐
                      ment to [1m.ta [22m(string‐valued).
       \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 [1m.ne[22m, minus the amount  of  vertical  motion
                      produced by [1m.ne[22m; also see register [1m.ne[22m.
       \n[[1m.u[22m]         Filling is enabled (Boolean‐valued); see [1m.fi [22mand [1m.nf[22m.
       \n[[1m.U[22m]         Unsafe  mode  is enabled (Boolean‐valued); see [4mgtroff[24m [1m-U[0m
                      option.
       \n[[1m.v[22m]         Vertical line spacing; see [1m.vs[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 previous 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 [4mgtroff[24m formatter.
       \n[[1m.y[22m]         Minor version number of the running [4mgtroff[24m formatter.
       \n[[1m.Y[22m]         Revision number of the running [4mgtroff[24m formatter.
       \n[[1m.z[22m]         Name  of  diversion (string‐valued).  Empty if output is
                      directed to the top‐level diversion.
       \n[[1m.zoom[22m]      Zoom multiplier of current font (in thousandths; zero if
                      no magnification); see [1m.fzoom[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‐related  registers  are  set  to  the  local time as determined by
       [4mlocaltime[24m(3) when the formatter launches.  This initialization  can  be
       overridden  by  [4mSOURCE_DATE_EPOCH[24m  and [4mTZ[24m; see section “Environment” of
       [4mgroff[24m(1).

       \n[[1m$$[22m]         Process ID of [4mgtroff[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 start of input
                      line.
       \n[[1mllx[22m]        Lower‐left [4mx[24m coordinate (in PostScript units)  of  Post‐
                      Script image; see [1m.psbb[22m.
       \n[[1mlly[22m]        Lower‐left  [4my[24m  coordinate (in PostScript units) of Post‐
                      Script image; see [1m.psbb[22m.
       \n[[1mln[22m]         Output line number; see [1m.nm[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  for‐
                      matted  output on the page.  They are reset to -1 by [1m\O0[0m
                      or [1m\O1[22m.
       \n[[1mrsb[22m]        As register [1msb[22m, adding maximum glyph height to  measure‐
                      ment.
       \n[[1mrst[22m]        As  register  [1mst[22m, adding maximum glyph depth to measure‐
                      ment.
       \n[[1msb[22m]         Maximum displacement of text baseline below its original
                      position 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 [4mgtroff[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
                      environment by [1m\w[22m.
       \n[[1mst[22m]         Maximum displacement of text baseline above its original
                      position after rendering into dummy environment by [1m\w[22m.
       \n[[1msystat[22m]     Return value of [4msystem()[24m function; see [1m.sy[22m.
       \n[[1murx[22m]        Upper‐right [4mx[24m coordinate (in PostScript units) of  Post‐
                      Script image; see [1m.psbb[22m.
       \n[[1mury[22m]        Upper‐right  [4my[24m coordinate (in PostScript units) of Post‐
                      Script image; see [1m.psbb[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  spe‐
       cific  typeface  that  a device can render as glyphs at a desired size.
       (Terminals and some output devices have fonts that render at  only  one
       or  two  sizes.  As examples of the latter, 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,[0m
       [4mitalic,[24m and [4mbold‐italic.[24m  For linguistic text, GNU [4mtroff[24m  groups  type‐
       faces  into  [4mfamilies[24m containing each of these styles.  (Font designers
       prepare families such that the styles share  esthetic  properties.)   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
       typesetting devices, at least one [4mspecial[24m [4mfont[24m is available, comprising
       [4munstyled[24m glyphs for mathematical operators and other purposes.

       Like AT&T [4mtroff,[24m 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 charac‐
       terizes it, including its glyph repertoire and the [4mmetrics[24m (dimensions)
       of each glyph.  This information permits the  formatter  to  accurately
       place  glyphs with respect to each other.  Before using a font descrip‐
       tion, 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  coupled to a specific font family, in GNU [4mtroff[24m an output de‐
       vice can associate a style in the abstract sense with a mounting  posi‐
       tion.   Thus  the  default  family can be combined with a style dynami‐
       cally, producing a [4mresolved[24m [4mfont[24m [4mname.[0m

       Fonts often have trademarked names, and even Free  Software  fonts  can
       require  renaming upon modification.  [4mgroff[24m maintains a convention that
       a device’s serif font family is given the name [1mT [22m(“Times”),  its  sans‐
       serif  family [1mH [22m(“Helvetica”), and its monospaced family [1mC [22m(“Courier”).
       Historical inertia has driven [4mgroff[24m’s font identifiers to short  upper‐
       case  abbreviations  of font names, as with [1mTR[22m, [1mTB[22m, [1mTI[22m, [1mTBI[22m, and a spe‐
       cial 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  de‐
       fault  mounting position, and therefore style, is always [1m1 [22m([1mR[22m).  By is‐
       suing appropriate formatter instructions, you can  override  these  de‐
       faults before your document writes its first glyph.

       Terminal  output  devices  cannot change font families and lack special
       fonts.  They support style changes  by  overstriking,  or  by  altering
       ISO 6429/ECMA‐48 [4mgraphic[24m [4mrenditions[24m (character cell attributes).

[1mHyphenation[0m
       When  filling,  [4mgroff[24m  hyphenates words as needed at user‐specified and
       automatically determined  hyphenation  points.   Explicitly  hyphenated
       words  such  as  “mother‐in‐law” are always eligible for breaking after
       each of their hyphens.  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 [1m.hw  [22mrequest  sets  user‐defined
       hyphenation  points  for  specified words at any subsequent occurrence.
       Otherwise, [4mgroff[24m determines hyphenation  points  automatically  by  de‐
       fault.

       Several  requests influence automatic hyphenation.  Because conventions
       vary, a variety of hyphenation modes is available to the  [1m.hy  [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  de‐
       tails),  and  at  which positions within that word automatically deter‐
       mined hyphenation points are permissible.  The default is “[1m1[22m” for  his‐
       torical  reasons,  but this is not an appropriate value for the English
       hyphenation patterns used by [4mgroff[24m; localization macro files loaded  by
       [4mtroffrc[24m and macro packages often override it.

       [1m0      [22mdisables hyphenation.

       [1m1      [22menables  hyphenation  except after the first and before the last
              character 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.   (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[24m respected for words whose hyphenations have been specified with the
       hyphenation character (“[1m\%[22m” by default) or the [1m.hw [22mrequest.

       Nonzero values are additive.  For example, mode 12 causes [4mgroff[24m to  hy‐
       phenate  neither  the  last two nor the first two characters of a word.
       Some values cannot be used together because they  contradict;  for  in‐
       stance,  values  4 and 16, and values 8 and 32.  As noted, it is super‐
       fluous to add 1 to any non‐zero even mode.

       The places within a word that are eligible for hyphenation  are  deter‐
       mined  by language‐specific data ([1m.hla[22m, [1m.hpf[22m, and [1m.hpfa[22m) and lettercase
       relationships ([1m.hcode [22mand [1m.hpfcode[22m).   Furthermore,  hyphenation  of  a
       word might be suppressed due to a limit on consecutive hyphenated lines
       ([1m.hlm[22m), a minimum line length threshold ([1m.hym[22m), or because the line can
       instead be adjusted with additional inter‐word space ([1m.hys[22m).

[1mLocalization[0m
       The set of hyphenation patterns is associated with the hyphenation lan‐
       guage  set by the [1m.hla [22mrequest.  The [1m.hpf [22mrequest is usually invoked by
       a localization file loaded by the [4mtroffrc[24m file.  [4mgroff[24m provides  local‐
       ization files for several languages; see [4mgroff_tmac[24m(5).

[1mWriting macros[0m
       The  [1m.de  [22mrequest defines a macro named for its argument.  If that name
       already exists as an alias, the target of the alias is  redefined;  see
       section  “Strings” above.  [4mgtroff[24m enters “copy mode” (see below), stor‐
       ing 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).  Alternatively, a second argument names a macro  whose
       call  syntax  ends the definition; this “end macro” is then called nor‐
       mally.  Spaces or tabs are permitted after the first control  character
       in  the  line containing 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 sufficiently escaped.  An end macro need not be
       defined until it is called.  This fact enables a nested  macro  defini‐
       tion 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, returning 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; its
       value can be changed by 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.  Applying string interpolation to a  macro
       does not change this name.

   [1mCopy mode[0m
       When  [4mgtroff[24m  processes  certain requests, most importantly those which
       define or append to a macro or string, it does  so  in  [4mcopy[24m  [4mmode[24m:  it
       copies  the  characters  of the definition into a dedicated storage re‐
       gion, interpolating the escape sequences [1m\n[22m, [1m\g[22m, [1m\$[22m,  [1m\*[22m,  [1m\V[22m,  and  [1m\?[0m
       normally; interpreting [1m\[4m[22mnewline[24m immediately; discarding comments [1m\" [22mand
       [1m\#[22m; interpolating the current leader, escape, or tab character with [1m\a[22m,
       [1m\e[22m,  and [1m\t[22m, respectively; and storing all other escape sequences in an
       encoded form.  The complement of copy mode—a [4mroff[24m formatter’s  behavior
       when  not  defining or appending to a macro, string, or diversion—where
       all macros are interpolated, requests invoked,  and  valid  escape  se‐
       quences processed immediately upon recognition, can be termed [4minterpre‐[0m
       [4mtation[24m [4mmode[24m.

       The  escape  character,  [1m\ [22mby default, can escape itself.  This enables
       you to control whether a given [1m\n[22m, [1m\g[22m, [1m\$[22m, [1m\*[22m, [1m\V[22m,  or  [1m\?  [22mescape  se‐
       quence  is  interpreted 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  charac‐
       ter followed by a backslash from which the escape character has removed
       its special meaning.  Consequently, [1m\\ [22mis not an escape sequence in the
       usual sense.  In any escape sequence [1m\[4m[22mX[24m that [4mgtroff[24m does not recognize,
       the  escape  character is ignored and [4mX[24m is output.  An unrecognized es‐
       cape sequence causes a warning in category “[1mescape[22m”,  with  two  excep‐
       tions,  [1m\\ [22mbeing one.  The other is [1m\.[22m, which escapes the control char‐
       acter.  It is used to permit nested macro definitions to end without  a
       named  macro  call to conclude them.  Without a syntax for escaping the
       control character, this would not be possible.  [4mroff[24m  documents  should
       not  use  the  [1m\\  [22mor [1m\. [22mcharacter sequences outside of copy mode; they
       serve only to obfuscate the input.  Use  [1m\e  [22mto  represent  the  escape
       character,  [1m\[rs]  [22mto  obtain  a backslash glyph, and [1m\& [22mbefore [1m. [22mand [1m'[0m
       where [4mgtroff[24m expects them as control characters if you mean to use them
       literally.

       Macro definitions can be nested to arbitrary depth.  In “[1m\\[22m”, each  es‐
       cape  character  is interpreted twice—once in copy mode, when the macro
       is defined, and once in interpretation mode, when the macro is  called.
       This fact leads to exponential growth in the quantity of escape charac‐
       ters  required  to delay interpolation of [1m\n[22m, [1m\g[22m, [1m\$[22m, [1m\*[22m, [1m\V[22m, and [1m\? [22mat
       each nesting level.  An alternative is to use [1m\E[22m, which  represents  an
       escape  character  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 prematurely.  If the multiplicity of backslashes com‐
       plicates 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[0m
       [4mtrap[24m  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 on the page ([1m.wh[22m, [1m.ch[22m); at  a
       given location in the current diversion ([1m.dt[22m)—together, these are known
       as  vertical  position  traps,  which  can  be  disabled and re‐enabled
       ([1m.vpt[22m).

       A diversion is not formatted in the context of a page, so it lacks page
       location 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 ([1m.blm[22m); at a line
       with leading space characters ([1m.lsm[22m); after a certain number of produc‐
       tive input lines ([1m.it[22m, [1m.itc[22m); or at the end  of  input  ([1m.em[22m).   Macros
       called by traps are passed no arguments.  Setting a trap is also called
       [4mplanting[24m  one.   It  is  said that a trap is [4msprung[24m if its condition is
       fulfilled.

       Registers associated with trap  management  include  vertical  position
       trap  enablement status ([1m\n[.vpt][22m), distance to the next trap ([1m\n[.t][22m),
       amount of needed ([1m.ne[22m‐requested) space that caused the most recent ver‐
       tical position trap to be sprung  ([1m\n[.ne][22m),  amount  of  needed  space
       truncated  from the amount requested ([1m\n[.trunc][22m), page ejection status
       ([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 undiverted output.  Many can be present; manage  them
       with  the  [1mwh  [22mand  [1mch  [22mrequests.  Non‐negative page locations given to
       these requests 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 pos‐
       sible  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 exist‐
       ing [4mvisible[24m trap (see below) at the same location is removed;  this  is
       [1m.wh[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
       reachable 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
       visible  by  either moving it into the page area or increasing the page
       length so that the trap is on the page.  Negative  trap  values  always
       use the [4mcurrent[24m page length; they are not converted to an absolute ver‐
       tical  position.   Use [1m.ptr [22mto dump page location traps to the standard
       error stream; their positions are reported in basic units.

   [1mThe implicit page trap[0m
       An [4mimplicit[24m [4mpage[24m [4mtrap[24m always exists  in  the  top‐level  diversion;  it
       works like a trap in some ways but not others.  Its purpose is to eject
       the  current page and start the next one.  It has no name, so it cannot
       be moved or deleted with [1mwh [22mor [1mch [22mrequests.   You  cannot  hide  it  by
       placing  another trap at its location, and can move it only by redefin‐
       ing the page length with [1m.pl[22m.  Its operation is suppressed when  verti‐
       cal page traps are disabled with the [1mvpt [22mrequest.

[1mDiversions[0m
       In [4mroff[24m systems it is possible to format text as if for output, but in‐
       stead of writing it immediately, one can [4mdivert[24m the formatted text into
       a named storage area.  It is retrieved later by specifying its name af‐
       ter  a  control character.  The same name space is used for such [4mdiver‐[0m
       [4msions[24m as for strings and macros; see section “Identifiers” above.  Such
       text is sometimes said to be “stored in a macro”, but this coinage  ob‐
       scures the important distinction between macros and strings on one hand
       and  diversions  on the other; the former store [4munformatted[24m input text,
       and the latter capture [4mformatted[24m output.  Diversions also do not inter‐
       pret arguments.  Applications of diversions include “keeps” (preventing
       a page break from occurring at an inconvenient place by forcing  a  set
       of  output  lines to be set as a group), footnotes, tables of contents,
       and indices.  For orthogonality it is said that GNU  [4mtroff[24m  is  in  the
       [4mtop‐level[24m  [4mdiversion[24m if no diversion is active (that is, formatted out‐
       put is being “diverted” immediately to the output device.

       Dereferencing an undefined diversion will create an empty one  of  that
       name  and  cause a warning in category [1mmac [22mto be emitted.  (see section
       “Warnings” in [4mgtroff[24m(1)).  A diversion does not exist for  the  purpose
       of testing with the [1md [22mconditional 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.
       [1mbox  [22mand  [1mboxa  [22mworks  similarly, but ignore partially collected lines.
       Call any of these macros again without an argument to  end  the  diver‐
       sion.

       Diversions  can be nested.  The registers [1m.d[22m, [1m.z[22m, [1mdn[22m, and [1mdl [22mreport in‐
       formation about the current (or last closed) diversion.  [1m.h [22mis meaning‐
       ful in diversions, including the top level.

       The [1m\!  [22mand [1m\?  [22mescape sequences and [1moutput [22mrequest escape from  a  di‐
       version,  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 [22mrequests reprocess diversions.

[1mPunning names[0m
       Macros, strings, and diversions share a name space; see section  “Iden‐
       tifiers”  above.  Internally, the same mechanism is used to store them.
       You can thus call a macro with string  interpolation  syntax  and  vice
       versa.   Interpolating a string does not hide existing macro arguments.
       The sequence [1m\\ [22mcan be placed at the end of a line in a  macro  defini‐
       tion or, within a macro definition, 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” exists when [4mgtroff[24m starts up; it is
       modified by formatting‐related requests and escape sequences.

       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 cur‐
       rent environment; it remains accessible 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 envi‐
       ronment stack, use the [1mpev [22mrequest; see section “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
         spacing, indentation, line numbering, centering, right‐alignment, un‐
         derlining, hyphenation parameters)

       • filling enablement; adjustment enablement and mode

       • tab  stops;  tab,  leader, escape, control, no‐break control, hyphen‐
         ation, and margin characters

       • input line traps

       • stroke and fill colors

       The [1mev [22mrequest pushes to and pops from the environment stack, while [1mevc[0m
       copies a named environment’s contents to the current one.

[1mUnderlining[0m
       In [4mRUNOFF[24m (see [4mroff[24m(7)), underlining, even  of  lengthy  passages,  was
       straightforward  because  only  fixed‐pitch  printing devices were tar‐
       geted.  Typesetter output posed a greater challenge.   There  exists  a
       [4mgroff[24m  request  [1m.ul [22m(see above) that underlines subsequent source lines
       on terminal devices, but on typesetters,  it  selects  an  italic  font
       style  instead.   The [4mms[24m macro package (see [4mgroff_ms[24m(7)) offers a macro
       [1m.UL[22m, but it too produces the desired effect only  on  typesetters,  and
       has other limitations.

       One  could  adapt  [4mms[24m’s approach to the construction of a macro as fol‐
       lows.
              .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 [4mdoclifter[24m(1) makes trouble, change the  macro  name  [1mUNDERLINE  [22minto
       some 2‐letter word, like [1mUl[22m.  Moreover, change the form of the font se‐
       lection 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[0m
       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 po‐
       sition,  enabling overstriking.  Thus, [1m\z[4m[22mc[24m[1m\(ul [22mformats [4mc[24m with an under‐
       rule 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[24m and [4mtroff[24m modes.

       Long  words  may  then look intimidating in the input; a clarifying ap‐
       proach 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
       The 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
       intermediate  output  formats  described  by CSTR #54 are documented in
       [4mgroff_diff[24m(7).  [4mgroff[24m provides an AT&T compatibility mode.  The [1m.cp [22mre‐
       quest and registers [1m.C [22mand [1m.cp [22mset and  test  the  enablement  of  this
       mode.

[1mDebugging[0m
       Preprocessors  use  the  [1m.lf [22mrequest to preserve the identities of line
       numbers and names of input files.  [4mgroff[24m emits a variety of error diag‐
       nostics and supports several categories of warning; the output of these
       can be selectively suppressed with [1m.warn [22m(and see the [1m-E[22m,  [1m-w[22m,  and  [1m-W[0m
       options  of  [4mgtroff[24m(1)).   A  trace of the formatter’s input processing
       stack can be  emitted  when  errors  or  warnings  occur  by  means  of
       [4mgtroff[24m(1)’s  [1m-b  [22moption,  or produced on demand with the [1m.backtrace [22mre‐
       quest.  [1m.tm[22m, [1m.tmc[22m, and [1m.tm1 [22mcan be used to emit  customized  diagnostic
       messages  or  for  instrumentation  while troubleshooting.  [1m.ex [22mand [1m.ab[0m
       cause early termination with successful and error  exit  codes  respec‐
       tively,  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—([1m.pm[22m);  environments
       ([1m.pev[22m), registers ([1m.pnr[22m), and page location traps ([1m.ptr[22m) to  the  stan‐
       dard error stream.

[1mAuthors[0m
       This document was written by by Trent A. Fisher, Werner Lemberg, and G.
       Branden Robinson ⟨g.branden.robinson@gmail.com⟩.  Section “Underlining”
       was primarily written by Bernd Warken ⟨groff-bernd.warken-72@web.de⟩.

[1mSee also[0m
       [4mGroff:[24m  [4mThe[24m  [4mGNU[24m [4mImplementation[24m [4mof[24m [4mtroff[24m, by Trent A. Fisher and Werner
       Lemberg, 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 output
       format 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 output format.

       [4mgroff[24m(1)
              is the preferred interface to the [4mgroff[24m system; it  manages  the
              pipeline  that  carries a source document through preprocessors,
              the [4mgtroff[24m formatter, and an output driver to viewable or print‐
              able form.  It also exhaustively lists the  man  pages  provided
              with the GNU [4mroff[24m system.

       [4mgroff_char[24m(7)
              discusses  character encoding issues, escape sequences that pro‐
              duce glyphs, and enumerates [4mgroff[24m’s predefined special character
              escape sequences.

       [4mgroff_diff[24m(7)
              covers differences between the GNU [4mtroff[24m formatter,  its  device
              and font description file formats, its device‐independent output
              format, and those of AT&T [4mtroff[24m, whose design it reimplements.

       [4mgroff_font[24m(5)
              describes  the formats of the files that describe devices ([4mDESC[24m)
              and fonts.

       [4mgroff_tmac[24m(5)
              surveys macro packages provided with [4mgroff[24m, describes how  docu‐
              ments  can  take  advantage  of them, offers guidance on writing
              macro packages and using diversions, and includes historical in‐
              formation on macro package naming conventions.

       [4mroff[24m(7)
              presents a detailed history of [4mroff[24m systems and summarizes  con‐
              cepts common to them.

groff 1.23.0                      2 July 2023                         [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  mathe‐
       matical  documents.  [4mgroff[24m works with [4mcharacters;[24m an output device ren‐
       ders [4mglyphs.[24m  [4mgroff[24m’s input character set is restricted to that defined
       by the standards ISO Latin‐1 (ISO 8859‐1) and CCSID  “code  page”  1047
       (an  EBCDIC  arrangement of Latin‐1).  For ease of document maintenance
       in UTF‐8 environments, it is advisable to use only  the  Unicode  basic
       Latin  code  points,  a subset of all of the foregoing historically re‐
       ferred to as US‐ASCII,  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 typeset‐
       ter’s glyph repertoire differed from that of the  computers  that  con‐
       trolled  it.  [4mtroff[24m’s solution was a form of escape sequence known as a
       [4mspecial[24m [4mcharacter[24m 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  per‐
       mits  users to define their own special character escape sequences with
       the [1mchar [22mrequest.  Special character names are [4mgroff[24m  identifiers;  see
       section  “Identifiers”  in  [4mgroff[24m(7).   Our  discussion  uses the terms
       “glyph name” and “special character name” interchangeably; we assume no
       character translations or redefinitions.

       This document lists all of the glyph names predefined by  [4mgroff[24m’s  font
       description  files and presents the systematic notation by which it en‐
       ables access to arbitrary Unicode code points and construction of  com‐
       posite  glyphs.   Glyphs  listed may be unavailable, or may vary in ap‐
       pearance, depending on the output device and font chosen when the  page
       was formatted.  This page was rendered for device [1mutf8 [22musing font [1mR[22m.

       A  few escape sequences that are not [4mgroff[24m special characters also pro‐
       duce 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 [4mgroff[24m(7).  A small number of spe‐
       cial characters represent glyphs that are not encoded in Unicode; exam‐
       ples include the baseline rule [1m\[ru] [22mand the Bell System logo [1m\[bs].[0m

       In [4mgroff[24m, you can test output device support for any  character  (ordi‐
       nary 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.

       For  brevity  in the remainder of this document, we shall refer to sys‐
       tems conforming to the ISO 646:1991 IRV, ISO 8859, or ISO 10646  (“Uni‐
       code”) character encoding standards as “ISO” systems, and those employ‐
       ing  IBM code page 1047 as “EBCDIC” systems.  That said, EBCDIC systems
       that support [4mgroff[24m are known to also support UTF‐8.

       While [4mgroff[24m accepts eight‐bit encoded input, not all such  code  points
       are  valid  as  input.  On ISO platforms, 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].)  On
       EBCDIC platforms, 0, 8–9, 11, 13–20,  23–31,  and  48–63  are  invalid.
       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[0m
       input;  anything  in the language, even over one million code points in
       Unicode, can be expressed using it.  On ISO systems, 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.  On EBCDIC systems,
       printable characters are in the range 66–201 and 203–254; those without
       counterparts in the ISO range 33–126 are discussed in the next  subsec‐
       tion.

       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
       others intimately familiar with the ISO character encodings.   The  de‐
       velopers of AT&T [4mtroff[24m chose mappings for them that would be useful for
       typesetting  technical literature in a broad range of scientific disci‐
       plines: Bell Labs used the system for preparation of AT&T’s patent fil‐
       ings with the U.S. government.  Further, the prevailing  character  en‐
       coding  standard  in  the 1970s, USAS X3.4‐1968 (“ASCII”), deliberately
       supported semantic ambiguity at some code points, and outright  substi‐
       tution  at  several others, to suit the localization demands of various
       national standards bodies.

       The table below presents the seven exceptional code points  with  their
       typical  keycap  engravings, their glyph mappings and semantics in [4mroff[0m
       systems, and the escape sequences producing  the  Unicode  basic  Latin
       character they replace.  The first, the neutral double quote, is a par‐
       tial  exception  because  it  does represent itself, but since the [4mroff[0m
       language also uses it to quote macro arguments, [4mgroff[24m supports  a  spe‐
       cial 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.)  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  charac‐
       ter  escape  sequences are shown in the traditional [1m\( [22mform.  [1m\- [22mand [1m\e[0m
       are 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[0m
       request 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 dis‐
       tinguishable  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” char‐
       acter  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
       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 equations, 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
       single 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 ordinary 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 es‐
       cape sequences should be used for quotation marks unless portability to
       limited or historical [4mtroff[24m implementations is necessary; on those sys‐
       tems, the input convention is to pair the grave accent with  the  apos‐
       trophe  for  single  quotes,  and  to double both characters for double
       quotes.  AT&T [4mtroff[24m defined no special characters 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).
        ┌─────────────────────────────────────────────────────────────────┐
        │ 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
       quotation, or define them yourself (except in man pages).

       Using Unicode basic Latin characters to compose boxes and lines is ill‐
       advised.   [4mroff[24m  systems have special characters for drawing horizontal
       and vertical lines; see subsection “Rules and lines” below.  Preproces‐
       sors like [4mgtbl[24m(1) and [4mgpic[24m(1) draw boxes and will produce the best pos‐
       sible 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 8859‐1 and code page 1047 allocated the  addi‐
       tional  space  to what Unicode calls “C1 controls” (control characters)
       and the “Latin‐1 supplement”.  The C1 controls  are  neither  printable
       nor usable as [4mgroff[24m input.

       Two  Latin‐1  supplement  characters  are  handled  specially on input.
       [4mgtroff[24m never produces them as output.

       NBSP   encodes a no‐break space; it is mapped  to  [1m\~[22m,  the  adjustable
              non‐breaking space escape sequence.

       SHY    encodes  a soft hyphen; it is mapped to [1m\%[22m, the hyphenation con‐
              trol escape sequence.

       The remaining characters in  the  Latin‐1  supplement  represent  them‐
       selves.   Although  they can be specified directly with the keyboard on
       systems configured 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  character escape sequences, shown below.  The glyph de‐
       scriptions 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  di‐
       rectly  represent  them are entered by one of several special character
       escape forms.  Such glyphs can be simple or composite, and accessed ei‐
       ther by name or numerically by code point.  Code points  and  combining
       properties  are  determined  by  character  encoding standards, whereas
       glyph names as used here originated in AT&T [4mtroff[24m special character es‐
       cape sequences.  Predefined glyph names use only characters in the  ba‐
       sic 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  sup‐
              ported 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
              apostrophe, can be any character not  occurring  in  [4mglyph‐name[24m.
              This  syntax  form  was introduced in later versions of AT&T de‐
              vice‐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  foregoing acute accent example can be expressed in [4mgroff[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 re‐
       quest 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 description files and diagnostic messages) [1m\a[22m, which  is  typi‐
       cally  undefined.  The only such glyph name [4mgroff[24m predefines is the mi‐
       nus 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
              accent, as in the word “café”, can be expressed as [1m\[e aa][22m.  See
              subsection “Accents” below for a table of combining glyph names.

       Unicode encodes far more characters than [4mgroff[24m  has  glyph  names  for;
       special  character  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[0m
       with the [1mchar [22mrequest; see [4mgroff[24m(7).

       [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] [22maccesses the (spacing) ring accent, pro‐
              ducing “˚”.

       Unicode code points can be composed as well; when they are,  GNU  [4mtroff[0m
       requires NFD (Normalization Form D), where all Unicode glyphs are maxi‐
       mally  decomposed.   (Exception:  precomposed characters in the Latin‐1
       supplement described above are also accepted.  Do not count on this ex‐
       ception remaining in a future GNU [4mtroff[24m that accepts  UTF‐8  input  di‐
       rectly.)   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 char‐
              acter escape sequences.  The code points of the base  glyph  and
              the combining 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  lead‐
              ing  zeroes.   This  legacy numeric special character escape se‐
              quence is used to map characters onto glyphs via  the  [1mtrin  [22mre‐
              quest in macro files loaded by [4mgrotty[24m(1).

[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
               replacement), [4mgroff[24m attempts reasonable equivalency on all out‐
               put devices.

       [1mInput   [22mshows the [4mgroff[24m character (ordinary or special)  that  normally
               produces  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 Uni‐
               code 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
               purposes.   On  typesetting  devices, such glyphs are typically
               drawn from a [4mspecial[24m font  (see  [4mgroff_font[24m(5)).   Often,  such
               glyphs  lack  bold  or  italic style forms or have metrics that
               look incongruous in ordinary prose.  A few which are not uncom‐
               mon 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  mathe‐
               matical  equations.   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
       subsection “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  symme‐
       try 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  special  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] [22mcould be considered a ligature of “sz”.  An  upper‐
       case 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
       Normally,  the  formatting  of a special character advances the drawing
       position as an ordinary character does.  [4mgroff[24m’s [1mcomposite [22mrequest des‐
       ignates a special character as  combining.   The  [4mcomposite.tmac[24m  macro
       file,  loaded  automatically by the default [4mtroffrc[24m, maps the following
       special characters to the combining characters shown below.   The  non‐
       combining  code point in parentheses is used when the special character
       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
       below 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,  often useful when documenting programming
       languages, is also available as a special character for convenient  em‐
       bedding  in macro arguments; 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
       confusable  with the [4mgroff[24m mnemonic for the visually similar but seman‐
       tically distinct multiplication dot; see subsection “Mathematical  sym‐
       bols” 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
       ‐        \[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‐in‐
       variant; [4mgroff[24m maps them rather 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 escape’s piling algorithm.  A general  solu‐
       tion to build brackets out of pieces is the following macro:
              .\" 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

       Another  complication  is  the  fact  that  some glyphs which represent
       bracket pieces in AT&T [4mtroff[24m can be used for other mathematical symbols
       as well, for example [1m\(lf [22mand [1m\(rf[22m, which provide the  floor  operator.
       Some  output  devices,  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
       “Brackets” 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 input character [1m_ [22malways accesses 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 subsec‐
       tion “Mathematical 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  de‐
       pending  on  the  device  and font selected.  Unicode does not encode a
       discrete “bitwise or” sign: on typesetting devices, it is drawn shorter
       than the bar, about the same height as a capital letter.  Terminal  de‐
       vices unify [1m\[ba] [22mand [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.
       Observe the two varieties of the plus‐minus, multiplication, and  divi‐
       sion signs; [1m\[+-][22m, [1m\[mu][22m, and [1m\[di] [22mare normally drawn from the special
       font,  but  have  text  font  variants.   Also be aware of three glyphs
       available in special font variants that are normally  drawn  from  text
       fonts: the plus, minus, and equals signs.  These variants may differ in
       appearance or spacing depending on the device and font selected.

       In  AT&T  [4mtroff[24m, [1m\(rn [22m(“root en extender”) served as the horizontal ex‐
       tension of the radical (square root) sign, [1m\(sr[22m, and was drawn  at  the
       maximum height of the typeface’s bounding box; this enabled the special
       character  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 counterparts  with  mathe‐
       matical spacing.

       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 + ***
       ÷        \[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
       language text; normally, the uppercase letters have upright shape,  and
       the lowercase ones are slanted.

       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     lowercase alpha +
       β        \[*b]   u03B2     lowercase beta +
       γ        \[*g]   u03B3     lowercase gamma +
       δ        \[*d]   u03B4     lowercase delta +
       ε        \[*e]   u03B5     lowercase epsilon +
       ζ        \[*z]   u03B6     lowercase zeta +
       η        \[*y]   u03B7     lowercase eta +
       θ        \[*h]   u03B8     lowercase theta +
       ι        \[*i]   u03B9     lowercase iota +
       κ        \[*k]   u03BA     lowercase kappa +
       λ        \[*l]   u03BB     lowercase lambda +
       μ        \[*m]   u03BC     lowercase mu +
       ν        \[*n]   u03BD     lowercase nu +
       ξ        \[*c]   u03BE     lowercase xi +
       ο        \[*o]   u03BF     lowercase omicron +
       π        \[*p]   u03C0     lowercase pi +
       ρ        \[*r]   u03C1     lowercase rho +
       σ        \[*s]   u03C3     lowercase sigma +
       τ        \[*t]   u03C4     lowercase tau +
       υ        \[*u]   u03C5     lowercase upsilon +
       ϕ        \[*f]   u03D5     lowercase phi +
       χ        \[*x]   u03C7     lowercase chi +
       ψ        \[*q]   u03C8     lowercase psi +
       ω        \[*w]   u03C9     lowercase omega +

       ϵ        \[+e]   u03F5     variant epsilon (lunate)
       ϑ        \[+h]   u03D1     variant theta (cursive form)
       ϖ        \[+p]   u03D6     variant pi (similar to omega)
       φ        \[+f]   u03C6     variant phi (curly shape)
       ς        \[ts]   u03C2     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 idiosyn‐
       cratic fifty years afterward.  (See section “History”  of  [4mroff[24m(7)  for
       more context.)  The face used by the Teletype Model 37 terminals of the
       Murray  Hill  Unix Room was based on ASCII, but assigned multiple mean‐
       ings to several code points, as suggested by that standard.  Decimal 34
       ([1m"[22m) served as a dieresis accent and neutral double quotation mark; dec‐
       imal 39 ([1m'[22m) as an acute accent, apostrophe, and closing (right)  single
       quotation mark; decimal 45 ([1m-[22m) as a hyphen and a minus sign; decimal 94
       ([1m^[22m)  as a circumflex accent 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[24m [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  ro‐
       man,  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  commissioned  a “special” font to ensure no loss of reper‐
       toire.

       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 resem‐
       bling 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  ap‐
       peared in the special font despite availability in text fonts “to insu‐
       late  the  appearance  of  equations from the choice of standard [read:
       text] fonts”—a priority since [4mtroff[24m was turned to the task of mathemat‐
       ical 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  dupli‐
       cated 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  aban‐
       doned.   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][0m
       were used as contextually appropriate.

       Devices supported by AT&T device‐independent [4mtroff[24m exhibited some  dif‐
       ferences  in  glyph detail.  For example, on the Autologic APS‐5 photo‐
       typesetter, 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/pkg/share/groff/1.23.0/tmac/composite.tmac[0m
              assigns alternate mappings for identifiers after the first in  a
              composite  special  character  escape  sequence.  See subsection
              “Accents” above.

       [4m/usr/pkg/share/groff/1.23.0/tmac/fallbacks.tmac[0m
              defines fallback mappings for Unicode code points  such  as  the
              increment sign (U+2206) and upper‐ and lowercase Roman numerals.

[1mAuthors[0m
       This  document  was written by James Clark ⟨jjc@jclark.com⟩, with addi‐
       tions by Werner Lemberg  ⟨wl@gnu.org⟩  and  Bernd  Warken  ⟨groff-bernd
       .warken-72@web.de⟩,  revised  to  use  [4mgtbl[24m(1) by Eric S. Raymond ⟨esr@
       thyrsus.com⟩, and largely rewritten by G. Branden  Robinson  ⟨g.branden
       .robinson@gmail.com⟩.

[1mSee also[0m
       [4mGroff:[24m  [4mThe[24m  [4mGNU[24m [4mImplementation[24m [4mof[24m [4mtroff[24m, by Trent A. Fisher and Werner
       Lemberg, is the primary [4mgroff[24m manual.  Section “Using Symbols”  may  be
       of  particular  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.
       Simonsen, J. Akkerhuis; EUUG Newsletter, Volume 9, No. 2, Summer 1989

       The Unicode Standard ⟨http://www.unicode.org⟩

       “7‐bit Character Sets”  ⟨https://www.aivosto.com/articles/charsets-7bit
       .html⟩  by  Tuomas  Salste documents the inherent ambiguity and config‐
       urable code points of the ASCII encoding standard.

       “Nroff/Troff User’s Manual” by Joseph F. Ossanna, 1976, AT&T Bell Labo‐
       ratories 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 original 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[0m
       users.

       [4mgroff_rfc1345[24m(7)  describes  an  alternative  set  of special character
       glyph names, which extends and in some cases overrides the  definitions
       listed above.

       [4mgroff[24m(1), [4mtroff[24m(1), [4mgroff[24m(7)

groff 1.23.0                      2 July 2023                    [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 an extension 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[0m
       formatter.  Differences arising from  [4mgroff[24m’s  implementation  of  AT&T
       [4mtroff[24m features are also noted.  See [4mroff[24m(7) for background.

[1mLanguage[0m
       GNU [4mtroff[24m features identifiers of arbitrary length; supports color out‐
       put,  non‐integral  type  sizes, and user‐defined characters; adds more
       conditional expression operators; recognizes additional  scaling  units
       and  numeric  operators;  enables  general  file  I/O (in “unsafe mode”
       only); and exposes more formatter state.

   [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 regis‐
       ters, fonts, strings/macros/diversions, environments,  special  charac‐
       ters,  streams,  and  colors can be of any length.  Anywhere AT&T [4mtroff[0m
       supports a parameterized escape sequence that uses an opening parenthe‐
       sis “(” 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 containing each of the
       styles “[1mR[22m”, “[1mI[22m”, “[1mB[22m”, and “[1mBI[22m”.  So that a document need not be coupled
       to  a  specific  font family, an output device can associate a style in
       the abstract sense with a mounting position.  Thus the  default  family
       can  be  combined  with  a style dynamically, producing a [4mresolved[24m [4mfont[0m
       [4mname.[24m  A document can [4mtranslate,[24m or remap, fonts with the [1mftr [22mrequest.

       Applying the requests [1mcs[22m, [1mbd[22m, [1mtkf[22m, [1muf[22m, or [1mfspecial [22mto an abstract style
       affects 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 mounting positions (if any) are  initially  associated  with  ab‐
       stract  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
       limited.   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 inte‐
       rior  of  filled  geometric  figures.  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[0m
       registers exercise color support.

   [1mFractional type sizes and new scaling units[0m
       AT&T  [4mtroff[24m interpreted all type size measurements in points.  Combined
       with integer arithmetic, this design choice made it impossible to  sup‐
       port, 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 type size.

       A [4mscaled[24m [4mpoint[24m is equal to 1/[4msizescale[24m points, where [4msizescale[24m is spec‐
       ified in the device description file, [4mDESC[24m,  and  defaults  to  1;  see
       [4mgroff_font[24m(5).   Requests  and  escape sequences in GNU [4mtroff[24m interpret
       arguments that represent a type size in  points,  which  the  formatter
       multiplies  by [4msizescale[24m and converts to an integer.  Arguments treated
       in this way 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.  Scaled points  may  be  specified
       explicitly  with the [1mz [22mscaling unit.  In GNU [4mtroff[24m, the register [1m\n[.s][0m
       can interpolate a non‐integral type size.  The register [1m\n[.ps]  [22minter‐
       polates the type size in scaled points.

       For  example,  if  [4msizescale[24m  is 1000, then a scaled point is one thou‐
       sandth of a point.  Consequently, “[1m.ps 10.5[22m” is  synonymous  with  “[1m.ps[0m
       [1m10.5z[22m”; both set the type size to 10,500 scaled points, or 10.5 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  disal‐
       lows  this.   Similarly,  it is nonsensical to use a scaling unit other
       than “[1mz[22m” or “[1mu[22m” in a numeric  expression  whose  default  scaling  unit
       is “[1mz[22m”, so GNU [4mtroff[24m disallows this as well.

       Another  new scaling unit, “[1ms[22m”, multiplies by the number of basic units
       in a scaled point.  Thus, “[1m\n[.ps]s[22m” is equal to  “[1m1m[22m”  by  definition.
       Do not confuse the “[1ms[22m” and “[1mz[22m” scaling units.

       Output  devices  may be limited in the type sizes they can employ.  The
       [1m.s [22mand [1m.ps [22mregisters represent the type size as selected by the  output
       driver  as  it  understands  a device’s capability.  The last [4mrequested[0m
       type size is interpolated in scaled points by  the  read‐only  register
       [1m.psr [22mand in points as a decimal fraction by the read‐only string‐valued
       register  [1m.sr[22m.  Both are associated with the environment.  For example,
       if a type size of 10.95 points is requested, and the nearest size  per‐
       mitted  by  a [1msizes [22mrequest (or by the [1msizes [22mor [1msizescale [22mdirectives in
       the device’s [4mDESC[24m file) is 11 points, the output driver uses the latter
       value.

       A further two new measurement units available in [4mgroff[24m are  “[1mM[22m”,  which
       indicates  hundredths  of  an  em, and “[1mf[22m”, which multiplies by 65,536.
       The latter provides convenient fractions for color definitions with the
       [1mdefcolor [22mrequest.  For example, 0.5f equals 32768u.

   [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 [4me1[24m and [4me2[24m.

       [4me1[24m[1m<?[4m[22me2[24m Interpolate the lesser of [4me1[24m and [4me2[24m.

       [1m([4m[22mc[24m[1m;[4m[22me[24m[1m)  [22mEvaluate [4me[24m using [4mc[24m as the default scaling unit, ignoring scaling
              units in [4me[24m if [4mc[24m is empty.

   [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, where [4mchr[24m is an ordinary
              character (Unicode basic Latin excluding control characters  and
              the space), a special character, or [1m\N'[4m[22mindex[24m[1m'[22m.

       [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 accessed with the [1mft[0m
              request (that is, abstract styles and font translation  are  ap‐
              plied),  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 a style [4msty[24m is registered.  Font translation applies.

       [1mv      [22mAlways false.  This condition is for compatibility with  certain
              other  [4mtroff[24m  implementations  only.   (This refers to [4mvtroff[24m, a
              translator that would convert the C/A/T output  from  early‐vin‐
              tage  AT&T [4mtroff[24m to a form suitable for Versatec and Benson‐Var‐
              ian plotters.)

   [1mDrawing commands[0m
       GNU [4mtroff[24m offers drawing commands to  create  filled  circles  and  el‐
       lipses,  and  polygons.   Stroked (outlined) objects are drawn with the
       stroke color and filled (solid) ones shaded with the fill color.  These
       are independent properties; if you want a filled, stroked  figure,  you
       must  draw  the same figure twice using each drawing command.  A filled
       figure is always smaller than a stroked one because the former is drawn
       only within its defined area, whereas strokes  have  a  line  thickness
       (set with another new drawing command, [1m\D't'[22m).

   [1mEscape sequences[0m
       [4mgroff[24m introduces several new escape sequences and extends the syntax of
       a  few AT&T [4mtroff[24m escape sequences (namely, [1m\D[22m, [1m\f[22m, [1m\k[22m, [1m\n[22m, [1m\s[22m, [1m\$[22m, and
       [1m\*[22m).  In the following list, escape sequences are  collated  alphabeti‐
       cally at first, and then by symbol roughly in Unicode code point order.

       [1m\A'[4m[22manything[24m[1m'[0m
              Interpolate  1  if  [4manything[24m is a valid identifier, and 0 other‐
              wise.  Because invalid input  characters  are  removed,  invalid
              identifiers are empty or contain spaces, tabs, or newlines.  You
              can  employ  [1m\A  [22mto validate a macro argument before using it to
              construct another escape sequence or identifier.

       [1m\B'[4m[22manything[24m[1m'[0m
              Interpolate 1 if [4manything[24m is a valid numeric expression,  and  0
              otherwise.  You might use [1m\B [22malong with the “[1mif[22m” request to fil‐
              ter out invalid macro arguments.

       [1m\D'C [4m[22md[24m[1m'[0m
              Draw  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 with [4mh[24m and [4mv[24m as the axes  and  the  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 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.

       [1m\D't [4m[22mn[24m[1m'[0m
              Set line thickness of geometric objects to to [4mn[24m basic units.   A
              zero  [4mn[24m  selects  the minimal supported thickness.  A negative [4mn[0m
              selects a thickness proportional to the type size; this  is  the
              default.

       [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 which will be
              interpolated at varying macro nesting depths.

       [1m\f[[4m[22mfont[24m[1m][0m
              Select [4mfont[24m, which may be a mounting position,  abstract  style,
              or  font  name,  to  choose the typeface.  [1m\f[] [22mand [1m\fP [22mare syn‐
              onyms; we recommend the former.

       [1m\F[4m[22mf[0m
       [1m\F([4m[22mfm[0m
       [1m\F[[4m[22mfamily[24m[1m][0m
              Select 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][0m
              Mark  horizontal  drawing  position  in  two‐character  register
              name [4mrg[24m or arbitrary register name [4mreg[24m.

       [1m\m[4m[22mc[0m
       [1m\m([4m[22mcl[0m
       [1m\m[[4m[22mcol[24m[1m][0m
              Set the stroke color.  [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][0m
              Set  the  fill color.  [1m\M[] [22mrestores the previous fill color, or
              the default if there is none.

       [1m\n[[4m[22mreg[24m[1m][0m
              Interpolate register [4mreg[24m.

       [1m\O[4m[22mn[0m
       [1m\O[[4m[22mn[24m[1m]  [22mSuppress [4mgtroff[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
              [4mgrohtml[24m(1).

              [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
                     aforementioned   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 [4mgpic[24m,  [4mgeqn[24m,  and  [4mgtbl[24m.   At  startup,
                     [4mgtroff[24m   is   at   the   outermost   suppression   level.
                     [4mpre-grohtml[24m generates these sequences when processing the
                     document, using [4mgtroff[24m with the [1mps [22moutput device,  Ghost‐
                     script,  and  the PNM tools to produce images in PNG for‐
                     mat.  These sequences start a new page if the  device  is
                     not  [1mhtml [22mor [1mxhtml[22m, to reduce the number of images cross‐
                     ing a page boundary.

              [1m\O5[[4m[22mPfile[24m[1m][0m
                     At the outermost suppression level, write the  name  [4mfile[0m
                     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, cen‐
                     tered, and inline alignments within the document, respec‐
                     tively.  [4mfile[24m is 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[[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  scaled
              points.

       [1m\V[4m[22me[0m
       [1m\V([4m[22mev[0m
       [1m\V[[4m[22menv[24m[1m][0m
              Interpolate  contents  of  the  environment variable [4menv[24m, as re‐
              turned by [4mgetenv[24m(3).  [1m\V [22mis interpreted even in copy mode.

       [1m\X'[4m[22manything[24m[1m'[0m
              Within [1m\X [22marguments, the escape sequences [1m\&[22m, [1m\)[22m, [1m\%[22m, and [1m\: [22mare
              ignored; [1m\[4m[22mspace[24m and [1m\~ [22mare converted to single space characters;
              and [1m\\ [22mis reduced to [1m\[22m.  So that the basic Latin subset  of  the
              Unicode  character set (that is, ISO 646:1991‐IRV or, popularly,
              “US‐ASCII”) can be reliably encoded  in  [4manything,[24m  the  special
              character  escape  sequences  [1m\-[22m,  [1m\[aq][22m,  [1m\[dq][22m,  [1m\[ga][22m, [1m\[ha][22m,
              [1m\[rs][22m, and [1m\[ti] [22mare  mapped  to  basic  Latin  characters;  see
              [4mgroff_char[24m(7).   For this transformation, character translations
              and definitions are ignored.  Other  escape  sequences  are  not
              supported.

              If  the [1muse_charnames_in_special [22mdirective appears in the output
              device’s [4mDESC[24m file, the use  of  special  character  escape  se‐
              quences  is  [4mnot[24m an error; they are simply output verbatim (with
              the exception of the seven mapped to Unicode basic Latin charac‐
              ters, discussed above).  [1muse_charnames_in_special  [22mis  currently
              employed only by [4mgrohtml[24m(1).

       [1m\Y[4m[22mm[0m
       [1m\Y([4m[22mma[0m
       [1m\Y[[4m[22mmac[24m[1m][0m
              Interpolate  a macro as a device control command.  This is simi‐
              lar to [1m\X'\*[[4m[22mmac[24m[1m]'[22m, except the contents of [4mmac[24m  are  not  inter‐
              preted,  and  [4mmac[24m  can  be  a  macro  and thus contain newlines,
              whereas the argument to [1m\X [22mcannot.  This inclusion  of  newlines
              requires  an extension to the AT&T [4mtroff[24m output format, and will
              confuse postprocessors that do not know about it.

       [1m\Z'[4m[22manything[24m[1m'[0m
              Save the drawing position, format  [4manything[24m,  then  restore  it.
              Tabs and leaders in the argument are ignored with an error diag‐
              nostic.

       [1m\#     [22mEverything  up  to  and  including  the next newline is ignored.
              This escape sequence is interpreted even in copy  mode.   [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][0m
              In a macro or string definition, interpolate the [4mnn[24mth  or  [4mnnn[24mth
              argument.   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 left of the right parenthesis, which is ugly.  Inserting  [1m\/[0m
              between  them  avoids  this  problem.   Use this escape sequence
              whenever an oblique 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 fol‐
              lowing glyph so that the distance between it and  the  preceding
              glyph  is  correct if the latter is of upright shape.  For exam‐
              ple, 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\, [22mbetween them avoids this problem.  Use this
              escape sequence whenever an upright glyph  is  followed  immedi‐
              ately by an oblique 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”).  This escape sequence is
              an  input word boundary, so the remainder of the word is subject
              to hyphenation as normal.

       [1m\?[4m[22manything[24m[1m\?[0m
              When used in a diversion, this transparently embeds [4manything[24m  in
              the  diversion.  [4manything[24m is read in copy mode.  When the diver‐
              sion is reread, [4manything[24m is interpreted.  [4manything[24m may not  con‐
              tain  newlines; use [1m\! [22mif you want to embed newlines in a diver‐
              sion.  The escape sequence [1m\? [22mis also recognized  in  copy  mode
              and  becomes  an  internal code; it is this code that terminates
              [4manything[24m.  Thus

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

              prints [1m4[22m.

       [1m\[[4m[22mchar[24m[1m][0m
              Typeset the special character [4mchar[24m.

       [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 [4mgroff_char[24m(7) for a list of components used in
              composite glyph names.

       [1m\~     [22mInsert an unbreakable space that is adjustable like an  ordinary
              space.   It  is  discarded  from  the end of an output line if a
              break is forced.

   [1mRestricted requests[0m
       To mitigate risks from untrusted input documents, the  [1mpi  [22mand  [1msy  [22mre‐
       quests are disabled by default.  [4mgtroff[24m(1)’s [1m-U [22moption enables the for‐
       matter’s  “unsafe  mode”,  restoring their function (and enabling addi‐
       tional [4mgroff[24m extension requests, [1mopen[22m, [1mopena[22m, and [1mpso[22m).

   [1mNew requests[0m
       [1m.aln [4m[22mnew[24m [4mold[0m
              Create alias [4mnew[24m for existing register named  [4mold[24m,  causing  the
              names to refer to the same stored value.  If [4mold[24m is undefined, a
              warning  in  category  “[1mreg[22m” is generated and the request is ig‐
              nored.  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[24m [4mold[0m
              Create alias [4mnew[24m for existing request, string, macro, or  diver‐
              sion  named  [4mold[24m,  causing the names to refer to the same stored
              object.  If [4mold[24m is undefined, a warning  in  category  “[1mmac[22m”  is
              produced,  and  the request is ignored.  The “[1mam[22m”, “[1mas[22m”, [1mda[22m, [1mde[22m,
              [1mdi[22m, and [1mds [22mrequests (together with their variants) create a  new
              object  only  if  the name of the macro, diversion, or string is
              currently undefined or if it is defined as a request;  normally,
              they  modify  the  value  of  an  existing object.  To remove an
              alias, invoke [1mrm [22mon its name.  The  object  itself  is  not  de‐
              stroyed until it has no more names.

              When a request, macro, string, or diversion is aliased, redefin‐
              itions  and appendments “write through” alias names.  To replace
              an alias with a separately defined object, you must use  the  [1mrm[0m
              request on its name first.

       [1m.am1 [4m[22mname[24m [[4mend‐name[24m]
              As “[1mam[22m”, but compatibility mode is disabled while the appendment
              to [4mname[24m is interpreted: a “compatibility save” token is inserted
              at  its  beginning,  and  a “compatibility restore” token at its
              end.  As a consequence, the requests “[1mam[22m”, [1mam1[22m, [1mde[22m, and [1mde1  [22mcan
              be intermixed freely since the compatibility save/restore tokens
              affect 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 compatibility mode is disabled during interpretation
              of the appendment.

       [1m.as1 [4m[22mname[24m [[4mcontents[24m]
              As “[1mas[22m”, but compatibility mode is disabled while the appendment
              to [4mname[24m is interpreted: a “compatibility save” token is inserted
              at  the beginning of [4mcontents[24m, and a “compatibility restore” to‐
              ken after it.  As a consequence, the requests “[1mas[22m”, [1mas1[22m, [1mds[22m, and
              [1mds1 [22mcan be intermixed freely since  the  compatibility  save/re‐
              store  tokens  affect only the portions of the strings 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  (ASCII)  characters,  characters translated with the [1mtrin[0m
              request, space characters, and some escape sequences, that  were
              formatted  in  the diversion [4mdiv[24m are treated like ordinary input
              characters when [4mdiv[24m is reread.  Doing so can be useful  in  con‐
              junction  with the [1mwritem [22mrequest.  [1masciify [22mcan be also used for
              gross hacks; for example, the following sets register [1mn [22mto 1.

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

              [1masciify [22mcannot return all items in a diversion to  their  source
              equivalent:  nodes such as those produced by [1m\N[[22m...[1m] [22mwill remain
              nodes, so the result cannot be guaranteed to be a  pure  string.
              See  section  “Copy mode” in [4mgroff[24m(7).  Glyph parameters such as
              the type face and  size  are  not  preserved;  use  [1munformat  [22mto
              achieve that.

       [1m.backtrace[0m
              Write  backtrace  of  input  stack to the standard error stream.
              See the [1m-b [22moption of [4mgtroff[24m(1).

       [1m.blm [22m[[4mname[24m]
              Set a blank line macro (trap).  If a blank line  macro  is  thus
              defined,  [4mgroff[24m  executes [4mmacro[24m when a blank line is encountered
              in the input file, instead of the usual behavior.  A  line  con‐
              sisting  only  of spaces is also treated as blank and subject to
              this trap.  If no argument is supplied, the default  blank  line
              behavior is (re‐)established.

       [1m.box [22m[[4mname[24m]
       [1m.boxa [22m[[4mname[24m]
              Divert  (or  append)  output to [4mname,[24m similarly to the [1mdi [22mand [1mda[0m
              requests, 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 typo‐
              graphical break or the [1mbr [22mrequest.  See “[1mcontinue[22m”.

       [1m.brp   [22mBreak and adjust line; this is the AT&T [4mtroff[24m escape sequence [1m\p[0m
              in request form.

       [1m.cflags [4m[22mn[24m [4mc1[24m [4mc2[24m ...
              Assign properties encoded by the number [4mn[24m to characters [4mc1[24m,  [4mc2[24m,
              and so on.  Ordinary and special characters have certain associ‐
              ated properties.  (Glyphs don’t: to GNU [4mtroff[24m, like AT&T device‐
              independent  [4mtroff[24m,  a glyph is an identifier corresponding to a
              rectangle with some metrics; see [4mgroff_font[24m(5).)  The first  ar‐
              gument  is  the sum of the desired flags and the remaining argu‐
              ments are  the  characters  to  be  assigned  those  properties.
              Spaces  between  the [4mcn[24m arguments are optional.  Any argument [4mcn[0m
              can be a character class defined with the [1mclass  [22mrequest  rather
              than an individual character.

              The  non‐negative  integer [4mn[24m is the sum of any of the following.
              Some combinations are nonsensical, 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 overlap‐
                     ping  other instances of itself horizontally.  Initially,
                     characters  “[1m\[ul]\[rn]\[ru]\[radicalex]\[sqrtex][22m”   have
                     this property.

              16     Mark the glyph associated with this character as overlap‐
                     ping  other  instances  of itself vertically.  Initially,
                     the character “[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‐sen‐
                     tence character followed by any number of characters with
                     this property is treated as the end of a sentence if fol‐
                     lowed  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.  Ini‐
                     tially, no characters have this property.

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

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

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

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

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

              In contrast to values 2 and 4, the values 128, 256, and 512 work
              pairwise.  If, for example, the left character  has  value  512,
              and  the right character 128, no break will be automatically in‐
              serted 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 [4mcontents[0m
              Define  the  ordinary  or special character [4mc[24m as [4mcontents[24m, which
              can be empty.  More precisely, [1mchar [22mdefines a [4mgroff[24m  object  (or
              redefines  an  existing one) that is accessed with the name [4mc[24m on
              input, and produces [4mcontents[24m on output.  Every time [4mc[24m is  to  be
              formatted,  [4mcontents[24m is processed in a temporary environment and
              the result is wrapped up into a  single  object.   Compatibility
              mode  is  turned  off and the escape character is set to [1m\ [22mwhile
              [4mcontents[24m is processed.  Any emboldening,  constant  spacing,  or
              track  kerning is applied to this object as a whole, not to each
              character in [4mcontents[24m.

              An object defined by this request can be used just like a  glyph
              provided  by the output device.  In particular, other characters
              can be translated to it with the [1mtr [22mrequest; it can be made  the
              tab  or  leader  fill character with the [1mtc [22mand [1mlc [22mrequests; se‐
              quences of it can be drawn with the [1m\l [22mand [1m\L [22mescape  sequences;
              and,  if  the [1mhcode [22mrequest is used on [4mc[24m, it is subject to auto‐
              matic hyphenation.

              To prevent infinite recursion, occurrences of [4mc[24m within  its  own
              definition are treated normally (as if it were not being defined
              with  [1mchar[22m).   The  [1mtr [22mand [1mtrin [22mrequests take precedence if [1mchar[0m
              both apply to [4mc[24m.  A character definition can be removed with the
              [1mrchar [22mrequest.

       [1m.chop [4m[22mobject[0m
              Remove the last character from the macro, string,  or  diversion
              [4mobject[24m.  This is useful for removing the newline from the end of
              a  diversion  that  is to be interpolated as a string.  This re‐
              quest can be used repeatedly on the  same  [4mobject[24m;  see  section
              “gtroff  Internals”  in  [4mGroff:[24m [4mThe[24m [4mGNU[24m [4mImplementation[24m [4mof[24m [4mtroff[24m,
              the [4mgroff[24m Texinfo manual, for discussion of  nodes  inserted  by
              [4mgroff[24m.

       [1m.class [4m[22mname[24m [4mc1[24m [4mc2[24m ...
              Define a character class (or simply “class”) [4mname[24m comprising the
              characters or range expressions [4mc1[24m, [4mc2[24m, and so on.

              A  class thus defined can then be referred to in lieu of listing
              all the characters within it.  Currently, only  the  [1mcflags  [22mre‐
              quest can handle references to character classes.

              In  the request’s simplest form, each [4mcn[24m is a character (or spe‐
              cial character).
                     .class [quotes] ' \[aq] \[dq] \[oq] \[cq] \[lq] \[rq]

              Since class and special character  names  share  the  same  name
              space,  we recommend starting and ending the class name with “[1m[[22m”
              and “[1m][22m”, respectively, to avoid collisions with existing charac‐
              ter names defined by [4mgroff[24m or the user (with  [1mchar  [22mand  related
              requests).   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”, thus you must use the [1m\C [22mescape to access a class
              with such a name.

              You  can  also  use a character range expression 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 Uni‐
              code code points (according to  the  [4mgroff[24m  glyph  list  [GGL]),
              which  determine the start and end values of the range.  If that
              fails, the class definition is  skipped.   Furthermore,  classes
              can be nested.
                     .class [prepunct] , : ; > }
                     .class [prepunctx] \C'[prepunct]' \[u2013]-\[u2016]
              The  class “[1m[prepunctx][22m” thus contains the contents of the class
              “[1m[prepunct][22m” and characters in the range U+2013–U+2016.

              If you want to include “[1m-[22m” in a class,  it  must  be  the  first
              character  value  in the argument list, otherwise it gets misin‐
              terpreted as part of the range syntax.

              It is not possible to use class names as end points of range de‐
              finitions.

              A typical use of the [1mclass [22mrequest is to  control  line‐breaking
              and hyphenation rules as defined by the [1mcflags [22mrequest.  For ex‐
              ample, to inhibit line breaks before the characters belonging to
              the “[1m[prepunctx][22m” class defined in the previous example, you can
              write the following.
                     .cflags 2 \C'[prepunctx]'

       [1m.close [4m[22mstream[0m
              Close the stream named [4mstream[24m, invalidating it as an argument to
              the [1mwrite [22mrequest.  See [1mopen[22m.

       [1m.composite [4m[22mc1[24m [4mc2[0m
              Map  character name [4mc1[24m to character name [4mc2[24m when [4mc1[24m is a combin‐
              ing component in a composite glyph.  Typically,  this  remaps  a
              spacing glyph to a combining one.

       [1m.continue[0m
              Skip  the remainder of a “[1mwhile[22m” loop’s body, immediately start‐
              ing the next iteration.  See [1mbreak[22m.

       [1m.color [4m[22mn[0m
              If [4mn[24m is non‐zero or missing, enable colors (the default), other‐
              wise disable them.

       [1m.cp [4m[22mn[24m  If [4mn[24m is non‐zero or missing, enable compatibility  mode,  other‐
              wise disable it.  In compatibility mode, long names are not rec‐
              ognized, and the incompatibilities 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”.  The color  components  can  be
              encoded  as a hexadecimal value starting with [1m# [22mor [1m##[22m.  The for‐
              mer indicates that each component is in the range 0–255  (0–FF),
              the  latter  the  range  0–65535  (0–FFFF).  Alternatively, each
              color component can be specified as a decimal  fraction  in  the
              range  0–1,  interpreted  using  a  default scaling unit of “[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
              redefined.   A  device’s  default stroke and fill colors are not
              necessarily the same.

       [1m.de1 [4m[22mname[24m [[4mend‐name[24m]
              Define a macro to be interpreted with  compatibility  mode  dis‐
              abled.   When [4mname[24m is called, compatibility mode enablement sta‐
              tus is saved; it is restored when the call completes.

       [1m.dei [4m[22mname[24m [[4mend‐name[24m]
              Define macro indirectly, with the name of the macro  to  be  de‐
              fined  in  string [4mname[24m and the name of the end macro terminating
              its definition in string [4mend‐name[24m.

       [1m.dei1 [4m[22mname[24m [[4mend‐name[24m]
              As [1mdei[22m, but compatibility mode is disabled while the  definition
              of the macro named in string [4mname[24m is interpreted.

       [1m.device [4m[22manything[0m
              Write  [4manything[24m, read in copy mode, to [4mgtroff[24m output as a device
              control command.  An initial neutral double quote is stripped to
              allow the embedding of leading spaces.

       [1m.devicem [4m[22mname[0m
              Write contents of macro or string [4mname[24m to [4mgtroff[24m output as a de‐
              vice control command.

       [1m.do [4m[22mname[24m [[4marg[24m ...]
              Interpret the string, request, diversion, or macro  [4mname[24m  (along
              with  any arguments) with compatibility mode disabled.  Compati‐
              bility mode is restored (only if it was active) when the  [4mexpan‐[0m
              [4msion[24m of [4mname[24m is interpreted; that is, the restored compatibility
              state applies to the contents of the macro, string, or diversion
              [4mname[24m  as well as data read from files or pipes if [4mname[24m is any of
              the [1mso[22m, [1msoquiet[22m, [1mmso[22m, [1mmsoquiet[22m, or [1mpso [22mrequests.

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

       [1m.ds1 [4m[22mname[24m [4mcontents[0m
              As [1mds[22m, but compatibility mode is disabled while [4mname[24m  is  inter‐
              preted:  a  “compatibility save” token is inserted 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 char‐
              acter 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  environ‐
              ment, except for the following data.

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

              • the activation status of temporary indentation;

              • input traps and their associated data;

              • the activation status of line numbering (which can be  reacti‐
                vated with “[1m.nm +0[22m”); and

              • the count of consecutive hyphenated lines (set to zero).

       [1m.fam [22m[[4mfamily[24m]
              Set default font family to [4mfamily[24m.  If no argument is given, the
              previous  font  family  is  selected, or the formatter’s default
              family if there is none.  The formatter’s default font family is
              “T” (Times), but it can be overridden by the  output  device—see
              [4mgroff_font[24m(5).   The  default font family is associated with the
              environment.  See [1m\F[22m.

       [1m.fchar [4m[22mc[24m [4mcontents[0m
              Define fallback character [4mc[24m as [4mcontents[24m.  The syntax of this re‐
              quest is the same as the [1mchar [22mrequest; the difference is that  a
              character  defined with [1mchar [22mhides a glyph with the same name in
              the selected font, whereas characters  defined  with  [1mfchar  [22mare
              checked  only  if [4mc[24m isn’t found in the selected font.  This test
              happens before special fonts are searched.

       [1m.fcolor [4m[22mcolor[0m
              Set the fill color to [4mcolor[24m.  Without an argument, the  previous
              fill color is selected.

       [1m.fschar [4m[22mf[24m [4mc[24m [4mcontents[0m
              Define  fallback  special character [4mc[24m for font [4mf[24m as [4mcontents[24m.  A
              character defined by [1mfschar [22mis located after the list  of  fonts
              declared  with  [1mfspecial  [22mis  searched but before those declared
              with the “[1mspecial[22m” request.

       [1m.fspecial [4m[22mf[24m [4ms1[24m [4ms2[24m ...
              When font [4mf[24m is selected, fonts [4ms1[24m, [4ms2[24m, ... are treated  as  spe‐
              cial; that is, they are searched for glyphs not found in [4mf[24m.  Any
              fonts  specified in the “[1mspecial[22m” request are searched after [4ms1[24m,
              [4ms2[24m, and so on.  Without [4ms[24m arguments, [1mfspecial [22mclears the list of
              fonts treated as special when [4mf[24m is selected.

       [1m.ftr [4m[22mf[24m [4mg[0m
              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
              operators, 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[0m
              Set zoom factor [4mzoom[24m for font [4mf[24m.  [4mzoom[24m must a non‐negative inte‐
              ger multiple of 1/1000th.  If it is missing or is equal to zero,
              it means the same as 1000, namely no magnification.  [4mf[24m must be a
              resolved font name, not an abstract style.

       [1m.gcolor [4m[22mcolor[0m
              Set  the stroke color to [4mcolor[24m.  Without an argument, the previ‐
              ous stroke color is selected.

       [1m.hcode [4m[22mc1[24m [4mcode1[24m [[4mc2[24m [4mcode2[24m] ...
              Set the hyphenation code of character [4mc1[24m to [4mcode1[24m, that of [4mc2[24m to
              [4mcode2[24m, and so on.  A hyphenation code must be an ordinary  char‐
              acter  (not  a  special  character escape sequence) other than a
              digit.  The request is ignored if given no arguments.

              For hyphenation to work, hyphenation codes must be set  up.   At
              startup,  [4mgroff[24m  assigns  hyphenation codes to the letters “a–z”
              (mapped to themselves), to the letters “A–Z” (mapped to  “a–z”),
              and  zero  to  all other characters.  Normally, hyphenation pat‐
              terns contain only lowercase letters which should be applied re‐
              gardless of case.  In other words, they assume  that  the  words
              “ABBOT”  and “Abbot” should be hyphenated exactly as “abbot” is.
              [1mhcode [22mextends this principle to letters outside the Unicode  ba‐
              sic  Latin  alphabet;  without it, words containing such letters
              won’t be hyphenated properly even if the  corresponding  hyphen‐
              ation patterns contain them.

       [1m.hla [4m[22mlang[0m
              Set  the  hyphenation  language to [4mlang[24m.  Hyphenation exceptions
              specified with the [1mhw [22mrequest and hyphenation patterns  and  ex‐
              ceptions specified with the [1mhpf [22mand [1mhpfa [22mrequests are associated
              with  the  hyphenation language.  The [1mhla [22mrequest is usually in‐
              voked by a localization file, which is in  turn  loaded  by  the
              [4mtroffrc[24m or [4mtroffrc-end[24m file; see the [1mhpf [22mrequest below.  The hy‐
              phenation language is associated with the environment.

       [1m.hlm [22m[[4mn[24m]
              Set the maximum number of consecutive hyphenated lines to [4mn[24m.  If
              [4mn[24m  is negative, there is no maximum.  If omitted, [4mn[24m is -1.  This
              value is associated with the  environment.   Only  lines  output
              from  a  given  environment count towards the maximum associated
              with that environment.  Hyphens resulting from [1m\%  [22mare  counted;
              explicit hyphens are not.

       [1m.hpf [4m[22mpattern‐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
              or the [1m-m[4m[22mname[24m command‐line option to [4mgroff[24m(1) and [4mgtroff[24m(1).

              The [4mpattern‐file[24m should have the same  format  as  (simple)  TeX
              pattern files.  The following scanning rules are implemented.

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

              • “Digraphs” like [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^ [22mcause 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  ex‐
                ceptions.

              • [1m\endinput [22mis recognized also.

              • For  backwards  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 com‐
                ment).

              Use the [1mhpfcode [22mrequest (see below) to map the encoding used  in
              hyphenation pattern files to [4mgroff[24m’s input encoding.

              The  set  of hyphenation patterns is associated with the hyphen‐
              ation language set by the [1mhla [22mrequest.  The [1mhpf [22mrequest is  usu‐
              ally  invoked by a localization file loaded by the [4mtroffrc[24m file.
              By default, [4mtroffrc[24m loads the  localization  file  for  English.
              (As  of  [4mgroff[24m 1.23.0, localization files for Czech ([4mcs[24m), German
              ([4mde[24m), English ([4men[24m), French ([4mfr[24m), Japanese  ([4mja[24m),  Swedish  ([4msv[24m),
              and  Chinese  ([4mzh[24m) exist.)  For Western languages, the localiza‐
              tion file sets the hyphenation mode and loads  hyphenation  pat‐
              terns and exceptions.

              A  second  call  to [1mhpf [22m(for the same language) replaces the old
              patterns with the new ones.

              Invoking [1mhpf [22mcauses an error if there  is  no  hyphenation  lan‐
              guage.

              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
              automatically hyphenate at all.

       [1m.hpfa [4m[22mpattern‐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] ...
              Define  mapping  values  for  character  codes in pattern files.
              This is an older mechanism no longer used by [4mgroff[24m’s  own  macro
              files;  for  its  successor, see [1mhcode [22mabove.  [1mhpf [22mor [1mhpfa [22mapply
              the mapping after reading or appending to  the  active  list  of
              patterns.   Its  arguments are pairs of character codes—integers
              from 0 to 255.  The request maps character code  [4ma[24m  to  code  [4mb[24m,
              code  [4mc[24m to code [4md[24m, and so on.  Character codes that would other‐
              wise be invalid in [4mgroff[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.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  hyphen‐
              ation  margin  is  reset  to  its default value, 0.  The default
              scaling unit is “[1mm[22m”.  The hyphenation margin is associated  with
              the  environment.   A  negative  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 it can be justified by adding no more than  [4mhyphenation‐space[0m
              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 current  envi‐
              ronment.   A  negative argument resets the hyphenation space ad‐
              justment threshold to  zero,  emitting  a  warning  in  category
              “[1mrange[22m”.

       [1m.itc [4m[22mn[24m [4mname[0m
              As  “[1mit[22m”,  but lines interrupted with the [1m\c [22mescape sequence are
              not applied to the line count.

       [1m.kern [4m[22mn[0m
              If [4mn[24m is non‐zero or missing, enable pairwise  kerning  (the  de‐
              fault), otherwise disable it.

       [1m.length [4m[22mreg[24m [4manything[0m
              Compute  the  number  of  characters  in [4manything[24m and return the
              count in the register [4mreg[24m.  If [4mreg[24m doesn’t exist, it is created.
              [4manything[24m is read in copy mode.

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

       [1m.linetabs [4m[22mn[0m
              If [4mn[24m is non‐zero or missing, enable  line‐tabs  mode,  otherwise
              disable  it (the default).  In this mode, tab stops are computed
              relative to the start of the pending output line, instead of the
              drawing position corresponding to the start of the  input  line.
              Line‐tabs mode is a property of the environment.

              For example, the following

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

       [1m.lsm [22m[[4mname[24m]
              Set  the leading space macro (trap) to [4mname[24m.  If there are lead‐
              ing space characters on an input line, [4mname[24m is invoked  in  lieu
              of the usual [4mroff[24m behavior; the leading spaces are removed.  The
              count  of  leading spaces on an input line is stored in [1m\n[lsn][22m,
              and the amount of corresponding horizontal  motion  in  [1m\n[lss][22m,
              irrespective  of  whether  a leading space trap is set.  When it
              is, the leading spaces are removed from the input line,  and  no
              motion  is produced before calling [4mname[24m.  If no argument is sup‐
              plied, the default leading space behavior is (re‐)established.

       [1m.mso [4m[22mfile[0m
              As “[1mso[22m”, except that [4mfile[24m is sought in the same  directories  as
              arguments  to  the [4mgroff[24m(1) and [4mgtroff[24m(1) [1m-m [22mcommand‐line option
              are (the “tmac path”).  If the file name to be interpolated  has
              the  form  [4mname[24m[1m.tmac  [22mand  it  isn’t found, [1mmso [22mtries to include
              [1mtmac.[4m[22mname[24m instead and vice versa.  If [4mfile[24m  does  not  exist,  a
              warning  in  category  “[1mfile[22m”  is emitted and the request has no
              other effect.

       [1m.msoquiet [4m[22mfile[0m
              As [1mmso[22m, but no warning is emitted if [4mfile[24m does not exist.

       [1m.nop [4m[22manything[0m
              Interpret [4manything[24m as if it were an input line.   [1mnop  [22mresembles
              “[1m.if  1[22m”;  it  puts  a break on the output if [4manything[24m is empty.
              Unlike “[1mif[22m”, it cannot govern conditional blocks.  Its  applica‐
              tion  is to maintain consistent indentation within macro defini‐
              tions even when producing text lines.

       [1m.nroff [22mMake the [1mn [22mconditional expression evaluate  true  and  [1mt  [22mfalse.
              See [1mtroff[22m.

       [1m.open [4m[22mstream[24m [4mfile[0m
              Open  [4mfile[24m  for writing and associate [4mstream[24m with it.  See [1mwrite[0m
              and [1mclose[22m.

       [1m.opena [4m[22mstream[24m [4mfile[0m
              As [1mopen[22m, but if [4mfile[24m exists, append to it instead of  truncating
              it.

       [1m.output [4m[22mcontents[0m
              Emit  [4mcontents[24m,  which  are  read in copy mode, to the formatter
              output; this is similar to [1m\! [22mused in the  top‐level  diversion.
              An initial neutral double quote in [4mcontents[24m is stripped to allow
              the embedding of leading spaces.

       [1m.pev   [22mReport  the state of the current environment followed by that of
              all other environments to the standard error stream.

       [1m.pnr   [22mWrite the names and values of all currently defined registers to
              the standard error 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  Post‐
              Script  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 [4m[22mcommand[0m
              As “[1mso[22m”, except that input comes from the standard output stream
              of [4mcommand[24m.

       [1m.ptr   [22mReport the names and vertical positions  of  all  page  location
              traps to the standard error stream.  Empty slots in the list are
              shown  as well, because they can affect the visibility of subse‐
              quently 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[0m
              argument on the pending output line, the vertical spacing  ([1mvs[22m),
              the extra post‐vertical line spacing set by the most positive [1m\x[0m
              argument  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 or special character [4mc[24m, undo‐
              ing the effect of a [1mchar[22m,  [1mfchar[22m,  or  [1mschar  [22mrequest.   Glyphs,
              which  are defined by font description files, cannot be removed.
              Spaces and tabs may separate [4mc[24m arguments.

       [1m.return[0m
              Within a macro, return immediately.  If called with an argument,
              return twice, namely from the current macro and from  the  macro
              one level higher.  No effect otherwise.

       [1m.rfschar [4m[22mf[24m [4mc[24m ...
              Remove each fallback special character [4mc[24m for font [4mf[24m.  Spaces and
              tabs may separate [4mc[24m arguments.  See [1mfschar[22m.

       [1m.rj [22m[[4mn[24m]
              Right‐align the next [4mn[24m input lines.  Without an argument, right‐
              align  the  next input line.  [1mrj [22mimplies “[1m.ce 0[22m”, and [1mce [22mimplies
              “[1m.rj 0[22m”.

       [1m.rnn [4m[22mr1[24m [4mr2[0m
              Rename register [4mr1[24m to [4mr2[24m.  If [4mr1[24m doesn’t exist, the  request  is
              ignored.

       [1m.schar [4m[22mc[24m [4mcontents[0m
              Define  global  fallback character [4mc[24m as [4mcontents[24m.  See [1mchar[22m; the
              distinction is that a character defined with  [1mschar  [22mis  located
              after  the  list  of fonts declared with the [1mspecial [22mrequest but
              before any mounted special fonts.

       [1m.shc [22m[[4mc[24m]
              Set the soft hyphen character, inserted when a word  is  hyphen‐
              ated automatically or at a hyphenation character, to [4mc[24m.  If [4mc[24m is
              omitted, 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 po‐
              tential  hyphenation  point, then the line is not broken at that
              point.  Neither character definitions  ([1mchar  [22mand  similar)  nor
              translations  ([1mtr [22mand similar) are considered when assigning the
              soft hyphen character.

       [1m.shift [4m[22mn[0m
              In a macro, shift the arguments by [4mn[24m positions: argument  [4mi[24m  be‐
              comes  argument  [4mi[24m-[4mn[24m;  arguments 1 to [4mn[24m are no longer available.
              If [4mn[24m is missing, arguments are shifted by 1.  No  effect  other‐
              wise.

       [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[0m
              can also be a range [4mm[24m–[4mn[24m.  In contrast to the device  description
              file  directive  of the same name (see [4mgroff_font[24m(5)), the argu‐
              ment list can’t extend over more than one line.

       [1m.soquiet [4m[22mfile[0m
              As “[1mso[22m”, but no warning is emitted if [4mfile[24m does not exist.

       [1m.special [4m[22mf[24m ...
              Declare each font [4mf[24m as special,  searching  it  for  glyphs  not
              found  in  the  selected  font.  Without arguments, this list of
              special fonts is made empty.

       [1m.spreadwarn [22m[[4mlimit[24m]
              Emit a [1mbreak [22mwarning 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” causes a warning if [1mbreak  [22mwarn‐
              ings  are  not  suppressed and [4mgtroff[24m must add 0.2 m or more for
              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).
              Special characters (see [4mgroff_char[24m(7)) will often  transform  in
              the  expected  way  due to the regular naming convention for ac‐
              cented characters.  When they  do  not,  use  substrings  and/or
              catenation.

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

       [1m.sty [4m[22mn[24m [4ms[0m
              Associate abstract style [4ms[24m with font mounting position [4mn[24m.

       [1m.substring [4m[22mstring[24m [4mstart[24m [[4mend[24m]
              Replace  the  string  named [4mstring[24m with its substring bounded by
              the indices [4mstart[24m and [4mend[24m, inclusively.  The first character  in
              the string has index 0.  If [4mend[24m is omitted, it is implicitly set
              to the largest valid value (the string length minus one).  Nega‐
              tive  indices  count  backwards  from the end of the string: the
              last character has index -1, the character before the  last  has
              index -2, and so on.

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

       [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[0m
              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 [4m[22mmessage[0m
              As [1mtm [22mrequest, but strips a leading neutral  double  quote  from
              [4mmessage[24m to allow the embedding of leading spaces.

       [1m.tmc [4m[22mmessage[0m
              As [1mtm1 [22mrequest, but does not append a newline.

       [1m.trf [4m[22mfile[0m
              Transparently  output  the  contents of file [4mfile[24m.  Each line is
              output as if preceded by [1m\![22m; however, the lines are not  subject
              to  copy‐mode  interpretation.   If the file does not end with a
              newline, then a newline is added.  Unlike [1mcf[22m, [4mfile[24m  cannot  con‐
              tain characters that are invalid as input to GNU [4mtroff[24m.

              For example, you can define a macro [4mx[24m containing the contents of
              file [4mf[24m, using

                     .di x
                     .trf f
                     .di

       [1m.trin [4m[22mabcd[0m
              This  is  the same as the [1mtr [22mrequest except that the [1masciify [22mre‐
              quest uses the character code  (if  any)  before  the  character
              translation.  Example:

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

              The result is “x a”.  Using [1mtr[22m, the result would be “x x”.

       [1m.trnt [4m[22mabcd[0m
              This  is the same as the [1mtr [22mrequest except that the translations
              do not apply to text that is transparently throughput into a di‐
              version with [1m\![22m.  For example,

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

              prints [1mb[22m; if [1mtrnt [22mis used instead of [1mtr [22mit prints [1ma[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 [22mhandles
              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 [4m[22mn[24m If [4mn[24m is non‐zero or missing, enable vertical position traps (the
              default),  otherwise  disable them.  Vertical position traps are
              those set by the [1mch[22m, [1mwh[22m, and [1mdt [22mrequests.

       [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 cate‐
              gory that is to be enabled; all other categories  are  disabled.
              The  categories and their associated codes are listed in section
              “Warnings” of [4mgtroff[24m(1).  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[22msi[0m
              Set  the  scaling unit used in warnings to [4msi[24m.  Valid values for
              [4msi[24m are [1mu[22m, [1mi [22m(the default), [1mc[22m, [1mp[22m, and [1mP[22m.

       [1m.while [4m[22mcond‐expr[24m [4manything[0m
              Evaluate the conditional expression  [4mcond‐expr[24m,  and  repeatedly
              execute  [4manything[24m  unless  and  until [4mcond‐expr[24m evaluates false.
              [4manything,[24m which is often a conditional block, is referred to  as
              the [1mwhile [22mrequest’s [4mbody.[0m

              [4mgtroff[24m treats the body of a [1mwhile [22mrequest 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 [22mrequest can slow signif‐
              icantly if the [1mwhile [22mbody is large.  Each time the macro is exe‐
              cuted, the [1mwhile [22mbody is parsed and stored again.  An often bet‐
              ter  solution—and  one  that  is more portable, since AT&T [4mtroff[0m
              lacked the [1mwhile [22mrequest—is to instead write a recursive  macro.
              It  will  be parsed only once (unless you redefine it).  To pre‐
              vent infinite loops, the default number of  available  recursion
              levels  is  1,000  or  somewhat  less (because things other than
              macro calls can be on the input stack).  You  can  disable  this
              protective  measure,  or  raise the limit, by setting the [1mslimit[0m
              register.  See section “Debugging” below.

              If a [1mwhile [22mbody begins with a  conditional  block,  its  closing
              brace must end an input line.

              The  [1mbreak  [22mand  [1mcontinue  [22mrequests alter a [1mwhile [22mloop’s flow of
              control.

       [1m.write [4m[22mstream[24m [4manything[0m
              Write [4manything[24m to [4mstream[24m, which must previously  have  been  the
              subject  of an [1mopen [22mrequest, followed by a newline.  [4manything[24m is
              read in copy mode.  An initial neutral double quote in  [4manything[0m
              is stripped to allow the embedding of leading spaces.

       [1m.writec [4m[22mstream[24m [4manything[0m
              As [1mwrite[22m, but without a trailing newline.

       [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 [22mrequest.   [4mname[0m
              is read in copy mode.

   [1mExtended requests[0m
       [1m.cf [4m[22mfile[0m
              In  a  diversion, embed an object which, when reread, will cause
              the contents of [4mfile[24m to be copied verbatim to  the  output.   In
              AT&T  [4mtroff[24m,  the contents of [4mfile[24m are immediately copied to the
              output regardless of whether a diversion is  being  written  to;
              this behavior is so anomalous that it must be considered a bug.

       [1m.de [4m[22mname[24m [[4mend‐name[24m]
       [1m.am [4m[22mname[24m [[4mend‐name[24m]
       [1m.ds [4m[22mname[24m [[4mcontents[24m]
       [1m.as [4m[22mname[24m [[4mcontents[24m]
              In  compatibility  mode, these requests behave similarly to [1mde1[22m,
              [1mam1[22m, [1mds1[22m, and [1mas1[22m, respectively: a “compatibility save” token is
              inserted at the beginning, and a “compatibility  restore”  token
              at  the  end,  with compatibility mode switched on during execu‐
              tion.

       [1m.hy [4m[22mn[24m  New values 16 and 32 are available; the former  enables  hyphen‐
              ation  before  the  last character in a word, and the latter en‐
              ables hyphenation after the first character in a word.

       [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 cur‐
              rent font’s space width (typically one‐fourth  to  one‐third  em
              for  Western  scripts; see [4mgroff_font[24m(5)).  The default for both
              parameters is 12.  Negative values are erroneous.

       [1m.ta [22m[[[4mn1[24m [4mn2[24m ... [4mnn[24m ][1mT [4m[22mr1[24m [4mr2[24m ... [4mrn[24m]
              [4mgroff[24m supports an extended syntax to specify repeating tab stops
              after the “[1mT[22m” mark.  These values are always taken  as  relative
              distances from the previous tab stop.  This is the idiomatic way
              to specify tab stops at equal intervals in [4mgroff[24m.

              The  syntax  summary  above instructs [4mgroff[24m to set tabs at posi‐
              tions [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 registers[0m
       GNU [4mtroff[24m exposes more formatter state via many  new  read‐only  regis‐
       ters.  Their names often correspond to the requests that affect them.

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

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

       [1m\n[.C]      [22mInterpolate  1 if compatibility mode is in effect, 0 other‐
                   wise.  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 number of input lines remaining to be centered.

       [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 colors are enabled, 0 otherwise.

       [1m\n[.cp]     [22mWithin a “[1mdo[22m” request, interpolate the saved value of  com‐
                   patibility 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 should
                   be placed.

       [1m\n[.ev]     [22mInterpolate name of current environment.  This is a string‐
                   valued register.

       [1m\n[.fam]    [22mInterpolate name of default font family.  This is a string‐
                   valued register.

       [1m\n[.fn]     [22mInterpolate resolved name of the selected font.  This is  a
                   string‐valued register.

       [1m\n[.fp]     [22mInterpolate next free 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 font height.  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 hyphenation mode of the environment.

       [1m\n[.hym]    [22mInteprolate hyphenation margin of the environment.

       [1m\n[.hys]    [22mInterpolate  hyphenation  space adjustment threshold of the
                   environment.

       [1m\n[.in]     [22mInterpolate indentation amount applicable  to  the  pending
                   output line.

       [1m\n[.int]    [22mInterpolate  1  if the previous output line was interrupted
                   (ended with [1m\c[22m), 0 otherwise.

       [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, 0 otherwise.

       [1m\n[.ll]     [22mInterpolate line length applicable to  the  pending  output
                   line.

       [1m\n[.lt]     [22mInterpolate title line length.

       [1m\n[.m]      [22mInterpolate  name  of the selected stroke color.  This is a
                   string‐valued register.

       [1m\n[.M]      [22mInterpolate name of the 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 caused a page location trap to be sprung.  See
                   [1m\n[.trunc][22m.

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

       [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.
                   See [1m-o [22mcommand‐line option to [4mgtroff[24m(1).

       [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 type size in scaled points.

       [1m\n[.psr]    [22mInterpolate  most  recently  requested  type size in scaled
                   points.

       [1m\n[.pvs]    [22mInterpolate post‐vertical line spacing amount.

       [1m\n[.rj]     [22mInterpolate number of input lines remaining  to  be  right‐
                   aligned.

       [1m\n[.slant]  [22mInterpolate font slant.  See [1m\S[22m.

       [1m\n[.sr]     [22mInterpolate  most recently requested type size in points as
                   a decimal fraction.  This is a string‐valued register.

       [1m\n[.ss][0m
       [1m\n[.sss]    [22mInterpolate values of minimal inter‐word  space  and  addi‐
                   tional  inter‐sentence  space, respectively, in twelfths of
                   the space width of the selected font.

       [1m\n[.sty]    [22mInterpolate selected abstract font style, if any.  This  is
                   a string‐valued register.

       [1m\n[.tabs]   [22mInterpolate  representation  of  the tab stop settings in a
                   form suitable for passage to the [1mta [22mrequest.

       [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  mo‐
                   tion  produced  by  the [1mne [22mrequest.  In other words, at the
                   point a trap is sprung, [1m\n[.trunc] [22mrepresents  the  differ‐
                   ence  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 [4mgtroff[24m(1).

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

       [1m\n[.warn]   [22mInterpolate   warning  mode.   See  section  “Warnings”  of
                   [4mgtroff[24m(1).

       [1m\n[.x]      [22mInterpolate major version number of the running [4mgtroff[24m for‐
                   matter.  For example, if the version number is 1.23.0, then
                   [1m\n[.x] [22mcontains 1.

       [1m\n[.y]      [22mInterpolate minor version number of the running [4mgtroff[24m for‐
                   matter.  For example, if the version number is 1.23.0, then
                   [1m\n[.y] [22mcontains 23.

       [1m\n[.Y]      [22mInterpolate revision number of the running  [4mgtroff[24m  format‐
                   ter.   For  example,  if the version number is 1.23.0, then
                   [1m\n[.Y] [22mcontains 0.

       [1m\n[.zoom]   [22mInterpolate magnification of 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][0m
              Interpolate  the (upper, lower, left, right) bounding box values
              (in PostScript units) of the most recently processed  PostScript
              image.

       The following (writable) registers are set by the [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
               highest  and lowest vertical positions attained by the argument
               formatted by the [1m\w [22mescape sequence, doing what AT&T [4mtroff[24m doc‐
               umented [1m\n[st] [22mand [1m\n[sb] [22mas doing.

       [1m\n[ssc] [22mThe amount of horizontal space (possibly negative) that  should
               be added 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 [22mar‐
               gument, the center of an accent from a  roman  font  should  be
               placed over that glyph.

       Other  writable  registers  are as follows.  Those relating to date and
       time are initialized using [4mlocaltime[24m(3) 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] [22mInterpolate number of minutes elapsed in the hour.

       [1m\n[seconds] [22mInterpolate number of seconds elapsed in the minute.

       [1m\n[systat]  [22mInterpolate return value of [4msystem[24m(3) function executed  by
                   most recent [1msy [22mrequest.

       [1m\n[slimit]  [22mInterpolates maximum quantity of objects on [4mgtroff[24m’s inter‐
                   nal input stack (default: 1000).  If non‐positive, there is
                   no  limit:  recursion  can continue until program memory is
                   exhausted.

       [1m\n[year]    [22mInterpolate Gregorian year.  AT&T  [4mtroff[24m’s  [1m\[yr]  [22minterpo‐
                   lates the Gregorian year minus 1900.

   [1mMiscellaneous[0m
       GNU  [4mtroff[24m  predefines one string, [1m.T[22m, containing the argument given to
       the [1m-T [22mcommand‐line option, namely the output device (for example,  [1mpdf[0m
       or  [1mutf8[22m).   The (read‐only) [4mregister[24m [1m.T [22minterpolates 1 if GNU [4mtroff[24m is
       run with the [1m-T [22mcommand‐line option, and 0 otherwise.

       A font not listed in the output device’s [4mDESC[24m file’s [1mfonts [22mdirective is
       automatically mounted at the next available font position  when  it  is
       selected.   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, po‐
       tentially putting an unwanted blank line on the  output.   See  section
       “Punning Names” in [4mgroff[24m(7).

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

       GNU  [4mtroff[24m keeps track of the nesting depth of escape sequence interpo‐
       lations and other uses of delimiters, as in the [1mtl [22mrequest and the out‐
       put comparison operator (that is, input like [1m'foo'bar' [22mas a conditional
       expression), so the only characters you need to avoid using  as  delim‐
       iters  are  those  that appear in the arguments you input, not any that
       result from interpolation.  Typically, [1m' [22mworks fine.  Use visible char‐
       acters as delimiters in GNU [4mtroff[24m, not “ASCII” controls like BEL  (Con‐
       trol+G).  The implementation of [1m\$@ [22mensures that the double quotes sur‐
       rounding  an  argument  appear at an interpolation depth different from
       that of the arguments themselves.  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 interpolation depth as the opening  [1m[[22m,  so
       input like
              \f[\*[my‐family]\*[my‐style]]
       works  as  desired.  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 [4mcharacters[24m).  This feature replaces the odd‐parity [1mtr [22mmapping  trick
       used  in  AT&T [4mtroff[24m documents, where a character, often [1m~[22m, was “sacri‐
       ficed” by mapping it to “nothing”, drafting it into  use  as  an  unad‐
       justable,  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 in‐
       stead, which has been adopted by every other active  [4mtroff[24m  implementa‐
       tion  except  that  of  Illumos,  as  well  as by the non[4m‐troff[24m [4mmandoc[24m.
       Translation of a character to [1m\~ [22mis unnecessary.

       GNU [4mtroff[24m permits tabs and spaces after the first dot on a control line
       that ends a macro definition.
              .if t \{\
              .  de bar
              .    nop Hello, I'm 'bar'.
              .  .
              .\}

[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  ap‐
       proach  in  the early 1980s.  Only the differences are documented here.
       For a fuller discussion, see [4mgroff_out[24m(5).

       Glyph and font names can be of arbitrary length; postprocessors  should
       not assume that they are at most two characters.  A glyph to be format‐
       ted  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 op‐
              tional second integer argument is ignored (this allows the  for‐
              matter  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 horizon‐
              tal motion quantum.  Use the [1mC [22mcommand to emplace glyphs of spe‐
              cial 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  horizon‐
              tally by [4mn[24m 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 arguments 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 under‐
              lining 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 [4mgtroff[24m escape sequences employing these exten‐
       sions 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.
              Normally 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
              argument is rounded to an integer multiple of the horizontal mo‐
              tion quantum, which can limit the precision of [4mn[24m.

       [1mDC [4m[22md[24m   Draw  a  filled  circle of diameter [4md[24m with its leftmost point at
              the drawing position.

       [1mDE [4m[22mh[24m [4mv[24m Draw a filled ellipse, of horizontal axis [4mh[24m and vertical axis [4mv[24m,
              with its leftmost point at the drawing position.

       [1mDp [4m[22mdx[24m1[4mdy[24m1...[4mdxndyn[0m
              Draw a polygon with, for [4mi[24m=1,...,[4mn[24m+1,  its  [4mi[24mth  vertex  at  the
              drawing  position +[4mij[24m−=Σ11([4mdxj[24m,[4mdyj[24m).  [4mgroff[24m output drivers automati‐
              cally 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[0m
              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[24m drawing position.

              At the moment, GNU [4mpic[24m uses this command only to generate trian‐
              gles and rectangles.

       [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 dri‐
              vers use a thickness proportional to the type size; this is  the
              GNU [4mtroff[24m default.  A negative [4mn[24m requests this explicitly.  An [4mn[0m
              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[24m treats each [4mxi[24m as a horizontal motion, each [4myi[24m as a ver‐
       tical 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 [22mand [1msb [22mregisters after using such a drawing command in
       a  [1m\w  [22mescape sequence).  For the sake of compatibility, GNU [4mtroff[24m also
       follows this rule, even though it frustrates extensions to the  [1mD  [22mcom‐
       mand that set drawing parameters rather than rendering objects, produc‐
       ing  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  el‐
       lipse,   [1mDE[22m.   Thus  after  executing  a  [1mD  [22mcommand  of  the  form  [1mD[4m[22mz[0m
       [4mx[24m1[4my[24m1...[4mxnyn[24m, the drawing position should be increased by ([4min[24m=Σ1[4mxi[24m,[4min[24m=Σ1[4myi[24m).
       In a future release, GNU [4mtroff[24m and its output drivers may  abandon  the
       application of this assumption to drawing commands not explicitly spec‐
       ified in the AT&T “Troff User’s Manual”.

       Fill color selection is implemented 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[0m
              escape 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 ar‐
       gument  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[0m
       command,  a  postprocessor should therefore be prepared for a plus sign
       after a newline; if it occurs, preserve the newline, discard  the  plus
       sign,  and  continue  to collect the input into the argument of the [1mx X[0m
       command.  A newline [4mnot[24m followed by a plus sign terminates the [1mx X [22mcom‐
       mand.  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 supports several warning categories; the output of these can be se‐
       lected  with  [1mwarn[22m.   Also see the [1m-E[22m, [1m-w[22m, and [1m-W [22moptions of [4mgtroff[24m(1).
       Backtraces can be automatically produced when errors or warnings  occur
       (the [1m-b [22moption of [4mgtroff[24m(1)) or generated on demand ([1mbacktrace[22m).

       [4mgroff[24m also adds more flexible diagnostic output requests ([1mtmc [22mand [1mtm1[22m).
       More  aspects  of  formatter  state  can be examined with requests that
       write lists of defined registers ([1mpnr[22m), environments  ([1mpev[22m),  and  page
       location traps ([1mptr[22m) to the standard error stream.

[1mImplementation differences[0m
       GNU  [4mtroff[24m’s  features sometimes cause incompatibilities with documents
       written assuming old implementations of [4mtroff[24m.  Some GNU extensions  to
       [4mtroff[24m are supported by other implementations.

       When  adjusting  to  both  margins,  AT&T [4mtroff[24m at first adjusts spaces
       starting from the right; GNU [4mtroff[24m begins from the left.   Both  imple‐
       mentations adjust spaces from opposite ends on alternating output lines
       to prevent “rivers” in the text.

       GNU [4mtroff[24m does not always hyphenate words as AT&T [4mtroff[24m does.  The AT&T
       implementation uses a set of hard‐coded rules specific to U.S. English,
       while  GNU  [4mtroff[24m  uses language‐specific hyphenation pattern files de‐
       rived from TeX.  In some versions of [4mtroff[24m there was limited  space  to
       store  hyphenation  exceptions (arguments to the [1mhw [22mrequest); GNU [4mtroff[0m
       has no such restriction.

       Long names may be GNU [4mtroff[24m’s most obvious innovation.  AT&T [4mtroff[24m  in‐
       terprets  “[1m.dsabcd[22m” as defining a string “[1mab[22m” with contents “[1mcd[22m”.  Nor‐
       mally, GNU [4mtroff[24m interprets this as a call of a macro  named  “[1mdsabcd[22m”.
       AT&T  [4mtroff[24m also interprets [1m\*[ [22mand [1m\n[ [22mas an interpolation of a string
       or register, respectively, called “[1m[[22m”.  In GNU [4mtroff[24m, however, the  “[1m[[22m”
       is  normally  interpreted  as beginning the enclosure of a long identi‐
       fier.  In compatibility mode, GNU [4mtroff[24m interprets names in the  tradi‐
       tional way, which means that they are limited to one or two characters.
       See  the  [1m-C  [22moption in [4mgtroff[24m(1) 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  ra‐
       tionale.   When  writing macro packages or documents that use GNU [4mtroff[0m
       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 [22mrequests—you may desire correct operation regardless
       of compatibility mode enablement in the surrounding  context.   It  may
       occur  to you to save the existing value of [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 inclusion.  You  cannot  use
       the  same  register name everywhere lest you “clobber” the value from a
       preceding or enclosing context.  The two‐character register name  space
       of  AT&T  [4mtroff[24m is confining and mnemonically challenging; you may wish
       to use GNU [4mtroff[24m’s more capacious name space.  However, attempting “[1m.nr[0m
       [1m_my_saved_C \n(.C[22m” will not work in compatibility  mode;  the  register
       name  is  too long.  “This is exactly what [1m.do [22mis for,” you think, “[1m.do[0m
       [1mnr _my_saved_C \n(.C[22m”.  The foregoing will always  save  zero  to  your
       register, because “[1mdo[22m” turns compatibility mode [4moff[24m while it interprets
       its argument list.  What you need is:
              .do nr _my_saved_C \n[.cp]
              .cp 0
       at the beginning of your file, followed by
              .cp \n[_my_saved_C]
              .do rr _my_saved_C
       at  the  end.   As in the C language, we all have to share one big name
       space, so choose a register name that is unlikely to collide with other
       uses.

       The existence of the [1m.T [22mstring is a common  feature  of  post‐CSTR  #54
       [4mtroff[24ms—DWB  3.3,  Solaris, Heirloom Doctools, and Plan 9 [4mtroff[24m all sup‐
       port it—but valid values are specific to each implementation.  The  be‐
       havior  of  the [1m.T [22mregister in GNU [4mtroff[24m differs from AT&T [4mtroff[24m, which
       interpolated 1 only if [4mnroff[24m was the formatter and was called with [1m-T[22m.

       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 identi‐
       fiers for their names.

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

       In compatibility mode, the escape sequences [1m\f[22m, [1m\H[22m, [1m\m[22m, [1m\M[22m, [1m\R[22m, [1m\s[22m, and
       [1m\S [22mare transparent at the beginning of an input line for the purpose of
       recognizing a control character, because they  modify  formatter  state
       ([1m\R[22m)  or  properties of the environment (the rest) and therefore do not
       create output nodes.  For example, this code produces  bold  output  in
       both cases, but the text differs,
              .de xx '
              Hello!
              ..
              \fB.xx\fP
       formatting “.xx” normally and “Hello!” in compatibility mode.

       GNU  [4mtroff[24m  request  names  unrecognized by other [4mtroff[24m implementations
       will likely be ignored; escape sequences that are GNU [4mtroff[24m  extensions
       are  liable  to format their function selector character.  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  So‐
       laris/Illumos [4mtroff[24ms, which will render it as [1m~[22m.

       GNU  [4mtroff[24m  does  not allow the use of the escape sequences [1m\|[22m, [1m\^[22m, [1m\&[22m,
       [1m\{[22m, [1m\}[22m, [1m\[4m[22mspace[24m, [1m\'[22m, [1m\`[22m, [1m\-[22m, [1m\_[22m, [1m\![22m, [1m\%[22m,  or  [1m\c  [22min  identifiers;  AT&T
       [4mtroff[24m  does.  The [1m\A [22mescape sequence (see subsection “Escape sequences”
       above) may be helpful in avoiding their use.

       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 be migrated to another [1m\s [22mform.  [Back‐
       ground: 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”.]

       Fractional  type  sizes  cause one noteworthy incompatibility.  In AT&T
       [4mtroff[24m the [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[24m points, which may be a much smaller measurement.  See subsec‐
       tion “Fractional type sizes and new scaling units” above.

       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 failure 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 (somewhat use‐
       lessly) does.

       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 ignores any arguments
       and reports the sizes in bytes.

       Unlike AT&T [4mtroff[24m, GNU [4mtroff[24m does not ignore the [1mss [22mrequest if the out‐
       put is a terminal device; instead, the values of minimum inter‐word and
       additional inter‐sentence space are each rounded down  to  the  nearest
       multiple of 12.

       In  GNU  [4mtroff[24m  there is a fundamental difference between (unformatted)
       characters and (formatted) glyphs.  Everything that affects how a glyph
       is output is stored with the glyph node; once a  glyph  node  has  been
       constructed,  it is unaffected by any subsequent requests that are exe‐
       cuted, including [1mbd[22m, [1mcs[22m, [1mtkf[22m, [1mtr[22m, or [1mfp [22mrequests.  Normally, glyphs are
       constructed from characters immediately before the glyph is added to an
       output line.  Macros, diversions, and strings are  all,  in  fact,  the
       same  type  of  object; they contain a sequence of intermixed character
       and glyph nodes.  Special characters transform from one to  the  other:
       before being added to the output, they behave as characters; afterward,
       they  are  glyphs.   A glyph node does not behave like a character node
       when it is processed by a macro: it does not inherit any of the special
       properties that the character from which it was constructed might  have
       had.  For example, the input
              .di x
              \\\\
              .br
              .di
              .x
       produces “[1m\\[22m” in GNU [4mtroff[24m.  Each pair of backslashes becomes one back‐
       slash  [4mglyph;[24m the resulting backslashes are thus not interpreted as es‐
       cape [4mcharacters[24m when they are reread as the diversion is output.   AT&T
       [4mtroff[24m [4mwould[24m interpret them as escape characters when rereading them and
       end up printing one “[1m\[22m”.

       One  way  to format a backslash in most documents is with the [1m\e [22mescape
       sequence; this formats the glyph of the current escape  character,  re‐
       gardless  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 character escape
       [1m\(rs [22mor [1m\[rs][22m, for “reverse solidus”,  from  its  name  in  the  ECMA‐6
       (ISO/IEC  646) standard.  [This escape sequence is not portable to AT&T
       [4mtroff[24m, but is to its lineal descendant, Heirloom Doctools [4mtroff[24m, as  of
       its 060716 release (July 2006).]

       To store an escape sequence in a diversion that is interpreted when the
       diversion  is  reread, either use the traditional [1m\! [22mtransparent output
       facility, or, if this is unsuitable, the new [1m\? [22mescape  sequence.   See
       subsection  “Escape  sequences”  above  and  sections  “Diversions” and
       “gtroff Internals” in [4mGroff:[24m [4mThe[24m [4mGNU[24m [4mImplementation[24m [4mof[24m [4mtroff[24m, the [4mgroff[0m
       Texinfo manual.

       In the somewhat pathological case where a diversion exists containing a
       partially collected line and a partially collected  line  at  the  top‐
       level diversion has never existed, AT&T [4mtroff[24m will output the partially
       collected line at the end of input; GNU [4mtroff[24m will not.

   [1mFormatter output incompatibilities[0m
       Its  extensions  notwithstanding,  the [4mgroff[24m intermediate output format
       has some incompatibilities with that of AT&T [4mtroff[24m, but better compati‐
       bility is sought; problem reports and patches are welcome.  The follow‐
       ing incompatibilities 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 James Clark ⟨jjc@jclark.com⟩, Werner  Lem‐
       berg  ⟨wl@gnu.org⟩, Bernd Warken ⟨groff-bernd.warken-72@web.de⟩, and G.
       Branden Robinson ⟨g.branden.robinson@gmail.com⟩.

[1mSee also[0m
       [4mGroff:[24m [4mThe[24m [4mGNU[24m [4mImplementation[24m [4mof[24m [4mtroff[24m, by Trent A. Fisher  and  Werner
       Lemberg,  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 output format 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  addi‐
       tional  insights  into the device and font description file formats and
       output format.

       [4mgroff[24m(1), [4mgroff[24m(7), [4mroff[24m(7)

groff 1.23.0                      2 July 2023                    [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,  con‐
       trolled 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 arrranged input.  An advantage of [4mhdtbl[24m is that the
       tables  are constructed without calling a preprocessor; this means that
       [4mgroff[24m(7)’s full macro capabilities are available.  On the  other  hand,
       table  processing with [4mhdtbl[24m is much slower than using the [4mgtbl[24m(1) pre‐
       processor.  A further advantage is that the HTML‐like syntax  of  [4mhdtbl[0m
       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 under‐
       stand the basic workflow of [4mhdtbl[24m.  First of all,  you  must  load  the
       [4mhdtbl.tmac[24m  file.  As with nearly all other [4mgroff[24m macro packages, there
       are two possibilities 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[24m macros).  Then you can include on or more tables  in  your  docu‐
       ment,  where  each one must be started and ended with the .TBL and .ETB
       macros, respectively.

       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 suffi‐
       cient, 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 ta‐
       ble 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 an‐
       other 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  start‐
       ing  a line, everything belonging to this macro including the macro it‐
       self 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[0m
       macros are given, together with the possible arguments.

       Macro arguments are separated by blanks.  The order of arguments is ar‐
       bitrary; 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
       colors  defined  by the user with the .defcolor request.  Argument val‐
       ues [4md[24m are decimal numbers with or without decimal point.  Argument val‐
       ues [4mm[24m are natural numbers.  Argument values [4mn[24m are numerical values with
       the usual [4mgroff[24m 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 subsec‐
       tion.

       Most of the argument default values can be changed by the user by  set‐
       ting 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 separa‐
                            tor  lines  between  the  table  rows  and  cells.
                            ‘border=0’  suppresses the surrounding 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[24m Number of table columns.  This argument is  neces‐
                            sary  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  be‐
                            tween 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 align‐
                            ment.   ‘tal=c’:  centered  alignment.    ‘tal=r’:
                            right alignment.
                            [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, respectively)”.  If there
                            are less width values than table columns, the last
                            width  value is used for the remaining 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  con‐
                            tents  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 caption 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
              really necessary and differs from .TD only in three default set‐
              tings, similar to the <TH> and <TD> HTML tags: The  contents  of
              .TH is horizontally and vertically centered and typeset in bold‐
              face.

              [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 table immediately, either at the current position  or  at
                 the top of the next page if its height is larger than the re‐
                 maining 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 ignored 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’  argu‐
              ment 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  omitted, the defaults take place, which the user can change by set‐
       ting the corresponding default registers or strings, as documented  be‐
       low.   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
              transparent.
              [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
              identifier, such as A for Avant Garde or HN for  Helvetica  Nar‐
              row.
              [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[0m
              request, the ‘fst’ argument can be used to specify the font fam‐
              ily  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  separator 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 sepa‐
              rator 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/pkg/share/doc/groff-1.23.0/examples/hdtbl/common.roff[0m
       provides another example setup in the “minimal Page setup” section.

       A  table which does not fit on a partially filled page is printed auto‐
       matically 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 pack‐
       age.  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 [4mgroff[24m mailing list ⟨groff@gnu.org⟩ or
       directly to the author.

[1mAuthors[0m
       The [4mhdtbl[24m macro package  was  written  by  Joachim  Walsdorff  ⟨Joachim
       .Walsdorff@urz.uni-heidelberg.de⟩.

[1mSee also[0m
       [4mgroff[24m(1)
              provides an overview of GNU [4mroff[24m and details how to invoke [4mgroff[0m
              at the command line.

       [4mgroff[24m(7)
              summarizes the [4mroff[24m language and GNU extensions to it.

       [4mgtbl[24m(1)
              describes the traditional [4mroff[24m preprocessor for tables.

groff 1.23.0                      2 July 2023                   [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[0m
       document formatting  system.   It  is  used  to  produce  manual  pages
       (“man pages”) like the one you are reading.

       This  document presents the macros thematically; for those needing only
       a quick reference, the following table lists them alphabetically,  with
       cross references to appropriate subsections below.

       Man  page authors and maintainers who are not already experienced [4mgroff[0m
       users should consult [4mgroff_man_style[24m(7), 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 typesetting 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.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.SB     [22mSmall bold                   Font style 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               Command 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                 Command synopsis macros

       We discuss other macros ([1m.AT[22m, [1m.DT[22m, [1m.HP[22m, [1m.OP[22m, [1m.PD[22m, and [1m.UC[22m)  in  subsec‐
       tion “Deprecated features” below.

       Throughout  Unix documentation, a manual entry is referred to simply as
       a “man page”, regardless of its length, without  gendered  implication,
       and irrespective 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 [1m.EX [22mand [1m.EE[22m.

       An empty macro argument can be specified with a pair  of  double‐quotes
       (""),  but  the [4mman[24m package is designed such that this should seldom be
       necessary.  Most macro arguments will be formatted as text in the  out‐
       put; exceptions are noted.

   [1mDocument structure macros[0m
       Document  structure  macros organize a man page’s content.  All of them
       break the output line.  [1m.TH [22m(title heading) identifies the document  as
       a  man page and configures the page headers and footers.  Section head‐
       ings ([1m.SH[22m), one of which is mandatory and many of which are convention‐
       ally expected, facilitate location of material by the  reader  and  aid
       the  man  page  writer  to  discuss all essential aspects of the topic.
       Subsection headings ([1m.SS[22m) are optional and permit  sections  that  grow
       long  to develop in a controlled way.  Many technical discussions bene‐
       fit from examples; lengthy ones, especially those  reflecting  multiple
       lines  of input to or output from the system, are usefully bracketed by
       [1m.EX [22mand [1m.EE[22m.  When none of the foregoing meets a structural demand, use
       [1m.RS[22m/[1m.RE [22mto inset a region within a (sub)section.

       [1m.TH [4m[22mtopic[24m [4msection[24m [[4mfooter‐middle[24m] [[4mfooter‐inside[24m] [[4mheader‐middle[24m]
              Determine the contents of the page header and footer.  The  sub‐
              ject  of  the man page is [4mtopic[24m and the section of the manual to
              which it belongs is [4msection.[24m  See [4mman[24m(1)  or  [4mintro[24m(1)  for  the
              manual  sectioning applicable to your system.  [4mtopic[24m and [4msection[0m
              are positioned together at the left  and  right  in  the  header
              (with  [4msection[24m  in  parentheses  immediately appended to [4mtopic[24m).
              [4mfooter‐middle[24m is centered in the footer.  The arrangement of the
              rest of the footer depends on whether double‐sided layout is en‐
              abled with  the  option  [1m-rD1[22m.   When  disabled  (the  default),
              [4mfooter‐inside[24m  is  positioned  at  the  bottom left.  Otherwise,
              [4mfooter‐inside[24m appears at the bottom left on recto (odd‐numbered)
              pages, and at the bottom right on verso  (even‐numbered)  pages.
              The outside footer is the page number, except in the continuous‐
              rendering mode enabled by the option [1m-rcR=1[22m, in which case it is
              the  [4mtopic[24m and [4msection,[24m as in the header.  [4mheader‐middle[24m is cen‐
              tered 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[0m
              will supply text for it.  The macro package may also  abbreviate
              [4mtopic[24m  and [4mfooter‐inside[24m with ellipses if they would overrun the
              space available in the header  and  footer,  respectively.   For
              HTML output, headers and footers are suppressed.

              Additionally,  this  macro breaks the page, resetting the number
              to 1 (unless the [1m-rC1 [22moption is given).   This  feature  is  in‐
              tended only for formatting multiple [4mman[24m documents in sequence.

              A valid [4mman[24m document calls [1m.TH [22monce, early in the file, prior to
              any other macro calls.

       [1m.SH [22m[[4mheading‐text[24m]
              Set [4mheading‐text[24m as a section heading.  If no argument is given,
              a  one‐line input trap is planted; text on the next line becomes
              [4mheading‐text.[24m  The left margin is reset to zero to set the head‐
              ing text in bold (or the font specified by the string [1mHF[22m),  and,
              on typesetting devices, slightly larger than the base type size.
              If  the  heading  font [1m\*[HF] [22mis bold, use of an italic style in
              [4mheading‐text[24m is mapped to the bold‐italic style if available  in
              the  font  family.   The  inset level is reset to 1, setting the
              left margin to the value of the [1mIN [22mregister.  Text  after  [4mhead‐[0m
              [4ming‐text[24m is set as an ordinary paragraph ([1m.P[22m).

              The  content  of [4mheading‐text[24m and ordering of sections follows a
              set of common practices, as has much of the layout  of  material
              within sections.  For example, a section called “Name” or “NAME”
              must  exist,  must  be the first section after the [1m.TH [22mcall, and
              must contain only text of the form
                     [4mtopic[24m[[1m, [4m[22manother‐topic[24m]... \- [4msummary‐description[0m
              for a man page to be properly indexed.   See  [4mgroff_man_style[24m(7)
              for  suggestions  and  [4mman[24m(7)  for the conventions prevailing on
              your system.

       [1m.SS [22m[[4msubheading‐text[24m]
              Set [4msubheading‐text[24m as a subsection heading indented  between  a
              section  heading and an ordinary paragraph ([1m.P[22m).  If no argument
              is given, a one‐line input trap is planted;  text  on  the  next
              line  becomes  [4msubheading‐text.[24m  The left margin is reset to the
              value of the [1mSN [22mregister to set the heading text 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, setting the left margin to the value of the
              [1mIN  [22mregister.   Text after [4msubheading‐text[24m is set as an ordinary
              paragraph ([1m.P[22m).

       [1m.EX[0m
       [1m.EE    [22mBegin and end example.  After [1m.EX[22m, filling  is  disabled  and  a
              constant‐width  (monospaced)  font is selected.  Calling [1m.EE [22men‐
              ables filling and restores the previous font.

              These macros are extensions introduced in Ninth Edition Research
              Unix.  Systems running that [4mtroff[24m, or  those  from  Documenter’s
              Workbench,  Heirloom Doctools, or Plan 9 [4mtroff[24m support them.  To
              be certain your page will be portable to systems  that  do  not,
              copy  their definitions from the [4man-ext.tmac[24m file of a [4mgroff[24m in‐
              stallation.

       [1m.RS [22m[[4minset‐amount[24m]
              Start a new relative inset level.  The position of the left mar‐
              gin is saved, then moved right by  [4minset‐amount,[24m  if  specified,
              and  by  the  amount of the [1mIN [22mregister otherwise.  Calls to [1m.RS[0m
              can be nested; each increments by 1 the inset level used by [1m.RE[22m.
              The level prior to any [1m.RS [22mcalls is 1.

       [1m.RE [22m[[4mlevel[24m]
              End a relative inset.  The left margin  corresponding  to  inset
              level  [4mlevel[24m  is  restored.   If no argument is given, the inset
              level is reduced by 1.

   [1mParagraphing macros[0m
       An ordinary paragraph ([1m.P[22m) is set without a first‐line  indentation  at
       the  current left margin.  In man pages and other technical literature,
       definition lists are  frequently  encountered;  these  can  be  set  as
       “tagged  paragraphs”,  which  have one ([1m.TP[22m) or more ([1m.TQ[22m) leading tags
       followed by a paragraph that has an additional  indentation.   The  in‐
       dented paragraph ([1m.IP[22m) macro is useful to continue the indented content
       of  a  narrative started with [1m.TP[22m, or to present an itemized or ordered
       list.  All of these macros break the output line.  If another paragraph
       macro has occurred since the previous [1m.SH [22mor [1m.SS[22m, they (except for [1m.TQ[22m)
       follow the break with a default amount of vertical space, which can  be
       changed  by  the  deprecated  [1m.PD [22mmacro; see subsection “Horizontal and
       vertical spacing” below.  They also reset the type size and font  style
       to  defaults  ([1m.TQ  [22magain excepted); see subsection “Font style macros”
       below.

       [1m.P[0m
       [1m.LP[0m
       [1m.PP    [22mBegin a new paragraph; these macros are synonymous.  The  inden‐
              tation  is  reset  to the default value; the left margin, as af‐
              fected by [1m.RS [22mand [1m.RE[22m, is not.

       [1m.TP [22m[[4mindentation[24m]
              Set a paragraph with a leading tag, and  the  remainder  of  the
              paragraph  indented.   A one‐line input trap is planted; text on
              the next line, which can be formatted with a macro, becomes  the
              tag, which is placed at the current left margin.  The tag can be
              extended  with  the  [1m\c [22mescape sequence.  Subsequent text is in‐
              dented by [4mindentation,[24m if specified, and by the amount of the [1mIN[0m
              register otherwise.  If the tag is not as wide as  the  indenta‐
              tion,  the  paragraph starts on the same line as the tag, at the
              applicable indentation, and continues on  the  following  lines.
              Otherwise,  the  descriptive part of the paragraph begins on the
              line following the tag.

       [1m.TQ    [22mSet an additional tag for a paragraph tagged with [1m.TP[22m.  An input
              trap is planted as with [1m.TP[22m.

              This macro is a GNU extension not  defined  on  systems  running
              AT&T,  Plan  9,  or  Solaris  [4mtroff[24m;  see [4man-ext.tmac[24m in section
              “Files” below.

       [1m.IP [22m[[4mtag[24m] [[4mindentation[24m]
              Set an indented paragraph with an optional tag.  The [4mtag[24m and [4min‐[0m
              [4mdentation[24m arguments, if present, are handled as with  [1m.TP[22m,  with
              the  exception  that  the  [4mtag[24m  argument to [1m.IP [22mcannot include a
              macro call.

   [1mCommand synopsis macros[0m
       [1m.SY [22mand [1m.YS [22maid you to construct a command synopsis that has the  clas‐
       sical Unix appearance.  They break the output line.

       These  macros  are  GNU extensions not defined on systems running AT&T,
       Plan 9, or Solaris [4mtroff[24m; see [4man-ext.tmac[24m in section “Files” below.

       [1m.SY [4m[22mcommand[0m
              Begin synopsis.  A new paragraph begins at the left  margin  un‐
              less [1m.SY [22mhas already been called without a corresponding [1m.YS[22m, in
              which  case only a break is performed.  Adjustment and automatic
              hyphenation are disabled.  [4mcommand[24m is set in bold.  If  a  break
              is  required, lines after the first are indented by the width of
              [4mcommand[24m plus a space.

       [1m.YS    [22mEnd synopsis.  Indentation, adjustment, and hyphenation are  re‐
              stored to their previous states.

   [1mHyperlink macros[0m
       Man page cross references are best presented with [1m.MR[22m.  Text may be hy‐
       perlinked  to  email addresses with [1m.MT[22m/[1m.ME [22mor other URIs with [1m.UR[22m/[1m.UE[22m.
       Hyperlinked text is supported on HTML and terminal output devices; ter‐
       minals and pager programs must support ECMA‐48 OSC 8  escape  sequences
       (see  [4mgrotty[24m(1)).   When device support is unavailable or disabled with
       the [1mU [22mregister (see section “Options” below), [1m.MT [22mand [1m.UR [22mURIs are ren‐
       dered between angle brackets after the linked text.

       [1m.MT[22m, [1m.ME[22m, [1m.UR[22m, and [1m.UE [22mare GNU extensions not defined on  systems  run‐
       ning AT&T, Plan 9, or Solaris [4mtroff[24m; see [4man-ext.tmac[24m in section “Files”
       below.  Plan 9 from User Space’s [4mtroff[24m implements [1m.MR[22m.

       The  arguments  to [1m.MR[22m, [1m.MT[22m, and [1m.UR [22mshould be prepared for typesetting
       since they can appear in the output.  Use special character escape  se‐
       quences  to encode Unicode basic Latin characters where necessary, par‐
       ticularly the hyphen‐minus.  The formatter removes [1m\: [22mescape  sequences
       from  hyperlinks  when supplying device control commands to output dri‐
       vers.

       [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[22mman‐[0m
              [4mual‐section[24m[1m)[22m”.   If  [4mtrailing‐text[24m  (typically  punctuation)  is
              specified,  it follows the closing parenthesis without interven‐
              ing space.  Hyphenation is disabled while the cross reference is
              set.  [4mtopic[24m is set in the font specified by the [1mMF [22mstring.   The
              cross  reference hyperlinks to a URI of the form “[1mman:[4m[22mtopic[24m([4mman‐[0m
              [4mual‐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 [1m.ME [22mis placed after the link text without  interven‐
              ing  space.  [4maddress[24m may not be visible in the rendered document
              if hyperlinks are enabled and supported by  the  output  driver.
              If they are not, [4maddress[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,  [4maddress[24m  is  formatted  and  hyperlinked
              [4mwithout[24m angle brackets.

       [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  [1m.UE  [22mis
              placed  after  the link text without intervening space.  [4muri[24m may
              not be visible in the rendered document if  hyperlinks  are  en‐
              abled  and supported by the output driver.  If they are not, [4muri[0m
              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,
              [4muri[24m is formatted and hyperlinked [4mwithout[24m angle brackets.

       The  hyperlinking of [1m.TP [22mparagraph tags with [1m.UR[22m/[1m.UE [22mand [1m.MT[22m/[1m.ME [22mis not
       yet supported; if attempted, the hyperlink will be typeset at  the  be‐
       ginning of the indented paragraph even on hyperlink‐supporting devices.

   [1mFont style macros[0m
       The  [4mman[24m macro package is limited in its font styling options, offering
       only [1mbold [22m([1m.B[22m), [4mitalic[24m ([1m.I[22m), and roman.  Italic text is usually set un‐
       derscored instead on terminal devices.  The [1m.SM [22mand [1m.SB [22mmacros set text
       in roman or bold, respectively, at a smaller type  size;  these  differ
       visually  from regular‐sized roman or bold text only on typesetting de‐
       vices.  It is often necessary to set text in different  styles  without
       intervening  space.  The macros [1m.BI[22m, [1m.BR[22m, [1m.IB[22m, [1m.IR[22m, [1m.RB[22m, and [1m.RI[22m, where
       “B”, “I”, and “R” indicate bold, italic, and roman,  respectively,  set
       their  odd‐  and even‐numbered arguments in alternating styles, with no
       space separating them.

       The default type size and family for typesetting  devices  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.  If no argument is  given,  a  one‐line  input
              trap  is  planted;  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.  If no argument is given,
              a one‐line input trap is planted; 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  type‐
              setting devices.  If no argument is given, a one‐line input trap
              is  planted; text on the next line, which can be further format‐
              ted with a macro, is set smaller.

       [1m.SB [22m[[4mtext[24m]
              Set [4mtext[24m in bold and (on typesetting devices) one point  smaller
              than the default type size.  If no argument is given, a one‐line
              input  trap is planted; text on the next line, which can be fur‐
              ther formatted with a macro, is set smaller and in  bold.   This
              macro is an extension introduced in SunOS 4.0.

       Unlike  the  above font style macros, the font style alternation macros
       below set no input traps; they must be given arguments to have  effect.
       Italic corrections are applied 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  [4mindentation[24m  argument accepted by [1m.IP[22m, [1m.TP[22m, and the deprecated [1m.HP[0m
       is a number plus an optional scaling unit, as  is  [1m.RS[22m’s  [4minset‐amount[24m.
       If  no scaling unit is given, the [4mman[24m package assumes “n”.  An indenta‐
       tion specified in a call to [1m.IP[22m, [1m.TP[22m, or the  deprecated  [1m.HP  [22mpersists
       until  (1)  another of these macros is called with an [4mindentation[24m argu‐
       ment, or (2) [1m.SH[22m, [1m.SS[22m, or [1m.P [22mor its synonyms is called; these clear the
       indentation entirely.

       The left margin used by ordinary paragraphs set with [1m.P [22m(and  its  syn‐
       onyms) not within an [1m.RS[22m/[1m.RE [22mrelative inset is 7.2n for typesetting de‐
       vices  and 7n for terminal devices (but see the [1m-rIN [22moption).  Headers,
       footers (both set with [1m.TH[22m), and section headings ([1m.SH[22m) are set at  the
       page  offset (see [4mgroff[24m(7)) and subsection headings ([1m.SS[22m) indented from
       it by 3n (but see the [1m-rSN [22moption).

       Several macros insert vertical space: [1m.SH[22m, [1m.SS[22m, [1m.TP[22m, [1m.P [22m(and  its  syn‐
       onyms), [1m.IP[22m, and the deprecated [1m.HP[22m.  The default inter‐section and in‐
       ter‐paragraph  spacing is is 1v for terminal devices and 0.4v for type‐
       setting devices.  (The deprecated macro [1m.PD [22mcan  change  this  vertical
       spacing,  but  its use is discouraged.)  Between [1m.EX [22mand [1m.EE [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 section “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 [4mgroff_man_style[24m(7).  Oth‐
       ers are supported for configuration of rendering parameters;  see  sec‐
       tion “Options” 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
              document 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
       administrator  in  a site’s [4mman.local[24m file (see section “Files” below).
       The presentation of [1m.TH [22mabove describes the default headers  and  foot‐
       ers.  Because these macros are hooks for [4mgroff[24m [4mman[24m internals, man pages
       have no reason to call them.  Such hook definitions will likely consist
       of  “.sp”  and “.tl” requests.  They must also increase the page length
       with “.pl” requests in continuous rendering mode; [1m.PT  [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  discour‐
       aged.

       [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 [1m.TH[22m.  This macro
              exists only to render man pages from historical systems.

              [4msystem[24m can be any of the following.

                     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
              translates poorly to HTML, under which exact space  control  and
              tabulation are not readily available.  Thus, information or dis‐
              tinctions  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  is  desirable  to restore them, you
              should probably be composing a table using [4mgtbl[24m(1) instead.

       [1m.HP [22m[[4mindentation[24m]
              Set up a paragraph with a hanging left indentation.  The  [4minden‐[0m
              [4mtation[24m argument, if present, is handled as with [1m.TP[22m.

              Use  of this presentation‐oriented macro is deprecated.  A hang‐
              ing indentation cannot be expressed naturally  under  HTML,  and
              non‐[4mroff[24m‐based  man  page interpreters may treat [1m.HP [22mas an ordi‐
              nary paragraph.  Thus, information or distinctions you  mean  to
              express with indentation may be lost.

       [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 [4mop‐[0m
              [4mtion‐argument[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  argu‐
              ments.

              Use  of  this  quasi‐semantic macro, an extension originating in
              Documenter’s Workbench [4mtroff[24m, is deprecated.  It  cannot  easily
              be  used to annotate options that take optional arguments or op‐
              tions 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 it
              is preferable to use font style alternation macros, which afford
              greater flexibility.

       [1m.PD [22m[[4mvertical‐space[24m]
              Define the 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,  the  spacing
              is  reset  to  its default value; see subsection “Horizontal and
              vertical spacing” above.

              Use of  this  presentation‐oriented  macro  is  deprecated.   It
              translates  poorly  to HTML, under which exact control of inter‐
              paragraph spacing is not readily available.   Thus,  information
              or  distinctions  that  you  use [1m.PD [22mto express are likely to be
              lost.

       [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 [1m.TH[22m.  This macro
              exists only to render man pages from historical systems.

              [4mversion[24m can be any of the following.

                     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
       M.  Douglas  McIlroy ⟨m.douglas.mcilroy@dartmouth.edu⟩ designed, imple‐
       mented, and documented the AT&T [4mman[24m macros for Unix  Version  7  (1979)
       and  employed them to edit the first volume of its [4mProgrammer’s[24m [4mManual[24m,
       a compilation of all man pages supplied by the system.  That  [4mman[24m  sup‐
       ported  the macros listed in this page not described as extensions, ex‐
       cept [1m.P [22mand the deprecated [1m.AT [22mand [1m.UC[22m.  The only strings defined  were
       [1mR [22mand [1mS[22m; no registers were documented.

       [1m.UC  [22mappeared in 3BSD (1980).  Unix System III (1980) introduced [1m.P [22mand
       exposed 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 [22mand [1mrq [22mstrings.  SunOS 2.0 (1985) recognized [1mC[22m,  [1mD[22m,  [1mP[22m,
       and  [1mX  [22mregisters.   4.3BSD (1986) added [1m.AT [22mand [1m.P[22m.  Ninth Edition Re‐
       search Unix (1986) introduced [1m.EX [22mand [1m.EE[22m.  SunOS 4.0 (1988) added [1m.SB[22m.

       The foregoing features were what James Clark implemented in early  ver‐
       sions  of  [4mgroff[24m.   Later,  [4mgroff[24m  1.20 (2009) originated [1m.SY[22m/[1m.YS[22m, [1m.TQ[22m,
       [1m.MT[22m/[1m.ME[22m, and [1m.UR[22m/[1m.UE[22m.  Plan 9 from User Space’s [4mtroff[24m introduced [1m.MR [22min
       2020.

[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
       consistent 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
              alignment  (ragged right margin).  Any valid argument to [4mgroff[24m’s
              “.ad”  request  may  be  used.   See  [4mgroff[24m(7)  for  less‐common
              choices.

       [1m-rcR=1 [22mEnable  continuous rendering.  Output is not paginated; instead,
              one (potentially very long) page is produced.  This is  the  de‐
              fault  for  terminal and HTML devices.  Use [1m-rcR=0 [22mto disable it
              on terminal devices; 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-rCS=1 [22mSet  section headings (the argument(s) to [1m.SH[22m) in full capitals.
              This transformation is off by default because it  discards  case
              distinction information.

       [1m-rCT=1 [22mSet the man page topic (the first argument to [1m.TH[22m) in full capi‐
              tals  in headers and footers.  This transformation is off by de‐
              fault because it discards case distinction information.

       [1m-rD1   [22mEnable double‐sided layout, formatting footers for even and  odd
              pages  differently;  see  the  description  of [1m.TH [22min subsection
              “Document 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.

       [1m-dHF=[4m[22mheading‐font[0m
              Set the font used for section and subsection headings;  the  de‐
              fault  is “[1mB[22m” (bold style of the default family).  Any valid ar‐
              gument to [4mgroff[24m’s “.ft” request may be used.  See [4mgroff[24m(7).

       [1m-rHY=0 [22mDisable automatic hyphenation.  Normally,  it  is  enabled  (1).
              The hyphenation mode is determined by the [4mgroff[24m locale; see sec‐
              tion “Localization“ of [4mgroff[24m(7).

       [1m-rIN=[4m[22mstandard‐indentation[0m
              Set  the  amount of indentation used for ordinary paragraphs ([1m.P[0m
              and its synonyms) and the default  indentation  amount  used  by
              [1m.IP[22m, [1m.RS[22m, [1m.TP[22m, and the deprecated [1m.HP[22m.  See subsection “Horizon‐
              tal  and  vertical spacing” above for the default.  For terminal
              devices, [4mstandard‐indentation[24m should always be an integer multi‐
              ple of unit “n” to get consistent indentation.

       [1m-rLL=[4m[22mline‐length[0m
              Set line length; the default is 78n  for  terminal  devices  and
              6.5i for typesetting devices.

       [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
              Set the font used for man page  topics  named  in  [1m.TH  [22mand  [1m.MR[0m
              calls;  the default is “[1mI[22m” (italic style of the default family).
              Any valid argument to [4mgroff[24m’s “.ft” request may be used.  If the
              [1mMF [22mstring ends in “I”, it is assumed to be an oblique  typeface,
              and  italic  corrections  are  applied before and after man page
              topics.

       [1m-rP[4m[22mn[24m   Start enumeration of pages at [4mn[24m.  The default is 1.

       [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‐indenta‐[0m
              [4mtion.[24m   See  subsection  “Horizontal and vertical spacing” above
              for the default.

       [1m-rU1   [22mEnable generation of URI hyperlinks in the  [4mgrohtml[24m  and  [4mgrotty[0m
              output  drivers.   [4mgrohtml[24m  enables them by default; [4mgrotty[24m does
              not, pending more widespread pager support for OSC 8 escape  se‐
              quences.  Use [1m-rU0 [22mto disable hyperlinks; this will make the ar‐
              guments to [1mMT [22mand [1mUR [22mcalls visible in the document text produced
              by link‐capable drivers.

       [1m-rX[4m[22mp[24m   Number  successors  of  page [4mp[24m as [4mp[24ma, [4mp[24mb, [4mp[24mc, and so forth.  The
              register tracking the suffixed page letter uses format “a”  (see
              the “.af” request in [4mgroff[24m(7)).

[1mFiles[0m
       [4m/usr/pkg/share/groff/1.23.0/tmac/an.tmac[0m
              Most  [4mman[24m macros are defined in this file.  It also loads exten‐
              sions from [4man-ext.tmac[24m (see below).

       [4m/usr/pkg/share/groff/1.23.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
              definitions, taking advantage of the fact that pages using  them
              must  call [1m.TH [22mor [1m.Dd[22m, respectively, before any other macros.  A
              [4mman[24m program or 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.

       [4m/usr/pkg/share/groff/1.23.0/tmac/an-ext.tmac[0m
              Except for [1m.SB[22m, definitions of macros described above as  exten‐
              sions  are  contained in this file; in some cases, they are sim‐
              pler versions of definitions appearing in [4man.tmac[24m, and  are  ig‐
              nored  if  the  formatter  is GNU [4mtroff[24m.  They are written to be
              compatible with AT&T [4mtroff[24m and permissively  licensed—not  copy‐
              lefted.  To reduce the risk of name space collisions, string and
              register  names  begin only with “[1mm[22m”[1m.  [22mWe encourage man page au‐
              thors who are concerned about portability to legacy Unix systems
              to copy these definitions into their pages, and  maintainers  of
              [4mtroff[24m  implementations  or  work‐alike  systems  that format man
              pages to re‐use them.

              The definitions for these macros are read  after  a  page  calls
              [1m.TH[22m, so they will replace any macros of the same names preceding
              it  in  your file.  If you use your own implementations of these
              macros, they must be defined after [1m.TH [22mis called to have any ef‐
              fect.  Furthermore, it is wise to define such page‐local  macros
              (if  at all) after the “Name” section to accommodate timid [4mmake‐[0m
              [4mwhatis[24m or [4mmandb[24m implementations that may give up their scan  for
              indexing material early.

       [4m/usr/pkg/share/groff/1.23.0/tmac/man.tmac[0m
              This is a wrapper that loads [4man.tmac[24m.

       [4m/usr/pkg/share/groff/1.23.0/tmac/mandoc.tmac[0m
              This is a wrapper that loads [4mandoc.tmac[24m.

       [4m/usr/pkg/share/groff/site-tmac/man.local[0m
              Put site‐local changes and customizations into this file.

[1mAuthors[0m
       The  initial GNU implementation of the [4mman[24m macro package was written by
       James Clark.  Later, Werner Lemberg ⟨wl@gnu.org⟩ supplied  the  [1mS[22m,  [1mLT[22m,
       and [1mcR [22mregisters, the last a 4.3BSD‐Reno [4mmdoc[24m(7) feature.  Larry Kollar
       ⟨kollar@alltel.net⟩  added the [1mFT[22m, [1mHY[22m, and [1mSN [22mregisters; the [1mHF [22mstring;
       and the [1mPT [22mand [1mBT [22mmacros.   G.  Branden  Robinson  ⟨g.branden.robinson@
       gmail.com⟩  implemented the [1mAD [22mand [1mMF [22mstrings; [1mCS[22m, [1mCT[22m, and [1mU [22mregisters;
       and the [1mMR [22mmacro.  Except for [1m.SB[22m, the extension macros were written by
       Lemberg, Eric S. Raymond ⟨esr@thyrsus.com⟩, and Robinson.

       This document was originally written for the Debian GNU/Linux system by
       Susan G. Kleinmann ⟨sgk@debian.org⟩.  It was corrected and  updated  by
       Lemberg  and Robinson.  The extension macros were documented by Raymond
       and Robinson.

[1mSee also[0m
       [4mgtbl[24m(1), [4mgeqn[24m(1), and [4mgrefer[24m(1) are preprocessors used with man  pages.
       [4mman[24m(1)  describes the man page librarian on your system.  [4mgroff_mdoc[24m(7)
       details the [4mgroff[24m version of the BSD‐originated alternative macro pack‐
       age for man pages.

       [4mgroff_man_style[24m(7), [4mgroff[24m(7), [4mgroff_char[24m(7), [4mman[24m(7)

groff 1.23.0                   30 December 2025                   [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[0m
       document  formatting  system.   It  is  used  to  produce  manual pages
       (“man pages”) like the one you are reading.

       This document presents the macros thematically; for those needing  only
       a  quick reference, the following table lists them alphabetically, with
       cross references to appropriate subsections below.

       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.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.SB     [22mSmall bold                   Font style 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               Command 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                 Command synopsis macros

       We discuss other macros ([1m.AT[22m, [1m.DT[22m, [1m.HP[22m, [1m.OP[22m, [1m.PD[22m, and [1m.UC[22m)  in  subsec‐
       tion “Deprecated features” below.

       Throughout  Unix documentation, a manual entry is referred to simply as
       a “man page”, regardless of its length, without  gendered  implication,
       and irrespective of the macro package selected for its composition.

       Man  pages  should be encoded using Unicode basic Latin code points ex‐
       clusively, and employ the Unix line‐ending convention (U+000A only).

   [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 [4mgtroff[24m(1) col‐
       lects words from the input and [4mfills[24m output lines with as many as  will
       fit.   [4mWords[24m  are  separated by spaces and newlines.  A transition to a
       new output line is called a [4mbreak.[24m  When formatted, a word may be  bro‐
       ken at hyphens, at [1m\% [22mor [1m\: [22mescape sequences (see subsection “Portabil‐
       ity”  below), or at predetermined locations if automatic hyphenation is
       enabled (see the [1m-rHY [22moption in section “Options”  below).   An  output
       line may be supplemented with [4minter‐sentence[24m [4mspace,[24m and then optionally
       [4madjusted[24m  with more space to a consistent line length (see the [1m-dAD [22mop‐
       tion).  [4mroff[24m(7) details these processes.

       An input line that starts with a dot (.) or neutral apostrophe (') is a
       [4mcontrol[24m [4mline.[24m  To call a macro, put its name after a dot on  a  control
       line.   We  refer  to  macros  in this document using this leading dot.
       Some macros interpret [4marguments,[24m words that follow the macro  name.   A
       newline, unless escaped (see subsection “Portability” below), marks the
       end of the macro call.  An input line consisting of a dot followed by a
       newline  is  called the [4mempty[24m [4mrequest;[24m it does nothing.  [4mText[24m [4mlines[24m are
       input lines that are not control lines.

       We describe below several [4mman[24m macros that plant one‐line  [4minput[24m  [4mtraps:[0m
       the  next input line that directly produces formatted output is treated
       specially.  For [4mman[24m documents that follow the advice in section “Porta‐
       bility” below, this means that control lines using  the  empty  request
       and  uncommented  input  lines  ending  with  an escaped newline do not
       spring the trap; anything else does (but see  the  [1m.TP  [22mmacro  descrip‐
       tion).

   [1mMacro reference preliminaries[0m
       A  tagged paragraph describes each macro.  We present coupled pairs to‐
       gether, as with [1m.EX [22mand [1m.EE[22m.

       Optional macro arguments are indicated by surrounding them with  square
       brackets.   If  a  macro  accepts  multiple arguments, those containing
       space characters must be double‐quoted to be interpreted correctly.  An
       empty macro argument can be specified  with  a  pair  of  double‐quotes
       (""),  but  the [4mman[24m package is designed such that this should seldom be
       necessary.  See section “Notes” below for examples of cases where  bet‐
       ter alternatives to empty arguments in macro calls are available.  Most
       macro arguments will be formatted 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.  [1m.TH [22m(title heading) identifies the document  as
       a  man page and configures the page headers and footers.  Section head‐
       ings ([1m.SH[22m), one of which is mandatory and many of which are convention‐
       ally expected, facilitate location of material by the  reader  and  aid
       the  man  page  writer  to  discuss all essential aspects of the topic.
       Subsection headings ([1m.SS[22m) are optional and permit  sections  that  grow
       long  to develop in a controlled way.  Many technical discussions bene‐
       fit from examples; lengthy ones, especially those  reflecting  multiple
       lines  of input to or output from the system, are usefully bracketed by
       [1m.EX [22mand [1m.EE[22m.  When none of the foregoing meets a structural demand, use
       [1m.RS[22m/[1m.RE [22mto inset a region within a (sub)section.

       [1m.TH [4m[22mtopic[24m [4msection[24m [[4mfooter‐middle[24m] [[4mfooter‐inside[24m] [[4mheader‐middle[24m]
              Determine the contents of the page header and footer.  [4mroff[24m sys‐
              tems refer to these collectively as “titles”.   The  subject  of
              the  man page is [4mtopic[24m and the section of the manual to which it
              belongs is [4msection.[24m  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.   See  [4mman[24m(1) or [4mintro[24m(1) for the manual sectioning ap‐
              plicable to your system.  [4mtopic[24m and [4msection[24m are  positioned  to‐
              gether  at  the  left  and  right in the header (with [4msection[24m in
              parentheses immediately appended to  [4mtopic[24m).   [4mfooter‐middle[24m  is
              centered  in  the  footer.   The  arrangement of the rest of the
              footer depends on whether double‐sided layout  is  enabled  with
              the  option [1m-rD1[22m.  When disabled (the default), [4mfooter‐inside[24m is
              positioned at the bottom left.  Otherwise, [4mfooter‐inside[24m appears
              at the bottom left on recto (odd‐numbered)  pages,  and  at  the
              bottom right on verso (even‐numbered) pages.  The outside footer
              is  the page number, except in the continuous‐rendering mode en‐
              abled by the option [1m-rcR=1[22m, in which case it is  the  [4mtopic[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 will supply
              text for it.  The macro package may also  abbreviate  [4mtopic[24m  and
              [4mfooter‐inside[24m  with  ellipses  ([1m...[22m)  if  they would overrun the
              space available in the header  and  footer,  respectively.   For
              HTML output, headers and footers are suppressed.

              Additionally,  this  macro breaks the page, resetting the number
              to 1 (unless the [1m-rC1 [22moption is given).   This  feature  is  in‐
              tended only for formatting multiple [4mman[24m documents in sequence.

              A valid [4mman[24m document calls [1m.TH [22monce, early in the file, prior to
              any other macro calls.

              By convention, [4mfooter‐middle[24m is the date of the most recent mod‐
              ification  to the man page source document, 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.  If no argument is given,
              a one‐line input trap is planted; text on the next line  becomes
              [4mheading‐text.[24m  The left margin is reset to zero to set the head‐
              ing  text in bold (or the font specified by the string [1mHF[22m), and,
              on typesetting devices, slightly larger than the base type size.
              If the heading font [1m\*[HF] [22mis bold, use of an  italic  style  in
              [4mheading‐text[24m  is mapped to the bold‐italic style if available in
              the font family.  The inset level is reset  to  1,  setting  the
              left  margin  to the value of the [1mIN [22mregister.  Text after [4mhead‐[0m
              [4ming‐text[24m is set as an ordinary paragraph ([1m.P[22m).

              The content of [4mheading‐text[24m and ordering of sections  follows  a
              set  of  common practices, as has much of the layout of material
              within sections.  For example, a section called “Name” or “NAME”
              must exist, must be the first section after the  [1m.TH  [22mcall,  and
              must contain only text of the form
                     [4mtopic[24m[[1m, [4m[22manother‐topic[24m]... \- [4msummary‐description[0m
              for  a man page to be properly indexed.  See [4mman[24m(7) for the con‐
              ventions prevailing on your system.

       [1m.SS [22m[[4msubheading‐text[24m]
              Set [4msubheading‐text[24m as a subsection heading indented  between  a
              section  heading and an ordinary paragraph ([1m.P[22m).  If no argument
              is given, a one‐line input trap is planted;  text  on  the  next
              line  becomes  [4msubheading‐text.[24m  The left margin is reset to the
              value of the [1mSN [22mregister to set the heading text 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, setting the left margin to the value of the
              [1mIN  [22mregister.   Text after [4msubheading‐text[24m is set as an ordinary
              paragraph ([1m.P[22m).

       [1m.EX[0m
       [1m.EE    [22mBegin and end example.  After [1m.EX[22m, filling  is  disabled  and  a
              constant‐width  (monospaced)  font is selected.  Calling [1m.EE [22men‐
              ables filling and restores the previous font.

              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,  and
              sentence  endings  are  still detected and additional inter‐sen‐
              tence space applied.  If the amount of additional inter‐sentence
              spacing is altered, the rendering of, for instance, regular  ex‐
              pressions  using  [1m. [22mor [1m? [22mfollowed by multiple spaces can change.
              Use the dummy character escape sequence [1m\& [22mbefore the spaces.

              These macros are extensions introduced in Ninth Edition Research
              Unix.  Systems running that [4mtroff[24m, or  those  from  Documenter’s
              Workbench,  Heirloom Doctools, or Plan 9 [4mtroff[24m support them.  To
              be certain your page will be portable to systems  that  do  not,
              copy  their definitions from the [4man-ext.tmac[24m file of a [4mgroff[24m in‐
              stallation.

       [1m.RS [22m[[4minset‐amount[24m]
              Start a new relative inset level.  The position of the left mar‐
              gin is saved, then moved right by  [4minset‐amount,[24m  if  specified,
              and  by  the  amount of the [1mIN [22mregister otherwise.  Calls to [1m.RS[0m
              can be nested; each increments by 1 the inset level used by [1m.RE[22m.
              The level prior to any [1m.RS [22mcalls is 1.

       [1m.RE [22m[[4mlevel[24m]
              End a relative inset.  The left margin  corresponding  to  inset
              level  [4mlevel[24m  is  restored.   If no argument is given, the inset
              level is reduced by 1.

   [1mParagraphing macros[0m
       An ordinary paragraph ([1m.P[22m) like this one is set  without  a  first‐line
       indentation at the current left margin.  In man pages and other techni‐
       cal  literature, definition lists are frequently encountered; these can
       be set as “tagged paragraphs”, which have one ([1m.TP[22m) or more ([1m.TQ[22m) lead‐
       ing tags followed by a paragraph that has  an  additional  indentation.
       The  indented  paragraph ([1m.IP[22m) macro is useful to continue the indented
       content of a narrative started with [1m.TP[22m, or to present an  itemized  or
       ordered  list.   All of these macros break the output line.  If another
       paragraph macro has occurred since the previous [1m.SH [22mor [1m.SS[22m,  they  (ex‐
       cept for [1m.TQ[22m) follow the break with a default amount of vertical space,
       which can be changed by the deprecated [1m.PD [22mmacro; see subsection “Hori‐
       zontal  and vertical spacing” below.  They also reset the type size and
       font style to defaults ([1m.TQ [22magain excepted); see subsection “Font style
       macros” below.

       [1m.P[0m
       [1m.LP[0m
       [1m.PP    [22mBegin a new paragraph; these macros are synonymous.  The  inden‐
              tation  is  reset  to the default value; the left margin, as af‐
              fected by [1m.RS [22mand [1m.RE[22m, is not.

       [1m.TP [22m[[4mindentation[24m]
              Set a paragraph with a leading tag, and  the  remainder  of  the
              paragraph  indented.   A one‐line input trap is planted; text on
              the next line, which can be formatted with a macro, becomes  the
              tag, which is placed at the current left margin.  The tag can be
              extended  with  the  [1m\c [22mescape sequence.  Subsequent text is in‐
              dented by [4mindentation,[24m if specified, and by the amount of the [1mIN[0m
              register otherwise.  If the tag is not as wide as  the  indenta‐
              tion,  the  paragraph starts on the same line as the tag, at the
              applicable indentation, and continues on  the  following  lines.
              Otherwise,  the  descriptive part of the paragraph begins on the
              line following the tag.

              The line containing the tag can include a macro  call,  for  in‐
              stance  to  set  the tag in bold with [1m.B[22m.  [1m.TP [22mwas used to write
              the first paragraph of this description of [1m.TP[22m, and [1m.IP [22mthe sub‐
              sequent one.

       [1m.TQ    [22mSet an additional tag for a paragraph tagged with [1m.TP[22m.  An input
              trap is planted as with [1m.TP[22m.

              This macro is a GNU extension not  defined  on  systems  running
              AT&T,  Plan  9,  or  Solaris  [4mtroff[24m;  see [4man-ext.tmac[24m in section
              “Files” below.

              The descriptions of [1m.P[22m, [1m.LP[22m, and [1m.PP [22mabove  were  written  using
              [1m.TP [22mand [1m.TQ[22m.

       [1m.IP [22m[[4mtag[24m] [[4mindentation[24m]
              Set an indented paragraph with an optional tag.  The [4mtag[24m and [4min‐[0m
              [4mdentation[24m  arguments,  if present, are handled as with [1m.TP[22m, with
              the exception that the [4mtag[24m argument  to  [1m.IP  [22mcannot  include  a
              macro call.

              Two convenient uses for [1m.IP [22mare

                  (1) to start a new paragraph with the same indentation as an
                      immediately preceding [1m.IP [22mor [1m.TP [22mparagraph, if no [4minden‐[0m
                      [4mtation[24m argument is given; and

                  (2) to set a paragraph with a short [4mtag[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.

   [1mCommand synopsis macros[0m
       [1m.SY  [22mand [1m.YS [22maid you to construct a command synopsis that has the clas‐
       sical Unix appearance.  They break the output line.

       These macros are GNU extensions not defined on  systems  running  AT&T,
       Plan 9, or Solaris [4mtroff[24m; see [4man-ext.tmac[24m in section “Files” below.

       [1m.SY [4m[22mcommand[0m
              Begin  synopsis.   A new paragraph begins at the left margin (as
              with [1m.P[22m) unless [1m.SY [22mhas already been  called  without  a  corre‐
              sponding  [1m.YS[22m, in which case only a break is performed.  Adjust‐
              ment and automatic hyphenation are disabled.  [4mcommand[24m is set  in
              bold.   If  a  break  is required, lines after the first are in‐
              dented by the width of [4mcommand[24m plus a space.

       [1m.YS    [22mEnd synopsis.  Indentation, adjustment, and hyphenation are  re‐
              stored to their previous states.

       Multiple  [1m.SY[22m/[1m.YS  [22mblocks can be specified, for instance to distinguish
       differing modes of operation of a complex  command  like  [4mtar[24m(1);  each
       will be vertically separated as paragraphs are.

       [1m.SY  [22mcan be repeated before [1m.YS [22mto indicate synonymous ways of invoking
       a particular mode of operation.

       [4mgroff[24m’s own command‐line interface serves to  illustrate  most  of  the
       specimens of synopsis syntax one is likely to encounter.

              .SY groff
              .RB [ \‐abcCeEgGijklNpRsStUVXzZ ]
              .RB [ \‐d\~\c
              .IR cs ]
              .RB [ \‐d\~\c
              .IB name =\c
              .IR string ]
              .RB [ \‐D\~\c
              .IR enc ]
              [4m(and[24m [4mso[24m [4mon[24m [4msimilarly)[0m
              .RI [ file\~ .\|.\|.]
              .YS
              .
              .
              .SY groff
              .B \‐h
              .
              .SY groff
              .B \‐\‐help
              .YS
              .
              .
              .SY groff
              .B \‐v
              .RI [ option\~ .\|.\|.\&]
              .RI [ file\~ .\|.\|.]
              .
              .SY groff
              .B \‐\‐version
              .RI [ option\~ .\|.\|.\&]
              .RI [ file\~ .\|.\|.]
              .YS

       produces the following output.

              [1mgroff [22m[[1m-abcCeEgGijklNpRsStUVXzZ[22m] [[1m-d [4m[22mcs[24m] [[1m-d [4m[22mname[24m[1m=[4m[22mstring[24m]
                    [[1m-D [4m[22menc[24m] [[1m-f [4m[22mfam[24m] [[1m-F [4m[22mdir[24m] [[1m-I [4m[22mdir[24m] [[1m-K [4m[22menc[24m] [[1m-L [4m[22marg[24m]
                    [[1m-m [4m[22mname[24m] [[1m-M [4m[22mdir[24m] [[1m-n [4m[22mnum[24m] [[1m-o [4m[22mlist[24m] [[1m-P [4m[22marg[24m] [[1m-r [4m[22mcn[24m]
                    [[1m-r [4m[22mreg[24m[1m=[4m[22mexpr[24m] [[1m-T [4m[22mdev[24m] [[1m-w [4m[22mname[24m] [[1m-W [4m[22mname[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, is used to vertically
         space the input file for readability by the document maintainer.   Do
         not put blank (empty) lines in a man page source document.

       • 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
         important  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 text.

       • Symbols  that  are  neither to be typed literally nor replaced at the
         user’s discretion appear in the roman style;  brackets  surround  op‐
         tional arguments, and an ellipsis indicates that the previous syntac‐
         tical element may be repeated arbitrarily.

       • The  non‐breaking adjustable space escape sequence [1m\~ [22mis used to pre‐
         vent the output line from being broken within  the  option  brackets;
         see subsection “Portability” 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 fur‐
         ther text will follow after space on the  output  line,  keeping  its
         last period from being interpreted as the end of a sentence and caus‐
         ing  additional inter‐sentence space to be placed after it.  See sub‐
         section “Portability” below.

   [1mHyperlink macros[0m
       Man page cross references like [4mls[24m(1) are best presented with [1m.MR[22m.  Text
       may be hyperlinked to email addresses with [1m.MT[22m/[1m.ME [22mor other  URIs  with
       [1m.UR[22m/[1m.UE[22m.  Hyperlinked text is supported on HTML and terminal output de‐
       vices;  terminals  and pager programs must support ECMA‐48 OSC 8 escape
       sequences (see [4mgrotty[24m(1)).  When device support is unavailable or  dis‐
       abled  with  the  [1mU [22mregister (see section “Options” below), [1m.MT [22mand [1m.UR[0m
       URIs are rendered between angle brackets after the linked text.

       [1m.MT[22m, [1m.ME[22m, [1m.UR[22m, and [1m.UE [22mare GNU extensions not defined on  systems  run‐
       ning AT&T, Plan 9, or Solaris [4mtroff[24m; see [4man-ext.tmac[24m in section “Files”
       below.  Plan 9 from User Space’s [4mtroff[24m implements [1m.MR[22m.

       The  arguments  to [1m.MR[22m, [1m.MT[22m, and [1m.UR [22mshould be prepared for typesetting
       since they can appear in the output.  Use special character escape  se‐
       quences  to encode Unicode basic Latin characters where necessary, par‐
       ticularly the hyphen‐minus.  (See section “Portability”  below.)   URIs
       can  be  lengthy;  rendering  them  can result in jarring adjustment or
       variations in line length, or  [4mgtroff[24m  warnings  when  a  hyperlink  is
       longer  than  an  output  line.   The application of non‐printing break
       point escape sequences [1m\: [22mafter each slash (or series thereof), and be‐
       fore 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  mistak‐
       enly  interpreting  a dot at the end of a line as a period (or multiple
       dots as an ellipsis).  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, ampersands, and number signs in HTTP(S) URIs.  The formatter re‐
       moves [1m\: [22mescape sequences from hyperlinks when supplying device control
       commands to output drivers.

       [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[22mman‐[0m
              [4mual‐section[24m[1m)[22m”.   If  [4mtrailing‐text[24m  (typically  punctuation)  is
              specified,  it follows the closing parenthesis without interven‐
              ing space.  Hyphenation is disabled while the cross reference is
              set.  [4mtopic[24m is set in the font specified by the [1mMF [22mstring.   The
              cross  reference hyperlinks to a URI of the form “[1mman:[4m[22mtopic[24m([4mman‐[0m
              [4mual‐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 [1m.ME [22mis placed after the link text without  interven‐
              ing  space.  [4maddress[24m may not be visible in the rendered document
              if hyperlinks are enabled and supported by  the  output  driver.
              If they are not, [4maddress[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,  [4maddress[24m  is  formatted  and  hyperlinked
              [4mwithout[24m angle brackets.

              When rendered by [4mgroff[24m to a PostScript device,

                     Contact
                     .MT fred\:.foonly@\:fubar\:.net
                     Fred Foonly
                     .ME
                     for more information.

              displays  as  “Contact  Fred  Foonly ⟨fred.foonly@fubar.net⟩ for
              more information.”.

       [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 [1m.UE [22mis
              placed after the link text without intervening space.   [4muri[24m  may
              not  be  visible  in the rendered document if hyperlinks are en‐
              abled and supported by the output driver.  If they are not,  [4muri[0m
              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,
              [4muri[24m is formatted and hyperlinked [4mwithout[24m angle brackets.

              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 .

              displays as “The GNU Project of  the  Free  Software  Foundation
              hosts   the   [4mgroff[24m   home  page  ⟨https://www.gnu.org/software/
              groff/⟩.”.

       The hyperlinking of [1m.TP [22mparagraph tags with [1m.UR[22m/[1m.UE [22mand [1m.MT[22m/[1m.ME [22mis  not
       yet  supported;  if attempted, the hyperlink will be typeset at the be‐
       ginning of the indented paragraph even on hyperlink‐supporting devices.

   [1mFont style macros[0m
       The [4mman[24m macro package is limited in its font styling options,  offering
       only [1mbold [22m([1m.B[22m), [4mitalic[24m ([1m.I[22m), and roman.  Italic text is usually set un‐
       derscored instead on terminal devices.  The [1m.SM [22mand [1m.SB [22mmacros set text
       in  roman  or  bold, respectively, at a smaller type size; these differ
       visually from regular‐sized roman or bold text only on typesetting  de‐
       vices.   It  is often necessary to set text in different styles without
       intervening space.  The macros [1m.BI[22m, [1m.BR[22m, [1m.IB[22m, [1m.IR[22m, [1m.RB[22m, and [1m.RI[22m,  where
       “B”,  “I”,  and “R” indicate bold, italic, and roman, respectively, set
       their odd‐ and even‐numbered arguments in alternating styles,  with  no
       space separating them.

       Because  font styles are presentational rather than semantic, conflict‐
       ing traditions have arisen regarding which font styles should  be  used
       to  mark  file or path names, environment variables, and inlined liter‐
       als.

       The default type size and family for typesetting  devices  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.  If no argument is  given,  a  one‐line  input
              trap  is  planted;  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 [1m.EX[22m/[1m.EE[0m
              example of interactive 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.  If no argument is given,
              a  one‐line  input trap is planted; 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 in‐
              troduced, for names of journals and  of  literary  works  longer
              than  an article, and anywhere a parameter requiring replacement
              by the user is encountered.  An exception involves variant  text
              in  a  context  already typeset in italics, such as file or path
              names with replaceable components; in  such  cases,  follow  the
              convention of mathematical typography: set the file or path name
              in  italics as usual but use roman for the variant part (see [1m.IR[0m
              and [1m.RI [22mbelow), and italics again in running roman text when re‐
              ferring to the variant material.

       [1m.SM [22m[[4mtext[24m]
              Set [4mtext[24m one point smaller than the default type size  on  type‐
              setting devices.  If no argument is given, a one‐line input trap
              is  planted; text on the next line, which can be further format‐
              ted with a macro, is set smaller.

              [4mNote:[24m terminals will render [4mtext[24m at normal size instead.  Do not
              rely upon [1m.SM [22mto communicate semantic information distinct  from
              using roman style at normal size; it will be hidden from readers
              using such devices.

       [1m.SB [22m[[4mtext[24m]
              Set  [4mtext[24m in bold and (on typesetting devices) one point smaller
              than the default type size.  If no argument is given, a one‐line
              input trap is planted; text on the next line, which can be  fur‐
              ther  formatted  with a macro, is set smaller and in bold.  This
              macro is an extension introduced in SunOS 4.0.

              [4mNote:[24m terminals will render [4mtext[24m in bold at the normal size  in‐
              stead.  Do not rely upon [1m.SB [22mto communicate semantic information
              distinct from using bold style at normal size; it will be hidden
              from readers using such devices.

       Observe  what  is  [4mnot[24m prescribed for setting in bold or italics above:
       elements of “synopsis language” such as ellipses  and  brackets  around
       options; proper names and adjectives; titles of anything other than ma‐
       jor works of literature; identifiers for standards documents or techni‐
       cal  reports such as CSTR #54, RFC 1918, Unicode 13.0, or POSIX.1‐2017;
       acronyms; and occurrences after the first of a technical term.

       Be frugal with italics for emphasis, and particularly with bold.  Arti‐
       cle titles and brief runs of literal text, such as references to  indi‐
       vidual  characters  or  short strings, including section and subsection
       headings of man pages, are suitable  objects  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.
       Italic  corrections are applied 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  em‐
       bedded  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 “Portability” 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.

                     After
                     .B .NH
                     is called,

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

                     if
                     .I file
                     is
                     .RB \[lq] \- \[rq],
                     the standard input stream is read.

       [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  [4mindentation[24m  argument accepted by [1m.IP[22m, [1m.TP[22m, and the deprecated [1m.HP[0m
       is a number plus an optional scaling unit, as  is  [1m.RS[22m’s  [4minset‐amount[24m.
       If  no scaling unit is given, the [4mman[24m package assumes “n”; that is, the
       width of a letter “n” in the font current when the macro is called (see
       section “Measurements” in [4mgroff[24m(7)).  An  indentation  specified  in  a
       call  to  [1m.IP[22m, [1m.TP[22m, or the deprecated [1m.HP [22mpersists until (1) another of
       these macros is called with an [4mindentation[24m argument, or (2)  [1m.SH[22m,  [1m.SS[22m,
       or [1m.P [22mor its synonyms is called; these clear the indentation entirely.

       The  left  margin used by ordinary paragraphs set with [1m.P [22m(and its syn‐
       onyms) not within an [1m.RS[22m/[1m.RE [22mrelative inset is 7.2n for typesetting de‐
       vices and 7n for terminal devices (but see the [1m-rIN [22moption).   Headers,
       footers  (both set with [1m.TH[22m), and section headings ([1m.SH[22m) are set at the
       page offset (see [4mgroff[24m(7)) and subsection headings ([1m.SS[22m) indented  from
       it by 3n (but see the [1m-rSN [22moption).

       It  may  be  helpful to think of the left margin and indentation as re‐
       lated but distinct concepts; [4mgroff[24m’s implementation of  the  [4mman[24m  macro
       package  tracks them separately.  The left margin is manipulated by [1m.RS[0m
       and [1m.RE [22m(and by [1m.SH [22mand [1m.SS[22m, which reset it to the default).   Indenta‐
       tion  is  controlled by the paragraphing macros (though, again, [1m.SH [22mand
       [1m.SS [22mreset it); it is imposed  by  the  [1m.TP[22m,  [1m.IP[22m,  and  deprecated  [1m.HP[0m
       macros,  and  cancelled  by  [1m.P [22mand its synonyms.  An extensive example
       follows.

       This ordinary ([1m.P[22m) paragraph is not in a relative  inset  nor  does  it
       possess an indentation.

              Now  we have created a relative inset (in other words, moved the
              left margin) with [1m.RS [22mand  started  another  ordinary  paragraph
              with [1m.P[22m.

              [1mtag    [22mThis  tagged paragraph, set with [1m.TP[22m, is still within the
                     [1m.RS [22mregion, but lines after the first have  a  supplemen‐
                     tary indentation that the tag lacks.

                     A  paragraph  like this one, set with [1m.IP[22m, will appear to
                     the reader as also associated with the tag above, because
                     [1m.IP [22mre‐uses the previous paragraph’s  indentation  unless
                     given  an  argument  to change it.  This paragraph is af‐
                     fected both by the moved left margin ([1m.RS[22m)  and  indenta‐
                     tion ([1m.IP[22m).
                     ┌──────────────────────────────────┐
                     │ This table is affected both by   │
                     │ the left margin and indentation. │
                     └──────────────────────────────────┘

              •      This indented paragraph has a bullet for a tag, making it
                     more  obvious  that  the  left margin and indentation are
                     distinct; only the former affects the tag, but  both  af‐
                     fect the text of the paragraph.

              This  ordinary  ([1m.P[22m)  paragraph  resets the indentation, but the
              left margin is still inset.
              ┌─────────────────────────────┐
              │ This table is affected only │
              │ by the left margin.         │
              └─────────────────────────────┘

       Finally, we have ended the relative inset by using [1m.RE[22m, which  (because
       we  used  only  one  [1m.RS[22m/[1m.RE [22mpair) has reset the left margin to the de‐
       fault.  This is an ordinary [1m.P [22mparagraph.

       Resist the temptation to mock up tabular or  multi‐column  output  with
       tab  characters  or  the indentation arguments to [1m.IP[22m, [1m.TP[22m, [1m.RS[22m, or the
       deprecated [1m.HP[22m; the result may not render comprehensibly on  an  output
       device you fail to check, or which is developed in the future.  The ta‐
       ble preprocessor [4mgtbl[24m(1) can likely meet your needs.

       Several  macros  insert vertical space: [1m.SH[22m, [1m.SS[22m, [1m.TP[22m, [1m.P [22m(and its syn‐
       onyms), [1m.IP[22m, and the deprecated [1m.HP[22m.  The default inter‐section and in‐
       ter‐paragraph spacing is is 1v for terminal devices and 0.4v for  type‐
       setting  devices  (“v”  is a unit of vertical distance, where 1v is the
       distance between adjacent text baselines in a single‐spaced  document).
       (The deprecated macro [1m.PD [22mcan change this vertical spacing, but its use
       is  discouraged.)  Between [1m.EX [22mand [1m.EE [22mcalls, the inter‐paragraph spac‐
       ing 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 section “Files” below.

   [1mStrings[0m
       The following strings are defined for use in  man  pages.   Others  are
       supported  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
              document 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.

       None  of the above is necessary in a contemporary man page.  [1m\*S [22mis su‐
       perfluous, since type size changes are invisible  on  terminal  devices
       and macros that change it restore its original value afterward.  Better
       alternatives  exist  for the rest; simply use the [1m\(rg[22m, [1m\(lq[22m, [1m\(rq[22m, and
       [1m\(tm [22mspecial character escape sequences directly.  Unless  a  man  page
       author  is  aiming for a pathological level of portability, such as the
       composition of pages for consumption on simulators of 1980s  Unix  sys‐
       tems  (or  Solaris  [4mtroff[24m,  though  even  it  supports [1m\(rg[22m), the above
       strings should be avoided.

   [1mPortability[0m
       It is wise to quote multi‐word section and subsection headings; the [1m.SH[0m
       and [1m.SS [22mmacros of [4mman[24m(7) implementations descended from Seventh Edition
       Unix supported six arguments at most.  A similar restriction applied to
       the [1m.B[22m, [1m.I[22m, [1m.SM[22m, and font style alternation macros.

       The two major syntactical categories for formatting control in the [4mroff[0m
       language are requests and escape sequences.  Since the [4mman[24m  macros  are
       implemented  in  terms of [4mgroff[24m requests and escape sequences, one can,
       in principle, supplement the functionality of  [4mman[24m  with  these  lower‐
       level elements where necessary.

       However, using raw [4mgroff[24m requests (apart from the empty request “[1m.[22m”) is
       likely  to  make your page render poorly when processed by other tools;
       many of these attempt to interpret page sources directly for conversion
       to HTML.  Some requests make implicit  assumptions  about  things  like
       character  and  page  sizes  that  may not hold in an HTML environment;
       also, many of these viewers don’t interpret the full [4mgroff[24m  vocabulary,
       a  problem that can lead to portions of your text being omitted or pre‐
       sented incomprehensibly.

       For portability to modern viewers, it is best to write your page solely
       with the macros described in this page (except for the ones  identified
       as  deprecated, which should be avoided).  The macros we have described
       as extensions ([1m.EX[22m/[1m.EE[22m, [1m.SY[22m/[1m.YS[22m, [1m.TQ[22m, [1m.UR[22m/[1m.UE[22m, [1m.MT[22m/[1m.ME[22m, [1m.MR[22m,  and  [1m.SB[22m)
       should be used with caution, as they may not be built in to some viewer
       that is important to your audience.  See [4man-ext.tmac[24m in section “Files”
       below.

       Similar  caveats  apply to escape sequences.  Some escape sequences are
       however required for correct typesetting even in man pages and  usually
       do not cause portability problems.  Several of these render glyphs cor‐
       responding  to punctuation code points in the Unicode basic Latin range
       (U+0000–U+007F) that are handled specially in [4mroff[24m  input;  the  escape
       sequences below must be used to render them correctly and portably when
       documenting  material  that  uses them syntactically—namely, any of the
       set [1m' - \ ^ ` ~ [22m(apostrophe, dash or minus, backslash, caret, grave ac‐
       cent, tilde).

       [1m\"     [22mComment.  Everything after the double‐quote to the  end  of  the
              input line is ignored.  Whole‐line comments should be placed im‐
              mediately after the empty request (“[1m.[22m”).

       [1m\[4m[22mnewline[0m
              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.  Use this escape se‐
              quence to split excessively long input lines for document  main‐
              tenance.

       [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.   This  escape  sequence is an input word boundary, so 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.

              This  escape  sequence  is  a  [4mgroff[24m extension also supported by
              Heirloom Doctools [4mtroff[24m 050915 (September 2005),  [4mmandoc[24m  1.14.5
              (2019‐03‐10),  and  [4mneatroff[24m  (commit 399a4936, 2014‐02‐17), but
              not by Plan 9, Solaris, or Documenter’s Workbench [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.

              This  escape  sequence  is  a  [4mgroff[24m extension 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 Documenter’s Workbench [4mtroff[24ms.

       [1m\&     [22mDummy  character.   Insert  at the beginning of an input line to
              prevent a dot or apostrophe from being interpreted as  beginning
              a  [4mroff[24m  control line.  Append to 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  typesetting
              devices like [1mdvi[22m, [1mpdf[22m, and [1mps[22m.

       [1m\c     [22mEnd  a  text line without inserting space or attempting a break.
              Normally, if filling is enabled, the  end  of  a  text  line  is
              treated  like  a  space;  an output line [4mmay[24m be broken there (if
              not, an adjustable space is inserted); if filling  is  disabled,
              the line [4mwill[24m be broken there, as in [1m.EX[22m/[1m.EE [22mexamples.  The next
              line  is interpreted as usual and can include a macro call (con‐
              trast with [1m\[4m[22mnewline[24m).  [1m\c [22mis useful when three font  styles  are
              needed in a single word, as in a command synopsis.

                     .RB [ \-\-stylesheet=\c
                     .IR name ]

              It  also  helps  when  changing font styles in [1m.EX[22m/[1m.EE [22mexamples,
              since they are not filled.

                     .EX
                     $ \c
                     .B groff \-T utf8 \-Z \c
                     .I file \c
                     .B | grotty \-i
                     .EE

              Alternatively, and perhaps with better portability, the [1m\f  [22mfont
              selection  escape  sequence can be used; see below.  Using [1m\c [22mto
              continue a [1m.TP [22mparagraph tag across multiple  input  lines  will
              render  incorrectly with [4mgroff[24m 1.22.3, [4mmandoc[24m 1.14.1, older ver‐
              sions of these programs, and perhaps with some other formatters.

       [1m\e     [22mFormat the current 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 ex‐
              plicit [1m\(rs [22m(“reverse solidus”)  special  character  escape  se‐
              quence.

       [1m\fB[22m, [1m\fI[22m, [1m\fR[22m, [1m\fP[0m
              Switch  to  bold,  italic, roman, or back to the previous style,
              respectively.  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, para‐
              graph, or style macro calls have intervened.

              As long as at most two styles are needed in a word, style macros
              like [1m.B [22mand [1m.BI [22musually result in more readable [4mroff[24m source than
              [1m\f [22mescape 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 below, but its descendants, like 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 [4mgroff_font[24m(5).

       [1m\-     [22mMinus sign or basic Latin hyphen‐minus.   This  escape  sequence
              produces  the  Unix command‐line option dash in the output.  “[1m-[22m”
              is a hyphen in the [4mroff[24m language; some output devices replace it
              with U+2010 (hyphen) or similar.

       [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).  Use in  macro  calls
              to  prevent ‘[1m"[22m” from being interpreted as beginning a quoted ar‐
              gument, or simply for readability.

                     .TP
                     .BI "split \(dq" text \(dq

       [1m\(lq[0m
       [1m\(rq   [22mLeft and right double quotation marks.  Use these for paired di‐
              rectional double quotes, “like this”.

       [1m\(em   [22mEm‐dash.  Use for an interruption—such as  this  one—in  a  sen‐
              tence.

       [1m\(en   [22mEn‐dash.   Use to separate the ends of a range, particularly be‐
              tween 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 for‐
              mat  “[1m^[22m”  as U+02C6 (modifier letter circumflex accent) or simi‐
              lar.

       [1m\(rs   [22mReverse solidus (backslash).  The backslash is the  default  es‐
              cape  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) or similar.

       For  maximum  portability,  escape sequences and special characters not
       listed above are better avoided in man pages.

   [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
       administrator  in  a site’s [4mman.local[24m file (see section “Files” below).
       The presentation of [1m.TH [22mabove describes the default headers  and  foot‐
       ers.  Because these macros are hooks for [4mgroff[24m [4mman[24m internals, man pages
       have no reason to call them.  Such hook definitions will likely consist
       of  “.sp”  and “.tl” requests.  They must also increase the page length
       with “.pl” requests in continuous rendering mode; [1m.PT  [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  discour‐
       aged.

       [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 [1m.TH[22m.  This macro
              exists only to render man pages from historical systems.

              [4msystem[24m can be any of the following.

                     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
              translates poorly to HTML, under which exact space  control  and
              tabulation are not readily available.  Thus, information or dis‐
              tinctions  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  is  desirable  to restore them, you
              should probably be composing a table using [4mgtbl[24m(1) instead.

       [1m.HP [22m[[4mindentation[24m]
              Set up a paragraph with a hanging left indentation.  The  [4minden‐[0m
              [4mtation[24m argument, if present, is handled as with [1m.TP[22m.

              Use  of this presentation‐oriented macro is deprecated.  A hang‐
              ing indentation cannot be expressed naturally  under  HTML,  and
              non‐[4mroff[24m‐based  man  page interpreters may treat [1m.HP [22mas an ordi‐
              nary paragraph.  Thus, information or distinctions you  mean  to
              express with indentation may be lost.

       [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 [4mop‐[0m
              [4mtion‐argument[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  argu‐
              ments.

              Use  of  this  quasi‐semantic macro, an extension originating in
              Documenter’s Workbench [4mtroff[24m, is deprecated.  It  cannot  easily
              be  used to annotate options that take optional arguments or op‐
              tions 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 it
              is preferable to use font style alternation macros, which afford
              greater flexibility.

       [1m.PD [22m[[4mvertical‐space[24m]
              Define the 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,  the  spacing
              is  reset  to  its default value; see subsection “Horizontal and
              vertical spacing” above.

              Use of  this  presentation‐oriented  macro  is  deprecated.   It
              translates  poorly  to HTML, under which exact control of inter‐
              paragraph spacing is not readily available.   Thus,  information
              or  distinctions  that  you  use [1m.PD [22mto express are likely to be
              lost.

       [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 [1m.TH[22m.  This macro
              exists only to render man pages from historical systems.

              [4mversion[24m can be any of the following.

                     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
       M.  Douglas  McIlroy ⟨m.douglas.mcilroy@dartmouth.edu⟩ designed, imple‐
       mented, and documented the AT&T [4mman[24m macros for Unix  Version  7  (1979)
       and  employed them to edit the first volume of its [4mProgrammer’s[24m [4mManual[24m,
       a compilation of all man pages supplied by the system.  That  [4mman[24m  sup‐
       ported  the macros listed in this page not described as extensions, ex‐
       cept [1m.P [22mand the deprecated [1m.AT [22mand [1m.UC[22m.  The only strings defined  were
       [1mR [22mand [1mS[22m; no registers were documented.

       [1m.UC  [22mappeared in 3BSD (1980).  Unix System III (1980) introduced [1m.P [22mand
       exposed 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 [22mand [1mrq [22mstrings.  SunOS 2.0 (1985) recognized [1mC[22m,  [1mD[22m,  [1mP[22m,
       and  [1mX  [22mregisters.   4.3BSD (1986) added [1m.AT [22mand [1m.P[22m.  Ninth Edition Re‐
       search Unix (1986) introduced [1m.EX [22mand [1m.EE[22m.  SunOS 4.0 (1988) added [1m.SB[22m.

       The foregoing features were what James Clark implemented in early  ver‐
       sions  of  [4mgroff[24m.   Later,  [4mgroff[24m  1.20 (2009) originated [1m.SY[22m/[1m.YS[22m, [1m.TQ[22m,
       [1m.MT[22m/[1m.ME[22m, and [1m.UR[22m/[1m.UE[22m.  Plan 9 from User Space’s [4mtroff[24m introduced [1m.MR [22min
       2020.

[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
       consistent 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
              alignment  (ragged right margin).  Any valid argument to [4mgroff[24m’s
              “.ad”  request  may  be  used.   See  [4mgroff[24m(7)  for  less‐common
              choices.

       [1m-rcR=1 [22mEnable  continuous rendering.  Output is not paginated; instead,
              one (potentially very long) page is produced.  This is  the  de‐
              fault  for  terminal and HTML devices.  Use [1m-rcR=0 [22mto disable it
              on terminal devices; 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-rCS=1 [22mSet  section headings (the argument(s) to [1m.SH[22m) in full capitals.
              This transformation is off by default because it  discards  case
              distinction information.

       [1m-rCT=1 [22mSet the man page topic (the first argument to [1m.TH[22m) in full capi‐
              tals  in headers and footers.  This transformation is off by de‐
              fault because it discards case distinction information.

       [1m-rD1   [22mEnable double‐sided layout, formatting footers for even and  odd
              pages  differently;  see  the  description  of [1m.TH [22min subsection
              “Document 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.

       [1m-dHF=[4m[22mheading‐font[0m
              Set the font used for section and subsection headings;  the  de‐
              fault  is “[1mB[22m” (bold style of the default family).  Any valid ar‐
              gument to [4mgroff[24m’s “.ft” request may be used.  See [4mgroff[24m(7).

       [1m-rHY=0 [22mDisable automatic hyphenation.  Normally,  it  is  enabled  (1).
              The hyphenation mode is determined by the [4mgroff[24m locale; see sec‐
              tion “Localization“ of [4mgroff[24m(7).

       [1m-rIN=[4m[22mstandard‐indentation[0m
              Set  the  amount of indentation used for ordinary paragraphs ([1m.P[0m
              and its synonyms) and the default  indentation  amount  used  by
              [1m.IP[22m, [1m.RS[22m, [1m.TP[22m, and the deprecated [1m.HP[22m.  See subsection “Horizon‐
              tal  and  vertical spacing” above for the default.  For terminal
              devices, [4mstandard‐indentation[24m should always be an integer multi‐
              ple of unit “n” to get consistent indentation.

       [1m-rLL=[4m[22mline‐length[0m
              Set line length; the default is 78n  for  terminal  devices  and
              6.5i for typesetting devices.

       [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
              Set  the  font  used  for  man  page topics named in [1m.TH [22mand [1m.MR[0m
              calls; the default is “[1mI[22m” (italic style of the default  family).
              Any valid argument to [4mgroff[24m’s “.ft” request may be used.  If the
              [1mMF  [22mstring ends in “I”, it is assumed to be an oblique typeface,
              and italic corrections are applied before  and  after  man  page
              topics.

       [1m-rP[4m[22mn[24m   Start enumeration of pages at [4mn[24m.  The default is 1.

       [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‐indenta‐[0m
              [4mtion.[24m  See subsection “Horizontal and  vertical  spacing”  above
              for the default.

       [1m-rU1   [22mEnable  generation  of  URI hyperlinks in the [4mgrohtml[24m and [4mgrotty[0m
              output drivers.  [4mgrohtml[24m enables them by  default;  [4mgrotty[24m  does
              not,  pending more widespread pager support for OSC 8 escape se‐
              quences.  Use [1m-rU0 [22mto disable hyperlinks; this will make the ar‐
              guments to [1mMT [22mand [1mUR [22mcalls visible in the document text produced
              by link‐capable drivers.

       [1m-rX[4m[22mp[24m   Number successors of page [4mp[24m as [4mp[24ma, [4mp[24mb, [4mp[24mc, and  so  forth.   The
              register  tracking the suffixed page letter uses format “a” (see
              the “.af” request in [4mgroff[24m(7)).  For example,  the  option  [1m-rX2[0m
              produces  the  following  page  numbers: 1, 2, 2a, 2b, ..., 2aa,
              2ab, and so on.

[1mFiles[0m
       [4m/usr/pkg/share/groff/1.23.0/tmac/an.tmac[0m
              Most [4mman[24m macros are defined in this file.  It also loads  exten‐
              sions from [4man-ext.tmac[24m (see below).

       [4m/usr/pkg/share/groff/1.23.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
              definitions,  taking advantage of the fact that pages using them
              must call [1m.TH [22mor [1m.Dd[22m, respectively, before any other macros.   A
              [4mman[24m program or 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.

       [4m/usr/pkg/share/groff/1.23.0/tmac/an-ext.tmac[0m
              Except  for [1m.SB[22m, definitions of macros described above as exten‐
              sions are contained in this file; in some cases, they  are  sim‐
              pler  versions  of definitions appearing in [4man.tmac[24m, and are ig‐
              nored if the formatter is GNU [4mtroff[24m.  They  are  written  to  be
              compatible  with  AT&T [4mtroff[24m and permissively licensed—not copy‐
              lefted.  To reduce the risk of name space collisions, string and
              register names begin only with “[1mm[22m”[1m.  [22mWe encourage man  page  au‐
              thors who are concerned about portability to legacy Unix systems
              to  copy  these definitions into their pages, and maintainers of
              [4mtroff[24m implementations or  work‐alike  systems  that  format  man
              pages to re‐use them.

              The  definitions  for  these  macros are read after a page calls
              [1m.TH[22m, so they will replace any macros of the same names preceding
              it in your file.  If you use your own implementations  of  these
              macros, they must be defined after [1m.TH [22mis called to have any ef‐
              fect.   Furthermore, it is wise to define such page‐local macros
              (if at all) after the “Name” section to accommodate timid  [4mmake‐[0m
              [4mwhatis[24m  or [4mmandb[24m implementations that may give up their scan for
              indexing material early.

       [4m/usr/pkg/share/groff/1.23.0/tmac/man.tmac[0m
              This is a wrapper that loads [4man.tmac[24m.

       [4m/usr/pkg/share/groff/1.23.0/tmac/mandoc.tmac[0m
              This is a wrapper that loads [4mandoc.tmac[24m.

       [4m/usr/pkg/share/groff/site-tmac/man.local[0m
              Put site‐local changes and customizations into this file.

                     .\" Use narrower indentation on terminals and similar.
                     .if n .nr IN 4n
                     .\" 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]>78n .nr LL 78n
                     .\" Ensure hyperlinks are enabled for terminals.
                     .nr U 1

              On multi‐user systems, it is more  considerate  to  users  whose
              preferences  may  differ from the administrator’s to be less ag‐
              gressive 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‐local file to manifest courtesy.
                     .soquiet \V[XDG_CONFIG_HOME]/man.local
                     .soquiet \V[HOME]/.man.local
              However, a security‐sandboxed [4mman[24m(1) program may lack permission
              to open such files.

[1mNotes[0m
       Some tips on troubleshooting your man pages follow.

       • Some ASCII characters look funny or copy and paste wrong.
              On devices with large glyph repertoires, like UTF‐8‐capable ter‐
              minals and PDF, several  keyboard  glyphs  are  mapped  to  code
              points  outside  the Unicode basic Latin range because that usu‐
              ally results in better typography in  the  general  case.   When
              documenting  GNU/Linux  command  or  C language syntax, however,
              this translation is sometimes not desirable.

              To get a “literal”...   ...should be input.
              ────────────────────────────────────────────
                                  [1m'   \(aq[0m
                                  [1m-   \-[0m
                                  [1m\   \(rs[0m
                                  [1m^   \(ha[0m
                                  [1m`   \(ga[0m
                                  [1m~   \(ti[0m
              ────────────────────────────────────────────

              Additionally, if a neutral double quote (") is needed in a macro
              argument, you can use [1m\(dq [22mto get it.  You should [4mnot[24m  use  [1m\(aq[0m
              for an ordinary apostrophe (as in “can’t”) or [1m\- [22mfor an ordinary
              hyphen  (as in “word‐aligned”).  Review subsection “Portability”
              above.

       • Do I ever need to use an empty macro argument ("")?
              Probably not.  When this seems necessary,  often  a  shorter  or
              clearer alternative is available.

                     Instead of...               ...should be considered.
              ────────────────────────────────────────────────────────────────
              [1m.TP ""                         .TP[0m
              ────────────────────────────────────────────────────────────────
              [1m.BI "" [4m[22mitalic‐text[24m [4mbold‐text[24m   [1m.IB [4m[22mitalic‐text[24m [4mbold‐text[0m
              ────────────────────────────────────────────────────────────────
              [1m.TH foo 1 "" "foo 1.2.3"       .TH foo 1 [4m[22myyyy[24m[1m‐[4m[22mmm[24m[1m‐[4m[22mdd[24m [1m"foo 1.2.3"[0m
              ────────────────────────────────────────────────────────────────
              [1m.IP "" 4n                      .IP[0m
              ────────────────────────────────────────────────────────────────
              [1m.IP "" 4n                      .RS 4n[0m
              [4mparagraph[24m                      [1m.P[0m
              ...                            [4mparagraph[0m
              ...                            [1m.RE[0m
              ────────────────────────────────────────────────────────────────
              [1m.B one two "" three            .B one two three[0m

              In the title heading ([1m.TH[22m), the date of the page’s last revision
              is  more  important than packaging information; it should not be
              omitted.  Ideally, a page maintainer will keep both up to date.

              [1m.IP [22mis sometimes ill‐understood and misused, especially when  no
              marker  argument  is supplied—an indentation argument is not re‐
              quired.  By setting an explicit indentation, you may be overrid‐
              ing 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)  paragraphs,  consider
              setting an inset region with [1m.RS [22mand [1m.RE [22minstead.

              In  the last example, the empty argument does have a subtly dif‐
              ferent effect than its suggested replacement: the empty argument
              causes an additional 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.

       • [1m.RS [22mdoesn’t indent relative to my indented paragraph.
              The [1m.RS [22mmacro sets the left margin; that  is,  the  position  at
              which  an  [4mordinary[24m paragraph ([1m.P [22mand its synonyms) will be set.
              [1m.IP[22m, [1m.TP[22m, and the deprecated [1m.HP [22muse the same  default  indenta‐
              tion.   If  not  given an argument, [1m.RS [22mmoves the left margin by
              this same amount.  To create an inset relative  to  an  indented
              paragraph,  call  [1m.RS [22mrepeatedly until an acceptable indentation
              is achieved, or give [1m.RS [22man  indentation  argument  that  is  at
              least  as much as the paragraph’s indentation amount relative to
              an adjacent [1m.P [22mparagraph.  See subsection “Horizontal and verti‐
              cal spacing” above for the values.

              Another approach you can use with tagged paragraphs is to  place
              an  [1m.RS [22mcall immediately after the paragraph tag; this will also
              force a break regardless of the width of the tag, which some au‐
              thors prefer.  Follow‐up paragraphs under the tag  can  then  be
              set  with [1m.P [22minstead of [1m.IP[22m.  Remember to use [1m.RE [22mto end the in‐
              dented region before starting the next tagged paragraph (at  the
              appropriate nesting level).

       • [1m.RE [22mdoesn’t move the inset back to the expected level.
       • warning: scaling unit invalid in context
       • warning: register 'an-saved-margin[4mn[24m' not defined
       • warning: register 'an-saved-prevailing-indent[4mn[24m' not defined
              The  [1m.RS  [22mmacro  takes an [4mindentation[24m [4mamount[24m as an argument; the
              [1m.RE [22mmacro’s argument is a specific [4minset[24m [4mlevel.[24m  [1m.RE 1  [22mgoes  to
              the  level  before any [1m.RS [22mmacros were called, [1m.RE 2 [22mgoes to the
              level of the first [1m.RS [22mcall you made, and so forth.  If you  de‐
              sire  symmetry in your macro calls, simply issue one [1m.RE [22mwithout
              an argument for each [1m.RS [22mthat precedes it.

              After calls to the [1m.SH [22mand [1m.SS [22msectioning macros,  all  relative
              insets  are cleared and calls to [1m.RE [22mhave no effect until [1m.RS [22mis
              used again.

       • Do I need to keep typing the indentation in a series of [1m.IP [22mcalls?
              Not if you don’t want to change it.  Review subsection “Horizon‐
              tal and vertical spacing” above.

                Instead of...     ...should be considered.
              ─────────────────────────────────────────────
              [1m.IP \(bu 4n         .IP \(bu 4n[0m
              [4mparagraph[24m           [4mparagraph[0m
              [1m.IP \(bu 4n         .IP \(bu[0m
              [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  “Com‐
              mand  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, however, 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 hypo‐
              thetical string [1mEL [22mthat  contained  an  ellipsis,  but  not  the
              trailing dummy character [1m\&[22m, would then need to be suffixed with
              the latter when not ending a sentence.

                  Instead of...              ...do this.
              ──────────────────────────────────────────────────
              [1m.ds EL \&.\|.\|.         Arguments are[0m
              [1mArguments are            .IR src‐file\~ .\|.\|.\&[0m
              [1m.IR src‐file\~ \*(EL\&   .IR dest‐dir .[0m
              [1m.IR dest‐dir .[0m
              ──────────────────────────────────────────────────

              The  first column practices a false economy; the savings in typ‐
              ing is offset by the cost of obscuring even the suggestion of an
              ellipsis to a casual reader of the source document, and  reduced
              portability  to  non‐[4mroff[24m man page formatters that cannot handle
              string definitions.

              There is an ellipsis code point in Unicode, and some fonts  have
              an  ellipsis glyph, which some man pages have accessed in a non‐
              portable way with the font‐dependent  [1m\N  [22mescape  sequence.   We
              discourage  the  use  of these; on terminals, they may crowd the
              dots into a half‐width character cell, and will  not  render  at
              all if the output device doesn’t have the glyph.  In syntax syn‐
              opses,  missing  ellipses  can  cause great confusion.  Dots and
              space are universally supported.

[1mAuthors[0m
       The initial GNU implementation of the [4mman[24m macro package was written  by
       James  Clark.   Later,  Werner Lemberg ⟨wl@gnu.org⟩ supplied the [1mS[22m, [1mLT[22m,
       and [1mcR [22mregisters, the last a 4.3BSD‐Reno [4mmdoc[24m(7) feature.  Larry Kollar
       ⟨kollar@alltel.net⟩ added the [1mFT[22m, [1mHY[22m, and [1mSN [22mregisters; the [1mHF  [22mstring;
       and  the  [1mPT  [22mand  [1mBT [22mmacros.  G. Branden Robinson ⟨g.branden.robinson@
       gmail.com⟩ implemented the [1mAD [22mand [1mMF [22mstrings; [1mCS[22m, [1mCT[22m, and [1mU  [22mregisters;
       and the [1mMR [22mmacro.  Except for [1m.SB[22m, the extension macros were written by
       Lemberg, Eric S. Raymond ⟨esr@thyrsus.com⟩, and Robinson.

       This document was originally written for the Debian GNU/Linux system by
       Susan  G.  Kleinmann ⟨sgk@debian.org⟩.  It was corrected and updated by
       Lemberg and Robinson.  The extension macros were documented by  Raymond
       and  Robinson.   Raymond  also  originated  the portability section, to
       which Ingo Schwarze ⟨schwarze@usta.de⟩ contributed most of the material
       on escape sequences.

[1mSee also[0m
       [4mgtbl[24m(1), [4mgeqn[24m(1), and [4mgrefer[24m(1) are preprocessors used with man  pages.
       [4mman[24m(1)  describes the man page librarian on your system.  [4mgroff_mdoc[24m(7)
       details the [4mgroff[24m version of the BSD‐originated alternative macro pack‐
       age for man pages.

       [4mgroff_man[24m(7), [4mgroff[24m(7), [4mgroff_char[24m(7), [4mman[24m(7)

groff 1.23.0                   30 December 2025             [4mgroff_man_style[24m(7)
───────────────────────────────────────────────────────────────────────────────
[4mgroff_mdoc[24m(7)           Miscellaneous Information Manual         [4mgroff_mdoc[24m(7)

[1mName[0m
       groff_mdoc — 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
       [4mgroff[24m(1)  document  formatting system.  [4mmdoc[24m is a structurally‐ and se‐
       mantically‐oriented  package  for  writing  Unix  manual   pages   with
       [4mgtroff[24m(1).   Its  predecessor,  the [4mman[24m(7) package, primarily addressed
       page layout and presentational concerns, leaving the selection of fonts
       and other typesetting details to the individual author.   This  discre‐
       tion has led to divergent styling practices 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 interpolate common noun phrases.  The [4mmanual[24m [4mdomain[24m offers seman‐
       tic macros corresponding 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, func‐
       tion 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 irrespective of the macro package selected for its composition.

[1mGetting started[0m
       The [4mmdoc[24m package attempts to simplify man page authorship  and  mainte‐
       nance  without  requiring  mastery of the [4mroff[24m language.  This document
       presents only essential facts about [4mroff.[24m For further  background,  in‐
       cluding  a  discussion of basic typographical concepts like “breaking”,
       “filling”, and “adjustment”, see [4mroff[24m(7).  Specialized  units  of  mea‐
       surement  also arise, namely ens, vees, inches, and points, abbreviated
       “n”, “v”, “i”, and “p”, respectively;  see  section  “Measurements”  of
       [4mgroff[24m(7).

       For  brief  examples, we employ an arrow notation illustrating a trans‐
       formation of input on the left to rendered output on the  right.   Con‐
       sider 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  docu‐
       ment,  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  charac‐
       ters  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 immediately 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, pre‐
       cede it with the ‘\&’ escape sequence; this is a dummy  character,  not
       formatted  for  output.  The backslash is the [4mroff[24m escape character; it
       can appear anywhere and it always followed by at least one more charac‐
       ter.  If followed by a newline, the backslash escapes  the  input  line
       break; you can thus keep input lines to a reasonable length without af‐
       fecting their interpretation.

       Macros  in  GNU  [4mtroff[24m accept an unlimited number of arguments, in con‐
       trast to other [4mtroff[24ms that often can’t handle more than nine.  In  lim‐
       ited  cases,  arguments  may be continued or extended on 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 argu‐
       ment lists for [4mcallable[24m macro names.  This means that  an  argument  in
       the  list  matching a general text or manual domain macro name (and de‐
       fined to be callable) will be called with the remaining arguments  when
       it is encountered.  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, macros whose argument lists are parsed for callable
       arguments are referred to as [4mparsed[24m, and those that may be called  from
       an  argument list are referred to as [4mcallable[24m.  This usage is a techni‐
       cal [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 argu‐
       ments 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
       arguments  that  are  to  be  treated  the same makes [4mmdoc[24m work faster;
       macros that parse arguments do so once (at most) for each.   For  exam‐
       ple, 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 standards mandate the inclusion of types [4mand[24m identi‐
       fiers in the parameter lists of function definitions, each ‘Fn’ parame‐
       ter after the first will be at least two words in length,  as  in  “[4mint[0m
       [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 charac‐
       ter, 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  draw‐
       back:  this  space does not adjust as others do when the output line is
       formatted.  An alternative is to use the unbreakable space  escape  se‐
       quence, ‘\~’, which cannot break but does adjust.  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 glyph[0m
       When you need the [4mroff[24m escape character ‘\’ to appear  in  the  output,
       use  ‘\e’ or ‘\(rs’ instead.  Technically, ‘\e’ formats the current es‐
       cape character; 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[0m
       special  character escape sequence that explicitly formats the “reverse
       solidus” (backslash) glyph.

   [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 requests 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 format it.  Further, this glyph should not be used  for  con‐
       ventional quotation; [4mmdoc[24m offers several quotation macros.  See subsec‐
       tion “Enclosure and quoting macros” below.

       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 [4mroff[24m(7).  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[0m
       handles punctuation characters specially in macro arguments.  This will
       be explained in section “General syntax” below.

       A  comment in the source file of a man page can begin with ‘[1m.\"[22m’ at the
       start of an input line, ‘[1m\"[22m’ after other input, or ‘[1m\#[22m’  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 topic [section‐identifier [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  dis‐
       cussed  in  section  “Page  structure  domain”,  which  follows section
       “Manual domain”.  Familiarize yourself with manual domain macros first;
       we use them to illustrate the use of page structure domain macros.

[1mConventions[0m
       In the descriptions of macros below, square brackets surround  optional
       arguments.   An ellipsis (‘...’) represents repetition of the preceding
       argument 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 op‐
       eration modes, particularly if the list of valid optional arguments  is
       dependent 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 new‐
       line 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 emit‐
       ted for many commands 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 measure‐
       ments, you escape potential conflicts with site‐local modifications  of
       the [4mmdoc[24m 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 designate the topic, date of last revision, and the operating sys‐
       tem  or  software  project associated with the page.  Call each once at
       the beginning of the document.  They  populate  the  page  headers  and
       footers, which are in [4mroff[24m parlance termed “titles”.

       [1m.Dd [4m[22mdate[0m
               This  first macro of any [4mmdoc[24m manual records the last modifica‐
               tion date of the document source.  Arguments  are  concatenated
               and separated with space characters.

               Historically,  [4mdate[24m  was  written  in  U.S. traditional format,
               “[4mMonth[24m [4mday[24m , [4myear[24m” where [4mMonth[24m is the full month name  in  Eng‐
               lish, [4mday[24m an integer without a leading zero, and [4myear[24m the four‐
               digit  year.   This localism is not enforced, however.  You may
               prefer  ISO  8601  format,  [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[22mtopic[24m [[4msection‐identifier[24m [[4msection‐keyword‐or‐title[24m]]
               [4mtopic[24m  is  the  subject  of the man page.  A [4msection‐identifier[0m
               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 sec‐
               tion 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
               integral 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 abbre‐
               viations.

                     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  com‐
               puter  architecture  recognized  by  [4mgroff[24m  [4mmdoc[24m,  its value is
               prepended to the default section title as specified by the sec‐
               ond parameter.  By default, 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 con‐
               tent are shown below.  Observe how ‘\&’ prevents the numeral  2
               from being 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 identi‐
               fiers.  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 distribu‐
               tion.  When composing a man page to be included in the base in‐
               stallation of an operating system, do not provide an  argument;
               [4mmdoc[24m  will  supply 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  nomencla‐
               ture  for the software specified.  In the following table, rec‐
               ognized [4mversion‐or‐release[24m arguments for some predefined  oper‐
               ating 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  diagnostic emitted.  Otherwise, unrecognized arguments
               are displayed verbatim in the page footer.  For instance,  this
               page  uses  “[1m.Os  groff 1.23.0[22m” whereas a locally produced page
               might employ “[1m.Os "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
       language  used  to  describe  commands,  subroutines and related files.
       Slightly different variations of this language are used to describe the
       three different aspects of writing a man page.  First, there is the de‐
       scription of [4mmdoc[24m macro command usage.  Second is the description of  a
       Unix  command [4mwith[24m [4mmdoc[24m macros, and third, the description of a command
       to a user in the verbal sense; that is, discussion of a command in  the
       text of a man page.

       In  the first case, [4mgtroff[24m macros are themselves a type of command; the
       general syntax for a [4mtroff[24m command is:

             [1m.Xx argument1 argument2 ...[0m

       ‘.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[24m argument designated as optional by the option brackets.   In  [4mmdoc[0m
       terms,  ⟨[4minfile[24m⟩ and ⟨[4moutfile[24m⟩ are called [4mmeta[24m [4marguments[24m; in this exam‐
       ple, the user has to replace the meta expressions given in angle brack‐
       ets with real file names.  Note that in this  document  meta  arguments
       are  used  to describe [4mmdoc[24m commands; in most man pages, meta variables
       are not specifically written with angle brackets.  The macros that for‐
       matted 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[0m
       or [4mfile[24m [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 confu‐
       sion, however the [4mmdoc[24m package does not have a macro for an argument [4mto[0m
       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 command 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 white space:

             [1m.Ar sptr , ptr ) ,[0m

       The result is:

             [4msptr[24m, [4mptr[24m),

       The punctuation is now recognized and output in the default  font  dis‐
       tinguishing  it from the argument strings.  To remove the special mean‐
       ing 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
       character 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 accidental evaluation of these characters, escape them  with  ‘\&’.
       Typical  syntax is shown in the first manual domain macro displayed be‐
       low, ‘.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 [4m...[24m’ is output.  This places the el‐
       lipsis  in italics, which is ugly and incorrect, and will be noticed on
       terminals that underline text instead of using an oblique typeface.  We
       recommend using ‘.Ar file No ...’ instead.

             [1mUsage: .Ar [22m[⟨argument⟩] ...

                      [1m.Ar              [4m[22mfile[24m [4m...[0m
                      [1m.Ar file No ...  [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 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 [4mconfig[24m(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
       exception that the ‘.Cm’ macro does not assert a dash in front of every
       argument.   Traditionally  flags are marked by the preceding dash, how‐
       ever, some commands or subsets of commands do not  use  them.   Command
       modifiers  may  also  be specified in conjunction with interactive com‐
       mands 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  speci‐
       fied 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 sec‐
       tion two manual 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        [22mDISPLAY
                      [1m.Ev PATH .         [22mPATH.
                      [1m.Ev PRINTER ) ) ,  [22mPRINTER)),

       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
       already  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 en‐
       closed 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 any‐
       where 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 sections two and three.  (It causes a break, allowing the
       function name to appear 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’
       (function  open)  and  ‘.Fc’  (function  close)  may be used with ‘.Fa’
       (function argument).

       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 delcaration 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,  respec‐
       tively.

   [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; other‐
             wise the value -1 is returned and the global variable [4merrno[24m is
             set to indicate the error.

       The [1m-std [22moption is valid only for manual page sections 2 and  3.   Cur‐
       rently, 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.
       Currently, 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 func‐
       tion 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
                            decryption (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 sec‐
       tion “Files” below.

       In a section titled “Library”, ‘Lb’ causes a break before and after its
       arguments.

   [1mLiterals[0m
       The  ‘Li’  literal  macro  may be used for special characters, symbolic
       constants, and other syntactical items that should be typed exactly  as
       displayed.

             [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 ...[0m

       The default width is 16n.

   [1mNames[0m
       The  ‘Nm’ macro is used for the document title or page topic.  Upon its
       first call, it has the peculiarity of remembering its  argument,  which
       should  always  be the topic of the man page.  When subsequently called
       without arguments, ‘Nm’ regurgitates this initial  name  for  the  sole
       purpose of making less work for the author.  Use of ‘Nm’ is also appro‐
       priate  when  presenting a command synopsis for the topic of a man page
       in section 1, 6, or 8.  Its behavior changes when presented with  argu‐
       ments 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 impor‐
       tance in the discussion.  Cross references to  other  man  page  topics
       should use ‘Xr’; including a second argument for the section number en‐
       ables  them to be hyperlinked.  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,  respec‐
       tively.

   [1mPathnames[0m
       The  ‘.Pa’  macro formats file specifications.  If called without argu‐
       ments, ‘[4m~[24m’ (recognized by many  shells)  is  output,  representing  the
       user’s home directory.

             [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”)

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

       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 sec‐
       tion titled “Synopsis”, ‘Vt’ causes a break  (useful  for  old‐style  C
       variable declarations).

             [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  sec‐
       tion), 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      [4m[22mmdoc[24m(7)
                      [1m.Xr xinit 1x ;  [4m[22mxinit[24m(1x);

       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’  com‐
       mand 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’ com‐
       mand 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’  com‐
       mand 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 ...[0m

                      [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 en‐
                             tire block of text.
             [1mLi [22m| [1m-literal   [22mSame as if the ‘.Li’ macro was used for  the  en‐
                             tire block of text.
             [1mSy [22m| [1m-symbolic  [22mSame  as  if the ‘.Sy’ macro was used for the en‐
                             tire 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
       enclose 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 irregu‐
       larities.  For each enclosure macro, there is a  pair  of  opening  and
       closing  macros that end with the lowercase letters ‘o’ and ‘c’ respec‐
       tively.

       [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 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[0m
                 program, [4mmdoc[24m supports two other macros that  are  now  obso‐
                 lete.   ‘.Es’ uses its first and second parameters as opening
                 and closing marks which are then used to  enclose  the  argu‐
                 ments  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 enclosed.

       [1m.Ql       [22mThe quoted literal macro behaves  differently  in  [4mtroff[24m  and
                 [4mnroff[24m  modes.   If formatted with [4mgnroff[24m(1), a quoted literal
                 is always quoted.  If formatted with [4mgtroff[24m, an item is  only
                 quoted  if the width of the item is less than three constant‐
                 width characters.  This is to make short strings more visible
                 where the font change to literal (constant‐width) is less no‐
                 ticeable.

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

       [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 argu‐
       ment 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 po‐
       sition  and  its  first  parameter.   For example, it is useful for old
       style argument lists where there is no space between the flag and argu‐
       ment:

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

             [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
       [4mgrefer[24m(1) style references.

             [1m.Rs     [22mReference start (does not take arguments).  In a  section
                     titled  “See  also”, it causes a break and begins collec‐
                     tion 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  argu‐
       ments  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 outside 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,
             Technical 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
       implemented similarly to all other macros opening and closing an enclo‐
       sure (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
       variable.

             .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 author 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  speci‐
                          fied,  headers,  footers,  and  page layout defaults
                          will not be set and things will be  rather  unpleas‐
                          ant.   The  [4mName[24m  section 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 de‐
                          scription 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  either  ‘.Nm’,  ‘.Cd’,  or  ‘.Fn’ (and possibly
                          ‘.Fo’, ‘.Fc’, ‘.Fd’, and ‘.Ft’).  The function  name
                          macro  ‘.Fn’  is required 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’ configura‐
                          tion 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”
                          section  is  a brief paragraph on the command, func‐
                          tion or file, followed by a lexical list of  options
                          and respective 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 sec‐
                          tion 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
                          environment  variables  and  clues to their behavior
                          and/or usage.

       [1m.Sh Files          [22mFiles which are used or created by the man page sub‐
                          ject should be listed via the  ‘.Pa’  macro  in  the
                          “Files” section.

       [1m.Sh Examples       [22mThere are several ways to create examples.  See sub‐
                          section “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 section 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
                          functions  (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  [4mgrefer[24m(1) style references are not accom‐
                          modated.

                          It is  recommended  that  the  cross  references  be
                          sorted  by  section  number,  then alphabetically by
                          name within each section, then separated by  commas.
                          Example:

                          [4mls[24m(1), [4mps[24m(1), [4mgroup[24m(5), [4mpasswd[24m(5)

       [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 ad‐
                          here to any standard, its history should be noted in
                          the [4mHistory[24m section.

       [1m.Sh History        [22mAny command which does not adhere  to  any  specific
                          standards  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 optional contact information.  Explicitly in‐
                          dicate whether the person authored the initial  man‐
                          ual  page  or the software 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 argu‐
       ment 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 pre‐
       vents breaks in the middle of options.  In the example  for  [1mmake  [22mcom‐
       mand‐line  arguments (see “What’s in a Name”), the keep prevents [4mgnroff[0m
       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[0m
       option 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 the right margin  (only
                               left‐justify).
            [1m-centered          [22mCenter lines between the current left and right
                               margin.   Note  that  each  single line is cen‐
                               tered.
            [1m-unfilled          [22mDo not fill;  break  lines  where  their  input
                               lines  are  broken.   This can produce overlong
                               lines without warning messages.
            [1m-filled            [22mDisplay a filled block.  The block of  text  is
                               formatted  (i.e., the text is justified on both
                               the left and right side).
            [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 dis‐
                               play type.  Any  [4mgtroff/mdoc[24m  commands  in  the
                               file will be processed.
            [1m-offset [22m⟨[4mstring[24m⟩   If [1m-offset [22mis specified with one of the follow‐
                               ing strings, the string is interpreted to indi‐
                               cate the level of indentation for the forthcom‐
                               ing 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 displays will line
                                           up.   The indentation value is nor‐
                                           mally 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 [4mgtroff[24m.

                               If  ⟨string⟩  is a valid numeric expression in‐
                               stead ([4mwith[24m  [4ma[24m  [4mscaling[24m  [4mindicator[24m  [4mother[24m  [4mthan[0m
                               ‘[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 ⟨string⟩ isn’t a numeric
                               expression, it is tested whether it is an  [4mmdoc[0m
                               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  off‐
                               set.
            [1m-compact           [22mSuppress insertion of vertical space before be‐
                               gin 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’
       begin‐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  in‐
       side 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
                (starting 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 ref‐
                            erences 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‐
                            positive 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  simi‐
                lar  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 un‐
                              like 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 manu‐
                      als.  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 con‐
                      strained.

                      [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 ar‐
                guments 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, interpret ⟨[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 [4mgtbl[24m(1), the table pre‐
                processor.

       Other keywords:

       [1m-width [22m⟨[4mstring[24m⟩   If ⟨[4mstring[24m⟩ starts with a ‘.’ (dot) immediately  fol‐
                         lowed  by a valid [4mmdoc[24m macro name, interpret ⟨[4mstring[24m⟩
                         and use the width of the result.  Almost all lists in
                         this document 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;  afterwards,  all  variables
                         are  restored again.  However, boxes (used for enclo‐
                         sures) can’t be saved in GNU [4mgtroff[24m(1); as  a  conse‐
                         quence,  arguments  must  always be [4mbalanced[24m to avoid
                         nasty errors.  For example,  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 indi‐
                         cators are ‘m’ and ‘n’, specifying the  so‐called  [4mEm[0m
                         and  [4mEn[24m  [4msquare[24m.   This is approximately the width of
                         the letters ‘m’ and ‘n’ respectively of  the  current
                         font (for [4mgnroff[24m output, both scaling indicators give
                         the  same  values).   If ⟨[4mstring[24m⟩ isn’t a numeric ex‐
                         pression, it is tested whether it is  an  [4mmdoc[24m  macro
                         name,  and  the  default  width 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 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 (nor‐
                         mally set to 6n, similar to the value used  in  ‘.Dl’
                         or  ‘.Bd’)  is  used.  If ⟨[4mstring[24m⟩ is a valid numeric
                         expression instead ([4mwith[24m [4ma[24m  [4mscaling[24m  [4mindicator[24m  [4mother[0m
                         [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  approxi‐
                         mately  the  width of the letters ‘m’ and ‘n’ respec‐
                         tively 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
                         offset value associated with this macro is used.  Fi‐
                         nally, 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 [4mgroff@gnu.org[24m and include a speci‐
       men with its provenance.

       [1m.Bt  [22mformats boilerplate text.

                  [1m.Bt  [22m→ is currently in beta test.

            It is neither callable nor parsed and takes no arguments.  Its de‐
            fault 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  sin‐
            gle digit) which is bad typographical behaviour.  Instead, set the
            return  value with the rest of the code, using ‘\~’ to tie the re‐
            turn 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  con‐
            tents of [4mfile[24m.  It is neither callable nor parsed.

       [1m.Lk  [22mEmbed hyperlink.

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

            Its default width is 6n.

       [1m.Mt  [22mEmbed email address.

                  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 para‐
            meter 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 de‐
            fault 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 [4mgroff_char[24m(7)  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   NaN      not a number
       \*(Ba    |         |         |     |        bar

       Some  column  headings  are shorthand for standardized character encod‐
       ings; “7‐bit” for ISO 646:1991 IRV (US‐ASCII), “8‐bit” for  ISO  8859‐1
       (Latin‐1)  and  IBM  code  page  1047, and “UCS” for ISO 10646 (Unicode
       character set).  Historically, [4mmdoc[24m configured the  string  definitions
       to fit the capabilities expected of the output 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  re‐
       sponsibility  of glyph substitution, as they possess relevant knowledge
       of their available repertoires.

[1mDiagnostics[0m
       The debugging macro ‘.Db’ offered by previous versions of [4mmdoc[24m  is  un‐
       available  in GNU [4mgtroff[24m(1) since the latter provides better facilities
       to check parameters; additionally, [4mgroff[24m [4mmdoc[24m implements many error and
       warning messages, 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
       consistent  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 de‐
       fault), or ‘l’ for left alignment (ragged right margin).  Any valid ar‐
       gument to [4mgroff[24m’s ‘ad’ request may be used.  See [4mgroff[24m(7) for less‐com‐
       mon 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 [4mgroff[24m(1).
             [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 (de‐
       fined with ‘.Dt’) can be presented in full capitals by setting the reg‐
       isters ‘CS’ and ‘CT’, respectively, to 1.   These  transformations  are
       off by default because 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 num‐
       ber at the bottom right on odd‐numbered (recto) pages, and at the  bot‐
       tom left on even‐numbered (verso) pages, swapping places with the argu‐
       ments 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  render‐
       ing is enabled.  The default is -0.5i.

       The ‘HF’ string sets the font used for section and subsection headings;
       the default is ‘B’ (bold style of the default family).  Any valid argu‐
       ment 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 [4mgroff[24m(7).   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 ‘IN’ and ‘SN’.
             [1mgroff -Tutf8 -rIN=5n -rSN=2n -mdoc foo.man [22m| [1mless -R[0m
       The default paragraph indentation is 7.2n on typesetters and 7n on ter‐
       minals.   The default subsection heading indentation amount is 3n; sec‐
       tion 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 78n for terminal devices and 6.5i
       otherwise.

       Setting the ‘P’ register starts enumeration of pages at its value.  The
       default is 1.

       To change the document font size to 11p or 12p, set  register  ‘S’  ac‐
       cordingly:
             [1mgroff -Tdvi -rS11 -mdoc foo.man > foo.dvi[0m
       Register ‘S’ is ignored when formatting for terminal devices.

       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 let‐
       ter uses format ‘a’ (see the ‘af’ request in [4mgroff[24m(7)).

[1mFiles[0m
       [4m/usr/pkg/share/groff/1.23.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
               definitions, taking advantage of the fact that pages using them
               must  call  [1mTH [22mor [1mDd[22m, respectively, before any other macros.  A
               user typing, 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/pkg/share/groff/1.23.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/pkg/share/groff/1.23.0/tmac/mdoc.tmac[0m
               is a wrapper that loads [4mdoc.tmac[24m.

       [4m/usr/pkg/share/groff/1.23.0/tmac/mdoc/doc-common[0m
               defines  macros, registers, and strings concerned with the pro‐
               duction of formatted output.  It includes strings of  the  form
               ‘doc-volume-ds-[4mX[24m’  and ‘doc-volume-as-[4mX[24m’ for manual section ti‐
               tles and architecture identifiers, respectively, where [4mX[24m is  an
               argument recognized by .[1mDt[22m.

       [4m/usr/pkg/share/groff/1.23.0/tmac/mdoc/doc-nroff[0m
               defines  parameters  appropriate  for rendering to terminal de‐
               vices.

       [4m/usr/pkg/share/groff/1.23.0/tmac/mdoc/doc-ditroff[0m
               defines parameters appropriate for rendering to typesetter  de‐
               vices.

       [4m/usr/pkg/share/groff/1.23.0/tmac/mdoc/doc-syms[0m
               defines  many  strings  and  macros  that interpolate formatted
               text, such as names of  operating  system  releases,  *BSD  li‐
               braries,  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  operating  system  release  (sometimes  omitted
               along  with  the ‘-’ preceding it), [4mS[24m an identifier for a stan‐
               dards body or committee, [4mI[24m one for an issue of a standard  pro‐
               mulgated by [4mS[24m, and [4mL[24m a keyword identifying a *BSD library.

       [4m/usr/pkg/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 [4mmandoc[24m: https://mandoc.bsd.lv/ project maintains an independent im‐
       plementation of the [4mmdoc[24m language and a renderer that  directly  parses
       its markup as well as that of [4mman[24m.

       [4mgroff[24m(1), [4mman[24m(1), [4mgtroff[24m(1), [4mgroff_man[24m(7), [4mmdoc[24m(7)

[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 sometimes 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 function‐
       ality may return in the next release.

groff 1.23.0                      2 July 2023                    [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[0m
       document  formatting  system.   The [4mme[24m package of macro definitions for
       the [4mroff[24m language provides a convenient facility for preparing  techni‐
       cal  papers  in  various formats.  This version is based on the [4mme[24m dis‐
       tributed 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
       conjunction with this package; however, the following may be used  with
       impunity  after  the  first call to a paragraphing macro like [1mlp [22mor [1mpp[22m.
       Some arguments are optional; see [4mgroff[24m(7) for details, particularly  of
       requests whose argument list is designated with an ellipsis.  An aster‐
       isk [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 output 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 [22mfalse
       [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 output 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 output lines

       Except  on title pages (produced by calling [1mtp[22m), [4mme[24m suppresses the out‐
       put of vertical space at the tops of pages (after  the  output  of  any
       page header); the [1msp [22mrequest will thus not work there.  You can instead
       call  [1mbl [22mor enclose the desired spacing request in a diversion, for in‐
       stance by calling [1m(b [22mand [1m)b[22m.  [4mme[24m also intercepts the  [1mll  [22mrequest;  see
       the “[4mme[24m Reference Manual” 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 repurposed.

   [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 [4mgeqn[24m equation
       [1mEQ   [22mbegin [4mgeqn[24m equation
       [1mGE   [22mend [4mggrn[24m picture with drawing position at bottom
       [1mGF   [22mend [4mggrn[24m picture with drawing position at top
       [1mGS   [22mstart [4mggrn[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 [4mgpic[24m picture with drawing position at bottom
       [1mPF   [22mend [4mgpic[24m picture with drawing position at top
       [1mPS   [22mstart [4mgpic[24m picture
       [1mTE   [22mend [4mgtbl[24m table
       [1mTH   [22mend heading for multi‐page [4mgtbl[24m table
       [1mTS   [22mstart [4mgtbl[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 (local)
       [1mxp   [22moutput index

       Some macros are provided for “old” [4mroff[24m(1) compatibility.  The “[4mme[24m Ref‐
       erence 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   [22mconcatenated 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/pkg/share/groff/1.23.0/tmac/e.tmac[0m
              implements the package.

       [4m/usr/pkg/share/groff/1.23.0/tmac/refer-me.tmac[0m
              implements [4mgrefer[24m(1) support for [4mme[24m.

       [4m/usr/pkg/share/groff/1.23.0/tmac/me.tmac[0m
              is  a  wrapper  enabling the package to be loaded with “[1mgroff -m[0m
              [1mme[22m”.

[1mNotes[0m
       Early [4mroff[24m macro packages often limited their names to a single letter,
       which followed the formatter’s [1mm [22mflag letter, resulting in [4mmm[24m, [4mms[24m,  [4mmv[24m,
       [4mmn[24m,  and so on.  The “e” in “me” stands for “Eric P. Allman”, who wrote
       the macro package and the  original  technical  papers  documenting  it
       while an undergraduate at the University of California.

[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/pkg/share/doc/groff-1.23.0/meintro.me[0m
       [4m/usr/pkg/share/doc/groff-1.23.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/pkg/share/doc/groff-1.23.0/meref.me[0m
       [4m/usr/pkg/share/doc/groff-1.23.0/meref.ps[0m
              is the “[4mme[24m Reference Manual”, by Eric  P.  Allman,  adapted  for
              [4mgroff[24m 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
       Lemberg, is the primary [4mgroff[24m manual.  You can browse it  interactively
       with “info groff”.

       For  preprocessors  supported  by  [4mme[24m,  see  [4mgeqn[24m(1), [4mggrn[24m(1), [4mgpic[24m(1),
       [4mgrefer[24m(1), and [4mgtbl[24m(1).

       [4mgroff[24m(1), [4mgtroff[24m(1), [4mgroff[24m(7)

groff 1.23.0                      2 July 2023                      [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 GNU implementation of the [4mmm[24m macro package is  part  of  the  [4mgroff[0m
       document  formatting system.  The [4mmm[24m package is suitable for the compo‐
       sition of letters, memoranda, reports, and books.

       Call an [4mmm[24m macro at the beginning of a document to initialize the pack‐
       age.  A simple [4mmm[24m document might use only [1mP [22mfor paragraphing.  Set num‐
       bered 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 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.  Cus‐
       tomized list arrangements are supported by [1mLB[22m.  [1mDS [22mand [1mDF [22mstart  static
       and floating displays, respectively; either is terminated with [1mDE[22m.

       [4mgroff[24m  [4mmm[24m is intended to be compatible with the [4mmm[24m implementation found
       in the AT&T Documenter’s Workbench (DWB), with  the  following  limita‐
       tions.

       • Omitted  features  include  the logo and company name strings, [1m}Z [22mand
         [1m]S[22m, respectively; the encoded company site location addresses  recog‐
         nized  as the third argument to the [1mAU [22mmacro; the [1mPv [22m(“private” head‐
         ing) register; and the [1mOK [22m(other keywords), and [1mPM [22m(proprietary mark‐
         ings) macros.

       • The [1mCS [22m(output cover sheet) macro is implemented only for  memorandum
         type 4.

       • The  [4mgrap[24m  preprocessor  is  not  explicitly  supported; no [1mG1 [22mand [1mG2[0m
         macros are defined.

       • The registers [1mA[22m, [1mC[22m, [1mE[22m, [1mT[22m, and [1mU[22m, typically  set  from  the  [4mtroff[24m  or
         [4mnroff[24m command lines with DWB [4mmm[24m, are not recognized.

       • When  setting  the registers [1mL [22mor [1mW [22mfrom the command line, use an ex‐
         plicit scaling unit to avoid surprises.

       • DWB [4mmm[24m’s [1mnP [22mmacro indented the second line of a paragraph to align it
         with the start of the text of the first (after the paragraph number);
         [4mgroff[24m [4mmm[24m’s does not.

       • Cut marks are not supported.

       DWB [4mmm[24m supported only seven levels of heading.  As a compatible  exten‐
       sion,  [4mgroff[24m [4mmm[24m supports fourteen, introducing new registers [1mH8 [22mthrough
       [1mH14[22m, and affecting the interpretation of the [1mHF [22mand [1mHP [22mstrings.

       Macro, register, and string descriptions in this page  frequently  men‐
       tion each other; most cross references are to macros.  Where a register
       or string is referenced, its type is explicitly identified.  [4mmm[24m’s macro
       names  are usually in full capitals; registers and strings tend to have
       mixed‐case names.

   [1mDocument styles[0m
       [4mgroff[24m [4mmm[24m offers three different frameworks for  document  organization.
       [1mCOVER[22m/[1mCOVEND  [22mis a flexible means of preparing any document requiring a
       cover page.  [1mLT[22m/[1mLO [22maids preparation of  typical  Anglophone  correspon‐
       dence  (business  letters, for example).  The [1mMT [22mmemorandum type mecha‐
       nism implements a group of formal styles historically used by AT&T Bell
       Laboratories.  Your document can  select  at  most  one  of  these  ap‐
       proaches; when used, each disables the others.

   [1mLocalization[0m
       [4mgroff[24m  [4mmm[24m is designed to be easily localized.  For languages other than
       English, strings that can appear in output are collected  in  the  file
       [4m/usr/pkg/share/groff/1.23.0/tmac/[24mxx[4m.tmac[24m,  where  [4mxx[24m is an ISO 639 two‐
       letter language identifier.  Localization packages should be loaded af‐
       ter [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/pkg/share/groff/1.23.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/pkg/share/groff/1.23.0/tmac/mm/[24mterritory[4m_locale[24m  to  be  loaded at
       package   initialization.    If   this   mechanism   is    not    used,
       [4m/usr/pkg/share/groff/1.23.0/tmac/mm/locale[24m is loaded instead.  No diag‐
       nostic is produced if these files do not exist.

   [1mRegisters and strings[0m
       Much  [4mmm[24m behavior can be configured by registers and strings.  A regis‐
       ter is assigned with the [1mnr [22mrequest.

              [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.
       [4mn[24m can be prefixed with a plus or minus sign if incrementation or decre‐
       mentation  (respectively)  of the register’s existing value by [4mn[24m is de‐
       sired.  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 specified,
       the register is automatically modified by [4mi[24m prior to interpolation 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 in‐
       terpolation escape sequence.

       Strings are defined 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 sequence ([1m\"[22m) so that extraneous spaces do  not  intrude  during
       document maintenance.  To include leading spaces in [4mcontents[24m, prefix it
       with  a  double quote.  Strings are interpolated with the [1m\* [22mescape se‐
       quence.

              [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[0m
       macro is not supported and may cause incorrect rendering, the  emission
       of diagnostic messages, and an error exit status from [4mgtroff[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 [22mre‐
       quest.

              [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
       In  [4mgroff[24m [4mmm[24m, the fonts (or rather, 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.
       Internally, font positions are used for backward compatibility.  From a
       practical  point  of view, it doesn’t make a big difference—a different
       font family can still be selected by invoking [4mgroff[24m’s  [1mfam  [22mrequest  or
       using  its  [1m-f  [22mcommand‐line option.  On the other hand, if you want to
       replace just, for example, font [1mI  [22mwith  Zapf  Chancery  Medium  italic
       (available  on  [4mgroff[24m’s [1mpdf [22mand [1mps [22moutput devices), you have to use the
       [1mfp [22mrequest, replacing the font at position 2 with “[1m.fp 2  ZCMI[22m”).   Be‐
       cause  the  cover  sheet,  memorandum  type,  and [4mgrefer[24m(1) integration
       macros explicitly request fonts named [1mB[22m, [1mI[22m, and [1mR[22m, you will  also  need
       to  remap  these  font  names  with  the [1mftr [22mrequest, for instance with
       “[1m.ftr I ZCMI[22m”.

[1mMacros[0m
       An explicitly empty argument may be specified with  a  pair  of  double
       quotes;  to call a macro [1mXX [22mwith an empty second argument but non‐empty
       first and third ones, you could input the following.

              .XX foo "" baz

       Macro names longer than two characters are GNU extensions; some shorter
       names were not part of DWB [4mmm[24m’s published interface but are  documented
       aspects of [4mgroff[24m [4mmm.[0m

       [1m)E [4m[22mlevel[24m [4mtext[0m
              Add heading text [4mtext[24m to the table of contents with [4mlevel[24m, which
              is  either  0 or in the range 1 to 7.  See also [1mH[22m.  This undocu‐
              mented DWB [4mmm[24m macro is exposed by [4mgroff[24m [4mmm[24m to enable  customized
              tables of contents.

       [1m1C [22m[[1m1[22m] Format  page text in one column.  The page is broken.  A [1m1 [22margu‐
              ment 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 [22mand [1mNCOL[22m.

       [1mAE     [22mAbstract end; stop collecting abstract text.  See [1mAS[22m.

       [1mAF [22m[[4mfirm‐name[24m]
              Specify  firm  associated with the document.  At most one can be
              declared; the firm name is used by memorandum types  and  avail‐
              able  to  cover  sheets.  [1mAF [22mterminates a document title started
              with [1mTL[22m, and can be called without an argument for that purpose.
              See [1mMT [22mand [1mCOVER[22m.

       [1mAL [22m[[4mtype[24m [[4mtext‐indent[24m [[1m1[22m]]]
              Begin an auto‐incrementing numbered list.  Item numbers start at
              one.  The [4mtype[24m argument assigns the register format (see  above)
              of  the list item enumerators.  The default is [1m1[22m.  An explicitly
              empty [4mtype[24m also indicates the default.  A  [4mtext‐indent[24m  argument
              overrides  register  [1mLi[22m.   A third argument suppresses the blank
              line that normally precedes each list item.  Use [1mLI  [22mto  declare
              list items, and [1mLE [22mto end the list.

       [1mAPP [22m[[4mid[24m [[4mtitle[24m]]
              Begin  an  appendix.  If the identifier [4mid[24m is omitted, it is in‐
              cremented (or initialized, if necessary).  The  register  format
              used  for  [4mid[24m is “A”.  The page is broken.  The register [1mAph [22mde‐
              termines whether an appendix heading is  then  formatted.   This
              heading  uses  the string [1mApp [22mfollowed by [4mid[24m.  Appendices appear
              in any table of contents (see [1mTC[22m).  The string [1mApptxt [22mis set  to
              [4mtitle[24m if the latter is present, and made empty otherwise.

       [1mAPPSK [4m[22mid[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
              [4mgtroff[24m are included in appendices.

       [1mAS [22m[[4mplacement[24m [[4mindentation[24m]]
              Abstract start; begin collecting abstract.  Input up to the next
              [1mAE  [22mcall  is included in the abstract.  [4mplacement[24m influences the
              location of the abstract on the cover sheet of a memorandum (see
              [1mMT[22m).  [1mCOVER[22m, by contrast, ignores [4mplacement[24m by default, but  can
              be customized to interpret it.

              [4m[1mplacement[24m   Effect[0m
              0           The  abstract  appears  on page 1 and cover sheet if
                          the document is a “released paper” memorandum  (“[1m.MT[0m
                          [1m4[22m”); otherwise, it appears on page 1 without a cover
                          sheet.
              1           The  abstract  appears only on the cover sheet (“[1m.MT[0m
                          [1m4[22m” only).

              An abstract does not appear at all  in  external  letters  (“[1m.MT[0m
              [1m5[22m”).   A  [4mplacement[24m  of  [1m2 [22mwas supported by DWB [4mmm[24m but is not by
              [4mgroff[24m [4mmm[24m.

              A second argument increases the indentation by  [4mindentation[24m  and
              reduces the line length by twice this amount.  A scaling unit of
              ens is assumed.  The default is 0.

       [1mAST [22m[[4mcaption[24m]
              Set  the  caption  above the abstract to [4mcaption[24m, or clear it if
              there is no argument.  The default is “ABSTRACT”.

       [1mAT [4m[22mtitle[24m ...
              Specify author’s title(s).  If present, [1mAT [22mmust appear just  af‐
              ter  the corresponding author’s [1mAU[22m.  Each [4mtitle[24m occupies an out‐
              put line beneath the author’s name in the signature  block  used
              by  [1mLT [22mletters (see [1mSG[22m) and in [1mMT [22mmemoranda.  The [1mms [22mcover sheet
              style also uses it.

       [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
              information is used by cover sheets, [1mMT [22mmemoranda, and [1mSG[22m.  Fur‐
              ther  arguments  comprise  initials, location, department, tele‐
              phone extension, room number or name, and up to three additional
              items.  Repeat [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 [22mbeneath them.  Above these rules, the text
              in the string [1mLetapp [22mis formatted; a  second  argument  replaces
              this text with a blank line.  See [1mLT[22m.

       [1mAVL [22m[[4mname[24m]
              As [1mAV[22m, but the date, date rule, and approval notation [1mLetapp [22mare
              omitted.

       [1mB [22m[[4mbold‐text[24m [[4mprevious‐font‐text[24m]] ...
              Join [4mbold‐text[24m in boldface with [4mprevious‐font‐text[24m in the previ‐
              ous font, without space between the arguments.  If no arguments,
              switch font to bold style.

       [1mB1     [22mBegin  boxed, kept display.  The text is indented one character,
              and the right margin is one character shorter.  This  is  a  GNU
              extension.

       [1mB2     [22mEnd boxed, kept display.  This is a GNU 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.  Items are prefixed with  a  bullet  and  a
              space.   A [4mtext‐indent[24m argument overrides register [1mPi[22m.  A second
              argument suppresses blank lines between items.  Use  [1mLI  [22mto  de‐
              clare 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, with‐
              out space between the arguments.

       [1mBS     [22mBegin  bottom block.  Input is collected until [1mBE [22mis called, and
              output 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 is ex‐
              pected to supply its own mark.  The line is always broken  after
              the  mark; contrast [1mVL[22m.  [4mtext‐indent[24m sets the indentation of the
              text, and [4mmark‐indent[24m the distance from the current list  inden‐
              tation  to the mark.  A third argument suppresses the blank line
              that normally precedes each list item.  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/pkg/share/groff/1.23.0/tmac/mm/[24mstyle[4m.cov[24m  and  load it with
              the [1mmso [22mrequest.  The default [4mstyle[24m is [1mms[22m; the [4mms.cov[24m file  pre‐
              pares  a  cover page resembling those of the [4mms[24m package.  A [4m.cov[0m
              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
              .TL
              .AF
              .AU
              .AT
              .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.   Items  are prefixed with an em dash and a
              space.  A [4mtext‐indent[24m argument overrides register [1mPi[22m.  A  second
              argument  suppresses  blank  lines between items.  Use [1mLI [22mto de‐
              clare list items, and [1mLE [22mto end the list.

       [1mDS [22m[[4mformat[24m [[4mfill[24m [[4mright‐indentation[24m]]]
              Begin static display.  Input until [1mDE  [22mis  called  is  collected
              into  a  display.  The display is output on a single page unless
              it is taller than the height of the  page.   [1mDS  [22mcan  be  nested
              (contrast 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‐adjust the lines.
              RB       Right‐adjust 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 [4mmm.[0m

              [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 [4mmm.[0m

              A third argument reduces the line length by [4mright‐indentation.[0m

              [4mmm[24m normally places blank lines before  and  after  the  display.
              Set register [1mDs [22mto 0 to suppress these.

       [1mEC [22m[[4mtitle[24m [[4moverride[24m [[4mflag[24m [[4mrefname[24m]]]]
              Caption  an  equation.   The caption consists of the string [1mLiec[0m
              followed by an automatically incrementing counter stored in  the
              register [1mEc[22m, punctuation configured by the register [1mOf[22m, then [4mti‐[0m
              [4mtle[24m  (if any).  Use the [1maf [22mrequest to configure [1mEc[22m’s number for‐
              mat.  [4moverride[24m and [4mflag[24m alter the equation  number  as  follows.
              Omitting [4mflag[24m and specifying [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.

              Equation  captions are centered irrespective of the alignment of
              any enclosing display.

              [4mrefname[24m stores the equation number using [1mSETR[22m;  it  can  be  re‐
              treived  with  “[1m.GETST  [4m[22mrefname[24m”.  This argument is a GNU exten‐
              sion.

              Captioned equations are listed in a table of contents  (see  [1mTC[22m)
              if the Boolean register [1mLe [22mis true.  Such a list uses the string
              [1mLe [22mas a heading.

       [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
              normal 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
              normal page header on even‐numbered pages.  See [1mPH[22m.  [1mEH  [22mdefines
              the string [1mTPeh[22m.

       [1mEN     [22mEnd equation input preprocessed by [4mgeqn[24m(1); see [1mEQ[22m.

       [1mEOP    [22mIf  defined,  this macro is called in lieu of normal page footer
              layout.  Headers and footers are formatted in a  separate  envi‐
              ronment.  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.  It also prints the
              text [4mname[24m or a default string if [4mname[24m is not specified.  This is
              used to include external pictures; just give  the  size  of  the
              picture.   [1m-L [22mleft‐aligns the picture; the default is to center.
              See [1mPIC[22m.

       [1mEQ [22m[[4mlabel[24m]
              Start equation input preprocessed by [4mgeqn[24m(1).  [1mEQ [22mand  [1mEN  [22mmacro
              calls  bracket  an  equation  region.  Such regions must be con‐
              tained in displays ([1mDS[22m/[1mDE[22m), except when the region is used  only
              to  configure [4mgeqn[24m and not to produce output.  If present, [4mlabel[0m
              appears aligned to the right and centered vertically within  the
              display;  see register [1mEq[22m.  If multiple [4meqn[24m regions occur within
              a display, only the last [4mlabel[24m (if any) is used.

       [1mEX [22m[[4mtitle[24m [[4moverride[24m [[4mflag[24m [[4mrefname[24m]]]]
              Caption an exhibit.  Arguments are handled  analogously  to  [1mEC[22m.
              The  register  [1mEx  [22mis the exhibit counter.  The string [1mLiex [22mpre‐
              cedes the exhibit number and any [4mtitle.[24m   Exhibit  captions  are
              centered irrespective of the alignment of any enclosing display.

              Captioned exhibits are listed in a table of contents (see [1mTC[22m) if
              the Boolean register [1mLx [22mis true.  Such a list uses the string [1mLx[0m
              as a heading.

       [1mFC [22m[[4mclosing‐text[24m]
              Output  the  string [1mLetfc[22m, or the specified [4mclosing‐text,[24m as the
              formal closing of a letter.

       [1mFD [22m[[4marg[24m [[1m1[22m]]
              Configure display of footnotes.  The first argument encodes  en‐
              ablement  of automatic hyphenation, adjustment to the right mar‐
              gin, indentation of footnote text, and left‐ vs. right‐alignment
              of the footnote 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.

              If a second argument, conventionally [1m1[22m, is given, footnote  num‐
              bering  is reset when a first‐level heading is encountered.  See
              [1mFS[22m.

       [1mFE     [22mEnd footnote; see [1mFS[22m.

       [1mFG [22m[[4mtitle[24m [[4moverride[24m [[4mflag[24m [[4mrefname[24m]]]]
              Caption a figure.  Arguments are handled analogously to [1mEC[22m.  The
              register [1mFg [22mis the figure counter.  The string [1mLifg [22mprecedes the
              figure number and any [4mtitle.[24m  Figure captions are centered irre‐
              spective of the alignment of any enclosing display.

              Captioned figures are listed in a table of contents (see [1mTC[22m)  if
              the Boolean register [1mLf [22mis true.  Such a list uses the string [1mLf[0m
              as a heading.

       [1mFS [22m[[4mlabel[24m]
              Start  footnote.   Input  until [1mFE [22mis called is collected into a
              footnote.  By  default,  footnotes  are  automatically  numbered
              starting  at 1; the number is available in register [1m:p [22mand, with
              a trailing period, in string [1mF[22m.  This string precedes the  foot‐
              note  text  at  the bottom of the column or page.  Footnotes are
              vertically separated by the product of registers [1mFs [22mand [1mLsp[22m.  In
              [4mgroff[24m [4mmm[24m, footnotes may be used in displays.

              A [4mlabel[24m argument replaces the contents of the string [1mF[22m; it  need
              not  be numeric.  In this event, the footnote marker in the body
              text must be explicitly written.

       [1mGETHN [4m[22mrefname[24m [[4mvarname[24m]
              Include the heading number where the corresponding  “[1m.SETR  [4m[22mref‐[0m
              [4mname[24m” was placed.  This is displayed as “X.X.X.” in pass 1.  See
              [1mINITR[22m.  If [4mvarname[24m is used, [1mGETHN [22msets the string [4mvarname[24m to the
              heading number.

       [1mGETPN [4m[22mrefname[24m [[4mvarname[24m]
              Include  the page number where the corresponding “[1m.SETR [4m[22mrefname[24m”
              was placed.  This is displayed as “9999” in pass 1.  See  [1mINITR[22m.
              If  [4mvarname[24m  is  used, [1mGETPN [22msets the string [4mvarname[24m to the page
              number.

       [1mGETR [4m[22mrefname[0m
              Combine [1mGETHN [22mand [1mGETPN [22mwith the text “chapter”  and  “,  page”.
              The string [1mQrf [22mcontains the text for the cross reference:

                     .ds Qrf See chapter \\*[Qrfh], page \\*[Qrfp].

              [1mQrf [22mmay be changed to support other languages.  Strings [1mQrfh [22mand
              [1mQrfp  [22mare  set  by [1mGETR [22mand contain the page and heading number,
              respectively.

       [1mGETST [4m[22mrefname[24m [[4mvarname[24m]
              Include the string saved with  the  second  argument  to  [1m.SETR[22m.
              This  is  a  dummy  string in pass 1.  If [4mvarname[24m is used, [1mGETST[0m
              sets it to the saved string.  See [1mINITR[22m.

       [1mH [4m[22mlevel[24m [[4mtitle[24m [[4msuffix[24m]]
              Set a numbered section heading at [4mlevel[24m.  [4mmm[24m  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  increases  automatically  with
              each  [1mH  [22mcall and is reset to zero when a more significant [4mlevel[0m
              is specified.  “[1m1[22m” is the most significant or coarsest  division
              of  the  document.  Text after an [1mH [22mcall is formatted as a para‐
              graph; calling [1mP [22mis unnecessary.

              [4mtitle[24m specifies an optional title; it must be  double‐quoted  if
              it  contains  spaces.  [4mmm[24m 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 interpolate the [1mF [22mstring; specify a
              footnote mark explicitly.  See [1mFS[22m.

              Heading behavior is highly configurable.  Several registers  set
              a  [4mthreshold,[24m  where  heading  levels  at or below the threshold
              value are handled in one way, and those above it  another.   For
              example,  a heading level within the threshold of register [1mCl [22mis
              included in the table of contents (see [1mTC[22m).

              [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 below 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 be‐
              low which a break occurs after the heading, and register [1mHs [22msets
              a threshold below which vertical space follows it.  If the head‐
              ing level is not less than both of these, a  [4mrun‐in[24m  [4mheading[24m  is
              produced;  paragraph text follows on the same output line.  Oth‐
              erwise, register [1mHi [22mconfigures the  indentation  of  text  after
              headings.   Threshold register [1mHc [22menables the centering of head‐
              ings; a heading level below both of the [1mHb [22mand [1mHc [22mthresholds  is
              centered.

              [4mHeading[24m  [4mtypeface[24m  [4mand[24m [4msize.[24m  The fonts used for heading numbers
              and titles at each level are configured by the [1mHF  [22mstring.   The
              string  [1mHP  [22mlikewise  assigns a type size to each heading level.
              The vertical spacing used by headings may be controlled  by  the
              user‐definable macros [1mHX [22mand/or [1mHZ[22m.

              [4mHeading[24m  [4mnumber[24m  [4mformat.[24m   Registers  named [1mH1 [22mthrough [1mH14 [22mstore
              counters 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  [22mregister.  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  [4mmm[24m calls [4mhook[24m  macros  to  enable
              further  customization  of  headings.  (DWB [4mmm[24m called these “ex‐
              its”.)  They can be used to change the heading’s [4mmark[24m (the  num‐
              bered  portion  before any heading title), its vertical spacing,
              and its vertical space requirements (for instance, to require  a
              minimum  quantity  of  subsequent  output  lines).   Define hook
              macros in expectation of the following parameters.  The argument
              [4mdeclared‐level[24m is the [4mlevel[24m argument to [1mH[22m, or [1m0  [22mfor  unnumbered
              headings  (see  [1mHU[22m).  [4mactual‐level[24m is the same as [4mdeclared‐level[0m
              for numbered headings, and the value of register [1mHu  [22mfor  unnum‐
              bered headings.  [4mtitle[24m is the corresponding argument to [1mH [22mor [1mHU[22m.

              [1mHX [4m[22mdeclared‐level[24m [4mactual‐level[24m [4mtitle[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 head‐
                            ing to be typeset.  If that amount is  not  avail‐
                            able,  the  page  is  broken prior to the heading.
                            The default is [1m2v[22m.

              [1mHY [4m[22mdeclared‐level[24m [4mactual‐level[24m [4mtitle[0m
                     [4mmm[24m calls [1mHY [22mafter  determing  the  heading  typeface  and
                     size.  It could be used to change indentation.

              [1mHZ [4m[22mdeclared‐level[24m [4mactual‐level[24m [4mtitle[0m
                     [4mmm[24m  calls  [1mHZ [22mafter formatting the heading, just before [1mH[0m
                     or [1mHU [22mreturns.  It could  be  used  to  change  the  page
                     header to include a section heading.

       [1mHC [22m[[4mhyphenation‐character[24m]
              Set  hyphenation  character.   Default value is “\%”.  Resets to
              the default if called  without  argument.   Hyphenation  can  be
              turned  off  by setting register [1mHy [22mto 0 at the beginning of the
              file.

       [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[22mheading‐text[0m
              Set an unnumbered section heading.  Except for a heading number,
              it is treated as a numbered heading of the level stored in  reg‐
              ister [1mHu[22m; 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 pre‐
              vious font, without space between the arguments.   If  no  argu‐
              ments, switch font to italic style.

       [1mIA [22m[[4mrecipient‐name[24m [[4mtitle[24m]]
              Specify the inside address in a letter.  Input is collected into
              the inside address until [1mIE [22mis called, and then output.  You can
              specify  multiple  recipients  with  empty [1mIA[22m/[1mIE [22mpairs; only the
              last address is used.  The arguments give each recipient a  name
              and title.  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
              specially  prepared  [4mroff[24m  comment to the standard error stream,
              with each [4margument[24m separated from its predecessor by a tab char‐
              acter.  The entry’s location information is arranged as  config‐
              ured 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 interpolat‐
              ing  the  string  [1mIndex[22m.  It then disables filling and calls [1m2C[22m;
              afterward, it restores filling and calls [1m1C[22m.

              Define macros to customize this behavior.  [1mINDP [22mcalls [1mTXIND  [22mbe‐
              fore  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[0m
              selects how the location of each index entry is reported.  [4mfile‐[0m
              [4mname[24m 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, it is called for each index entry with
              the arguments given to [1mIND[22m.

       [1mINITR [4m[22mid[0m
              Initialize the cross reference  macros.   Cross  references  are
              written to the standard error stream, which should be redirected
              into  a  file  named id[4m.qrf[24m.  [4mmmroff[24m(1) handles this and the two
              formatting passes it requires.  The first pass identifies  cross
              references, and the second one includes them.

              See [1mSETR[22m, [1mGETPN[22m, and [1mGETHN[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.

       [1mISODATE [22m[[1m0[22m]
              Use ISO 8601 format for the date string [1mDT [22mused  by  some  cover
              sheet and memorandum types; that is, [4mYYYY[24m‐[4mMM[24m‐[4mDD[24m.  Must be called
              before  [1mND [22mto be effective.  If given an argument of [1m0, [22mthe tra‐
              ditional date format for the [4mgroff[24m locale is used; this is  also
              the default.

       [1mLB [4m[22mtext‐indent[24m [4mmark‐indent[24m [4mpad[24m [4mtype[24m [[4mmark[24m [[4mpre‐item‐space[24m [[4mpre‐list‐[0m
       [4mspace[24m]]]
              Begin  list.  The macros [1mAL[22m, [1mBL[22m, [1mBVL[22m, [1mDL[22m, [1mML[22m, [1mRL[22m, and [1mVL [22mcall [1mLB[0m
              in various ways; they are simpler to use and may be preferred if
              they suit the desired purpose.

              The nesting level of lists is tracked by [4mmm;[24m the outermost level
              is 0.  The text of each list item is  indented  by  [4mtext‐indent;[0m
              the default is taken from the [1mLi [22mregister (in ens).  Each item’s
              mark is indented by [4mmark‐indent;[24m the default is [1m0n[22m.  The mark is
              normally left‐aligned.  If [4mpad[24m is greater than zero, [4mmark‐indent[0m
              is  overridden such that [4mpad[24m ens of space follow the mark.  [4mtype[0m
              selects one of six possible ways to display the mark.

              [4m[1mtype[24m   Output for a mark “x”[0m
              1      x.
              2      x)
              3      (x)
              4      [x]
              5      <x>
              6      {x}

              If [4mtype[24m is 0 and [4mmark[24m is unspecified, the items are set  with  a
              hanging  indent.   Otherwise,  [4mmark[24m  is  interpreted as a string
              defining the mark.  If [4mtype[24m is greater than zero, items are  au‐
              tomatically  numbered; [4mmark[24m is interpreted as a register format.
              The default [4mtype[24m is [1m0[22m.

              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[0m
              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,
              either  all  (the  default) or only those from the current level
              down to [4mlist‐level[24m if specified.  [1mH [22mcalls [1mLC [22mautomatically.

       [1mLE [22m[[1m1[22m] End list.  The current list is terminated.   An  argument  of  [1m1[0m
              causes  vertical  space  in the amount of register [1mLsp [22mto follow
              the list.

       [1mLI [22m[[4mmark[24m [[4mitem‐mark‐mode[24m]]
              Begin a list item.  Input is collected into a  list  item  until
              the  current  list  is terminated or [1mLI [22mis called again.  By de‐
              fault, the item’s text is preceded by any mark configured by the
              current list.  If only [4mmark[24m is specified, it replaces  the  con‐
              figured mark.  A second argument prefixes [4mmark[24m to the configured
              mark;  an  [4mitem‐mark‐mode[24m value of 1 places an unbreakable space
              after [4mmark,[24m while a value of 2 does not (rendering the two adja‐
              cent).  Also see register [1mLimsp[22m.

       [1mLO [4m[22moption[24m [[4mvalue[24m]
              Specify letter options; see [1mLT[22m.  Standard options  are  as  fol‐
              lows.  See [1mIA [22mregarding the inside address and string [1mDT [22mregard‐
              ing the date.

              [4m[1moption[24m   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 confidental 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 confiden‐
                       tal notation (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 [22mis 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
              below).  A letter begins with the writer’s address ([1mWA[22m/[1mWE[22m), fol‐
              lowed  by the date ([1mND[22m), the inside address ([1mIA[22m/[1mIE[22m), the body of
              the letter ([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 may be omitted.  Letter options specified with [1mLO [22madd fur‐
              ther  annotations, which are extensible; see section “Internals”
              below.

              [4m[1mstyle[24m   Description[0m
              [1mBL      [22mBlocked: the writer’s address, date, formal closing, and
                      signature are  indented  to  the  center  of  the  line.
                      Everything else is left‐aligned.
              [1mSB      [22mSemi‐blocked:  as  [1mBL[22m,  but the first line of each para‐
                      graph is indented by [1m5m[22m.
              [1mFB      [22mFully blocked: everything begins at the left margin.
              [1mSP      [22mSimplified: 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‐[0m
              [4mwidth[24m/15.  [1m1C [22mreturns to single‐column layout.  [1mMC [22mis a GNU  ex‐
              tension.  See [1mMULB [22mfor an alternative.

       [1mML [4m[22mmark[24m [[4mtext‐indent[24m [[1m1[22m]]
              Start  a  list  with the [4mmark[24m argument preceding each list item.
              [4mtext‐indent[24m overrides the default indentation of the list  items
              set  by  register [1mLi[22m.  If a third argument, conventionally [1m1[22m, is
              given, the blank line that normally precedes each list  item  is
              suppressed.   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 de‐
              veloped, affecting the document layout.  Some of these  included
              a cover page with a caption categorizing the document.  [4mgroff[24m [4mmm[0m
              uses      [4mtype[24m      to      construct      the     file     name
              [4m/usr/pkg/share/groff/1.23.0/tmac/mm/[24mtype[4m.MT[24m and load it with the
              [1mmso [22mrequest.  Memorandum types 0 to 5 are supported;  any  other
              value of [4mtype[24m is mapped to type 6.  If [4mtype[24m is omitted, [1m0 [22mis im‐
              plied.   [4maddressee[24m  sets  a string analogous to one used by AT&T
              cover sheet macros that are not implemented in [4mgroff[24m [4mmm[24m.

              [4m[1mtype[24m   Description[0m
              0      normal memorandum; no caption
              1      captioned “MEMORANDUM FOR FILE”
              2      captioned “PROGRAMMER’S NOTES”
              3      captioned “ENGINEER’S NOTES”
              4      released paper
              5      external letter

              See [1mCOVER [22mfor a more flexible cover sheet 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‐[0m
              [4mlength[24m is not given, the difference between current and new page
              offset  is used.  Use [1mPGFORM [22mwithout arguments to return to nor‐
              mal.

       [1mMULB [4m[22mcw1[24m [4mspace1[24m [[4mcw2[24m [4mspace2[24m] ... [4mcwn[0m
              Begin alternative multi‐column mode.  All column widths must  be
              specified, as must the amount of space between each column pair.
              The arguments’ default scaling unit is [1mn[22m.  [1mMULB [22muses a diversion
              and operates in a separate environment.

       [1mMULN   [22mBegin next column in alternative column mode.

       [1mMULE   [22mEnd alternative multi‐column mode and emit the columns.

       [1mNCOL   [22mMove to the start of the 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).

       [1mNE     [22mEnd notation begun with [1mNS[22m; filling is enabled.

       [1mnP [22m[[4mtype[24m]
              Begin a numbered paragraph at heading level two.  See [1mP[22m.

       [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  out‐
              put,  and  filling is disabled until [1mNE [22mis called.  Typically, a
              list of names or attachments lies within [1mNS[22m/[1mNE[22m.  If [4mcode[24m is  ab‐
              sent  or does not match one of the values listed under the [1mLetns[0m
              string description below, each line of notations is formatted as
              “Copy ([4mline[24m) to”.  If a second argument,  conventionally  [1m1[22m,  is
              given, [4mcode[24m 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
              normal  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
              normal  page  header on odd‐numbered pages.  See [1mPH[22m.  [1mOH [22mdefines
              the string [1mTPoh[22m.

       [1mOP     [22mMake sure that the following text is printed at the  top  of  an
              odd‐numbered  page.   Does not output an empty page if currently
              at the top of an odd page.

       [1mP [22m[[4mtype[24m]
              Begin new paragraph.  If [4mtype[24m is missing or  0, [1mP [22msets the para‐
              graph fully left-aligned.  A [4mtype[24m of 1 idents the first line  by
              [1m\[Pi]  [22mens.   Set  the register [1mPt [22mto select a default paragraph
              indentation style.  The register [1mPs [22mcontrols the vertical  spac‐
              ing between paragraphs.

       [1mPE     [22mPicture end; see [4mgpic[24m(1).

       [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[0m
              defines the string [1mEOPf[22m.  See [1mEF[22m, [1mOF[22m, and [1mEOP[22m.

       [1mPGFORM [22m[[4mlinelength[24m [[4mpagelength[24m [[4mpageoffset[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[0m
              can be used without arguments to reset everything after  a  [1mMOVE[0m
              call.  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.  This macro must be called be‐
              fore  any macros that produce output to affect the layout of the
              first page.

       [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
              respective locations on the line.  A “[1m%[22m” character in [4marg[24m is re‐
              placed 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 noth‐
              ing at the upper left and right.  Header macros call [1mPX [22m(if  de‐
              fined)  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 arguments align the picture or indent it by [4mn[24m  (assuming  a
              scaling  unit  of  [1mm[22m).  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  [22mand
              [4mmmroff[24m(1).

       [1mPS     [22mPicture start; see [4mgpic[24m(1).

       [1mPY     [22mPicture end with flyback.  Ends a [4mgpic[24m(1) picture, returning the
              vertical position to where it was prior to the picture.  This is
              a GNU extension.

       [1mR [22m[[4mroman‐text[24m [[4mprevious‐font‐text[24m]] ...
              Join [4mroman‐text[24m in roman style with  [4mprevious‐font‐text[24m  in  the
              previous font, without space between the arguments.  If no argu‐
              ments, 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, with‐
              out space between the arguments.

       [1mRD [22m[[4mprompt[24m [[4mdiversion[24m [[4mstring[24m]]]
              Read  from  standard input to diversion and/or string.  The text
              is saved in a diversion named [4mdiversion[24m.   Recall  the  text  by
              writing  the name of the diversion after a dot on an empty line.
              A string is also defined if [4mstring[24m is given.   [4mDiversion[24m  and/or
              [4mprompt[24m can be empty ("").

       [1mRF     [22mReference  end.  Ends a reference definition and returns to nor‐
              mal processing.  See [1mRS[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 reference list.  Each item is preceded by an automatically
              incremented  number  between square brackets; compare [1mAL[22m.  [4mtext‐[0m
              [4mindent[24m changes the default indentation.  Use [1mLI [22mto declare  list
              items,  and  [1mLE [22mto end the list.  A second argument, convention‐
              ally [1m1[22m, suppresses the blank line that  normally  precedes  each
              list item.

       [1mRP [22m[[4msuppress‐counter‐reset[24m [[4mpage‐ejection‐policy[24m]]
              Format  a reference page, 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  refer‐
              ences are output; the register [1mRpe [22mconfigures this behavior, and
              a  second  argument  overrides its value.  [1mTC [22mcalls [1mRP [22mautomati‐
              cally if references have accumulated.

              References are list items, and  thus  are  vertically  separated
              (see  [1mLB[22m).   Setting  register  [1mLs [22mto [1m0 [22msuppresses this spacing.
              The string [1mRp [22mcontains the reference page caption.

       [1mRS [22m[[4mreference‐string[24m]
              Begin an automatically numbered reference  definition.   By  de‐
              fault,  references  are  numbered  starting  at 1; the number is
              available in register [1m:R[22m.  Interpolate the string [1mRf  [22mwhere  the
              reference  mark  should be and write the reference between [1mRS[22m/[1mRF[0m
              on an input line after the reference mark.  If  [4mreference‐string[0m
              is  specified,  [4mgroff[24m  [4mms[24m  also  stores  the reference mark in a
              string of that name, which can be interpolated as  [1m\*[[4m[22mreference‐[0m
              [4mstring[24m[1m] [22msubsequently.

       [1mS [22m[[4mtype‐size[24m [[4mvertical‐spacing[24m]]
              Set  type  size  and vertical spacing.  Each argument is a [4mgroff[0m
              measurement, using an appropriate scaling unit and an optional [1m+[0m
              or [1m- [22mprefix to increment or decrement the current value.  An ar‐
              gument of [1mP [22mrestores the previous value, [1mC [22mindicates the current
              value, and [1mD [22mrequests the default.  An empty or omitted argument
              is treated as [1mP[22m.

       [1mSA [22m[[4mmode[24m]
              Set or restore the default enablement of adjustment.  Specify  [1m0[0m
              or  [1m1  [22mas  [4mmode[24m to set a document’s default explicitly; [1m1 [22mis as‐
              sumed by [4mmm[24m.  Adjustment can be temporarily suspended  with  the
              [1mna  [22mrequest.  When the [1mH [22mor [1mHU [22mmacros are used to format a head‐
              ing, or when [1mSA [22mis called without a [4mmode[24m argument,  the  default
              adjustment is restored.

       [1mSETR [4m[22mrefname[24m [[4mstring[24m]
              Remember the current heading and page numbers as [4mrefname[24m.  Saves
              [4mstring[24m  if  [4mstring[24m  is defined.  [4mstring[24m is retrieved with [1mGETST[22m.
              See [1mINITR[22m.

       [1mSG [22m[[4marg[24m [[1m1[22m]]
              Signature line.  Prints the authors  name(s)  after  the  formal
              closing.   The  argument  is  appended  to  the  reference data,
              printed at either the first or last author.  The reference  data
              is the location, department, and initials specified with [1mAU[22m.  It
              is  printed at the first author if the second argument is given,
              otherwise at the last.  No reference data is printed if the  au‐
              thor(s) is specified through [1mWA[22m/[1mWE[22m.  See section “Internals” be‐
              low.

       [1mSK [22m[[4mn[24m] Skip  [4mn[24m  pages.  If [4mn[24m is 0 or omitted, the page is broken unless
              the drawing position is already at the top of  a  page.   Other‐
              wise,  [4mn[24m  pages,  blank  except for any headers and footers, are
              printed.

       [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[24m and [4mpost[24m at normal size.

       [1mSP [22m[[4mlines[24m]
              Space  vertically.  [4mlines[24m can have any scaling factor, like “3i”
              or “8v”.  Several [1mSP [22mcalls in a line only produces  the  maximum
              number  of  lines,  not  the  sum.  [1mSP [22mis ignored also until the
              first text line in a page.  Add [1m\& [22mbefore a call to [1mSP [22mto  avoid
              this.

       [1mTAB    [22mReset tab stops to every 5 ens.

       [1mTB [22m[[4mtitle[24m [[4moverride[24m [[4mflag[24m [[4mrefname[24m]]]]
              Caption  a table.  Arguments are handled analogously to [1mEC[22m.  The
              register [1mTb [22mis the table counter.  The string [1mLitb [22mprecedes  the
              table  number  and any [4mtitle.[24m  Table captions are centered irre‐
              spective of the alignment of any enclosing display.

              Captioned tables are listed in a table of contents (see  [1mTC[22m)  if
              the Boolean register [1mLt [22mis true.  Such a list uses the string [1mLt[0m
              as a heading.

       [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 references are pending (see [1mRS[22m), calls [1mRP[22m.  It then begins a
              new page with the contents caption, stored in the string  [1mLicon[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 [22mregister), along with its  associated  page  number.
              By  default,  an entry is indented 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[24m vees of space.  Entries at head‐
              ing levels up to and including [4mtlevel[24m are followed by  a  leader
              and  a right‐aligned page number.  If the Boolean‐valued [4mtab[24m ar‐
              gument is true, the leader is replaced with horizontal motion in
              the same amount.  For entries above heading  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  [1mTC [22mis called with at most four arguments, it calls the user‐
              defined macro [1mTX [22m(if defined) prior to formatting  the  contents
              caption,  and [1mTY [22m(if defined) [4minstead[24m of formatting the contents
              caption.

              Analogous handling of lists of figures, tables,  equations,  and
              exhibits  is achieved by defining [1mTX[4m[22mxx[24m and [1mTY[4m[22mxx[24m macros, where [4mxx[0m
              is “FG”, “TB”, “EC”,  or  “EX”,  respectively.   Similarly,  the
              strings  [1mLifg[22m, [1mLitb[22m, [1mLiex[22m, and [1mLiec [22mdetermine captions for their
              respective lists.

       [1mTE     [22mTable end.  See [1mTS[22m.

       [1mTH     [22mEnd table heading.  It is repeated after page  breaks  within  a
              table.   See  [1mTS[22m.  The [1mN [22margument supported by DWB [4mmm[24m is not im‐
              plemented by [4mgroff[24m [4mmm.[0m

       [1mTL [22m[[4mcharging‐case‐number[24m [[4mfiling‐case‐number[24m]]
              Begin document title.  Input is collected into the  title  until
              [1mAF  [22mor  [1mAU  [22mis called, and output as directed by the cover page.
              [4mcharging‐case‐number[24m and [4mfiling‐case‐number[24m are saved for use in
              memorandum types 0 and 5.  See [1mMT[22m.

       [1mTM [4m[22mnumber[24m ...
              Declare technical memorandum number(s) used by [1mMT[22m.

       [1mTP     [22mIf defined, this macro is called in lieu of normal  page  header
              layout.   Headers  and footers are formatted in a separate envi‐
              ronment.  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] Table start.  Argument “H” tells [4mmm[24m that the table has  a  head‐
              ing.  See [1mTE[22m, [1mTH[22m, and [4mgtbl[24m(1).

       [1mVERBON [22m[[4mformat[24m [[4mtype‐size[24m [[4mfont[24m]]]
              Begin verbatim display, where characters have equal width.  [4mfor‐[0m
              [4mmat[24m  controls  several parameters.  Add up the values of desired
              features; the default is [1m0[22m.  On typesetting devices, further ar‐
              guments configure the [4mtype‐size[24m in scaled points, and  the  face
              ([4mfont[24m); the default is [1mCR [22m(Courier roman).

              [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
                      arguments 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.  If the mark is  wider  than  [4mmark‐indent,[0m
              one  space  separates  it  from  subsequent  text; contrast [1mBVL[22m.
              [4mtext‐indent[24m sets the indentation of the  text,  and  [4mmark‐indent[0m
              the  distance  from the current list indentation to the mark.  A
              third argument suppresses the blank line that normally  precedes
              each list item.  Use [1mLI [22mto declare list items, and [1mLE [22mto end the
              list.

       [1mVM [22m[[1m-T[22m] [[4mtop[24m [[4mbottom[24m]]
              Vertical  margin.  Increase the top and bottom margin by [4mtop[24m and
              [4mbottom[24m, respectively.  If option [1m-T [22mis specified, set those mar‐
              gins to [4mtop[24m and [4mbottom[24m.  If no argument is given, reset the mar‐
              gin to zero, or to the default (“7v 5v”) if [1m-T [22mis used.   It  is
              highly  recommended that macros [1mTP [22mand/or [1mEOP [22mare defined if us‐
              ing [1m-T [22mand setting top and/or bottom margin to less than the de‐
              fault.  This undocumented DWB [4mmm[24m macro is exposed by [4mgroff[24m [4mmm[24m to
              increase user control of page layout.

       [1mWA [22m[[4mwriter’s‐name[24m [[4mtitle[24m]]
              Specify the writer(s) of an [1mLT [22mletter.  Input is collected  into
              the  writer’s  address until [1mWA [22mis called, and then output.  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  subse‐
                       quent 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.   These  are
       presented in quotation marks.

       [1mApp    [22m“APPENDIX”

       [1mApptxt [22mstores the [4mtitle[24m argument to the last [1mAPP [22mcall.

       [1mBU     [22minterpolates a bullet (see [1mBL[22m).

       [1mCi     [22mis  a  list  of indentation amounts to use for table of contents
              heading levels, overriding their  automatic  computation.   Each
              word  must be a horizontal measurement (like “[1m1i[22m”) and is mapped
              one‐to‐one to heading levels 1, 2, and so on.

       [1mDT     [22mThe date; set by the [1mND [22mmacro (defaults to the date the document
              is formatted).  The format is the conventional one for the [4mgroff[0m
              locale, but see the [1mISODATE [22mmacro and [1mIso [22mregister.

       [1mEM     [22minterpolates an em dash.

       [1mF      [22minterpolates an automatically numbered footnote marker; the num‐
              ber is used by the next [1mFS [22mcall without an argument.   In  [4mtroff[0m
              mode,  the  marker  is  superscripted; in [4mnroff[24m mode, it is sur‐
              rounded by square brackets.

       [1mH1txt  [22mUpdated by [1m.H [22mand [1m.HU [22mto the current heading text.  Also updated
              in table of contents & friends.

       [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 [4mmm[24m’s default was “[1m3 3[0m
              [1m2 2 2 2 2[22m”.

       [1mHP     [22massigns type sizes, separated by spaces, to  heading  levels  in
              one‐to‐one  correspondence.   Each size is interpreted in scaled
              points; zero values are translated to [1m10[22m.   Omitted  values  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[0m
              “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 no‐
              tation  is   included   between   parentheses,   prefixed   with
              [1mLetns!copy[22m,  and suffixed with [1mLetns!to[22m.  Observe the spaces af‐
              ter “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[0m
              Select the notation format used by [1mNS [22mwhen it is given no  argu‐
              ment.  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”

       [1mLicon  [22m“CONTENTS”

       [1mLiec   [22m“Equation”

       [1mLiex   [22m“Exhibit”

       [1mLifg   [22m“Figure”

       [1mLitb   [22m“TABLE”

       [1mLt     [22m“LIST OF TABLES”

       [1mLx     [22m“LIST OF EXHIBITS”

       [1mMO1[22m...[1mMO12[0m
              “January” through “December”

       [1mQrf    [22m“See chapter \\*[Qrfh], page \\n[Qrfp].”

       [1mRf     [22minterpolates  an automatically numbered reference mark; the num‐
              ber is used by the next [1mRS [22mcall.  In [4mtroff[24m mode, the  marker  is
              superscripted;  in [4mnroff[24m mode, it is surrounded by square brack‐
              ets.

       [1mRp     [22m“REFERENCES”

       [1mSm     [22minterpolates ℠, the service mark sign.

       [1mTcst   [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 “1”.

[1mRegisters[0m
       Default  register  values,  where meaningful, are shown in parentheses.
       Many are also marked as Boolean‐valued, meaning that they  are  consid‐
       ered  “true” (on, enabled) when they have a positive value, and “false”
       (off, disabled) otherwise.

       [1m.mgm   [22mindicates that [4mgroff[24m [4mmm[24m is in use (Boolean‐valued; [1m1[22m).

       [1m:p     [22mis an auto‐incrementing footnote counter; see [1mFS[22m.

       [1m:R     [22mis an auto‐incrementing reference counter; see [1mRS[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 subse‐
              quent arguments to [1mAU[22m) in  memorandum  “from”  information;  see
              [1mCOVER [22mand [1mMT [22m(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([1m2[22m).  The [1mCl [22mregister controls whether a heading is [4msaved[0m
              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 unlikely to get the result you want.

       [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 stan‐
              dard error stream.  A value of 0 outputs nothing; 1 reports for‐
              matting progress.  Higher values communicate internal state  in‐
              formation 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
                      column.
              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
                      remain.

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

       [1mEj     [22msets the threshold for page breaks (ejection) prior to the  for‐
              mat of headings.  Headings at levels above this value are set on
              the same page and column 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).

       [1mH1[22m...[1mH14[0m
              are 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 A copy of register register [1mH1[22m, but  it  is  incre‐
              mented just before a page break.  This can be useful in user‐de‐
              fined macros; see [1mH [22mand [1mHX[22m.

       [1mHb     [22msets  the  threshold  for  breaking  the line after formatting a
              heading.  Text after headings at levels above this value are set
              on the same output line if possible; 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     [22mconfigures  the indentation of text 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
              vertical space; see [1mH[22m.  Headings at levels above  the  value  in
              register [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 de‐
              vices: [1m1v[22m).

       [1mHps2   [22mconfigures the amount of vertical space preceding a  heading  at
              or  below the [1mHps [22mthreshold; see [1mH [22m([4mtroff[24m devices: [1m1v[22m; [4mnroff[24m de‐
              vices: [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  lowest
              when the heading 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).

       [1mIso    [22mconfigures  the  use  of ISO 8601 date format if specified (with
              any value) on the command line; see [1mISODATE[22m.  The default is de‐
              termined by localization files.

       [1mL      [22mdefines the page length for the document, and must be  set  from
              the  command  line.  A scaling unit should be appended.  The de‐
              fault 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
              exhibit  captions,  respectively, after a table of contents; see
              [1mTC [22m(Boolean‐valued; [1mLe[22m: [1m0[22m; [1mLf[22m, [1mLt[22m, [1mLx[22m: [1m1[22m).

       [1mLetwam [22msets the maximum number of input lines permitted in  a  writer’s
              address; see [1mWA [22mand [1mWE [22m([1m14[22m).

       [1mLi     [22mconfigures  the  amount  of  indentation  in ens applied to list
              items; see [1mLI [22m([1m6[22m).

       [1mLimsp  [22minserts a space between the prefix and the mark in automatically
              numbered lists; see [1mAL [22m(Boolean‐valued; [1m1[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([1m99[22m).

       [1mLsp    [22mconfigures the base amount of vertical space used for separation
              in  the  document.   [4mmm[24m  applies  this spacing to many contexts,
              sometimes with multipliers; see [1mDS[22m, [1mFS[22m, [1mH[22m, [1mLI[22m, and [1mP [22m([4mtroff[24m  de‐
              vices: [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  cur‐
              rent  first‐level heading) and [4my[24m the page number within the sec‐
              tion.  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 GNU 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     [22mcauses  paragraphs  after first‐level headings (only) to be num‐
              bered in the format [4ms[24m.[4mp[24m, where [4ms[24m is is the section  number  (the
              number  of  the  current first‐level heading) and [4mp[24m is the para‐
              graph 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 de‐
              fault is [1m.75i [22mon terminal devices.  On typesetters, it is  [1m.963i[0m
              or set to [1m1i [22mby the [4mpapersize.tmac[24m package; see [4mgroff_tmac[24m(5).

       [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  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 regis‐
              ter [1m% [22mexcept when “section‐page” numbering is enabled.

       [1mPi     [22mconfigures the amount of indentation in ens applied to the first
              line of a paragraph; see [1mP [22m([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 [1mOE [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, [1mDE[22m, or [1mLE[0m

       [1mRef    [22mis used internally to control [4mmmroff[24m(1)’s two‐pass  approach  to
              index  and  reference management; see [1mINITI [22mand [1mRS [22m(Boolean‐val‐
              ued; [1m0[22m).

       [1mRpe    [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 list of references.
              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[0m
              unless register [1mN [22mis set to [1m3 [22mor [1m5 [22mat the command line (Boolean‐
              valued).

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

       [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  com‐
              mand  line.   A  scaling  unit  should be appended.  The default
              is  [1m6i  [22mor  assigned  by   the   [4mpapersize.tmac[24m   package;   see
              [4mgroff_tmac[24m(5).

[1mInternals[0m
       The  [1mLT [22mletter macros call further macros depending on the letter type,
       with which they are suffixed.  It is therefore possible to define addi‐
       tional letter types, either in the territory‐specific macro file, or as
       local additions.  [1mLT [22msets the registers [1mPt [22mand [1mPi [22mto 0 and  5,  respec‐
       tively.   The  following macros must be defined to support a new letter
       type.

       [1mlet@init_[4m[22mtype[0m
              [1mLT [22mcalls this macro to initialize 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[0m
              unless the letterhead is desired on subsequent pages.

       [1mlet@sg_[4m[22mtype[24m [4mname[24m [4mtitle[24m [4mn[24m [4mis‐final[24m [[4mSG‐arg[24m ...]
              [1mSG [22mcalls this macro only for letters; [1mMT  [22mmemoranda  have  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 ap‐
              pended to the signature line.

       [1mlet@fc_[4m[22mtype[24m [4mclosing[0m
              This macro is called by [1mFC[22m, and has the formal  closing  as  the
              argument.

       [1mLO  [22mimplements letter options.  It requires that a string named [1mLet[4m[22mtype[0m
       be defined, where [4mtype[24m is the letter type.  [1mLO [22mthen assigns its  second
       argument ([4mvalue[24m) to the string [1mlet*lo-[4m[22mtype[24m.

[1mFiles[0m
       [4m/usr/pkg/share/groff/1.23.0/tmac/m.tmac[0m
              is the [4mgroff[24m implementation of the memorandum macros.

       [4m/usr/pkg/share/groff/1.23.0/tmac/mm.tmac[0m
              is wrapper to load [4mm.tmac[24m.

       [4m/usr/pkg/share/groff/1.23.0/tmac/refer-mm.tmac[0m
              implements [4mgrefer[24m(1) support for [4mmm[24m.

       [4m/usr/pkg/share/groff/1.23.0/tmac/mm/ms.cov[0m
              implements an [4mms[24m‐like cover sheet.

       [4m/usr/pkg/share/groff/1.23.0/tmac/mm/0.MT[0m
              implements memorandum types 0–3 and 6.

       [4m/usr/pkg/share/groff/1.23.0/tmac/mm/4.MT[0m
              implements memorandum type 4.

       [4m/usr/pkg/share/groff/1.23.0/tmac/mm/5.MT[0m
              implements memorandum type 5.

       [4m/usr/pkg/share/groff/1.23.0/tmac/mm/locale[0m
              performs  any (further) desired necessary localization; empty by
              default.

[1mAuthors[0m
       The GNU version of the [4mmm[24m macro package was written by Jörgen Hägg ⟨jh@
       axis.se⟩ of Lund, Sweden.

[1mSee also[0m
       [4mMM[24m [4m-[24m [4mA[24m [4mMacro[24m [4mPackage[24m [4mfor[24m [4mGenerating[24m [4mDocuments[24m ⟨https://tkurtbond.github
       .io/troff/mm-all.pdf⟩, the DWB 3.3 [4mmm[24m manual,  introduces  the  package
       but does not document GNU extensions.

       [4mGroff:[24m  [4mThe[24m  [4mGNU[24m [4mImplementation[24m [4mof[24m [4mtroff[24m, by Trent A. Fisher and Werner
       Lemberg, is the primary [4mgroff[24m manual.  You can browse it  interactively
       with “info groff”.

       [4mgroff[24m(1),    [4mgtroff[24m(1),    [4mgtbl[24m(1),    [4mgpic[24m(1),   [4mgeqn[24m(1),   [4mgrefer[24m(1),
       [4mgroff_mmse[24m(7)

groff 1.23.0                      2 July 2023                      [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ögerjusterad text.

       [1mCOVER  [22mkan  använda [4mse_ms[24m som argument. Detta ger ett svenskt försätts‐
       blad. Se [4mgroff_mm[24m(7) för övriga detaljer.

[1mBrev[0m
       Tillgängliga brevtyper:

       [1m.LT SVV[0m
              Vänsterställd löptext  med  adressat  i  position  T0  (vänster‐
              ställt).

       [1m.LT SVH[0m
              Högerställd  löptext med adressat i position T4 (passar fönster‐
              kuvert).

       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  pre‐
              fix.

       [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
              liknande).

       [1m.LO SIDOR [4m[22mantal[0m
              Anger totala antalet sidor och skrivs ut  efter  sidnumret  inom
              parenteser.

       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
       Jörgen Hägg, Lund, Sweden <Jorgen.Hagg@axis.se>

[1mFiler[0m
       [4m/usr/pkg/share/groff/1.23.0/tmac/mse.tmac[0m

       [4m/usr/pkg/share/groff/1.23.0/tmac/mm/se_[24m*[4m.cov[0m

[1mSe också[0m
       [4mgroff_mm[24m(7)

groff 1.23.0                      2 July 2023                    [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:
       typesetting and document processing.   The  former  provide  access  to
       [4mgroff[24m’s  typesetting  capabilities  in  ways that are simpler to master
       than [4mgroff[24m’s requests and escape sequences.  The latter provide  highly
       customizable  markup tags that allow the user to design and output pro‐
       fessional‐looking documents with a minimum of typesetting intervention.

       Files processed with [4mpdfmom[24m(1) produce PDF  documents.   The  documents
       include a PDF outline that appears in the navigation pane panel of doc‐
       ument viewers, and may contain clickable internal and external links.

       Normally.   [4mgroff[24m’s  native  PDF driver, [4mgropdf[24m(1), 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  Post‐
       Script driver, [4mgrops[24m(1).  Not all PDF features are available when [1m-T ps[0m
       is given; its primary use is to allow processing of files with embedded
       PostScript images.

       Files processed with [1mgroff -mom [22m(or [1m-m mom[22m) format for the device spec‐
       ified  with  the  [1m-T  [22moption.  (In this installation, [1mps [22mis the default
       output device.)

       [4mmom[24m comes with her own comprehensive documentation in HTML.  A PDF man‐
       ual, “Producing PDFs with [4mgroff[24m and [4mmom[24m”, discusses preparation of  PDF
       documents with [4mmom[24m in detail.

[1mFiles[0m
       [4m/usr/pkg/share/groff/1.23.0/tmac/mom.tmac[0m
              is  a  wrapper  enabling the package to be loaded with “[1mgroff -m[0m
              [1mmom[22m”.

       [4m/usr/pkg/share/groff/1.23.0/tmac/om.tmac[0m
              implements the package.

       [4m/usr/pkg/share/doc/groff-1.23.0/html/mom/toc.html[0m
              is the entry point to the HTML documentation.

       [4m/usr/pkg/share/doc/groff-1.23.0/pdf/mom-pdf.pdf[0m
              is “Producing PDFs with [4mgroff[24m and [4mmom[24m”, by Deri James and  Peter
              Schaffter.

       [4m/usr/pkg/share/doc/groff-1.23.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
              numbered 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 [22mset 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  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\*[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  con‐
              dense 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
              numbered endnotes)

       [1m\*[EXT][0m
       [1m\*[EXTX][0m
              Pseudo‐extending on/off

              [1m\*[EXT]  [22mbegins  pseudo‐extending type.  [1m\*[EXTX] [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:
                     [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
              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\*[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 in‐
              lines to function properly.  Please see [4mIMPORTANT[24m, below.

              String tabs need to be marked off with inline  escape  sequences
              before being set up with the [1m.ST [22mmacro.  Any input line may con‐
              tain  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.  [4mIn‐[0m
              [4mline[24m [4mescape[24m [4msequences[24m (e.g., [4mfont[24m or [4mpoint[24m [4msize[24m [4mchanges[24m, or hor‐
              izontal  movements,  including  padding)  are taken into account
              when [4mmom[24m determines 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 [22mmacro.

              [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 correct 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 ac‐
              tive, 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 exam‐
              ple,  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  be‐
              yond which you don’t want your type to go.  When the bottom mar‐
              gin  is  reached,  [4mmom[24m  starts a new page.  [1m.B_MARGIN requires a[0m
              [1munit of measure.  [22mDecimal fractions are allowed.  To set a nomi‐
              nal bottom margin 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 doc‐
              ument  processing macros are very hard‐nosed about aligning bot‐
              tom margins.

              Note: The meaning of [1m.B_MARGIN [22mis slightly different when you’re
              using 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
              exist, either because you haven’t registered the  style  or  be‐
              cause  the  [4mfont[24m  [4mstyle[24m does not exist in the current [4mfamily[24m [4mset[0m
              with [1m.FAMILY[22m.  By default, [1mmom [22mthen aborts, which allows you  to
              correct the problem.

              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 con‐
              junction 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‐existent  [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‐existent  [4mfont[24m but will continue processing your file
                     with a [4mfallback[24m [4mfont[24m of [1mTimes Roman Medium  Roman[22m;  addi‐
                     tionally,  [1mTR  [22mwill be the [4mfallback[24m [4mfont[24m whenever you try
                     to access a [4mfamily[24m 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 ABORT" [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[24m 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[0m
              and the desired font with a single macro.  While  this  saves  a
              few  keystrokes,  I  recommend using [1m.FAMILY for [4m[22mfamily[24m, and [1m.FT[0m
              [1mfor [4m[22mfont[24m, except 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.

              If  you  are  running [4mgroff[24m 1.19.2 or later, when you invoke the
              [1m.FAMILY [22mmacro, [4mmom[24m [4mremembers[24m the font style [1m([22mRoman[1m, Italic[22m, etc)
              currently in use (if the font style exists in  the  new  [4mfamily[24m)
              and  will continue 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
              will set all subsequent type in the fallback font  (by  default,
              [1mCourier  Medium Roman[22m) until she encounters a [1m.FT [22mrequest that’s
              valid for the [4mfamily[24m.

              For example, assuming you don’t have the font  [1mMedium  Condensed[0m
              [1mRoman [22m([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 [22mre‐
              quest that’s valid for [1mHelvetica[22m.

              Please see the Appendices, [4mAdding[24m [4mfonts[24m [4mto[24m [4mgroff[24m,  for  informa‐
              tion on adding fonts and families to [4mgroff[24m,[4mas[24mwell[4mas[24mto see a list
              of  the  extensions  [4mmom[24m  provides  to [4mgroff[24m’s basic [1mR[22m, [1mI[22m, [1mB[22m, [1mBI[0m
              styles.

              Suggestion: When adding [4mfamilies[24m [4mto[24m [4mgroff[24m, I recommend following
              the established standard for the naming families and fonts.  For
              example, 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.FAMI‐[0m
              [1mLY[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[24m 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 argu‐
              ments 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  dif‐
              fering weights and shapes within the same family.

              Have  a  look  here for a list of the weight/style arguments [4mmom[0m
              allows.  Be aware, though, that you must have  the  fonts,  cor‐
              rectly installed and named, in order to use the arguments.  (See
              [4mAdding[24m [4mfonts[24m [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
              version  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, us‐
              ing either the fallback font or the font that was in effect pri‐
              or to the invalid [1m.FT [22mcall.

              [1m.FT [22mwill also accept, as an argument, a  full  [4mfamily[24m  and  [4mfont[0m
              [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
              except 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  mea‐
              sure.

              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 [4min‐[0m
              [4mdent[24m 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
              [4mmeasure[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
              additive.   Each  time you pass a measure to [1m.HI[22m, the measure is
              treated literally.  [4mRecipe:[24m A numbered list  using  [4mhanging[24m  [4min‐[0m
              [4mdents[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 be‐
              gin  the first line with a number, a period, and a figure space,
              the actual text ([4mThe[24m [4mmost[24m [4mimportant[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 [4mmea‐[0m
              [4msure[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  in‐
              dents;  at subsequent invocations when you wish to supply a mea‐
              sure, both must be given again.  As with [1m.IL [22mand [1m.IR[22m,  the  mea‐
              sures  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 in‐
              dents 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 spec‐
              ify text‐dependent measures, in which case no unit of measure is
              required.  For example,
                     [1m.IB \w'margarine' \w'jello'[0m
              left indents text by the width of the word [4mmargarine[24m  and  right
              indents by the width of [4mjello[24m.

              Like  [1m.IL  [22mand [1m.IR[22m, [1m.IB [22mwith no argument indents by its last ac‐
              tive values.  See the brief explanation of how mom  handles  in‐
              dents 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[24m  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.  Sub‐
              sequent invocations with a measure add to the previous  measure.
              A  minus  sign may be prepended to the argument to subtract from
              the current measure.  The [1m\w [22minline escape may be used to speci‐
              fy 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 indicating that you should update your documents.

              As a consequence of this change, [1m.ILX[22m, [1m.IRX [22mand [1m.IBX [22mmay now al‐
              so be invoked as [1m.ILQ[22m, [1m.IRQ [22mand [1m.IBQ[22m.  Both  forms  are  accept‐
              able.

              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 having 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 sup‐
              ply a measure again.

              [1m.IQ CLEAR[22m, as you’d suspect, quits and clears the values for all
              indent 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.  Sub‐
              sequent  invocations  with  a measure add to the previous indent
              measure.  A [4mminus[24m [4msign[24m may be prepended to the argument to  sub‐
              tract 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 required.  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 val‐
              ue.

              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
              starting any serious typesetting.  A  unit  of  measure  is  re‐
              quired.   Decimal  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 invok‐
              ing [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
              document 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‐col‐[0m
              [4mumn[24m  [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 explanation of [4mmulti‐columns[24m and some sample in‐
              put.

              [4mNote:[24m Do not confuse [1m.MCO [22mwith the [1m.COLUMNS [22mmacro in  the  docu‐
              ment 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 mo‐
              ment [1m.MCX [22mis invoked.

              If you pass the [4m<distance>[24m argument to [1m.MCX[22m, it advances [4m1[24m [4mline‐[0m
              [4mspace[24m  below  the  longest  column (see above) [4mPLUS[24m the distance
              specified by the argument.  The argument requires a unit of mea‐
              sure; therefore, to advance an extra 6 points below  where  [1m.MCX[0m
              would normally place you, you’d enter
                     [1m.MCX 6p[0m

              [4mNote:[24m  If you wish to advance a precise distance below the base‐
              line of the longest column, use [1m.MCX [22mwith an argument of [1m0  [22m(ze‐
              ro;  no  [4munit[24m  [4mof[24m [4mmeasure[24m required) in conjunction with the [1m.ALD[0m
              macro, 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 something 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 mar‐
              gin,  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
              baseline  of  the  first line of text down by one linespace.  To
              compensate, 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
              enter
                     [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
              allowed.  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: [1mLETTER[22m, [1mLEGAL[22m, [1mSTATEMENT[22m, [1mTABLOID[22m, [1mLEDGER[22m, [1mFOLIO[22m,  [1mQUAR‐[0m
              [1mTO[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[24m  of something, [1m.PT_SIZE [22mdoes not require that you supply
              a [4munit[24m [4mof[24m [4mmeasure[24m since it’s a near  universal  convention  that
              [4mtype[24m  [4msize[24m is measured in [4mpoints[24m.  Therefore, to change the [4mtype[0m
              [4msize[24m to, say, [4m11[24m [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-[0m
              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[0m
              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 ex‐
              ample
                     [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  [22mre‐
              quires 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  invok‐
              ing  [1m.R_MARGIN  [22mafterward, [4mmom[24m automatically sets [1m.R_MARGIN [22mto [4m1[0m
              [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, overrid‐
              den.

              Note: [1m.R_MARGIN [22mbehaves in a special way when you’re  using  the
              document 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  direc‐
              tion 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  line‐
              space.  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
              conveniently, 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  zip‐
              ping  down the page with a left indent of [4m2[24m [4mpicas[24m turned on, and
              you call a [4mtab[24m 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 indent.

              [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[0m
              does not automatically move to the baseline of the first line in
              the [4mprevious[24m [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 [4mtem‐[0m
              [4mporary[24m [4mindent[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
              measure; [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
              additive.  In the following example, the second [1m".TI 2P" [22mis  ex‐
              actly [4m2[24m [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 [22mmacro 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[0m
              with the [1m\c [22minline escape sequence.  Conversely, if you did give
              a [1mQUAD [22margument 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
              entered
                     .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 fol‐
              lowing [1m.TN[22m.

       [1m.TQ    TQ [22mtakes you out of whatever [4mtab[24m you were in, advances  [4m1[24m  [4mline‐[0m
              [4mspace[24m, and restores the [4mleft[24m [4mmargin[24m, [4mline[24m [4mlength[24m, [4mquad[24m [4mdirection[0m
              and [4mfill[24m [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  measure,  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 baseline.  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  mar‐
              gins in document 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  posi‐
              tion  on  the current page.  Therefore, [1m.T_MARGIN [22mshould only be
              used at the top of a file (prior to entering text) or after NEW‐
              PAGE, like this:
                     [1m.NEWPAGE[0m
                     [1m.T_MARGIN 6P[0m
                     [4m<text>[0m

[1mAuthors[0m
       [4mmom[24m was written by Peter Schaffter ⟨peter@schaffter.ca⟩.   PDF  support
       was  provided by Deri James ⟨deri@chuzzlewit.myzen.co.uk⟩.  This manual
       page was written by Bernd Warken.

[1mSee also[0m
       [4m/usr/pkg/share/doc/groff-1.23.0/html/mom/toc.html[0m
              entry point to the HTML documentation

       ⟨http://www.schaffter.ca/mom/momdoc/toc.html⟩
              HTML documentation online

       ⟨http://www.schaffter.ca/mom/⟩
              the [4mmom[24m macros homepage

       [4mGroff:[24m [4mThe[24m [4mGNU[24m [4mImplementation[24m [4mof[24m [4mtroff[24m, by Trent A. Fisher  and  Werner
       Lemberg,  is the primary [4mgroff[24m manual.  You can browse it interactively
       with “info groff”.

       [4mpdfmom[24m(1), [4mgroff[24m(1), [4mgtroff[24m(1)

groff 1.23.0                      2 July 2023                     [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[0m
       document  formatting system.  The [4mms[24m package is suitable for the compo‐
       sition of letters, memoranda, reports, and books.

       These [4mgroff[24m macros support cover page and table of contents generation,
       automatically numbered headings, several paragraph styles, a variety of
       text styling options, footnotes, and  multi‐column  page  layouts.   [4mms[0m
       supports the [4mgtbl[24m(1), [4mgeqn[24m(1), [4mgpic[24m(1), and [4mgrefer[24m(1) preprocessors for
       inclusion of tables, mathematical equations, diagrams, and standardized
       bibliographic citations.

       This  implementation is mostly compatible with the documented interface
       and behavior of AT&T Unix Version 7 [4mms[24m.  Many  extensions  from  4.2BSD
       (Berkeley) and Tenth Edition Research Unix have been recreated.

[1mUsage[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  compose a simple document from scratch, begin it by calling
       [1m.LP [22mor [1m.PP[22m.  Longer documents have a structure as follows.

       [1mDocument type[0m
              Calling the [1mRP [22mmacro at the beginning of your document puts  the
              document description (see below) on a cover page.  Otherwise, [4mms[0m
              places  this information on the first page, followed immediately
              by the body text.  Some document types found in other [4mms[24m  imple‐
              mentations  are  specific  to AT&T or Berkeley, and are not sup‐
              ported in [4mgroff[24m [4mms[24m.

       [1mFormat and layout[0m
              By setting registers and strings, you can configure  your  docu‐
              ment’s  typeface,  margins,  spacing,  headers  and footers, and
              footnote arrangement.  See  subsection  “Document  control  set‐
              tings” below.

       [1mDocument description[0m
              A  document description consists of any of: a title, one or more
              authors’ names and affiliated institutions, an abstract,  and  a
              date  or other identifier.  See subsection “Document description
              macros” below.

       [1mBody text[0m
              The main matter of your document  follows  its  description  (if
              any).   [4mms[24m  supports  highly structured text consisting of para‐
              graphs interspersed with multi‐level  headings  (chapters,  sec‐
              tions,  subsections, and so forth) and augmented by lists, foot‐
              notes, tables, diagrams, and similar material.   The  preponder‐
              ance 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.
              You then call a macro to emit the table of contents at  the  end
              of your document.  The table of contents must necessarily follow
              the rest of the text since GNU [4mtroff[24m is a single‐pass formatter;
              it  thus  cannot  determine the page number of a division of the
              text until it has been set and output.  Since [4mms[24m output was  de‐
              signed  for  the production of hard copy, the traditional proce‐
              dure was to manually relocate the pages containing the table  of
              contents  between the cover page and the body text.  Today, page
              resequencing is more often done in the digital domain.  An index
              works similarly, but because it typically needs to be sorted af‐
              ter collection, its preparation requires separate processing.

   [1mDocument control settings[0m
       The following tables list the document control registers, strings,  and
       special 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 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 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 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 discus‐
       sion in the applicable section below.  The [1mPO[22m, [1mLL[22m, and [1mLT [22mregister  de‐
       faults vary by output device and paper format; the values shown are for
       typesetters  using  U.S. letter paper, and then terminals.  See section
       “Paper format” of [4mgroff[24m(1).  The [1mPD [22mand [1mDD  [22mregisters  use  the  larger
       value if the vertical motion quantum of the output device is too coarse
       for  the smaller one; usually, this is the case only for output to ter‐
       minals and emulators thereof.  The “gutter” affected  by  [1m\n[MINGW]  [22mis
       the  gap  between  columns  in  multiple‐column page arrangements.  The
       [1mTC-MARGIN [22mregister and [1mTC-LEADER [22mspecial character affect  the  format‐
       ting 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; [1m.DA [22mor [1m.ND [22mcan be called to set the  document  date
       (or  other identifier) at any time before (a) the abstract, if present,
       or (b) its information is required in a header or footer.  Use of these
       macros is optional, except that [1m.TL [22mis mandatory if any  of  [1m.RP[22m,  [1m.AU[22m,
       [1m.AI[22m, or [1m.AB [22mis called, and [1m.AE [22mis mandatory if [1m.AB [22mis called.

       [1m.RP [22m[[1mno-repeat-info[22m] [[1mno-renumber[22m]
              Use  the “report” (AT&T: “released paper”) format for your docu‐
              ment, creating a separate cover page.  The  default  arrangement
              is  to  place  most  of  the document description (title, author
              names and institutions, 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 on subsequently (but see the [1mDA [22mmacro below re‐
              garding the date).  Normally, [1m.RP [22msets the page number following
              the cover page to 1.  Specifying the optional [1mno-renumber  [22margu‐
              ment  suppresses  this alteration.  Optional arguments can occur
              in any order.  “[1mno[22m” is recognized as a synonym of [1mno-repeat-info[0m
              for AT&T compatibility.

       [1m.TL    [22mSpecify the document title.  [4mms[24m collects  text  on  input  lines
              following this call into the title until reaching [1m.AU[22m, [1m.AB[22m, or a
              heading or paragraphing macro call.

       [1m.AU    [22mSpecify  an author’s name.  [4mms[24m collects text on input lines fol‐
              lowing this call into the author’s name until reaching [1m.AI[22m, [1m.AB[22m,
              another [1m.AU[22m, or a heading or paragraphing macro call.   Call  it
              repeatedly to specify multiple authors.

       [1m.AI    [22mSpecify the preceding author’s institution.  An [1m.AU [22mcall is use‐
              fully  followed  by at most one [1m.AI [22mcall; if there are more, the
              last [1m.AI [22mcall controls.  [4mms[24m collects text on input lines follow‐
              ing this call into the author’s institution until reaching  [1m.AU[22m,
              [1m.AB[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 [1m.RP [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 [1m.RP [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 [1m.AE [22mcall.  By  de‐
              fault,  [4mms[24m  places  the  word “ABSTRACT” centered and in italics
              above the text of the abstract.  The optional argument “[1mno[22m” sup‐
              presses 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 ver‐
       tical  spacing  (distance  between  text baselines), respectively.  The
       font family and type size are ignored  on  terminal  devices.   Setting
       these  parameters  before the first call of a heading, paragraphing, or
       (non‐date) document description macro also  applies  them  to  headers,
       footers, and (for [1mFAM[22m) footnotes.

       The [1mHY [22mregister defines the automatic hyphenation mode used with the [1mhy[0m
       request.   Setting  [1m\n[HY]  [22mto [1m0 [22mis equivalent to using the [1mnh [22mrequest.
       This is a Tenth Edition Research Unix extension.

   [1mTypographical symbols[0m
       [4mms[24m provides a few strings to obtain typographical  symbols  not  easily
       entered with the keyboard.  These and many others are available as spe‐
       cial character escape sequences—see [4mgroff_char[24m(7).

       [1m\*[-]  [22mInterpolate an em dash.

       [1m\*[Q][0m
       [1m\*[U]  [22mInterpolate  typographer’s  quotation marks where available, and
              neutral 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.  All paragraphing macro calls cause the insertion
       of 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 is started close to the bottom of
       a page, and there is insufficient  space  to  accommodate  [1m\n[PORPHANS][0m
       lines  before  an automatic page break, then a page break is forced be‐
       fore the start of 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[[4mmarker[24m [[4mwidth[24m]]
              Set a paragraph with a left indentation.  The optional [4mmarker[24m is
              not indented and is empty by default.  [4mwidth[24m overrides  the  in‐
              dentation amount in [1m\n[PI][22m; its default unit is “[1mn[22m”.  Once spec‐
              ified,  [4mwidth[24m applies to further [1m.IP [22mcalls 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 in‐
              dented from both margins by [1m\n[QI][22m.  The text  between  [1m.QS  [22mand
              [1m.QE  [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]  [22mon  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[24m macros print headings in [1mbold [22musing the same font family and, by de‐
       fault, type size as the body text.  Headings  are  available  with  and
       without  automatic  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
              heading  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 output.  If [4mdepth[24m is omitted, it is taken to
              be [1m1[22m.  If you specify [4mdepth[24m 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[24m [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 in‐
              dices as their predecessors.  This feature is a Berkeley  exten‐
              sion.

       After  [1m.NH  [22mis  called,  the  assigned  number is made available in the
       strings [1mSN-DOT [22m(as it appears in a printed heading with default format‐
       ting, followed by a terminating period) and [1mSN-NO-DOT [22m(with the  termi‐
       nating period omitted).  These 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][0m
       is 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  [1m.NH  [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 documented by Berkeley); this string facili‐
       tates  its  inclusion in, for example, table captions, equation labels,
       and [1m.XS[22m/[1m.XA[22m/[1m.XE [22mtable of contents entries.

       [1m.SH [22m[[4mdepth[24m]
              Set an unnumbered heading.  The optional [4mdepth[24m argument is a GNU
              extension indicating the  heading  depth  corresponding  to  the
              [4mdepth[24m  argument  of  [1m.NH[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] [22mand [1m\n[PSINCR] [22mheading size adjustment mech‐
              anism 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
       increment 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 in‐
       cremental heading size feature.

       In other words, if the value of [1mGROWPS [22mregister  is  greater  than  the
       [4mdepth[24m  argument  to  a [1m.NH [22mor [1m.SH [22mcall, the type size of a heading pro‐
       duced by these macros increases by [1m\n[PSINCR] [22munits over [1m\n[PS]  [22mmulti‐
       plied by the difference of [1m\n[GROWPS] [22mand [4mdepth[24m.

       The  [1m\n[HORPHANS]  [22mregister  operates in conjunction with the [1mNH [22mand [1mSH[0m
       macros to inhibit the printing of isolated headings at the bottom of  a
       page;  it specifies the minimum number of lines of the subsequent para‐
       graph that must be kept on the same page as the heading.   If  insuffi‐
       cient  space remains on the current page to accommodate the heading and
       this number of lines of paragraph text, a page break is  forced  before
       the heading is printed.  Any display macro call or [4mtbl[24m, [4mpic[24m, or [4meqn[24m re‐
       gion  between  the heading and the subsequent paragraph suppresses this
       grouping.

   [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 intu‐
       itive.  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.  With‐
              out  arguments, [4mms[24m styles subsequent text in bold until the next
              paragraphing, heading, or no‐argument typeface macro call.

       [1m.R [22m[[4mtext[24m [[4mpost[24m [[4mpre[24m]]]
              As [1m.B[22m, but use the roman style (upright text of  normal  weight)
              instead of bold.  Argument recognition is a GNU extension.

       [1m.I [22m[[4mtext[24m [[4mpost[24m [[4mpre[24m]]]
              As [1m.B[22m, but use an italic or oblique style instead of bold.

       [1m.BI [22m[[4mtext[24m [[4mpost[24m [[4mpre[24m]]]
              As  [1m.B[22m,  but  use a bold italic or bold oblique style instead of
              upright bold.  This is a Tenth Edition Research Unix extension.

       [1m.CW [22m[[4mtext[24m [[4mpost[24m [[4mpre[24m]]]
              As [1m.B[22m, but use a constant‐width (monospaced) roman typeface  in‐
              stead of bold.  This is a Tenth Edition Research Unix extension.

       [1m.BX [22m[[4mtext[24m]
              Typeset [4mtext[24m and draw a box around it.  On terminal devices, re‐
              verse 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.  [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.   You  can specify this macro multiple times to en‐
              large the type size as needed.

       [1m.SM    [22mSet subsequent text in smaller type (2 points smaller  than  the
              current size) until the next type size, paragraphing, or heading
              macro call.  You can specify this macro multiple times to reduce
              the type size as needed.

       [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
       ordinarily 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  may  need to indent a region of text while otherwise formatting it
       normally.  Indented regions can be nested.

       [1m.RS    [22mBegin a region where headings, paragraphs, and displays are  in‐
              dented (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 its contents and allows text  following  the
       keep  (in  the source document) to fill in the remainder of the current
       page.  When the page breaks, whether by reaching the end or [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 argument 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; if you need to box  a  word  or  phrase
       within  a  line, see the [1mBX [22mmacro in section “Highlighting” above.  Box
       lines are drawn as close as possible to the text they enclose  so  that
       they  are  usable  within paragraphs.  If you wish to place one or more
       paragraphs in a boxed keep, you may improve their appearance by calling
       [1m.B1 [22mafter the first paragraphing macro, and by adding a small amount of
       vertical space before calling [1m.B2[22m.

       If you want a boxed keep to float, you will need to enclose the [1m.B1 [22mand
       [1m.B2 [22mcalls within a pair of [1m.KF [22mand [1m.KE [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[0m
       requests between lines.  Displays can be kept on a single page  or  al‐
       lowed 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
              centered.

       [1m.DS R[0m
       [1m.RD    [22mBegin  ([1mDS[22m:  kept)  right‐aligned display.  This is a GNU exten‐
              sion.

       [1m.DE    [22mEnd any display.

       The distance stored in [1m\n[DD] [22mis inserted before and after each pair of
       display macros; this is a Berkeley extension.  In [4mgroff[24m [4mms[24m,  this  dis‐
       tance  replaces  any  adjacent  inter‐paragraph  distance or subsequent
       spacing prior to a section heading.  The [1mDI [22mregister is  a  GNU  exten‐
       sion;  its value is an indentation applied to displays created with [1m.DS[0m
       and [1m.ID [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 ef‐
       fect at the next display boundary.

   [1mTables, figures, equations, and references[0m
       The [4mms[24m package is often used with the [4mgtbl[24m, [4mgpic[24m, [4mgeqn[24m, and [4mgrefer[24m pre‐
       processors.  The [1m\n[DD] [22mdistance is also applied to regions of the doc‐
       ument preprocessed with [4mgeqn[24m, [4mgpic[24m, and [4mgtbl[24m.  Mark text meant for pre‐
       processors  by enclosing it in pairs of tokens as follows, with nothing
       between the dot and the macro name.  The preprocessors match these  to‐
       kens only at the start of an input line.

       [1m.TS [22m[[1mH[22m]
       [1m.TE    [22mDemarcate  a table to be processed by the [4mtbl[24m preprocessor.  The
              optional [1mH [22margument instructs [4mms[24m to  repeat  table  rows  (often
              column headings) at the top of each new page the table spans, if
              applicable;  calling  the  [1mTH  [22mmacro marks the end of such rows.
              [4mgtbl[24m(1) provides a comprehensive reference to  the  preprocessor
              and offers examples of its use.

       [1m.PS[0m
       [1m.PE[0m
       [1m.PF    .PS  [22mbegins  a  picture to be processed by the [4mpic[24m preprocessor;
              either of [1m.PE [22mor [1m.PF [22mends it, the latter with “flyback”  to  the
              vertical position at its top.

       [1m.EQ [22m[[4malign[24m [[4mlabel[24m]]
       [1m.EN    [22mDemarcate  an  equation to be processed by the [4meqn[24m preprocessor.
              The equation is centered by default; [4malign[24m can be [1mC[22m, [1mL[22m, or [1mI  [22mto
              (explicitly) center, left‐align, or indent it by [1m\n[DI][22m, respec‐
              tively.  If specified, [4mlabel[24m is set right‐aligned.

       [1m.[[0m
       [1m.]     [22mDemarcate  a bibliographic citation to be processed by the [4mrefer[0m
              preprocessor.  [4mgrefer[24m(1) provides a comprehensive  reference  to
              the preprocessor and the format of its bibliographic database.

       When  [4mgrefer[24m  emits  collected references (as might be done on a “Works
       Cited” page), it interpolates the string [1m\*[REFERENCES]  [22mas  an  unnum‐
       bered heading ([1m.SH[22m).

       Attempting  to  place  a multi‐page table inside a keep can lead to un‐
       pleasant 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  [4mmarker,[0m
       which is a small integer, a symbol, or arbitrary user‐specified text.

       [1m\**    [22mPlace  an  [4mautomatic[24m  [4mnumber,[24m an automatically generated numeric
              footnote marker, in the text.  Each time this string is interpo‐
              lated, the number it produces increments by one.  Automatic num‐
              bers 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[[4mmarker[24m]
              Begin  a footnote.  The [1m.FS-MARK [22mhook (see below) is called with
              any supplied [4mmarker[24m argument, which is then also placed  at  the
              beginning  of the footnote text.  If [4mmarker[24m is omitted, the next
              pending automatic number enqueued  by  interpolation  of  the  [1m*[0m
              string 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 ar‐
       guments as [1m.FS [22mitself.  By default, this macro has an empty definition.
       [1m.FS-MARK [22mis a GNU extension.

       Footnote  text  is formatted as paragraphs are, using analogous parame‐
       ters.  The registers [1mFI[22m, [1mFPD[22m, [1mFPS[22m, and [1mFVS [22mcorrespond to  [1mPI[22m,  [1mPD[22m,  [1mPS[22m,
       and [1mVS[22m, respectively; [1mFPD[22m, [1mFPS[22m, and [1mFVS [22mare GNU extensions.

       The [1mFF [22mregister controls the formatting of automatically numbered foot‐
       note paragraphs, and those for which [1m.FS [22mis given a [4mmarker[24m argument, at
       the bottom of a column or page as follows.

              0      Set  an  automatic number, or a specified [1mFS [4m[22mmarker[24m argu‐
                     ment, as a superscript (on typesetter  devices)  or  sur‐
                     rounded  by square brackets (on terminals).  The footnote
                     paragraph is indented as with [1m.PP [22mif there is an [1m.FS  [22mar‐
                     gument or an automatic number, and as with [1m.LP [22motherwise.
                     This is the default.

              1      As  [1m0[22m,  but set the marker as regular text, and follow an
                     automatic number with a period.

              2      As [1m1[22m, but without indentation (like [1m.LP[22m).

              3      As [1m1[22m, but set the  footnote  paragraph  with  the  marker
                     hanging (like [1m.IP[22m).

   [1mLanguage and localization[0m
       [4mgroff[24m  [4mms[24m  provides several strings that you can customize for your own
       purposes, or redefine to adapt the macro  package  to  languages  other
       than English.  It is already localized for Czech, German, French, Ital‐
       ian,  and  Swedish.   Load the desired localization macro package after
       [4mms[24m; see [4mgroff_tmac[24m(5).

                  [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 de‐
       fine the strings [1mLH[22m, [1mCH[22m, and [1mRH [22mto set  the  left,  center,  and  right
       headers,  respectively; and [1mLF[22m, [1mCF[22m, and [1mRF [22mto set the left, center, and
       right footers.  This approach suffices for documents that do  not  dis‐
       tinguish 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 extensions.

       [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‐
              numbered  (verso)  pages, respectively; the [1mOF [22mand [1mEF [22mmacros de‐
              fine footers for them.

       With either method, a percent sign [1m% [22min header or footer  text  is  re‐
       placed  by the current page number.  By default, [4mms[24m places no header on
       a page numbered “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 num‐
              bered “1”.  This is a Berkeley extension.

       For  even  greater  flexibility,  [4mms[24m permits redefinition of the macros
       called when the page header and footer traps  are  sprung.   [1mPT  [22m(“page
       trap”)  is called by [4mms[24m when the header is to be written, and [1mBT [22m(“bot‐
       tom 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[0m
       macro  after  [1m.PT[22m; you can define [1m.HD [22mif you need additional processing
       after setting the header.  The [1mHD [22mhook is a  Berkeley  extension.   Any
       such  macros  you  (re)define must implement 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
       setting 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
       following 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 [22mand [1mPORPHANS [22mregisters work with respect to column breaks  in‐
       stead 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 argu‐
              ments, it is equivalent to the  [1m2C  [22mmacro.   Otherwise,  [4mcolumn‐[0m
              [4mwidth[24m  is the width of each column and [4mgutter‐width[24m is the mini‐
              mum distance between 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 [1m.XS[22m/[1m.XE [22mpairs, supplements an
       entry—for instance, when it requires multiple output lines, whether be‐
       cause 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 horizontal motion escape sequences, or by
       providing a second argument to the [1mXA [22mmacro.  [1m.XS [22mand [1m.XA [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; [1m.TC [22mre‐
       sets 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 en‐
              try 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 [1m.XA [22mwithin [1m.XS[22m/[1m.XE [22mis
              optional; it can be repeated.  If [4mindentation[24m is present, a sup‐
              plemental  entry  is indented by that amount; ens are assumed if
              no unit is indicated.  Text on input lines between [1m.XS  [22mand  [1m.XE[0m
              is stored for later recall by [1m.PX[22m.

       [1m.PX [22m[[1mno[22m]
              Switch  to single‐column layout.  Unless “[1mno[22m” is specified, cen‐
              ter 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[0m
       obviates the need to repeat heading text after [1m.XS [22mcalls.  Call [1m.XN [22mand
       [1m.XH [22mafter [1m.NH [22mand [1m.SH[22m, respectively.  Text to be appended to  the  for‐
       matted  section heading, but not to appear in the table of contents en‐
       try, can follow these calls.

       [1m.XN [4m[22mheading‐text[0m
              Format [4mheading‐text[24m and create a corresponding table of contents
              entry; the indentation is computed from the  [4mdepth[24m  argument  of
              the preceding [1mNH [22mcall.

       [1m.XH [4m[22mdepth[24m [4mheading‐text[0m
              As [1m.XN[22m, but use [4mdepth[24m to determine the indentation.

       [4mgroff[24m  [4mms[24m  encourages  customization of table of contents entry produc‐
       tion.  (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 [1m.XN [22mand [1m.XH[22m, and  call  [1mXN-INIT  [22mand
              [1mXH-INIT[22m,  respectively,  then  call [1mXH-UPDATE-TOC [22mwith the argu‐
              ments 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
       contents entry with its page number; define the [1mTC-LEADER [22mspecial char‐
       acter  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 de‐
       scribed above as Berkeley and Tenth Edition Research  Unix  extensions,
       and adds several of its own.

       •  The  internals  of  [4mgroff[24m  [4mms[24m  differ from the internals 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 documented in the AT&T [4mms[24m manual (“Typing Documents
          on  the  UNIX System: Using 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  er‐
          rors, rather than to ignore them silently.

       •  Tenth  Edition  Research Unix supported [1mP1[22m/[1mP2 [22mmacros to bracket code
          examples; [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 diag‐
          nostic message.

       •  Multiple line spacing is not supported.  Use a larger vertical spac‐
          ing 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[0m
          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
          displays, cause a reset of paragraph rendering parameters,  and  may
          change the indentation; they do so not by incrementing or decrement‐
          ing  it,  but by setting it absolutely.  This can cause problems for
          documents that define additional macros of their own that try to ma‐
          nipulate indentation.  Use [1m.RS [22mand [1m.RE [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[0m
          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  “Measurements”  in  the  [4mgroff[24m  Texinfo  manual  or in
          [4mgroff[24m(7)).  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 -rPS=10.5p[22m” at the shell prompt is
          equivalent to placing “[1m.nr PS 10.5p[22m” at the beginning of  the  docu‐
          ment.

       •  AT&T  [4mms[24m’s  [1mAU  [22mmacro  supported  arguments  used with some document
          types; [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[24m  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
          access the page number via the usual [1m% [22mregister and  invoke  the  [1maf[0m
          request  to assign a different format to it if desired.  (If you re‐
          define the [4mms[24m [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[24m [4mms[24m’s [1m.PT [22mdoes; see the macro package source.  [4mgroff[0m
          [4mms[24m aliases the [1mPN [22mregister to [1m%[22m.)

       •  The AT&T [4mms[24m manual documents registers [1mCW [22mand [1mGW [22mas setting the  de‐
          fault  column  width  and “intercolumn gap”, respectively, and which
          applied when [1m.MC [22mwas called with fewer than two arguments.  [4mgroff[24m [4mms[0m
          instead treats [1m.MC [22mwithout arguments as synonymous with  [1m.2C[22m;  there
          is  thus  no occasion for a default column width register.  Further,
          the [1mMINGW [22mregister and the second argument to [1m.MC [22mspecify a  [4mminimum[0m
          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[24m [4mms[24m do.

       •  The register [1mGS [22mis set to 1 by the [4mgroff[24m [4mms[24m macros, but is not  used
          by  the  AT&T  [4mms[24m package.  Documents that need to determine whether
          they are being formatted with [4mgroff[24m  [4mms[24m  or  another  implementation
          should test this register.

   [1mUnix Version 7 macros not implemented by [4mgroff[24m [4mms[0m
       Several  macros  described  in  the Unix Version 7 [4mms[24m documentation are
       unimplemented by [4mgroff[24m [4mms[24m because they are specific to the requirements
       of documents produced internally by Bell Laboratories,  some  of  which
       also  require a glyph for the Bell System logo that [4mgroff[24m does not sup‐
       port.  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  ad‐
       dresses of Bell Labs sites ([1mHO[22m, [1mIH[22m, [1mMH[22m, [1mPY[22m, [1mWH[22m), or lacked a stable de‐
       finition over time ([1mUX[22m).

[1mLegacy features[0m
       [4mgroff[24m  [4mms[24m  retains some legacy features solely to support formatting of
       historical documents; contemporary ones should  not  use  them  because
       they can render poorly.  See [4mgroff_char[24m(7) 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
       The following conventions are used for names of  macros,  strings,  and
       registers.  External names available to documents that use the [4mgroff[24m [4mms[0m
       macros contain only uppercase letters and digits.

       Internally, the macros are divided into modules.  Conventions for iden‐
       tifier names are 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.

       •  Constructed   names  used  to  implement  arrays  are  of  the  form
          [4marray[24m[1m![4m[22mindex[24m.

       Thus the [4mgroff[24m [4mms[24m macros reserve the following names:

       •  Names containing the characters [1m*[22m, [1m@[22m, and [1m:[22m.

       •  Names containing only uppercase letters and digits.

[1mFiles[0m
       [4m/usr/pkg/share/groff/1.23.0/tmac/s.tmac[0m
              implements the package.

       [4m/usr/pkg/share/groff/1.23.0/tmac/refer-ms.tmac[0m
              implements [4mgrefer[24m(1) support for [4mms[24m.

       [4m/usr/pkg/share/groff/1.23.0/tmac/ms.tmac[0m
              is a wrapper enabling the package to be loaded  with  “[1mgroff  -m[0m
              [1mms[22m”.

[1mAuthors[0m
       The  GNU version of the [4mms[24m macro package was written by James Clark and
       contributors.   This  document  was  written  by  Clark,  Larry  Kollar
       ⟨lkollar@despammed.com⟩,  and  G. Branden Robinson ⟨g.branden.robinson@
       gmail.com⟩.

[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/pkg/share/doc/groff-1.23.0/ms.ms[0m
       [4m/usr/pkg/share/doc/groff-1.23.0/ms.ps[0m
              “Using  [4mgroff[24m  with  the  [4mms[24m  Macro  Package”;  Larry Kollar and
              G. Branden Robinson.

       [4m/usr/pkg/share/doc/groff-1.23.0/msboxes.ms[0m
       [4m/usr/pkg/share/doc/groff-1.23.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 exten‐
              sion package, enabling colored, bordered boxes when the [1mpdf [22mout‐
              put device is used.

       [4mGroff:[24m [4mThe[24m [4mGNU[24m [4mImplementation[24m [4mof[24m [4mtroff[24m, by Trent A. Fisher  and  Werner
       Lemberg,  is the primary [4mgroff[24m manual.  You can browse it interactively
       with “info groff”.

       [4mgroff[24m(1), [4mgtroff[24m(1), [4mgtbl[24m(1), [4mgpic[24m(1), [4mgeqn[24m(1), [4mgrefer[24m(1)

groff 1.23.0                      2 July 2023                      [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
       [4mgroff[24m(7) based on the glyph mnemonics specified in RFC 1345 and the di‐
       graph 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
       sequence  with  a mnemonic glyph name, its second argument is a special
       character escape sequence based on the code point, and the comment  de‐
       scribes the glyph defined.

       The RFC 1345 glyph names cover a wide range of Unicode code points, in‐
       cluding  supplemental Latin, Greek, Cyrillic, Hebrew, Arabic, Hiragana,
       Katakana, and Bopomofo letters, punctuation,  math  notation,  currency
       symbols, industrial and entertainment icons, and box‐drawing symbols.

       The  Vim  digraph table is practically a subset of RFC 1345 (being lim‐
       ited to two‐character mnemonics), but, as a newer implementation,  adds
       four  mnemonics  not specified in the RFC (the horizontal ellipsis, the
       Euro sign, and two mappings for the rouble sign).  These have also been
       added to [4mrfc1345.tmac[24m.

       [4mrfc1345.tmac[24m contains a total of 1,696 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 contains 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 exam‐
       ple, “[1m\[<<][22m” means the “much less than” sign (U+226A) when [4mrfc1345.tmac[0m
       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
       [4mgroff_char[24m(7) 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  [4mgtroff[24m(1)  option  “[1m-m[0m
       [1mrfc1345[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  characters defined in [4mrfc1345.tmac[24m are accented Latin letters,
       and will be affected by this deficiency,  producing  subpar  typography
       ⟨https://savannah.gnu.org/bugs/?59932⟩.

[1mFiles[0m
       [4m/usr/pkg/share/groff/1.23.0/tmac/rfc1345.tmac[0m
              implements the character mappings.

[1mAuthors[0m
       [4mrfc1345.tmac[24m was contributed by Dorai Sitaram ⟨ds26gte@yahoo.com⟩.

[1mSee also[0m
       RFC  1345 ⟨https://tools.ietf.org/html/rfc1345⟩, by Keld Simonsen, June
       1992.

       The Vim digraph table can be listed using  the  [4mvim[24m(1)  command  “[1m:help[0m
       [1mdigraph-table[22m”.

       [4mgroff_char[24m(7)

groff 1.23.0                      2 July 2023                 [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 [4mgroff[24m(7) document formatting system,
       designed as an aid for debugging documents written in its language.  It
       issues 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 [4mgroff[24m(1)).  You can achieve finer  con‐
       trol  by  including  the macro file within the document; invoke the [1mmso[0m
       request, 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 argu‐
       ments are expanded one level more.  This causes problems if an argument
       uses four or more backslashes to delay interpretation of an escape  se‐
       quence.  For example, 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
       escape character that is not interpreted in copy mode.
              .foo \En[bar]

[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  stan‐
       dard 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 this when using a macro package like [4mms[24m or
       [4mmom[24m, where we may not want to be distracted  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 de‐
       fined (by [4ms.tmac[24m), their calls were not traced; contrast with the macro
       “Mymac”.

[1mFiles[0m
       [4m/usr/pkg/share/groff/1.23.0/tmac/trace.tmac[0m
              implements the package.

[1mAuthors[0m
       [4mtrace.tmac[24m was written by James Clark.  This document  was  written  by
       Bernd  Warken  ⟨groff-bernd.warken-72@web.de⟩  and  G. Branden Robinson
       ⟨g.branden.robinson@gmail.com⟩.

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

       [4mgroff[24m(1)
              gives an overview of the [4mgroff[24m document formatting system.

       [4mtroff[24m(1)
              supplies details of the [1m-m [22mcommand‐line option.

       [4mgroff_tmac[24m(5)
              offers a survey of [4mgroff[24m macro packages.

       [4mgroff[24m(7)
              is a reference manual for the [4mgroff[24m language.

groff 1.23.0                      2 July 2023                   [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  [4mgroff[24m(7) document formatting system.  This macro file is automati‐
       cally loaded by the default [4mtroffrc[24m file when  the  formatter  (usually
       [4mgroff[24m(1))  is  called with either of the options [1m-Thtml [22mor [1m-Txhtml[22m.  To
       see hyperlinks in action, format this man page using one of  those  op‐
       tions.

       This  document  is  a basic guide; the HTML output driver ([4mgrohtml[24m) re‐
       mains in an alpha state.  It has been included with the distribution to
       encourage testing.

       Here is a summary of the functions found in this macro set.

       .JOBNAME     split output into multiple files
       .HX          automatic heading level cut off
       .BCL         specify colours on a web page
       .BGIMG       specify background image
       .URL         create a URL using two parameters
       .FTP         create an FTP reference
       .MTO         create an HTML email address
       .TAG         generate an HTML name
       .IMG         include an image file
       .PIMG        include PNG image
       .MPIMG       place PNG on the margin and wrap text around it
       .HnS         begin heading
       .HnE         end heading
       .LK          emit automatically collected links.
       .HR          produce a horizontal rule
       .NHR         suppress automatic generation of rules.
       .HTL         only generate HTML title
       .HEAD        add data to <head> block
       .ULS         unorder list begin
       .ULE         unorder list end
       .OLS         ordered list begin
       .OLE         ordered list end
       .DLS         definition list begin
       .DLE         definition list end
       .LI          insert a list item
       .DC          generate a drop capital
       .HTML        pass an HTML raw request to the device driver
       .CDS         code example begin
       .CDE         code example end
       .ALN         place links on left of main text.
       .LNS         start a new two‐column table with links in the left.
       .LNE         end the two‐column table.
       .LINKSTYLE   initialize default URL attributes.

[1mMacros[0m
       [1m.JOBNAME filename[0m
              Split output into multiple HTML files.  A file is split whenever
              a .SH or .NH 1 is encountered.  Its argument is  the  file  stem
              name  for  future  output  files.   This option is equivalent to
              [4mgrohtml[24m’s [1m-j [22moption.

       [1m.HX n  [22mSpecify the cut off depth when  generating  links  from  section
              headings.   For example, a parameter of 2 would cause [4mgrohtml[24m to
              generate a list of links for [1m.NH 1 [22mand [1m.NH 2 [22mbut not for  [1m.NH 3[22m.
              Whereas

                     .HX 0

              tells  [4mgrohtml[24m  that  no heading links should be created at all.
              Another method for turning automatic headings off is by  issuing
              the command‐line switch [1m-P-l [22mto [4mgroff[24m.

       [1m.BCL [4m[22mforeground[24m [4mbackground[24m [4mactive[24m [4mnot‐visited[24m [4mvisited[0m
              This macro takes five parameters: foreground, background, active
              hypertext  link, hypertext link not yet visited, and visited hy‐
              pertext link colour.

       [1m.BGIMG imagefile[0m
              the only parameter to this macro is the background image file.

       [1m.URL url [description] [after][0m
              generates a URL using either one, two, or three arguments.   The
              first parameter is the actual URL, the second is the name of the
              link,  and the third is optional stuff to be printed immediately
              afterwards.  If [1mdescription [22mand [1mafter [22mare absent  then  the  [1mURL[0m
              becomes the anchor text.  Hyphenation is disabled while printing
              the actual URL; explicit breakpoints should be inserted with the
              [1m\:  [22mescape  sequence.   Here  is  how  to encode foo ⟨http://foo
              .org/⟩:

                     [1m.URL http://\:foo\:.org/ foo :[0m

              If this is processed by a device other than [1m-Thtml [22mor [1m-Txhtml [22mit
              appears as:

                     foo ⟨http://foo.org⟩:

              The URL macro can be of any type; for example, we can  reference
              Eric Raymond’s [4mpic[24m guide ⟨pic.html⟩ by:

                     [1m.URL pic\:.html "Eric Raymond's pic guide"[0m

       [1m.MTO address [description] [after][0m
              Generate  an email HTML reference.  The first argument is manda‐
              tory as the email address.  The optional second argument is  the
              text  you  see  in your browser.  If an empty argument is given,
              [1maddress [22mis used instead.  An optional third  argument  is  stuff
              printed  immediately  afterwards.  Hyphenation is disabled while
              printing the actual email address.  For example, Joe User  ⟨joe@
              user.org⟩ can be achieved by the following macro:

                     [1m.MTO joe@user.org "Joe User"[0m

              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  circumvent  this,  [1mwww.tmac [22minserts a zero‐width
              character which expands to a harmless space (only  if  run  with
              [1m-Thtml [22mor [1m-Txhtml[22m).

       [1m.FTP url [description] [after][0m
              indicates that data can be obtained via FTP.  The first argument
              is  the  URL  and the second is the browser text.  A third argu‐
              ment, similar to the macros above, is intended for stuff printed
              immediately afterwards.  The second and the third parameter  are
              optional.   Hyphenation  is  disabled  while printing the actual
              URL.  As an example, here is the location of the GNU FTP  server
              ⟨ftp://ftp.gnu.org/⟩.   The macro example above can be specified
              as:

                     [1m.FTP ftp://\:ftp\:.gnu\:.org/ "GNU FTP server" .[0m

       [1m.TAG name[0m
              Generates an HTML name tag from its argument.  This can then  be
              referenced using the URL ⟨#URL⟩ macro.  As you can see, you must
              precede the tag name with [1m# [22msince it is a local reference.  This
              link  was  achieved  via  placing  a  TAG in the URL description
              above; the source looks like this:

                     .TP
                     .B URL
                     generates
                     .TAG URL
                     a URL using either two or three arguments.
                     ...

       [1m.IMG [-R|-L|-C] filename [width] [height][0m
              Include a picture into the document.  The first argument is  the
              horizontal  location:  right,  left,  or center ([1m-R[22m, [1m-L[22m, or [1m-C[22m).
              Alignment is centered by default ([1m-C[22m).  The second  argument  is
              the  filename.   The optional third and fourth arguments are the
              width and height.  If the width is absent it defaults to 1 inch.
              If the height is absent it defaults to  the  width.   This  maps
              onto  an HTML img tag.  If you are including a PNG image then it
              is advisable to use the [1mPIMG [22mmacro.

       [1m.PIMG [-R|-L|-C] filename [width [height]][0m
              Include an image in PNG format.  This macro  takes  exactly  the
              same  parameters as the [1mIMG [22mmacro; it has the advantage of work‐
              ing with PostScript and HTML devices also since it can automati‐
              cally convert the image into the EPS format, using the following
              programs of the [1mnetpbm [22mpackage: [1mpngtopnm[22m, [1mpnmcrop[22m, and  [1mpnmtops[22m.
              If  the  document  isn’t  processed with [1m-Thtml [22mor [1m-Txhtml [22mit is
              necessary to use the [1m-U [22moption of [4mgroff[24m.

       [1m.MPIMG [-R|-L] [-G gap] filename [width [height]][0m
              Place a PNG image on the margin and wrap text  around  it.   The
              first parameters are optional.  The alignment: left or right ([1m-L[0m
              or [1m-R[22m) specifies the margin where the picture is placed at.  The
              default  alignment is left ([1m-L[22m).  Optionally, [1m-G [4m[22mgap[24m can be used
              to arrange a gap between the picture and  the  text  that  wraps
              around it.  The default gap width is zero.
              The  first  non‐optional argument is the filename.  The optional
              following arguments are the width and height.  If the  width  is
              absent  it  defaults  to 1 inch.  If the height is absent it de‐
              faults to the width.  Example:

                     .MPIMG -L -G 2c foo.png 3c 1.5c

              The height and width may also  be  given  as  percentages.   The
              PostScript  device calculates the width from the [1m.l [22mregister and
              the height from the [1m.p [22mregister.  For example:

                     .MPIMG -L -G 2c foo.png 15%

       [1m.HnS n [22mBegin heading.  The numeric heading level [4mn[24m is specified by  the
              first  parameter.   Use this macro if your headings contain URL,
              FTP or MTO macros.  Example:

                     .HnS 1
                     .HR
                     GNU Troff
                     .URL https://\:www\:.gnu\:.org/\:software/\:groff/
                     \[em]a
                     .URL http://www\:.gnu\:.org/ GNU
                     project.
                     .HR
                     .HnE

              In this case you might wish to disable automatic links to  head‐
              ings.  This can be done via [1m-P-l [22mfrom the command line.

       [1m.HnE   [22mEnd heading.

       [1m.LK    [22mForce [4mgrohtml[24m to place the automatically generated links at this
              position.

       [1m.HR    [22mGenerate  a  full‐width  horizontal rule for [1m-Thtml [22mand [1m-Txhtml[22m.
              No effect for all other devices.

       [1m.NHR   [22mSuppress generation of the top and bottom  rules  which  [4mgrohtml[0m
              emits by default.

       [1m.HTL   [22mGenerate  an HTML title only.  This differs from the [1mTL [22mmacro of
              the [1mms [22mmacro package which generates both an HTML title  and  an
              <H1>  heading.  Use it to provide an HTML title as search engine
              fodder but a graphic title in the document.   The  macro  termi‐
              nates when a space or break is seen (.sp, .br).

       [1m.HEAD  [22mAdd  arbitrary  HTML  data  to the <head> block.  Ignored if not
              processed with [1m-Thtml [22mor [1m-Txhtml[22m.  Example:

                     .HEAD "<link \
                       rel=""icon"" \
                       type=""image/png"" \
                       href=""http://foo.org//bar.png""/>"

       [1m.HTML  [22mAll text after this macro is treated as raw HTML.  If the  docu‐
              ment  is  processed  without [1m-Thtml [22mor [1m-Txhtml [22mthen the macro is
              ignored.  Internally, this macro is used as a building block for
              other higher‐level macros.

              For example, the [1mBGIMG [22mmacro is defined as

                     .de BGIMG
                     .   HTML <body background=\\$1>
                     ..

       [1m.DC l text [color][0m
              Produce a drop capital.  The first parameter is the letter to be
              dropped and enlarged, the second parameter [1mtext [22mis the adjoining
              text whose height the first letter should not exceed.   The  op‐
              tional  third  parameter is the color of the dropped letter.  It
              defaults to black.

       [1m.CDS   [22mStart displaying a code section in constant width font.

       [1m.CDE   [22mEnd code display

       [1m.ALN [color] [percentage][0m
              Place section heading links automatically to  the  left  of  the
              main  text.  The color argument is optional and if present indi‐
              cates which HTML background color is to be used under the links.
              The optional percentage indicates the amount of width to  devote
              to  displaying the links.  The default values are #eeeeee and 30
              for color and percentage width, respectively.  This macro should
              only be called once at the beginning  of  the  document.   After
              calling this macro each section heading emits an HTML table con‐
              sisting  of  the  links  in the left and the section text on the
              right.

       [1m.LNS   [22mStart a new two‐column table with  links  in  the  left  column.
              This can be called if the document has text before the first .SH
              and  if  .ALN is used.  Typically this is called just before the
              first paragraph and after the main title as  it  indicates  that
              text  after  this point should be positioned to the right of the
              left‐hand navigational links.

       [1m.LNE   [22mEnd a two‐column table.  This should be called at the end of the
              document if .ALN was used.

       [1m.LINKSTYLE color [ fontstyle [ openglyph closeglyph ] ][0m
              Initialize default URL attributes to be used if this  macro  set
              is not used with the HTML device.  The macro set initializes it‐
              self with the following call

                     .LINKSTYLE blue CR \[la] \[ra]

              but these values will be superseded by a user call to LINKSTYLE.

[1mSection heading links[0m
       By  default  [4mgrohtml[24m generates links to all section headings and places
       these at the top of the HTML document.  (See LINKS ⟨#LK⟩ for details of
       how to switch this off or alter the position).

[1mLimitations of [4mgrohtml[0m
       [4mgtbl[24m(1) tables are rendered as PNG images.  Paul DuBois’s approach with
       [4mtblcvt[24m(1), part of  the  [4mtroffcvt[24m  distribution  ⟨http://www.snake.net/
       software/troffcvt/⟩, should be explored.

[1mFiles[0m
       [4m/usr/pkg/share/groff/1.23.0/tmac/www.tmac[0m

[1mAuthors[0m
       The  [4mwww[24m  macro package was written by Gaius Mulley ⟨gaius@glam.ac.uk⟩,
       with  additions  by  Werner  Lemberg  ⟨wl@gnu.org⟩  and  Bernd   Warken
       ⟨groff-bernd.warken-72@web.de⟩.

[1mSee also[0m
       [4mgroff[24m(1), [4mgtroff[24m(1), [4mgrohtml[24m(1), [4mnetpbm[24m(1)

groff 1.23.0                      2 July 2023                     [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 in‐
       terpreter for an extensible text formatting language and a set of  pro‐
       grams 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 [4mPro‐[0m
       [4mgramming[24m [4mLanguage[24m and W. Richard Stevens’s [4mAdvanced[24m [4mProgramming[24m [4min[24m  [4mthe[0m
       [4mUnix[24m [4mEnvironment[24m have been written using [4mroff[24m systems.  GNU [4mroff[24m—[4mgroff[24m—
       is arguably the most widespread [4mroff[24m implementation.

       Below we present typographical concepts that form the background of all
       [4mroff[24m implementations, narrate the development history of some [4mroff[24m sys‐
       tems,  detail the command pipeline managed by [4mgroff[24m(1), survey the for‐
       matting language, suggest tips for editing [4mroff[24m  input,  and  recommend
       further reading materials.

[1mConcepts[0m
       [4mroff[24m input files contain text interspersed with instructions to control
       the  formatter.   Even in the absence of such instructions, a [4mroff[24m for‐
       matter still processes its input in several ways, by filling, hyphenat‐
       ing, breaking, and adjusting it, and supplementing it  with  inter‐sen‐
       tence space.  These processes are basic to typesetting, and can be con‐
       trolled at the input document’s discretion.

       When a device‐independent [4mroff[24m formatter starts up, it obtains informa‐
       tion  about  the  device for which it is preparing output from the lat‐
       ter’s description file (see [4mgroff_font[24m(5)).  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‐end‐
       ing 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 excep‐
       tions separate words.

       A [4mroff[24m formatter attempts to detect boundaries between  sentences,  and
       supplies  additional  inter‐sentence space between them.  It flags cer‐
       tain characters (normally “[1m![22m”, “[1m?[22m”, and “[1m.[22m”) as  potentially  ending  a
       sentence.   When  the formatter encounters one of these [4mend‐of‐sentence[0m
       [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 char‐
       acter 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 charac‐
       ter cancels detection of the end of a sentence.  However, several char‐
       acters are treated [4mtransparently[24m after the occurrence of an end‐of‐sen‐
       tence  character.   That is, a [4mroff[24m does not cancel end‐of‐sentence de‐
       tection when it processes them.  This is because  such  characters  are
       often  used  as footnote markers or to close quotations and parentheti‐
       cals.  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 se‐
       quences whose purpose is to obtain glyphs that are not easily typed  at
       the keyboard, or which have special meaning to the formatter (like [1m\[22m).

       When  an  output  line is nearly full, it is uncommon for the next word
       collected from the input to exactly fill it—typically,  there  is  room
       left  over  only for part of the next word.  The process of splitting a
       word so that it appears partially on one line (with a hyphen  to  indi‐
       cate to the reader that the word has been broken) with its remainder on
       the next is [4mhyphenation.[24m  Hyphenation points can be manually specified;
       [4mgroff[24m  also  uses a hyphenation algorithm and language‐specific pattern
       files to decide which words can be hyphenated and  where.   Hyphenation
       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 parame‐
       ters that can prevent it in certain circumstances.

       Once an output line is full, the next word (or remainder of  a  hyphen‐
       ated one) is placed on a different output line; this is called a [4mbreak.[0m
       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  automatic  break,  a  [4mroff[24m 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  out‐
       puts  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 being  [4madjusted[24m  (see  below).   Again,  macro
       packages  may  provide  other methods of producing indented paragraphs.
       Trailing spaces on [4mtext[24m [4mlines[24m (see below) are discarded.   The  end  of
       input causes a break.

       After the formatter performs an automatic break, it may then [4madjust[24m the
       line,  widening inter‐word spaces until the text reaches the right mar‐
       gin.  Extra spaces between words are preserved.  Leading  and  trailing
       spaces  are handled as noted above.  Text can be aligned to the left or
       right margin only, or centered, using [4mrequests.[0m

       A [4mroff[24m formatter translates horizontal tab characters, also called sim‐
       ply “tabs”, in the input into movements to the next  tab  stop.   These
       tab stops are by default located every half inch measured from the cur‐
       rent position on the input line.  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 fill‐
       ing.   The formatter provides facilities for sophisticated table compo‐
       sition; there are many details  to  track  when  using  the  “tab”  and
       “field”  low‐level  features,  so  most  users turn to the [4mgtbl[24m(1) pre‐
       processor to lay out tables.

   [1mRequests and macros[0m
       A [4mrequest[24m is an instruction to the formatter that occurs after  a  [4mcon‐[0m
       [4mtrol[24m  [4mcharacter,[24m which is recognized at the beginning of an input line.
       The regular control character is a dot “[1m.[22m”.  Its counterpart,  the  [4mno‐[0m
       [4mbreak[24m [4mcontrol[24m [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 is expecting 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[0m
       [4mline.[24m  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 the for‐
       matter is expected to perform.  If a request is meaningless without ar‐
       guments, it is typically ignored.  Of key importance are  the  requests
       that define macros.  Macros are invoked like requests, enabling the re‐
       quest repertoire to be extended or overridden.

       A  [4mmacro[24m can be thought of as an abbreviation you can define for a col‐
       lection 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.[0m
       Interpolations  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[24m [4munits,[24m a convenient length measure for the output
       device or file format.  The formatter and output driver use basic units
       to reckon page measurements.  The device description file  defines  its
       resolution and page dimensions (see [4mgroff_font[24m(5)).

       A  [4mpage[24m is a two‐dimensional structure upon which a [4mroff[24m system imposes
       a rectangular coordinate system with its upper left corner as the  ori‐
       gin.  Coordinate values are in basic units and increase down and to the
       right.   Useful  ones  are therefore always positive and within numeric
       ranges corresponding to the page boundaries.

       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 mea‐
       sured, or where a geometric object will  commence  rendering.   Notion‐
       ally,  glyphs are drawn from the text baseline upward and to the right.
       ([4mgroff[24m does not yet support right‐to‐left scripts.)  The [4mtext[24m  [4mbaseline[0m
       is  a  (usually invisible) line upon which the glyphs of a typeface are
       aligned.  A glyph therefore “starts” at  its  bottom‐left  corner.   If
       drawn  at  the  origin,  a  typical letter glyph would lie partially or
       wholly off the page, depending on whether, like “g”, it features a  de‐
       scender below the baseline.

       Such  a situation is nearly always undesirable.  It is furthermore con‐
       ventional not to write or draw  at  the  extreme  edges  of  the  page.
       Therefore  the  initial  drawing position of a [4mroff[24m formatter is not at
       the origin, but below and to the right of  it.   This  rightward  shift
       from the left edge is known as the [4mpage[24m [4moffset.[24m  ([4mgroff[24m’s terminal out‐
       put devices have page offsets of zero.)  The downward shift leaves room
       for a text output line.

       Text  is  arranged  on a one‐dimensional lattice of text baselines from
       the top to the bottom of the page.  [4mVertical[24m [4mspacing[24m  is  the  distance
       between adjacent text baselines.  Typographic tradition sets this quan‐
       tity  to  120% of the type size.  The initial vertical drawing position
       is one unit of vertical spacing below the page top.  Typographers  term
       this unit a [4mvee.[0m

       Vertical  spacing has an impact on page‐breaking decisions.  Generally,
       when a break occurs, the formatter moves the drawing  position  to  the
       next  text baseline automatically.  If the formatter were already writ‐
       ing to the last line that would fit on the page, advancing by  one  vee
       would  place the next text baseline off the page.  Rather than let that
       happen, [4mroff[24m formatters instruct the output driver to eject  the  page,
       start  a  new  one, and again set the drawing position to 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 will also
       break the page, producing a useless blank  one.   Macro  packages  keep
       users from having to confront this difficulty by setting “traps”; more‐
       over,  all but the simplest page layouts tend to have headers and foot‐
       ers, or at least bear vertical margins larger than 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;  fur‐
       ther, escape sequence recognition can be turned off and back on.

       [4mStrings[24m store character sequences.  In [4mgroff[24m, they can be parameterized
       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
       expressions to clarify their meaning when stored or interpolated.  Some
       read‐only predefined registers interpolate text.

       [4mFonts[24m are identified either by a name or by a mounting position (a non‐
       negative number).  Four styles are available on all devices.  [1mR [22mis “ro‐
       man”:  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 out‐
       put devices and usually underlined instead on terminal devices.  [1mBI  [22mis
       [4m[1mbold‐italic[24m[22m,  combining  both of the foregoing style variations.  Type‐
       setting devices group these four styles into [4mfamilies[24m  of  text  fonts;
       they  also  typically  offer one or more [4mspecial[24m fonts that provide un‐
       styled glyphs; see [4mgroff_char[24m(7).

       [4mgroff[24m supports named [4mcolors[24m for glyph rendering and drawing of  geomet‐
       ric  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
       distinction  between  those  two  elements is not always obvious (and a
       full discussion is beyond our scope).  In brief,  “A”  is  a  character
       when we consider 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 formatting  process  turns  input  characters  into  output
       glyphs.   A  few characters commonly seen on keyboards are treated spe‐
       cially by the [4mroff[24m language and may not look correct in output if  used
       unthinkingly;  they  are  the  (double) 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[24m [4mcharacter[24m escape sequences;
       see [4mgroff_char[24m(7).

       [4mgroff[24m  offers [4mstreams[24m, identifiers for writable files, but for security
       reasons this feature is disabled by default.

       A further few language elements arise as page layouts become  more  so‐
       phisticated  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  auto‐
       matically by the formatter, that is associated with a macro, calling it
       when that condition is fulfilled.

       Footnote  support  often exercises all three of the foregoing features.
       A simple implementation might work as follows.  A pair of macros is de‐
       fined: one starts a footnote and the other ends it.  The  author  calls
       the  first  macro where a footnote marker is desired.  The macro estab‐
       lishes a diversion so that the footnote text is collected at the  place
       in  the  body text where its corresponding marker appears.  An environ‐
       ment is created for the footnote so that it is set at a  smaller  type‐
       face.  The footnote text is formatted in the diversion using that envi‐
       ronment, 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 much more body text in the docu‐
       ment, a trap, set a small distance above the page  bottom,  is  sprung.
       The macro called by the trap draws a line across the page and emits the
       stored diversion.  Thus, the footnote is rendered.

[1mHistory[0m
       Computer‐driven  document formatting dates back to the 1960s.  The [4mroff[0m
       system 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 descendants, and because bits  were  expensive  in  those
       days;  five‐  and  six‐bit character encodings were still in widespread
       usage, and mixed‐case alphabetics in  file  names  seen  as  a  luxury.
       [4mRUNOFF[24m introduced a syntax of inlining formatting directives amid docu‐
       ment 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 overwhelm the former in popular
       usage and later derivatives of the program.  A sample of control  words
       from  a [4mRUNOFF[24m manual of December 1966 ⟨http://web.mit.edu/Saltzer/www/
       publications/ctss/AH.9.01.html⟩ was documented as follows (with the pa‐
       rameter notation slightly altered).  The abbreviations 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
       General  Electric (GE) to inaugurate the Multics ⟨http://www.multicians
       .org⟩ project.  After a few years, Bell Labs discontinued its  partici‐
       pation  in  Multics, famously prompting the development of Unix.  Mean‐
       while, Saltzer’s [4mRUNOFF[24m proved influential, seeing many ports  and  de‐
       rivations elsewhere.

       In  1969,  Doug  McIlroy wrote one such reimplementation, adding exten‐
       sions, 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  com‐
       mands  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  differ‐
       ently),  temporary indent ([1m.ti[22m), character translation ([1m.tr[22m), and auto‐
       matic 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 heuris‐
       tic system for automatically placing hyphenation points,  designed  and
       implemented  by  Molly Wagner.  It furthermore introduced numeric vari‐
       ables, termed registers.  By 1971, this program had been ported to Mul‐
       tics 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 [22mrequest, and what later [4mroff[24ms would call diversions were avail‐
       able  via  “footnote”  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 ac‐
       quire  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  typewriters) 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 practicali‐
       ties of preparing standardized documents like patent applications  (and
       Unix  manual  pages), combined with McIlroy’s enthusiasm for macro lan‐
       guages, perhaps created an irresistible pressure to make [4mroff[24m  extensi‐
       ble.   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 language—it sported a swath of features now  consid‐
       ered  essential  to [4mroff[24m systems: definition of macros ([1m.de[22m), diversion
       of text thither ([1m.di[22m), and removal 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).  Incremental 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 lead‐
       ers  ([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 configuration 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 [4mpipe[24m(2) 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 Murray Hill acquired a Graphic Systems  C/A/T  phototypesetter,
       and  with it came the necessity of expanding the capabilities of a [4mroff[0m
       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[24m (for  “typesetter  roff”).   Unfortunately,
       surviving  documentation  does not illustrate what requests were imple‐
       mented at this time for C/A/T support; the [4mtroff[24m(1) man page in  Fourth
       Edition  Unix  (November  1973) does not feature a request list, unlike
       [4mnroff[24m(1).  Apart from typesetter‐driven features, 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, ital‐
       ics, and a symbol font specially commissioned by Bell Labs from Graphic
       Systems, Kernighan and Lorinda Cherry implemented [4meqn[24m  for  typesetting
       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[24m programs in the “Troff User’s Manual”, first published  in  1976,
       with  further  revisions  as  late as 1992 by Kernighan.  (The original
       version was entitled “Nroff/Troff User’s Manual”, which  may  partially
       explain  why  [4mroff[24m practitioners have tended to refer to it by its AT&T
       document identifier, “CSTR #54”.)  Its final revision serves as the  [4mde[0m
       [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 System”, describing [4mms[24m and basic [4mnroff[24m/[4mtroff[24m usage, updat‐
       ing it as the package accrued features.  Sixth Edition 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
       documented  the  [4mman[24m  macro package, introducing most of the macros de‐
       scribed in [4mgroff_man[24m(7) 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
       device.   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 Benson‐Varian plotters.

       Ossanna  had passed away unexpectedly in 1977, and after the release of
       Version 7, with the C/A/T typesetter becoming supplanted by alternative
       devices 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  to‐
       day.   He  described these novelties in the article “A Typesetter‐inde‐
       pendent 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  print‐
       ers  with  built‐in  interpreters  for  it.  An output driver for Post‐
       Script, [4mdpost[24m, was swiftly developed.  However, AT&T’s software licens‐
       ing 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  distributed under copyleft ⟨http://www.gnu.org/copyleft⟩ licenses,
       ensuring to all the availability of source code and the freedom to mod‐
       ify and redistribute it, properties unprecedented in  [4mroff[24m  systems  to
       that  point.  [4mgroff[24m rapidly attracted contributors, and has served as a
       replacement for almost all applications of AT&T [4mtroff[24m  (exceptions  in‐
       clude [4mmv[24m, a macro package for preparation of viewgraphs and slides, and
       the  [4mideal[24m preprocessor, which produces diagrams from mathematical con‐
       straints).   Beyond  that,  it  has  added   numerous   features;   see
       [4mgroff_diff[24m(7).   Since  its  inception  and  for at least the following
       three decades, it has been used by practically all  GNU/Linux  and  BSD
       operating systems.

       [4mgroff[24m  continues to be developed, is available for almost all operating
       systems 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 Documenter’s Workbench (DWB) [4mtroff[24m (a descendant of the Bell  Labs
       code), released it under a free but GPL‐incompatible license.  This im‐
       plementation  ⟨https://github.com/n-t-roff/DWB3.3⟩ was made portable to
       modern POSIX systems, and adopted and enhanced first by  Gunnar  Ritter
       and   then   Carsten   Kunze   to   produce   Heirloom  Doctools  [4mtroff[0m
       ⟨https://github.com/n‐t‐roff/heirloom‐doctools⟩.

       In July 2013, Ali Gholami Rudi announced [4mneatroff[24m  ⟨https://github.com/
       aligrudi/neatroff⟩, a permissively licensed new implementation.

       Another  descendant  of  DWB  [4mtroff[24m  is  part of Plan 9 from User Space
       ⟨https://9fans.github.io/plan9port/⟩.  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  spe‐
       cific  to  a  macro package, like [4mmmroff[24m(1), or more general.  [4mgroff[24m(1)
       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, [4mgrog[24m(1), is available to infer from a document’s
       contents which [4mgroff[24m arguments 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  sec‐
       ondary  storage.   (On non‐Unix systems, pipelines may have to be simu‐
       lated 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 descrip‐
       tion  language that is then interpreted by a postprocessor for viewing,
       printing, or further processing.

       Each program interprets input in a language that is independent of  the
       others;  some  are purely descriptive, as with [4mgtbl[24m(1) and [4mroff[24m output,
       and some permit the definition of macros, as with [4mgeqn[24m(1) and [4mroff[24m  in‐
       put.   Most [4mroff[24m input files employ the macros of a document formatting
       package, intermixed with instructions for one  or  more  preprocessors,
       and seasoned with escape sequences and requests from the [4mroff[24m language.
       Some  documents are simpler still, since their formatting packages dis‐
       courage direct use of [4mroff[24m requests; man pages are a prominent example.
       Many features of the [4mroff[24m language are seldom needed by users; only au‐
       thors of macro packages require a substantial command of them.

   [1mPreprocessors[0m
       A [4mroff[24m preprocessor is a program that, directly or  ultimately,  gener‐
       ates output in the [4mroff[24m language.  Typically, each preprocessor defines
       a  language  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[0m
       input.  Preprocessors must consequently be run in an appropriate order;
       [4mgroff[24m(1)  handles  this automatically for all preprocessors supplied by
       the GNU [4mroff[24m system.

       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
       program  must  process it before the input is seen by the formatter, or
       incorrect rendering is almost guaranteed.

       GNU [4mroff[24m provides several preprocessors, including  [4mgeqn[24m,  [4mggrn[24m,  [4mgpic[24m,
       [4mgtbl[24m,  [4mgrefer[24m,  and  [4mgsoelim[24m.  See [4mgroff[24m(1) 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 [4mgroff_out[24m(5), intended for pro‐
       cessing by a selected device.  This page description language  is  spe‐
       cialized  in  its  parameters, but not its syntax, for the selected de‐
       vice; the format is device‐[4mindependent[24m, but not  device‐[4magnostic[24m.   The
       parameters the formatter uses to arrange the document are stored in [4mde‐[0m
       [4mvice[24m and [4mfont[24m [4mdescription[24m [4mfiles[24m; see [4mgroff_font[24m(5).

       AT&T  Unix  had two formatters—[4mnroff[24m for terminals, and [4mtroff[24m for type‐
       setters.  Often, the name [4mtroff[24m is used loosely to refer to both.  When
       generalizing thus, [4mgroff[24m documentation prefers the term “[4mroff[24m”.  In GNU
       [4mroff[24m, the formatter program is always [4mgtroff[24m(1).

   [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 unre‐
       lated software can interpret.  An  [4moutput[24m  [4mdriver[24m  is  a  program  that
       parses  the  output  of [4mtroff[24m and produces instructions specific to the
       device or file format it supports.  An output driver might support mul‐
       tiple devices, particularly if they are similar.

       The names of the devices and their driver programs  are  not  standard‐
       ized.   Technological  fashions  evolve;  the devices used for document
       preparation when AT&T [4mtroff[24m was first  written  in  the  1970s  are  no
       longer  used  in  production  environments.   Device  capabilities have
       tended to increase,  improving  resolution  and  font  repertoire,  and
       adding color output and hyperlinking.  Further, to reduce file size and
       processing time, AT&T [4mtroff[24m’s page description language placed low lim‐
       its on the magnitudes of some quantities it could represent.  Its Post‐
       Script output driver, [4mdpost[24m(1), had a resolution of 720 units per inch;
       [4mgroff[24m’s [4mgrops[24m(1) uses 72,000.

[4m[1mroff[24m programming[0m
       Documents  using  [4mroff[24m are normal text files interleaved with [4mroff[24m for‐
       matting elements.  The [4mroff[24m language is powerful enough to support  ar‐
       bitrary  computation  and  it supplies facilities that encourage exten‐
       sion.  The primary such facility is macro definition;  with  this  fea‐
       ture, macro packages have been developed that are tailored for particu‐
       lar 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  acquire  and  master.  The macro definitions of a package are
       typically kept in a file called  [4mname[24m[1m.tmac  [22m(historically,  [1mtmac.[4m[22mname[24m).
       Find  details  on  the  naming  and  placement  of  macro  packages  in
       [4mgroff_tmac[24m(5).

       A macro package anticipated for use in a document can  be  declared  to
       the formatter by the command‐line option [1m-m[22m; see [4mgtroff[24m(1).  It can al‐
       ternatively be specified within a document using the [1mmso [22mrequest of the
       [4mgroff[24m language; see [4mgroff[24m(7).

       Well‐known  macro  packages  include  [4mman[24m for traditional man pages and
       [4mmdoc[24m for BSD‐style manual pages.  Macro 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 All‐
       man), [4mmm[24m (from “memorandum macros”), and [4mmom[24m, a punningly named package
       exercising many [4mgroff[24m extensions.  See [4mgroff_tmac[24m(5) for more.

   [1mThe [4mroff[24m formatting language[0m
       The [4mroff[24m language provides requests, escape sequences, macro definition
       facilities,  string  variables, registers for storage of numbers or di‐
       mensions, 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 ex‐
       pressions 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 mater‐
       ial, or otherwise change the state of the parser.  The user can  define
       their  own  request‐like elements by composing together text, requests,
       and escape sequences [4mad[24m [4mlibitum.[24m  A document writer will not  (usually)
       note  any difference in usage for requests or macros; both are found on
       control lines.  However, there is a distinction; requests take either a
       fixed number of arguments (sometimes zero), silently ignoring  any  ex‐
       cess,  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 embedding a space in an  argument;  in  other
       words,  of  quoting it.  This then demands a mechanism of embedding the
       quoting character itself, in case [4mit[24m is needed literally in a macro ar‐
       gument.  AT&T [4mtroff[24m had complex rules involving the placement and repe‐
       tition of the double quote to achieve both aims.  [4mgroff[24m cuts this  knot
       by  supporting a special character escape sequence for the neutral dou‐
       ble 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
       anywhere, 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  inter‐
       polated 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  employ‐
       ing  “full‐service” macro packages (see [4mgroff_tmac[24m(5)) 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[0m
       suffix.

[1mInput conventions[0m
       Since [4mgtroff[24m fills text automatically, it is  common  practice  in  the
       [4mroff[24m  language  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
         recognition.   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 supple‐
         ments  to the sentence that are added, deleted, or updated to clarify
         it.  Parenthetical 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
         advice, makes it less common that an input line  will  wrap  in  your
         text  editor,  and  thus will help you perceive excessively long con‐
         structions in your text.  Recall that natural languages originate  in
         speech,  not  writing, 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, tab, 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 reflowing the input doesn’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.

       • 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  [4mgtroff[24m  to  ignore
         the remainder of the input line.

       • Use  the  empty request—a control character followed immediately by a
         newline—to visually manage separation of  material  in  input  files.
         Many  of  the  [4mgroff[24m project’s own documents use an empty request be‐
         tween sentences, after macro definitions, and where a  break  is  ex‐
         pected,  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  sugges‐
       tions 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[0m
       document is Emacs; see [4memacs[24m(1).  It provides an [4mnroff[24m major mode  that
       is suitable 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 method is to include 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, such as  those  commonly  used  by  man
         pages, trigger the automatic activation of the [4mnroff[24m mode.

       • Technically, having the sequence

                .\" -*- nroff -*-

         in the first line of a file will cause Emacs to enter the [4mnroff[24m major
         mode  when  it is loaded into the buffer.  Unfortunately, some imple‐
         mentations of the [4mman[24m(1) 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 [4mvim[24m(1),
       an extension of the [4mvi[24m(1) program.  Vim’s highlighting can be  made  to
       recognize  [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  configured to enable, several features; consult the editor’s
       online help topics “auto-setting”, “filetype”, and “syntax”.  Then  put
       the following at the end of your [4mroff[24m files, after any Emacs configura‐
       tion:

                     .\" 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 Bernd Warken ⟨groff-bernd.warken-72@web
       .de⟩ and G. Branden Robinson ⟨g.branden.robinson@gmail.com⟩.

[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
       [4mUnix[24m       [4mText[24m       [4mProcessing[24m       ⟨https://github.com/larrykollar/
       Unix-Text-Processing⟩, by Dale Dougherty and Tim O’Reilly, 1987, Hayden
       Books.  This well‐regarded text brings the reader from a  state  of  no
       knowledge  of Unix or text editing (if necessary) to sophisticated com‐
       puter‐aided typesetting.  It has been placed under a free software  li‐
       cense  by  its  authors and updated by a team of [4mgroff[24m contributors and
       enthusiasts.

       “History of Unix  Manpages”  ⟨http://manpages.bsd.lv/history.html⟩,  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 origi‐
       nal documentation and recollections of the authors and their  contempo‐
       raries.

       troff.org  ⟨http://www.troff.org/⟩,  Ralph  Corderoy’s [4mtroff[24m site, pro‐
       vides an overview and pointers to much historical [4mroff[24m information.

       Multicians ⟨http://www.multicians.org/⟩, a site by Multics enthusiasts,
       contains a lot of information on the MIT projects CTSS and Multics, in‐
       cluding [4mRUNOFF[24m; it is especially useful for its glossary and  the  many
       links to historical documents.

       The  Unix  Archive  ⟨http://www.tuhs.org/Archive/⟩, curated by the Unix
       Heritage Society, provides the source code and some binaries of histor‐
       ical Unices (including the source code of some versions  of  [4mtroff[24m  and
       its documentation) contributed by their copyright holders.

       Jerry Saltzer’s home page ⟨http://web.mit.edu/Saltzer/www/publications/
       pubs.html⟩  stores  some documents using the original [4mRUNOFF[24m formatting
       language.

       [4mgroff[24m ⟨http://www.gnu.org/software/groff⟩, GNU [4mroff[24m’s  web  site,  pro‐
       vides 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 significance are two mentioned in section “History”  above,
       describing  the language and its device‐independent implementation, re‐
       spectively.

       “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  Bernd
       Warken’s   “roff   classical”  GitHub  repository  ⟨https://github.com/
       bwarken/roff_classical.git⟩.

   [1mManual pages[0m
       As a system of multiple components, a [4mroff[24m system potentially has  many
       man pages, each describing an aspect of it.  Unfortunately, there is no
       consistent  naming  scheme for these pages among the different [4mroff[24m im‐
       plementations.

       For GNU [4mroff[24m, the [4mgroff[24m(1) man page enumerates all man  pages  distrib‐
       uted with the system, and individual pages frequently refer to external
       resources  as  well  as  manuals distributed with [4mgroff[24m on a variety of
       topics.

       With other [4mroff[24ms, you are on your own, but [4mtroff[24m(1)  might  be  a  good
       starting point.

groff 1.23.0                      2 July 2023                          [4mroff[24m(7)
