_a_d_d_f_t_i_n_f_o(1)                General Commands Manual               _a_d_d_f_t_i_n_f_o(1)

NNaammee
       addftinfo - add font metrics to _t_r_o_f_f fonts for use with _g_r_o_f_f

SSyynnooppssiiss
       aaddddffttiinnffoo [--aasscc--hheeiigghhtt _n] [--bbooddyy--ddeepptthh _n] [--bbooddyy--hheeiigghhtt _n]
                 [--ccaapp--hheeiigghhtt _n] [--ccoommmmaa--ddeepptthh _n] [--ddeesscc--ddeepptthh _n]
                 [--ffiigg--hheeiigghhtt _n] [--xx--hheeiigghhtt _n] _r_e_s_o_l_u_t_i_o_n _u_n_i_t_‐_w_i_d_t_h _f_o_n_t

       aaddddffttiinnffoo ----hheellpp

       aaddddffttiinnffoo --vv
       aaddddffttiinnffoo ----vveerrssiioonn

DDeessccrriippttiioonn
       _a_d_d_f_t_i_n_f_o  reads  an  AT&T _t_r_o_f_f font description file _f_o_n_t, adds addi‐
       tional font metric information required by GNU _t_r_o_f_f(1), and writes the
       combined result to the standard output.  The information added  is  de‐
       rived  from the font’s existing parameters and assumptions about tradi‐
       tional _t_r_o_f_f 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 _r_e_s_o_l_u_t_i_o_n and _u_n_i_t_‐_w_i_d_t_h arguments
       should be the same as the corresponding parameters in  the  _D_E_S_C  file.
       _f_o_n_t  is  the  name  of the file describing the font; if _f_o_n_t ends with
       “II”, the font is assumed to be oblique (or italic).

OOppttiioonnss
       ----hheellpp displays a usage message, while --vv and  ----vveerrssiioonn  show  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  _n  is in _s_c_a_l_e_d _p_o_i_n_t_s_, inches/_r_e_s_o_l_u_t_i_o_n for a font whose
       type size is _u_n_i_t_‐_w_i_d_t_h; see _g_r_o_f_f___f_o_n_t(5).

       --aasscc--hheeiigghhtt _n
              height of characters with ascenders, such as “b”, “d”, or “l”

       --bbooddyy--ddeepptthh _n
              depth of characters such as parentheses

       --bbooddyy--hheeiigghhtt _n
              height of characters such as parentheses

       --ccaapp--hheeiigghhtt _n
              height of uppercase letters such as “A”

       --ccoommmmaa--ddeepptthh _n
              depth of a comma

       --ddeesscc--ddeepptthh _n
              depth of characters with descenders, such as “p”, “q”, or “y”

       --ffiigg--hheeiigghhtt
              height of figures (numerals)

       --xx--hheeiigghhtt _n
              height of lowercase letters without ascenders such as “x”

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

SSeeee aallssoo
       _g_r_o_f_f___f_o_n_t(5), _g_r_o_f_f(1), _g_r_o_f_f___c_h_a_r(7)

groff 1.23.0                      3 June 2025                     _a_d_d_f_t_i_n_f_o(1)
───────────────────────────────────────────────────────────────────────────────
_a_f_m_t_o_d_i_t(1)                 General Commands Manual                _a_f_m_t_o_d_i_t(1)

NNaammee
       afmtodit  - adapt Adobe Font Metrics files for _g_r_o_f_f PostScript and PDF
       output

SSyynnooppssiiss
       aaffmmttooddiitt [--cckkmmnnssxx] [--aa _s_l_a_n_t] [--dd _d_e_v_i_c_e_‐_d_e_s_c_r_i_p_t_i_o_n_‐_f_i_l_e]
                [--ee _e_n_c_o_d_i_n_g_‐_f_i_l_e] [--ff _i_n_t_e_r_n_a_l_‐_n_a_m_e] [--ii _i_t_a_l_i_c_‐_c_o_r_r_e_c_t_i_o_n_‐
                _f_a_c_t_o_r] [--oo _o_u_t_p_u_t_‐_f_i_l_e] [--ww _s_p_a_c_e_‐_w_i_d_t_h] _a_f_m_‐_f_i_l_e _m_a_p_‐_f_i_l_e
                _f_o_n_t_‐_d_e_s_c_r_i_p_t_i_o_n_‐_f_i_l_e

       aaffmmttooddiitt ----hheellpp

       aaffmmttooddiitt --vv
       aaffmmttooddiitt ----vveerrssiioonn

DDeessccrriippttiioonn
       _a_f_m_t_o_d_i_t adapts an Adobe Font Metric file, _a_f_m_‐_f_i_l_e, for use  with  the
       ppss and ppddff output devices of _t_r_o_f_f(1).  _m_a_p_‐_f_i_l_e associates a _g_r_o_f_f or‐
       dinary  or special character name with a PostScript glyph name.  Output
       is written in _g_r_o_f_f___f_o_n_t(5) format  to  _f_o_n_t_‐_d_e_s_c_r_i_p_t_i_o_n_‐_f_i_l_e_,  a  file
       named for the intended _g_r_o_f_f font name (but see the --oo option).

       _m_a_p_‐_f_i_l_e should contain a sequence of lines of the form
              _p_s_‐_g_l_y_p_h _g_r_o_f_f_‐_c_h_a_r
       where  _p_s_‐_g_l_y_p_h  is the PostScript glyph name and _g_r_o_f_f_‐_c_h_a_r is a _g_r_o_f_f
       ordinary (if of unit length) or special (if longer)  character  identi‐
       fier.   The  same  _p_s_‐_g_l_y_p_h  can occur multiple times in the file; each
       _g_r_o_f_f_‐_c_h_a_r 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 _d_e_v_p_s_/_g_e_n_e_r_a_t_e subdirectory of the default font di‐
       rectory.

       If a PostScript glyph is not mentioned in _m_a_p_‐_f_i_l_e, and a _g_r_o_f_f charac‐
       ter name can’t be deduced using the Adobe Glyph List (AGL,  built  into
       _a_f_m_t_o_d_i_t),  then _a_f_m_t_o_d_i_t puts the PostScript glyph into the _g_r_o_f_f font
       description file as an unnamed glyph which can only be accessed by  the
       “\N”  escape  sequence in a _r_o_f_f document.  In particular, this is true
       for glyph variants named in the form “_f_o_o._b_a_r”; all  glyph  names  con‐
       taining  one or more periods are mapped to unnamed entities.  Unless --ee
       is specified, the encoding defined in the AFM file (i.e., entries  with
       non‐negative  codes)  is  used.   Refer  to  section “Using Symbols” in
       _G_r_o_f_f_: _T_h_e _G_N_U _I_m_p_l_e_m_e_n_t_a_t_i_o_n _o_f _t_r_o_f_f, the _g_r_o_f_f  Texinfo  manual,  or
       _g_r_o_f_f___c_h_a_r(7),  which describe how _g_r_o_f_f character identifiers are con‐
       structed.

       Glyphs not encoded in the AFM file (i.e., entries indexed as “-1”)  are
       still  available in _g_r_o_f_f; 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 _g_r_o_f_f 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  _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_p_s_/_d_o_w_n_l_o_a_d  and  _/_u_s_r_/
       _s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_p_d_f_/_d_o_w_n_l_o_a_d enables it to  be  embedded  in
       the output produced by _g_r_o_p_s(1) and _g_r_o_p_d_f(1), respectively.

       If  the  --ii  option is used, _a_f_m_t_o_d_i_t automatically generates an italic
       correction, a left italic correction, and a  subscript  correction  for
       each  glyph  (the significance of these is explained in _g_r_o_f_f___f_o_n_t(5));
       they can be specified for individual glyphs by adding to  the  _a_f_m_‐_f_i_l_e
       lines of the form:
              italicCorrection _p_s_‐_g_l_y_p_h _n
              leftItalicCorrection _p_s_‐_g_l_y_p_h _n
              subscriptCorrection _p_s_‐_g_l_y_p_h _n
       where _p_s_‐_g_l_y_p_h is the PostScript glyph name, and _n 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 --ss option should be given if the font is  “special”,  meaning  that
       _g_r_o_f_f  should  search  it  whenever a glyph is not found in the current
       font.  In that case, _f_o_n_t_‐_d_e_s_c_r_i_p_t_i_o_n_‐_f_i_l_e should be listed as an argu‐
       ment to the ffoonnttss directive in the output device’s _D_E_S_C file; if it  is
       not  special,  there is no need to do so, since _t_r_o_f_f(1) will automati‐
       cally mount it when it is first used.

OOppttiioonnss
       ----hheellpp displays a usage message, while --vv and  ----vveerrssiioonn  show  version
       information; all exit afterward.

       --aa _s_l_a_n_t
              Use  _s_l_a_n_t as the slant (“angle”) parameter in the font descrip‐
              tion file; this is used by _g_r_o_f_f in the positioning of  accents.
              By  default _a_f_m_t_o_d_i_t uses the negative of the IIttaalliiccAAnnggllee speci‐
              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 --aa to give it a smaller slant.

       --cc     Include  comments  in  the font description file identifying the
              PostScript font.

       --dd _d_e_v_i_c_e_‐_d_e_s_c_r_i_p_t_i_o_n_‐_f_i_l_e
              The device description file is _d_e_s_c_‐_f_i_l_e rather than the default
              _D_E_S_C.  If not found in the current directory, the  _d_e_v_p_s  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 --dd).

       --ee _e_n_c_o_d_i_n_g_‐_f_i_l_e
              The  PostScript font should be reencoded to use the encoding de‐
              scribed in _e_n_c_‐_f_i_l_e.  The format of  _e_n_c_‐_f_i_l_e  is  described  in
              _g_r_o_p_s(1).  If not found in the current directory, the _d_e_v_p_s sub‐
              directory of the default font directory is searched.

       --ff _i_n_t_e_r_n_a_l_‐_n_a_m_e
              The internal name of the _g_r_o_f_f font is set to _n_a_m_e.

       --ii _i_t_a_l_i_c_‐_c_o_r_r_e_c_t_i_o_n_‐_f_a_c_t_o_r
              Generate  an  italic correction for each glyph so that its width
              plus its italic correction is equal to  _i_t_a_l_i_c_‐_c_o_r_r_e_c_t_i_o_n_‐_f_a_c_t_o_r
              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
              _i_t_a_l_i_c_‐_c_o_r_r_e_c_t_i_o_n_‐_f_a_c_t_o_r 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 --mm is given.

              This option is normally needed only  with  italic  (or  oblique)
              fonts.   The  font description files distributed with _g_r_o_f_f were
              created using an option of --ii5500 for italic fonts.

       --oo _o_u_t_p_u_t_‐_f_i_l_e
              Write to _o_u_t_p_u_t_‐_f_i_l_e instead of _f_o_n_t_‐_d_e_s_c_r_i_p_t_i_o_n_‐_f_i_l_e_.

       --kk     Omit any kerning data from the _g_r_o_f_f font; use  only  for  mono‐
              spaced (constant‐width) fonts.

       --mm     Prevent  negative  left italic correction values.  Font descrip‐
              tion files for roman styles distributed with _g_r_o_f_f were  created
              with “--ii00 --mm” to improve spacing with _e_q_n(1).

       --nn     Don’t  output  a lliiggaattuurreess command for this font; use with mono‐
              spaced (constant‐width) fonts.

       --ss     Add the ssppeecciiaall directive to the font description file.

       --ww _s_p_a_c_e_‐_w_i_d_t_h
              Use _s_p_a_c_e_‐_w_i_d_t_h as the with of inter‐word spaces.

       --xx     Don’t use the built‐in Adobe Glyph List.

FFiilleess
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_p_s_/_D_E_S_C
              describes the ppss output device.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_p_s_/F
              describes the font known as _F on device ppss.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_p_s_/_d_o_w_n_l_o_a_d
              lists fonts available for embedding within the PostScript  docu‐
              ment (or download to the device).

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_p_s_/_g_e_n_e_r_a_t_e_/_d_i_n_g_b_a_t_s_._m_a_p
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_p_s_/_g_e_n_e_r_a_t_e_/_d_i_n_g_b_a_t_s_-_r_e_v_e_r_s_e_d_._m_a_p
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_p_s_/_g_e_n_e_r_a_t_e_/_s_l_a_n_t_e_d_-_s_y_m_b_o_l_._m_a_p
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_p_s_/_g_e_n_e_r_a_t_e_/_s_y_m_b_o_l_._m_a_p
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_p_s_/_g_e_n_e_r_a_t_e_/_t_e_x_t_._m_a_p
              map  names  in  the  Adobe Glyph List to _g_r_o_f_f special character
              identifiers for  Zapf  Dingbats  (ZZDD),  reversed  Zapf  Dingbats
              (ZZDDRR),  slanted symbol (SSSS), symbol (SS), and text fonts, respec‐
              tively.  These _m_a_p_‐_f_i_l_es are used to produce the  font  descrip‐
              tion files provided with _g_r_o_f_f for the _g_r_o_p_s output driver.

DDiiaaggnnoossttiiccss
       AGL name '_x' already mapped to groff name '_y'; ignoring AGL name
       'uni_X_X_X_X'
              You  can disregard these if they’re in the form shown, where the
              ignored AGL name contains four  hexadecimal  digits  _X_X_X_X.   The
              Adobe  Glyph  List  (AGL) has its own names for glyphs; they are
              often different from _g_r_o_f_f’s special character names.   _a_f_m_t_o_d_i_t
              is  constructing a mapping from _g_r_o_f_f 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 _a_f_m_t_o_d_i_t discards the excess map‐
              pings.  For example, if _x is **DD, _y is DDeellttaa, and _z  is  uunnii00339944,
              _a_f_m_t_o_d_i_t  is telling you that the _g_r_o_f_f font description that it
              is writing cannot map the _g_r_o_f_f special character \\[[**DD]]  to  AGL
              glyphs DDeellttaa and uunnii00339944 at 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  _m_a_p_‐_f_i_l_e
              and re‐run _a_f_m_t_o_d_i_t using it.

SSeeee aallssoo
       _G_r_o_f_f_:  _T_h_e  _G_N_U _I_m_p_l_e_m_e_n_t_a_t_i_o_n _o_f _t_r_o_f_f, by Trent A. Fisher and Werner
       Lemberg, is the primary _g_r_o_f_f manual.  Section “Using Symbols”  may  be
       of  particular  note.   You  can  browse  it  interactively  with “info
       '(groff)Using Symbols'”.

       _g_r_o_f_f(1), _g_r_o_p_d_f(1), _g_r_o_p_s(1), _g_r_o_f_f___f_o_n_t(5)

groff 1.23.0                      3 June 2025                      _a_f_m_t_o_d_i_t(1)
───────────────────────────────────────────────────────────────────────────────
_c_h_e_m(1)                     General Commands Manual                    _c_h_e_m(1)

NNaammee
       chem - embed chemical structure diagrams in _g_r_o_f_f documents

SSyynnooppssiiss
       cchheemm [----] [_f_i_l_e ...]

       cchheemm --hh
       cchheemm ----hheellpp

       cchheemm --vv
       cchheemm ----vveerrssiioonn

DDeessccrriippttiioonn
       _c_h_e_m produces chemical structure diagrams.   Today’s  version  is  best
       suited  for  organic  chemistry  (bonds, rings).  The _c_h_e_m program is a
       _g_r_o_f_f preprocessor like _e_q_n, _p_i_c, _t_b_l, etc.  It  generates  _p_i_c  output
       such  that  all _c_h_e_m parts are translated into diagrams of the _p_i_c lan‐
       guage.

       If no operands are given, or if _f_i_l_e is “--”, _c_h_e_m  reads  the  standard
       input  stream.   --hh  and ----hheellpp display a usage message, whereas --vv and
       ----vveerrssiioonn display version information; all exit.

       The program _c_h_e_m originates from the  Perl  source  file  _c_h_e_m_._p_l.   It
       tells  _p_i_c  to include a copy of the macro file _c_h_e_m_._p_i_c.  Moreover the
       _g_r_o_f_f source file _p_i_c_._t_m_a_c is loaded.

       In a style reminiscent of _e_q_n and _p_i_c, the _c_h_e_m diagrams are written in
       a special language.

       A set of _c_h_e_m lines looks like this

              .cstart
              _c_h_e_m _d_a_t_a
              .cend

       Lines containing the keywords ..ccssttaarrtt and ..cceenndd start and end the input
       for _c_h_e_m, respectively.  In _p_i_c context, i.e., after the call  of  ..PPSS,
       _c_h_e_m  input  can optionally be started by the line bbeeggiinn cchheemm and ended
       by the line with the single word eenndd instead.

       Anything outside these initialization lines is copied  through  without
       modification;  all  data  between the initialization lines is converted
       into _p_i_c commands to draw the diagram.

       As an example,

              .cstart
              CH3
              bond
              CH3
              .cend

       prints two CCHH33 groups with a bond between them.

       If you want to create just _g_r_o_f_f output, you must run _c_h_e_m followed  by
       _g_r_o_f_f with the option --pp for the activation of _p_i_c:

              _c_h_e_m [_f_i_l_e ...] || ggrrooffff --pp ...

LLaanngguuaaggee
       The  _c_h_e_m 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., CC, NNHH33, ..., and strings.

   SSeettttiinngg vvaarriiaabblleess
       There  are  some  variables that can be set by commands.  Such commands
       have two possible forms, either

              _v_a_r_i_a_b_l_e _v_a_l_u_e

       or

              _v_a_r_i_a_b_l_e == _v_a_l_u_e

       This sets the given _v_a_r_i_a_b_l_e to the argument _v_a_l_u_e.  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:

       tteexxtthhtt _a_r_g
              Set the height of the text to _a_r_g; default is 0.16.

       ccwwiidd _a_r_g
              Set the character width to _a_r_g; default is 0.12.

       ddbb _a_r_g Set the bond length to _a_r_g; default is 0.2.

       ssiizzee _a_r_g
              Scale the diagram to make it look plausible at point  size  _a_r_g;
              default is 10 point.

   BBoonnddss
       This

              bboonndd [_d_i_r_e_c_t_i_o_n] [_l_e_n_g_t_h _n] [ffrroomm _N_a_m_e|_p_i_c_s_t_u_f_f]

       draws a single bond in direction from nearest corner of _N_a_m_e.  bboonndd can
       also  be ddoouubbllee bboonndd, ffrroonntt bboonndd, bbaacckk bboonndd, etc.  (We will get back to
       _N_a_m_e soon.)

       _d_i_r_e_c_t_i_o_n is the angle in degrees (0 up, positive clockwise) or  a  di‐
       rection  word like uupp, ddoowwnn, ssww (= 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 ffrroomm place.  For instance, to make a  simple  alkyl
       chain:
              CCHH33
              bboonndd                (this one goes right from the CH3)
              CC                   (at the right end of the bond)
              ddoouubbllee bboonndd uupp      (from the C)
              OO                   (at the end of the double bond)
              bboonndd rriigghhtt ffrroomm CC
              CCHH33

       A  length  in  inches  may be specified to override the default length.
       Other _p_i_c commands can be tacked on to the end of a  bond  command,  to
       created dotted or dashed bonds or to specify a ttoo place.

   RRiinnggss
       There  are  lots  of rings, but only five‐ and six‐sided rings get much
       support.  rriinngg by itself is a six‐sided ring; bbeennzzeennee  is  the  benzene
       ring  with  a  circle  inside.  aarroommaattiicc puts a circle into any kind of
       ring.

              rriinngg [ppooiinnttiinngg (uupp|rriigghhtt|lleefftt|ddoowwnn)] [aarroommaattiicc] [ppuutt MMooll aatt _n]
                   [ddoouubbllee _i,_j _k,_l ... [_p_i_c_s_t_u_f_f]

       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 ..VV11, ..., ..VV_n, with ..VV11 in the pointing di‐
       rection.  So the corners of RR11 are RR11..VV11 (the _t_o_p), RR11..VV22, RR11..VV33, RR11..VV44
       (the  _b_o_t_t_o_m),  etc., whereas for RR22, RR22..VV11 is the rightmost vertex and
       RR22..VV44 the 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 ddoouubbllee _n_1,,_n_2 _n_3,,_n_4 ...;; each
       number pair adds an interior bond.  So the alternate form of a  benzene
       ring is

              rriinngg ddoouubbllee 11,,22 33,,44 55,,66

       Heterocycles  (rings  with something other than carbon at a vertex) are
       written as ppuutt _X aatt _V, as in

              RR:: rriinngg ppuutt NN aatt 11 ppuutt OO aatt 22

       In this heterocycle, RR..NN and RR..OO become synonyms for RR..VV11 and RR..VV22.

       There are two five‐sided rings.  rriinngg55 is pentagonal with a  side  that
       matches the six‐sided ring; it has four natural directions.  A ffllaattrriinngg
       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.

   MMooiieettiieess aanndd ssttrriinnggss
       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.,

              BB11:: bboonndd ;; OOHH

       Here the moiety is OOHH; it is set after a bond.

       As the second kind a moiety can be positioned as the first  word  in  a
       _p_i_c‐like command, e.g.,

              CCHH33 aatt CC ++ ((00..55,,00..55))

       Here  the  moiety  is CCHH33.  It is placed at a position relative to CC, a
       moiety used earlier in the chemical structure.

       So moiety names can be specified as _c_h_e_m positions  everywhere  in  the
       _c_h_e_m code.  Beneath their printing moieties are names for places.

       The  moiety BBPP is special.  It is not printed but just serves as a mark
       to be referred to in later _c_h_e_m commands.  For example,

              bboonndd ;; BBPP

       sets a mark at the end of the bond.  This can be used then for specify‐
       ing a place.  The name BBPP is derived  from  _b_r_a_n_c_h  _p_o_i_n_t  (i.e.,  line
       crossing).

       A string within double quotes "" is interpreted as a part of a _c_h_e_m com‐
       mand.   It  represents  a  string  that  should be printed (without the
       quotes).  Text within quotes ""..."" is treated more or less like a  moi‐
       ety except that no changes are made to the quoted part.

   NNaammeess
       In  the  alkyl chain above, notice that the carbon atom CC was 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

              _N_a_m_e:: ...

       _N_a_m_e is often the name of a moiety like CCHH33, but it  need  not  to  be.
       Any name that begins with a capital letter and which contains only let‐
       ters and numbers is valid:

              FFiirrsstt:: bboonndd
                     bboonndd 3300 ffrroomm FFiirrsstt

   MMiisscceellllaanneeoouuss
       The specific construction

              bboonndd ... ;; mmooiieettyy

       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 .. or a single quote '' in the first column of a line
       signals a _t_r_o_f_f command, which is copied through as‐is.

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

       A  line  whose first word is ppiicc is copied through as‐is after the word
       ppiicc has been removed.

       The command

              ssiizzee _n

       scales the diagram to make it look plausible at point size  _n  (default
       is 10 point).

       Anything else is assumed to be _p_i_c code, which is copied through with a
       label.

       Since  _c_h_e_m is a _p_i_c preprocessor, it is possible to include _p_i_c state‐
       ments in the middle of a diagram to draw things  not  provided  for  by
       _c_h_e_m  itself.   Such  _p_i_c statements should be included in _c_h_e_m code by
       adding ppiicc as the first word of this line for clarity.

       The following _p_i_c commands are accepted as _c_h_e_m  commands,  so  no  ppiicc
       command word is needed:

              ddeeffiinnee Start the definition of _p_i_c macro within _c_h_e_m.

              [[      Start a block composite.

              ]]      End a block composite.

              {{      Start a macro definition block.

              }}      End a macro definition block.

       The macro names from ddeeffiinnee statements are stored and their call is ac‐
       cepted as a _c_h_e_m command as well.

   WWiisshh lliisstt
       This TODO list was collected by Brian Kernighan.

       Error  checking is minimal; errors are usually detected and reported in
       an oblique fashion by _p_i_c.

       There is no library or file inclusion mechanism, and there is no short‐
       hand for repetitive structures.

       The extension mechanism is to create _p_i_c 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 $$...$$ con‐
       struct of _e_q_n).

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

       There is no decent primitive for brackets.

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

       A squiggle bond is needed.

FFiilleess
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_p_i_c_/_c_h_e_m_._p_i_c
              A collection of _p_i_c macros needed by _c_h_e_m.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_p_i_c_._t_m_a_c
              A macro file which redefines ..PPSS, ..PPEE, and ..PPFF to center _p_i_c di‐
              agrams.

       _/_u_s_r_/_s_h_a_r_e_/_d_o_c_/_g_r_o_f_f_-_b_a_s_e_/_e_x_a_m_p_l_e_s_/_c_h_e_m_/*_._c_h_e_m
              Example files for _c_h_e_m.

       _/_u_s_r_/_s_h_a_r_e_/_d_o_c_/_g_r_o_f_f_-_b_a_s_e_/_e_x_a_m_p_l_e_s_/_c_h_e_m_/_1_2_2_/*_._c_h_e_m
              Example files from the _c_h_e_m article by its authors, “CHEM—A Pro‐
              gram  for  Typesetting Chemical Structure Diagrams: User Manual”
              (CSTR #122).

AAuutthhoorrss
       The GNU version of _c_h_e_m was written by Bernd Warken.  It  is  based  on
       the documentation of Brian Kernighan’s original _a_w_k version of _c_h_e_m.

SSeeee aallssoo
       “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

       _g_r_o_f_f(1), _p_i_c(1)

groff 1.23.0                      3 June 2025                          _c_h_e_m(1)
───────────────────────────────────────────────────────────────────────────────
_e_q_n(1)                      General Commands Manual                     _e_q_n(1)

NNaammee
       eqn - format mathematics (equations) for _g_r_o_f_f or MathML

SSyynnooppssiiss
       eeqqnn [--CCNNrrRR] [--d _x_y] [--ff _F] [--mm _n] [--MM _d_i_r] [--pp _n] [--ss _n] [--TT _d_e_v]
           [_f_i_l_e ...]

       eeqqnn ----hheellpp

       eeqqnn --vv
       eeqqnn ----vveerrssiioonn

DDeessccrriippttiioonn
       The  GNU implementation of _e_q_n is part of the _g_r_o_f_f(7) document format‐
       ting system.  _e_q_n is a _t_r_o_f_f(1) preprocessor  that  translates  expres‐
       sions in its own language, embedded in _r_o_f_f(7) input files, into mathe‐
       matical  notation  typeset by _t_r_o_f_f(1).  It copies each _f_i_l_e’s contents
       to the standard output stream, translating each _e_q_u_a_t_i_o_n between  lines
       starting  with  ..EEQQ  and ..EENN, or within a pair of user‐specified delim‐
       iters.  Normally, _e_q_n is not executed directly by the user, but invoked
       by specifying the --ee option to _g_r_o_f_f(1).  While GNU _e_q_n’s input  syntax
       is  highly  compatible with AT&T _e_q_n, the output _e_q_n produces cannot be
       processed by AT&T _t_r_o_f_f; GNU _t_r_o_f_f (or a  _t_r_o_f_f  implementing  relevant
       GNU  extensions)  must  be  used.  If no _f_i_l_e operands are given on the
       command line, or if _f_i_l_e is “--”, _e_q_n reads the standard input stream.

       Unless the --RR option is used, _e_q_n searches for the file  _e_q_n_r_c  in  the
       directories  given  with the --MM option first, then in _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/
       _s_i_t_e_-_t_m_a_c, and finally in  the  standard  macro  directory  _/_u_s_r_/_s_h_a_r_e_/
       _g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c.   If it exists and is readable, _e_q_n processes it be‐
       fore any input files.

       This man page primarily discusses the differences between GNU  _e_q_n  and
       AT&T  _e_q_n.   Most of the new features of the GNU _e_q_n input language are
       based on TeX.  There are some references to the differences between TeX
       and GNU _e_q_n below; these may safely be ignored if you do not know TeX.

       Three points are worth special note.

       • GNU _e_q_n emits  Presentation  MathML  output  when  invoked  with  the
         “--TT MMaatthhMMLL” option.

       • GNU _e_q_n does not support terminal devices well, though it may suffice
         for simple inputs.

       • GNU  _e_q_n  sets the input token “......” as an ellipsis on the text base‐
         line, not the three centered dots of AT&T _e_q_n.  Set  an  ellipsis  on
         the math axis with the GNU extension macro ccddoottss.

   AAnnaattoommyy ooff aann eeqquuaattiioonn
       _e_q_n  input  consists of tokens.  Consider a form of Newton’s second law
       of motion.  The input

              .EQ
              F =
              m a
              .EN

       becomes _F=_m_a.  Each of FF, ==, mm, and aa is 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.

       {{ }}    Braces  perform  grouping.  Whereas “ee ssuupp aa bb” expresses “(_e to
              the _a) times _b”, “ee ssuupp {{ aa bb }}” means “_e to the (_a  times  _b)”.
              When  immediately  preceded  by a “lleefftt” or “rriigghhtt” primitive, a
              brace loses its special meaning.

       ^^ ~~    are the _h_a_l_f _s_p_a_c_e and _f_u_l_l _s_p_a_c_e_, 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  _e_q_n  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;  _e_q_n 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.

       _P_r_i_m_i_t_i_v_e_s are fundamental keywords of the _e_q_n language.  They can con‐
       figure  an  aspect  of  the  preprocessor’s  state,  as  when setting a
       “global” font selection or type size (ggffoonntt and ggssiizzee), or declaring or
       deleting macros (“ddeeffiinnee” and uunnddeeff); these are termed _c_o_m_m_a_n_d_s_.  Other
       primitives perform formatting operations on the tokens after  them  (as
       with ffaatt, oovveerr, ssqqrrtt, or uupp).

       Equation  _c_o_m_p_o_n_e_n_t_s include mathematical variables, constants, numeric
       literals, and operators.  _e_q_n remaps some input character sequences  to
       _g_r_o_f_f  special character escape sequences for economy in equation entry
       and to  ensure  that  glyphs  from  an  unstyled  font  are  used;  see
       _g_r_o_f_f___c_h_a_r(7).

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

       _M_a_c_r_o_s  permit primitives, components, and other macros to be collected
       and referred to by a single token.  Predefined macros  make  convenient
       the  preparation  of  _e_q_n input in a form resembling its spoken expres‐
       sion; for example, consider ccooss, hhaatt, iinnff, and lliimm.

   SSppaacciinngg aanndd ttyyppeeffaaccee
       GNU _e_q_n 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 “lleetttteerr”  subtype  of  “oorrddiinnaarryy”
       also assigns a style.

         ordinary      character such as “1”, “a”, or “!”
           letter      character to be italicized by default
           digit       _n_/_a
         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.

       ttyyppee _t _e
              Apply type _t to expression _e.

       cchhaarrttyyppee _t _t_e_x_t
              Assign each character in (unquoted) _t_e_x_t type _t, persistently.

       _e_q_n 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"    ^~

       _e_q_n  assigns  all other ordinary and special _r_o_f_f characters, including
       numerals 0–9, the “oorrddiinnaarryy” type.  (The “ddiiggiitt” 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  “lleetttteerr” type to style them in italics.  The macros
       for producing ellipses, “......”, ccddoottss, and llddoottss, use the “iinnnneerr” type.

   PPrriimmiittiivveess
       _e_q_n supports without alteration the AT&T _e_q_n  primitives  aabboovvee,  bbaacckk,
       bbaarr,  bboolldd,  ddeeffiinnee,  ddoowwnn, ffaatt, ffoonntt, ffrroomm, ffwwdd, ggffoonntt, ggssiizzee, iittaalliicc,
       lleefftt, lliinneeuupp, mmaarrkk, mmaattrriixx, nnddeeffiinnee, oovveerr, rriigghhtt,  rroommaann,  ssiizzee,  ssqqrrtt,
       ssuubb, ssuupp, ttddeeffiinnee, ttoo, uunnddeerr, and uupp.

   NNeeww pprriimmiittiivveess
       The  GNU extension primitives “ttyyppee” and cchhaarrttyyppee are discussed in sub‐
       section “Spacing and typeface” above; “sseett” in  subsection  “Customiza‐
       tion” below; and ggrrffoonntt and ggbbffoonntt in subsection “Fonts” below.  In the
       following synopses, _X can be any character not appearing in the parame‐
       ter thus bracketed.

       _e_1 aacccceenntt _e_2
              Set  _e_2 as an accent over _e_1.  _e_2 is assumed to be at the appro‐
              priate height for a lowercase letter without an ascender;    _e_q_n
              vertically shifts it depending on _e_1’s height.  For example, hhaatt
              is defined as follows.

                     accent { "^" }

              ddoottddoott,  ddoott,  ttiillddee,  vveecc,  and ddyyaadd are also defined using the
              aacccceenntt primitive.

       bbiigg _e  Enlarge the expression _e; semantics like those  of  CSS  “large”
              are  intended.  In _t_r_o_f_f output, the type size is increased by 5
              scaled points.  MathML output emits the following.

                     <mstyle mathsize='big'>

       ccooppyy _f_i_l_e
       iinncclluuddee _f_i_l_e
              Interpolate the contents of _f_i_l_e, omitting lines beginning  with
              ..EEQQ or ..EENN.  If a relative path name, _f_i_l_e is sought relative to
              the current working directory.

       iiffddeeff _n_a_m_e _X _a_n_y_t_h_i_n_g _X
              If _n_a_m_e is defined as a primitive or macro, interpret _a_n_y_t_h_i_n_g.

       nnoosspplliitt _t_e_x_t
              As  "_t_e_x_t",  but since _t_e_x_t 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.

       _e oopppprriimmee
              As pprriimmee, but set the prime symbol as an operator on _e.  In  the
              input  “AA oopppprriimmee ssuubb 11”, the “1” is tucked under the prime as a
              subscript to the “A” (as is conventional in  mathematical  type‐
              setting),  whereas when pprriimmee is used, the “1” is a subscript to
              the prime character.  The precedence of oopppprriimmee is the  same  as
              that  of  bbaarr  and “uunnddeerr”, and higher than that of other primi‐
              tives except aacccceenntt and uuaacccceenntt.  In unquoted  text,  a  neutral
              apostrophe ('') that is not the first character on the input line
              is treated like oopppprriimmee.

       ssddeeffiinnee _n_a_m_e _X _a_n_y_t_h_i_n_g _X
              As  “ddeeffiinnee”,  but  _n_a_m_e  is not recognized as a macro if called
              with arguments.

       _e_1 ssmmaalllloovveerr _e_2
              As oovveerr, but reduces the type size of _e_1 and _e_2, and  puts  less
              vertical space between _e_1 and _e_2 and the fraction bar.  The oovveerr
              primitive  corresponds  to  the TeX \\oovveerr primitive in displayed
              equation styles; ssmmaalllloovveerr corresponds to \\oovveerr  in  non‐display
              (“inline”) styles.

       ssppaaccee _n
              Set  extra  vertical  spacing around the equation, replacing the
              default values, where _n is an integer in hundredths  of  an  em.
              If  positive,  _n increases vertical spacing before the equation;
              if negative, it does so after the equation.  This primitive pro‐
              vides an interface to _g_r_o_f_f’s \\xx escape sequence, but  with  the
              opposite  sign  convention.  It has no effect if the equation is
              part of a _p_i_c(1) picture.

       ssppeecciiaall _t_r_o_f_f_‐_m_a_c_r_o _e
              Construct an object by calling  _t_r_o_f_f_‐_m_a_c_r_o  on  _e.   The  _t_r_o_f_f
              string  00ss  contains the _e_q_n output for _e, and the registers 00ww,
              00hh, 00dd, 00sskkeerrnn, and 00sskkeeww the width,  height,  depth,  subscript
              kern,  and  skew  of _e, respectively.  (The _s_u_b_s_c_r_i_p_t _k_e_r_n 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 _s_k_e_w 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 00ss so that it  outputs  the  de‐
              sired  result, returns the drawing position to the text baseline
              at the beginning of _e, 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 \\[[mmii]] and \\[[ppll]] special characters instead of + and -
              because they are part of the argument to a _t_r_o_f_f macro,  so  _e_q_n
              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 _e_q_n macro bbooxx to wrap the call of the _t_r_o_f_f macro BBxx.

                     .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

       sspplliitt ""_t_e_x_t""
              As  _t_e_x_t,  but  since _t_e_x_t 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.

       _e_1 uuaacccceenntt _e_2
              Set _e_2 as an accent under _e_1.  _e_2 is assumed to be at the appro‐
              priate height for a letter without a descender;  _e_q_n  vertically
              shifts  it  depending  on whether _e_1 has a descender.  uuttiillddee is
              predefined using uuaacccceenntt as a tilde accent below the baseline.

       uunnddeeff _n_a_m_e
              Remove definition of macro or primitive _n_a_m_e,  making  it  unde‐
              fined.

       vvcceenntteerr _e
              Vertically  center _e about the _m_a_t_h _a_x_i_s, a horizontal line upon
              which fraction bars and characters  such  as  “+”  and  “−”  are
              aligned.   MathML  already behaves this way, so _e_q_n ignores this
              primitive when producing that output format.  The  built‐in  ssuumm
              macro is defined as if by the following.

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

   EExxtteennddeedd pprriimmiittiivveess
       GNU _e_q_n extends the syntax of some AT&T _e_q_n primitives, introducing one
       deliberate incompatibility.

       ddeelliimm oonn
              _e_q_n  recognizes  an  “oonn”  argument  to the ddeelliimm primitive spe‐
              cially, restoring any delimiters previously disabled with “ddeelliimm
              ooffff”.  If delimiters haven’t been specified, neither command has
              effect.  Few _e_q_n documents are expected to use “o”  and  “n”  as
              left  and  right  delimiters, respectively.  If yours does, con‐
              sider swapping them, or select others.

       ccooll _n {{ ... }}
       ccccooll _n {{ ... }}
       llccooll _n {{ ... }}
       rrccooll _n {{ ... }}
       ppiillee _n {{ ... }}
       ccppiillee _n {{ ... }}
       llppiillee _n {{ ... }}
       rrppiillee _n {{ ... }}
              The integer value _n (in hundredths of an em) increases the  ver‐
              tical  spacing  between  rows,  using _g_r_o_f_f’s \\xx escape sequence
              (the value has no effect in MathML mode).  Negative  values  are
              accepted but have no effect.  If more than one _n occurs in a ma‐
              trix or pile, the largest is used.

   CCuussttoommiizzaattiioonn
       When  _e_q_n  generates  _t_r_o_f_f  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 sseett primitive.

       sseett _p _n
              assigns  parameter  _p  the  integer value _n; _n is interpreted in
              units of hundredths of an em unless otherwise stated.  For exam‐
              ple,

                     set x_height 45

              says  that  _e_q_n  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.

              mmiinniimmuumm__ssiizzee     sets  a  floor  for  the  type  size (in scaled
                               points) at which equations are set (55).

              ffaatt__ooffffsseett       The ffaatt  primitive  emboldens  an  equation  by
                               overprinting  two  copies of the equation hori‐
                               zontally offset by this amount (44).  In  MathML
                               mode,  components  to  which ffaatt__ooffffsseett applies
                               instead use the following.
                                      <mstyle mathvariant='double-struck'>

              oovveerr__hhaanngg        A 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 (00).

              aacccceenntt__wwiiddtthh     When  bbaarr or uunnddeerr is applied to a single char‐
                               acter, the line is this long  (3311).   Normally,
                               bbaarr  or  uunnddeerr  produces a line whose length is
                               the width of the object to which it applies; in
                               the case of a single character, this  tends  to
                               produce a line that looks too long.

              ddeelliimmiitteerr__ffaaccttoorr Extensible  delimiters  produced  with the lleefftt
                               and rriigghhtt primitives 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 (990000).

              ddeelliimmiitteerr__sshhoorrttffaallll
                               Extensible delimiters produced  with  the  lleefftt
                               and rriigghhtt primitives 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 (5500).

              nnuullll__ddeelliimmiitteerr__ssppaaccee
                               This  much horizontal space is inserted on each
                               side of a fraction (1122).

              ssccrriipptt__ssppaaccee     The width of subscripts and superscripts is in‐
                               creased by this amount (55).

              tthhiinn__ssppaaccee       This amount of space is automatically  inserted
                               after  punctuation characters.  It also config‐
                               ures the width of the space produced by  the  ^^
                               token (1177).

              mmeeddiiuumm__ssppaaccee     This  amount of space is automatically inserted
                               on either side of binary operators (2222).

              tthhiicckk__ssppaaccee      This amount of space is automatically  inserted
                               on  either  side of relations.  It also config‐
                               ures the width of the space produced by  the  ~~
                               token (2288).

              xx__hheeiigghhtt         The  height of lowercase letters without ascen‐
                               ders such as “x” (4455).

              aaxxiiss__hheeiigghhtt      The height above the baseline of the center  of
                               characters such as “+” and “−” (2266).  It is im‐
                               portant that this value is correct for the font
                               you are using.

              ddeeffaauulltt__rruullee__tthhiicckknneessss
                               This  should  be  set  to  the thickness of the
                               \\[[rruu]] character, or the thickness of horizontal
                               lines produced with the \\DD escape sequence (44).

              nnuumm11             The oovveerr primitive shifts up the  numerator  by
                               at least this amount (7700).

              nnuumm22             The ssmmaalllloovveerr primitive shifts up the numerator
                               by at least this amount (3366).

              ddeennoomm11           The  oovveerr primitive shifts down the denominator
                               by at least this amount (7700).

              ddeennoomm22           The ssmmaalllloovveerr primitive shifts down the denomi‐
                               nator by at least this amount (3366).

              ssuupp11             Normally superscripts  are  shifted  up  by  at
                               least this amount (4422).

              ssuupp22             Superscripts  within superscripts or upper lim‐
                               its or numerators of  ssmmaalllloovveerr  fractions  are
                               shifted  up by at least this amount (3377).  Con‐
                               ventionally, this is less than ssuupp11.

              ssuupp33             Superscripts  within  denominators  or   square
                               roots or subscripts or lower limits are shifted
                               up  by  at least this amount (2288).  Convention‐
                               ally, this is less than ssuupp22.

              ssuubb11             Subscripts are  normally  shifted  down  by  at
                               least this amount (2200).

              ssuubb22             When  there  is  both  a subscript and a super‐
                               script, the subscript is  shifted  down  by  at
                               least this amount (2233).

              ssuupp__ddrroopp         The  baseline  of a superscript is no more than
                               this much below the top of the object on  which
                               the superscript is set (3388).

              ssuubb__ddrroopp         The  baseline  of  a subscript is at least this
                               much below the bottom of the  object  on  which
                               the subscript is set (55).

              bbiigg__oopp__ssppaacciinngg11  The baseline of an upper limit is at least this
                               much  above  the top of the object on which the
                               limit is set (1111).

              bbiigg__oopp__ssppaacciinngg22  The baseline of a lower limit is at least  this
                               much  below  the  bottom of the object on which
                               the limit is set (1177).

              bbiigg__oopp__ssppaacciinngg33  The bottom of an upper limit is at  least  this
                               much  above  the top of the object on which the
                               limit is set (2200).

              bbiigg__oopp__ssppaacciinngg44  The top of a lower limit is at least this  much
                               below  the  bottom  of  the object on which the
                               limit is set (6600).

              bbiigg__oopp__ssppaacciinngg55  This much vertical space is added above and be‐
                               low limits (1100).

              bbaasseelliinnee__sseepp     The baselines of the rows in a pile  or  matrix
                               are  normally  this  far  apart (114400).  Usually
                               equal to the sum of nnuumm11 and ddeennoomm11.

              sshhiifftt__ddoowwnn       The midpoint between the top baseline  and  the
                               bottom  baseline in a matrix or pile is shifted
                               down by this much from the axis (2266).   Usually
                               equal to aaxxiiss__hheeiigghhtt.

              ccoolluummnn__sseepp       This  much  space is added between columns in a
                               matrix (110000).

              mmaattrriixx__ssiiddee__sseepp  This much space is added at each side of a  ma‐
                               trix (1177).

              ddrraaww__lliinneess       If non‐zero, _e_q_n draws lines using the _t_r_o_f_f \\DD
                               escape  sequence, rather than the \\ll escape se‐
                               quence and the \\[[rruu]]  special  character.   The
                               _e_q_n_r_c file sets the default: 11 on ppss, hhttmmll, and
                               the X11 devices, otherwise 00.

              bbooddyy__hheeiigghhtt      is the presumed height of an equation above the
                               text  baseline;  _e_q_n  adds  any excess as extra
                               pre‐vertical line spacing with _t_r_o_f_f’s  \\xx  es‐
                               cape sequence (8855).

              bbooddyy__ddeepptthh       is  the presumed depth of an equation below the
                               text baseline; _e_q_n adds  any  excess  as  extra
                               post‐vertical  line spacing with _t_r_o_f_f’s \\xx es‐
                               cape sequence (3355).

              nnrrooffff            If non‐zero, then nnddeeffiinnee behaves  like  ddeeffiinnee
                               and  ttddeeffiinnee  is ignored, otherwise ttddeeffiinnee be‐
                               haves like ddeeffiinnee and nnddeeffiinnee is ignored.   The
                               _e_q_n_r_c  file  sets  the  default:  11  on  aasscciiii,
                               llaattiinn11, uuttff88, and ccpp11004477 devices, otherwise 00.

   MMaaccrrooss
       In GNU _e_q_n, macros can take arguments.  A word defined by  any  of  the
       ddeeffiinnee,  nnddeeffiinnee,  or ttddeeffiinnee primitives followed immediately by a left
       parenthesis is treated as a _p_a_r_a_m_e_t_e_r_i_z_e_d _m_a_c_r_o _c_a_l_l_: 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, $$_n,  where  _n  is
       between  1  and  9 inclusive, is replaced by the _nth argument; if there
       are fewer than _n arguments, it is replaced by nothing.

   PPrreeddeeffiinneedd mmaaccrrooss
       GNU _e_q_n supports the  predefined  macros  offered  by  AT&T  _e_q_n:  aanndd,
       aapppprrooxx,  aarrcc,  ccooss,  ccoosshh, ddeell, ddeett, ddoott, ddoottddoott, ddyyaadd, eexxpp, ffoorr, ggrraadd,
       hhaallff, hhaatt, iiff, iinntteerr, IImm, iinnff, iinntt, lliimm, llnn, lloogg,  mmaaxx,  mmiinn,  nnootthhiinngg,
       ppaarrttiiaall,  pprriimmee,  pprroodd,  RRee,  ssiinn,  ssiinnhh, ssuumm, ttaann, ttaannhh, ttiillddee, ttiimmeess,
       uunniioonn, vveecc, ====, !!==, ++==, -->>, <<--, <<<<, >>>>, and “......”.  The lowercase clas‐
       sical Greek letters are available as aallpphhaa, bbeettaa, cchhii, ddeellttaa,  eeppssiilloonn,
       eettaa,  ggaammmmaa, iioottaa, kkaappppaa, llaammbbddaa, mmuu, nnuu, oommeeggaa, oommiiccrroonn, pphhii, ppii, ppssii,
       rrhhoo, ssiiggmmaa, ttaauu, tthheettaa, uuppssiilloonn, xxii, and zzeettaa.  Spell them with an ini‐
       tial capital letter (AAllpphhaa) or in full capitals (AALLPPHHAA) to  obtain  up‐
       percase forms.

       GNU  _e_q_n  further  defines the macros ccddoott, ccddoottss, and uuttiillddee (all dis‐
       cussed above), ddoollllaarr, which sets a dollar sign, and llddoottss, which  sets
       an ellipsis on the text baseline.

   FFoonnttss
       _e_q_n  uses  up  to three typefaces to set an equation: italic (oblique),
       roman (upright), and bold.  Assign each a _g_r_o_f_f typeface with the prim‐
       itives ggffoonntt, ggrrffoonntt, and ggbbffoonntt..  The defaults are the  styles  II,  RR,
       and  BB  (applied  to  the current font family).  The cchhaarrttyyppee primitive
       (see above) sets a character’s type, which determines the face used  to
       set  it.  The “lleetttteerr” type is set in italics; others are set in roman.
       Use the bboolldd primitive to select an (upright) bold style.

       ggbbffoonntt _f
              Select _f as the bold font.  This is a GNU extension.

       ggffoonntt _f
              Select _f as the italic font.

       ggrrffoonntt _f
              Select _f as the roman font.  This is a GNU extension.

OOppttiioonnss
       ----hheellpp displays a usage message, while --vv and  ----vveerrssiioonn  show  version
       information; all exit afterward.

       --CC     Recognize  ..EEQQ  and  ..EENN even when followed by a character other
              than space or newline.

       --dd _x_y  Specify delimiters _x for left and _y for right ends of  equations
              not  bracketed  by  ..EEQQ/..EENN.  _x and _y need not be distinct.  Any
              “ddeelliimm _x_y” statements in the source file override this option.

       --ff _F   is equivalent to “ggffoonntt _F”.

       --mm _n   is equivalent to “sseett mmiinniimmuumm__ssiizzee _n”.

       --MM _d_i_r Search _d_i_r for _e_q_n_r_c before those listed  in  section  “Descrip‐
              tion” above.

       --NN     Prohibit  newlines within delimiters.  This option allows _e_q_n to
              recover better from missing closing delimiters.

       --pp _n   Set sub‐ and superscripts _n points smaller than the  surrounding
              text.   This  option  is deprecated.  _e_q_n normally sets sub‐ and
              superscripts at 70% of the type size of the surrounding text.

       --rr     Reduce the type size of subscripts at most once relative to  the
              base type size for the equation.

       --RR     Don’t load _e_q_n_r_c.

       --ss _n   is equivalent to “ggssiizzee _n”.  This option is deprecated.

       --TT _d_e_v Prepare output for the device _d_e_v.  In most cases, the effect of
              this is to define a macro _d_e_v with a value of 11; _e_q_n_r_c uses this
              to  provide definitions appropriate for the device.  However, if
              the specified driver is “MathML”, the output  is  MathML  markup
              rather  than  _t_r_o_f_f  input, and _e_q_n_r_c is not loaded at all.  The
              default output device is ppss.

FFiilleess
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_e_q_n_r_c
              Initialization file.

MMaatthhMMLL mmooddee lliimmiittaattiioonnss
       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 _t_r_o_f_f does.

       • _e_q_n customization parameters have no effect on generated MathML.

       • The ssppeecciiaall, uupp, ddoowwnn, ffwwdd, and  bbaacckk  primitives  cannot  be  imple‐
         mented, and yield a MathML “<merror>” message instead.

       • The  vvcceenntteerr  primitive is silently ignored, as centering on the math
         axis is the MathML default.

       • Characters that _e_q_n sets extra large in _t_r_o_f_f mode—notably the  inte‐
         gral  sign—may  appear  too  small  and need to have their “<mstyle>”
         wrappers adjusted by hand.

       As in its _t_r_o_f_f mode, _e_q_n in MathML mode leaves the ..EEQQ and ..EENN  tokens
       in  place,  but  emits nothing corresponding to ddeelliimm delimiters.  They
       can, however, be recognized as  character  sequences  that  begin  with
       “<math>”, end with “</math>”, and do not cross line boundaries.

CCaavveeaattss
       Tokens  must be double‐quoted in _e_q_n input if they are not to be recog‐
       nized as names of macros or primitives, or if they  are  to  be  inter‐
       preted  by  _t_r_o_f_f.   In particular, short ones, like “ppii” and “PPII”, can
       collide with _t_r_o_f_f identifiers.  For instance, the _e_q_n  command  “ggffoonntt
       PPII”  does not select _g_r_o_f_f’s Palatino italic font for the global italic
       face; you must use “ggffoonntt ""PPII""” 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,  _e_q_n  does not inherently distinguish displayed and inline
       equation styles; see the ssmmaalllloovveerr  primitive  above.   However,  macro
       packages  frequently  define  EEQQ  and  EENN macros 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.

BBuuggss
       _e_q_n  abuses  terminology—its  “equations” can be inequalities, bare ex‐
       pressions, or unintelligible gibberish.  But  there’s  no  changing  it
       now.

       In _n_r_o_f_f mode, lowercase Greek letters are rendered in roman instead of
       italic style.

       In  MathML mode, the mmaarrkk and lliinneeuupp features 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.

EExxaammpplleess
       We first illustrate _e_q_n 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 ~~.

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

SSeeee aallssoo
       “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.

       _T_h_e  _T_e_X_b_o_o_k,  by  Donald  E. Knuth, 1984, Addison‐Wesley Professional.
       Appendix G discusses many of the parameters  from  section  “Customiza‐
       tion” above in greater detail.

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

       _g_r_o_f_f(1), _t_r_o_f_f(1), _p_i_c(1), _g_r_o_f_f___f_o_n_t(5)

groff 1.23.0                      3 June 2025                           _e_q_n(1)
───────────────────────────────────────────────────────────────────────────────
_e_q_n_2_g_r_a_p_h(1)                General Commands Manual               _e_q_n_2_g_r_a_p_h(1)

NNaammee
       eqn2graph - convert an _e_q_n equation into a cropped image

SSyynnooppssiiss
       eeqqnn22ggrraapphh [--ffoorrmmaatt _o_u_t_p_u_t_‐_f_o_r_m_a_t] [_c_o_n_v_e_r_t_‐_a_r_g_u_m_e_n_t ...]

       eeqqnn22ggrraapphh ----hheellpp

       eeqqnn22ggrraapphh --vv
       eeqqnn22ggrraapphh ----vveerrssiioonn

DDeessccrriippttiioonn
       _e_q_n_2_g_r_a_p_h  reads a one‐line _e_q_n(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 _n_o_t be preceded by the ..EEQQ macro that nor‐
       mally precedes it within _g_r_o_f_f(1) macros; nor do you need to have  dol‐
       lar‐sign or other delimiters around the equation.

       Arguments  not recognized by _e_q_n_2_g_r_a_p_h are passed to the ImageMagick or
       GraphicsMagick program _c_o_n_v_e_r_t(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 _c_o_n_v_e_r_t’s --ttrriimm option to the  small‐
       est possible bounding box that contains all the black pixels.

OOppttiioonnss
       ----hheellpp  displays  a  usage message, while --vv and ----vveerrssiioonn show version
       information; all exit afterward.

       --ffoorrmmaatt _o_u_t_p_u_t_‐_f_o_r_m_a_t
              Write the image in _o_u_t_p_u_t_‐_f_o_r_m_a_t, which must  be  understood  by
              _c_o_n_v_e_r_t; the default is PNG.

EEnnvviirroonnmmeenntt
       _G_R_O_F_F___T_M_P_D_I_R
       _T_M_P_D_I_R
       _T_M_P
       _T_E_M_P   These  environment  variables are searched in the given order to
              determine the directory where temporary files will  be  created.
              If none are set, _/_t_m_p is used.

AAuutthhoorrss
       _e_q_n_2_g_r_a_p_h  was  written  by  Eric S. Raymond,  based  on  a  recipe for
       _p_i_c_2_g_r_a_p_h(1), by W. Richard Stevens.

SSeeee aallssoo
       _p_i_c_2_g_r_a_p_h(1), _g_r_a_p_2_g_r_a_p_h(1), _e_q_n(1), _g_r_o_f_f(1), _c_o_n_v_e_r_t(1)

groff 1.23.0                      3 June 2025                     _e_q_n_2_g_r_a_p_h(1)
───────────────────────────────────────────────────────────────────────────────
_g_d_i_f_f_m_k(1)                  General Commands Manual                 _g_d_i_f_f_m_k(1)

NNaammee
       gdiffmk - mark differences between _g_r_o_f_f/_n_r_o_f_f/_t_r_o_f_f files

SSyynnooppssiiss
       ggddiiffffmmkk [--aa _a_d_d_‐_m_a_r_k] [--cc _c_h_a_n_g_e_‐_m_a_r_k] [--dd _d_e_l_e_t_e_‐_m_a_r_k] [--xx _d_i_f_f_‐
               _c_o_m_m_a_n_d] [--DD [--BB] [--MM _m_a_r_k_1 _m_a_r_k_2]] [----] _f_i_l_e_1 _f_i_l_e_2 [_o_u_t_p_u_t]

       ggddiiffffmmkk ----hheellpp

       ggddiiffffmmkk ----vveerrssiioonn

DDeessccrriippttiioonn
       _g_d_i_f_f_m_k compares two _r_o_f_f(7) documents, _f_i_l_e_1 and _f_i_l_e_2, and creates  a
       _r_o_f_f document consisting of _f_i_l_e_2 with added margin character (..mmcc) re‐
       quests indicating output lines that differ from _f_i_l_e_1_.  If the _f_i_l_e_1 or
       _f_i_l_e_2 argument is “--”, _g_d_i_f_f_m_k reads the standard input stream for that
       input.   If  the  _o_u_t_p_u_t operand is present, _g_d_i_f_f_m_k writes output to a
       file of that name.  If it is “--” or absent, _g_d_i_f_f_m_k  writes  output  to
       the  standard  output  stream.   “--” cannot be both an input and output
       operand.

OOppttiioonnss
       ----hheellpp displays a usage message and ----vveerrssiioonn  shows  version  informa‐
       tion; both exit afterward.

       --aa _a_d_d_‐_m_a_r_k
              Use _a_d_d_‐_m_a_r_k for source lines not in _f_i_l_e_1 but present in _f_i_l_e_2.
              Default: “++”.

       --BB     By  default,  the deleted texts marked by the --DD option end with
              an added _r_o_f_f break request, ..bbrr, 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 --DD.

       --cc _c_h_a_n_g_e_‐_m_a_r_k
              Use _c_h_a_n_g_e_‐_m_a_r_k for changed source lines.  Default: “||”.

       --dd _d_e_l_e_t_e_‐_m_a_r_k
              Use the _d_e_l_e_t_e_‐_m_a_r_k for deleted source lines.  Default: “**”.

       --DD     Show the deleted portions from changed and deleted text.

       --MM _m_a_r_k_1 _m_a_r_k_2
              Change  the  delimiting  marks  for  the --DD option.  It makes no
              sense to use this option without --DD.  Default delimiting  marks:
              “[[[[” ... “]]]]”.

       --xx _d_i_f_f_‐_c_o_m_m_a_n_d
              Use  the _d_i_f_f_‐_c_o_m_m_a_n_d command to perform the comparison of _f_i_l_e_1
              and _f_i_l_e_2.  In particular, _d_i_f_f_‐_c_o_m_m_a_n_d should  accept  the  GNU
              _d_i_f_f(1) --DD option.  Default: ddiiffff.

       ----     Treat all subsequent arguments as file names, even if they begin
              with “--”.

BBuuggss
       The  output  is  not necessarily compatible with all macro packages and
       all preprocessors.  A  workaround  that  often  overcomes  preprocessor
       problems  is  to run _g_d_i_f_f_m_k on the output of all the preprocessors in‐
       stead of the input source.

       _g_d_i_f_f_m_k relies on the --DD option of GNU _d_i_f_f to make a  merged  “#ifdef”
       output  format.  Busybox _d_i_f_f is known to not support it.  Also see the
       --xx _d_i_f_f_‐_c_o_m_m_a_n_d option.

AAuutthhoorrss
       _g_d_i_f_f_m_k was written by Mike Bianchi, now retired.  It is maintained  by
       the _g_r_o_f_f developers.

SSeeee aallssoo
       _g_r_o_f_f(1), _n_r_o_f_f(1), _g_t_r_o_f_f(1), _r_o_f_f(7), _d_i_f_f(1)

groff 1.23.0                      3 June 2025                       _g_d_i_f_f_m_k(1)
───────────────────────────────────────────────────────────────────────────────
_g_l_i_l_y_p_o_n_d(1)                General Commands Manual               _g_l_i_l_y_p_o_n_d(1)

NNaammee
       glilypond - embed LilyPond musical notation in _g_r_o_f_f documents

SSyynnooppssiiss
       gglliillyyppoonndd [--kk] [{----llyy22eeppss|----ppddff22eeppss}] [--ee _d_i_r_e_c_t_o_r_y] [--oo _o_u_t_p_u_t_‐_f_i_l_e]
                 [--pp _f_i_l_e_n_a_m_e_‐_p_r_e_f_i_x] [--tt _t_d_i_r] [{--vv|--VV}] [----] [_f_i_l_e ...]
       gglliillyyppoonndd [{----llyy22eeppss|----ppddff22eeppss}] [----eeppss__ddiirr _d_i_r_e_c_t_o_r_y] [----kkeeeepp__aallll]
                 [----oouuttppuutt _o_u_t_p_u_t_‐_f_i_l_e] [----pprreeffiixx _f_i_l_e_n_a_m_e_‐_p_r_e_f_i_x] [----tteemmpp__ddiirr
                 _t_d_i_r] [----vveerrbboossee] [----] [_f_i_l_e ...]

       gglliillyyppoonndd --??
       gglliillyyppoonndd --hh
       gglliillyyppoonndd ----hheellpp
       gglliillyyppoonndd ----uussaaggee

       gglliillyyppoonndd --ll
       gglliillyyppoonndd ----lliicceennssee

       gglliillyyppoonndd ----vveerrssiioonn

DDeessccrriippttiioonn
       _g_l_i_l_y_p_o_n_d  is  a  _g_r_o_f_f(7)  preprocessor  that enables the embedding of
       LilyPond music scores in _g_r_o_f_f documents.  If no operands are given, or
       if _f_i_l_e is “--”, _g_l_i_l_y_p_o_n_d reads the standard input stream.   A  double‐
       dash  argument (“----”) causes all subsequent arguments to be interpreted
       as _f_i_l_e operands, even if their names start with a dash.

UUssaaggee
       At present, _g_l_i_l_y_p_o_n_d works with the _g_r_o_f_f ppss, ddvvii, hhttmmll, and xxhhttmmll de‐
       vices.  The llbbpp and lljj44 devices are untested.  Unfortunately,  the  ppddff
       device does not yet work.

OOppttiioonn oovveerrvviieeww
       --??|--hh|----hheellpp|----uussaaggee
              Display usage information and exit.

       ----vveerrssiioonn
              Display version information and exit.

       --ll|----lliicceennssee
              Display copyright license information and exit.

   OOppttiioonnss ffoorr bbuuiillddiinngg EEPPSS ffiilleess
       ----llyy22eeppss
              Direct  _l_i_l_y_p_o_n_d(1)  to  create  Encapsulated  PostScript  (EPS)
              files.  This is the default.

       ----ppddff22eeppss
              The program _g_l_i_l_y_p_o_n_d generates a PDF file using _l_i_l_y_p_o_n_d.  Then
              the EPS file is generated by _p_d_f_2_p_s and _p_s_2_e_p_s.

   DDiirreeccttoorriieess aanndd ffiilleess
       --ee|----eeppss__ddiirr _d_i_r_e_c_t_o_r_y___n_a_m_e
              Normally all _E_P_S files are  sent  to  the  temporary  directory.
              With  this option, you can generate your own directory, in which
              all useful _E_P_S files are send.  So at last, the temporary direc‐
              tory can be removed.

       --pp|----pprreeffiixx _b_e_g_i_n___o_f___n_a_m_e
              Normally all temporary files get names that start with the llyy_._._.
              prefix.  With this option, you can freely change this prefix.

       --kk|----kkeeeepp__aallll
              Normally all temporary files without the _e_p_s files are  deleted.
              With  this  option,  all  generated files either by the _l_i_l_y_p_o_n_d
              program or other format transposers are kept.

       --tt|----tteemmpp__ddiirr _d_i_r
              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.

   OOuuttppuutt
       --oo|----oouuttppuutt _f_i_l_e___n_a_m_e
              Normally all _g_r_o_f_f output of this program  is  sent  to  SSTTDDOOUUTT.
              With  this  option, that can be changed, such that the output is
              stored into a file named in the option argument _f_i_l_e___n_a_m_e.

       --vv|--VV|----vveerrbboossee
              A lot more of information is sent to STDERR.

   SShhoorrtt ooppttiioonn ccoolllleeccttiioonnss
       The argument handling of options

       _S_h_o_r_t _o_p_t_i_o_n_s are arguments that start with a single dash --.   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 _P_O_S_I_X and _G_N_U option management.

       For example,

       --kkVVee _s_o_m_e___d_i_r
              is  a  collection  of the short options --kk and --VV without option
              argument, followed by the short option --ee with  option  argument
              that  is  the  following part of the argument _s_o_m_e___d_i_r.  So this
              argument could also be written as several  arguments  --kk  --VV  --ee
              _s_o_m_e___d_i_r.

   HHaannddlliinngg ooff lloonngg ooppttiioonnss
       Arguments that start with a double dash ---- are so‐called _l_o_n_g _o_p_t_i_o_n_s _R
       _.  Each double dash argument can only have a single long option.

       _L_o_n_g  _o_p_t_i_o_n_s  have or have not an option argument.  An option argument
       can be the next argument or can be appended with an equal sign == to the
       same argument as the long option.

       ----hheellpp is a long option without an option argument.

       ----eeppss__ddiirr _s_o_m_e___d_i_r
       ----eeppss__ddiirr==_s_o_m_e___d_i_r
              is the long option ----eeppss__ddiirr with the option argument _s_o_m_e___d_i_r.

       Moreover the program allows abbreviations of long options, as  much  as
       possible.

       The  _l_o_n_g _o_p_t_i_o_n ----kkeeeepp__aallll can be abbreviated from ----kkeeeepp__aall up to ----kk
       because the program does not have another _l_o_n_g _o_p_t_i_o_n whose name starts
       with the character kk.

       On the other hand, the option ----vveerrssiioonn cannot be  abbreviated  further
       than ----vveerrss because there is also the _l_o_n_g _o_p_t_i_o_n ----vveerrbboossee that can be
       abbreviated up to ----vveerrbb.

       An  option  argument  can  also  be appended to an abbreviation.  So is
       ----ee==_s_o_m_e___d_i_r the same as ----eeppss__ddiirr _s_o_m_e___d_i_r.

       Moreover the program allows an arbitrary usage of upper and lower  case
       in the option name.  This is _P_e_r_l style.

       For  example,  the  _l_o_n_g  _o_p_t_i_o_n  ----kkeeeepp__aallll  can as well be written as
       ----KKeeeepp__AAllll or even as an abbreviation like ----KKeeEE.

LLiillyyPPoonndd rreeggiioonnss iinn _rr_oo_ff_ff iinnppuutt
   IInntteeggrraatteedd LLiillyyPPoonndd ccooddee
       A _l_i_l_y_p_o_n_d part within a structure written in the _g_r_o_f_f language is the
       whole part between the marks
              ..lliillyyppoonndd ssttaarrtt
       and
              ..lliillyyppoonndd eenndd
       A _g_r_o_f_f input can have several of these _l_i_l_y_p_o_n_d parts.

       When processing such a _l_i_l_y_p_o_n_d part between ..lliillyyppoonndd ssttaarrtt and ..lliillyy‐‐
       ppoonndd eenndd we say that the gglliillyyppoonndd program is in _l_i_l_y_p_o_n_d _m_o_d_e.

       These _l_i_l_y_p_o_n_d parts are sent into temporary _l_i_l_y_p_o_n_d  files  with  the
       file name extension ..llyy.  These files are transformed later on into _E_P_S
       files.

   IInncclluussiioonn ooff _.._ll_yy ffiilleess
       An  additional  command  line  for  file inclusion of _l_i_l_y_p_o_n_d files is
       given by
       ..lliillyyppoonndd iinncclluuddee _f_i_l_e___n_a_m_e
       in _g_r_o_f_f input.  For each such _i_n_c_l_u_d_e command, one  file  of  _l_i_l_y_p_o_n_d
       code  can  be  included into the _g_r_o_f_f code.  Arbitrarily many of these
       commands can be included in the _g_r_o_f_f input.

       These include commands can only be used  outside  the  _l_i_l_y_p_o_n_d  parts.
       Within the _l_i_l_y_p_o_n_d _m_o_d_e, this inclusion is not possible.  So ..lliillyyppoonndd
       iinncclluuddee  may not be used in _l_i_l_y_p_o_n_d _m_o_d_e, i.e. between ..lliillyyppoonndd ssttaarrtt
       and ..lliillyyppoonndd eenndd.  These included _l_y‐files are also  transformed  into
       _E_P_S files.

GGeenneerraatteedd ffiilleess
       By  the  transformation process of _l_i_l_y_p_o_n_d parts into _E_P_S 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.

   CCoommmmaanndd‐‐lliinnee ooppttiioonnss ffoorr ddiirreeccttoorriieess
       The temporary directory for this program is  either  created  automati‐
       cally or can be named by the option --tt|----tteemmpp__ddiirr _d_i_r.

       Moreover, the _E_P_S files that are later on referred by ..PPSSPPIICC command in
       the  final _g_r_o_f_f output can be stored in a different directory that can
       be set by the command‐line option  --ee|----eeppss__ddiirr  _d_i_r_e_c_t_o_r_y___n_a_m_e.   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 --pp or ----pprreeffiixx.

       All  of  the  temporary files except the _E_P_S files are deleted finally.
       This  can  be  changed  by  setting  the  command‐line  options  --kk  or
       ----kkeeeepp__ffiilleess.  With this, all temporary files and directories are kept,
       not deleted.

       These  _E_P_S  files are stored in a temporary or _E_P_S directory.  But they
       cannot be deleted by the transformation process because they are needed
       for the display which can take a long time.

TTrraannssffoorrmmaattiioonn pprroocceesssseess ffoorr ggeenneerraattiinngg EEPPSS ffiilleess
   MMooddee ppddff22eeppss
       This mode is the actual default and can also be chosen  by  the  option
       ----ppddff22eeppss.

       In  this mode, the ..llyy files are transformed by the _l_i_l_y_p_o_n_d(1) program
       into _P_D_F files, using
              lliillyyppoonndd ----ppddff ----oouuttppuutt==_f_i_l_e_‐_n_a_m_e
       for each ..llyy file.  The _f_i_l_e_‐_n_a_m_e must be provided without  the  exten‐
       sion ..ppddff.  By this process, a file _f_i_l_e_‐_n_a_m_e..ppddff is generated.

       The  next step is to transform these _P_D_F files into a _P_S file.  This is
       done by the _p_d_f_2_p_s(1) program using
              $ ppddff22ppss _f_i_l_e_‐_n_a_m_e..ppddff _f_i_l_e_‐_n_a_m_e..ppddss
       The next step creates an _E_P_S file from the _P_S file.  This  is  done  by
       the _p_s_2_e_p_s(1) program using
              $ ppss22eeppss _f_i_l_e_‐_n_a_m_e..ppss

       By  that, a file _f_i_l_e_‐_n_a_m_e..eeppss is created for each _l_i_l_y_p_o_n_d part in the
       _g_r_o_f_f file or standard input.

       The last step to be done is replacing all _l_i_l_y_p_o_n_d parts by  the  _g_r_o_f_f
       command
              ..PPSSPPIICC _f_i_l_e_‐_n_a_m_e..eeppss

   MMooddee llyy22eeppss
       In  earlier  time, this mode was the default.  But now it does not work
       any more, so accept the new default _p_d_f_2_e_p_s.  For  testing,  this  mode
       can also be chosen by the _g_l_i_l_y_p_o_n_d option ----llyy22eeppss.

       In  this  mode,  the  ..llyy files are transformed by the _l_i_l_y_p_o_n_d program
       into many files of different formats, including _e_p_s files, using
              $ lliillyyppoonndd ----ppss --ddbbaacckkeenndd==eeppss --ddggss--llooaadd--ffoonnttss ----oouuttppuutt==_f_i_l_e_‐_n_a_m_e
       for each ..llyy file.  The output _f_i_l_e_-_n_a_m_e must be  provided  without  an
       extension, its directory is temporary.

       There  are many _E_P_S files created.  One having the complete transformed
       llyy file, named _f_i_l_e_-_n_a_m_e..eeppss.

       Moreover there are _E_P_S files for each page, named _f_i_l_e_-_n_a_m_e--_d_i_g_i_t..eeppss.

       The last step to be done is replacing all _l_i_l_y_p_o_n_d parts by the collec‐
       tion of the corresponding _E_P_S page files.  This is done by  _g_r_o_f_f  com‐
       mands
       ..PPSSPPIICC _f_i_l_e_‐_n_a_m_e--_d_i_g_i_t..eeppss

GGeenneerraatteedd _gg_rr_oo_ff_ff oouuttppuutt
       The new _g_r_o_f_f(7) structure generated by _g_l_i_l_y_p_o_n_d is either

       1)     sent  to  standard  output and can there be saved into a file or
              piped into _g_r_o_f_f(1) or

       2)     stored into a file by given the option --oo  || --output _f_i_l_e___n_a_m_e

AAuutthhoorrss
       _g_l_i_l_y_p_o_n_d was written by Bernd Warken.

SSeeee aallssoo
       _g_r_o_f_f(1)
              describes the usage of the _g_r_o_f_f command and  contains  pointers
              to further documentation of the _g_r_o_f_f system.

       _g_r_o_f_f___t_m_a_c(5)
              describes the ..PPSSPPIICC request.

       _l_i_l_y_p_o_n_d(1)
              briefly  describes the _l_i_l_y_p_o_n_d command and contains pointers to
              further documentation.

       _p_d_f_2_p_s(1)
              transforms a _P_D_F file into a _P_o_s_t_S_c_r_i_p_t format.

       _p_s_2_e_p_s(1)
              transforms a _P_S file into an _E_P_S format.

groff 1.23.0                      3 June 2025                     _g_l_i_l_y_p_o_n_d(1)
───────────────────────────────────────────────────────────────────────────────
_g_p_e_r_l(1)                    General Commands Manual                   _g_p_e_r_l(1)

NNaammee
       gperl - execute Perl commands in _g_r_o_f_f documents

SSyynnooppssiiss
       ggppeerrll [_f_i_l_e ...]

       ggppeerrll --hh
       ggppeerrll ----hheellpp

       ggppeerrll --vv
       ggppeerrll ----vveerrssiioonn

DDeessccrriippttiioonn
       This is a preprocessor for _g_r_o_f_f(1).  It allows the use of _p_e_r_l(7) code
       in _g_r_o_f_f(7) files.  The result of a _P_e_r_l _p_a_r_t can be  stored  in  groff
       _s_t_r_i_n_g_s  or  _n_u_m_e_r_i_c_a_l _r_e_g_i_s_t_e_r_s based on the arguments at a final line
       of a _P_e_r_l _p_a_r_t.

       If no operands are given, or if _f_i_l_e is “--”, _g_p_e_r_l reads  the  standard
       input  stream.  A double‐dash argument (“----”) causes all subsequent ar‐
       guments to be interpreted as _f_i_l_e operands, even if their  names  start
       with  a  dash.   --hh  and ----hheellpp display a usage message, whereas --vv and
       ----vveerrssiioonn display version information; all exit afterward.

PPeerrll rreeggiioonnss
       _P_e_r_l parts in _g_r_o_f_f _f_i_l_e_s are enclosed by two ..PPeerrll requests with  dif‐
       ferent arguments, a _s_t_a_r_t_i_n_g and an _e_n_d_i_n_g command.

   SSttaarrttiinngg PPeerrll mmooddee
       The  starting _P_e_r_l _r_e_q_u_e_s_t can either be without arguments, or by a re‐
       quest that has the term ssttaarrtt as its only argument.

              •      ..PPeerrll

              •      ..PPeerrll ssttaarrtt

   EEnnddiinngg PPeerrll mmooddee wwiitthhoouutt ssttoorraaggee
       A ..PPeerrll command line with an argument different from ssttaarrtt  finishes  a
       running  _P_e_r_l _p_a_r_t.  Of course, it would be reasonable to add the argu‐
       ment ssttoopp; that’s possible, but not necessary.

              •      ..PPeerrll ssttoopp

              •      ..PPeerrll _o_t_h_e_r___t_h_a_n___s_t_a_r_t
       The argument _o_t_h_e_r___t_h_a_n___s_t_a_r_t can  additionally  be  used  as  a  _g_r_o_f_f
       string variable name for storage — see next section.

   EEnnddiinngg PPeerrll mmooddee wwiitthh ssttoorraaggee
       A useful feature of _g_p_e_r_l is to store one or more results from the _P_e_r_l
       _m_o_d_e.

       The output of a _P_e_r_l _p_a_r_t can be got with backticks ``......``.

       This  program  collects all printing to STDOUT (normal standard output)
       by the Perl pprriinntt program.  This pseudo‐printing output can  have  sev‐
       eral lines, due to printed line breaks with \\nn.  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 _g_p_e_r_l in either

       _g_r_o_f_f _s_t_r_i_n_g_s
              by creating a groff command ..ddss

       _g_r_o_f_f _r_e_g_i_s_t_e_r
              by creating a groff command ..rrnn

       The storage modes can be determined by arguments of  a  final  stopping
       ..PPeerrll  command.   Each  argument ..ddss changes the mode into _g_r_o_f_f _s_t_r_i_n_g
       and ..nnrr changes the mode into _g_r_o_f_f _r_e_g_i_s_t_e_r for all  following  output
       parts.

       By default, all output is saved as strings, so ..ddss is not really needed
       before  the  first  ..nnrr command.  That suits to _g_r_o_f_f(7), because every
       output can be saved as _g_r_o_f_f string, but the registers can be very  re‐
       strictive.

       In _s_t_r_i_n_g _m_o_d_e, _g_p_e_r_l generates a _g_r_o_f_f _s_t_r_i_n_g storage line
              ..ddss _v_a_r___n_a_m_e _c_o_n_t_e_n_t
       In _r_e_g_i_s_t_e_r _m_o_d_e the following groff command is generated
              ..nnrr _v_a_r___n_a_m_e _c_o_n_t_e_n_t

       We present argument collections in the following.  You can add as first
       argument for all ssttoopp.  We omit this additional element.

       ..PPeerrll ..ddss _v_a_r___n_a_m_e
              This  will  store  1  output  line  into  the groff string named
              _v_a_r___n_a_m_e by the automatically created command
                     ..ddss _v_a_r___n_a_m_e _o_u_t_p_u_t

       ..PPeerrll _v_a_r___n_a_m_e
              If _v_a_r___n_a_m_e is different from ssttaarrtt this is  equivalent  to  the
              former  command, because the string mode is string with ..ddss com‐
              mand.  default.

       ..PPeerrll _v_a_r___n_a_m_e_1 _v_a_r___n_a_m_e_2
              This will store 2 output lines into groff string names _v_a_r___n_a_m_e_1
              and _v_a_r___n_a_m_e_2, because the default mode ..ddss is active, such that
              no ..ddss argument is needed.  Of course, this is equivalent to
                     ..PPeerrll ..ddss _v_a_r___n_a_m_e_1 _v_a_r___n_a_m_e_2
              and
                     ..PPeerrll ..ddss _v_a_r___n_a_m_e_1 ..ddss _v_a_r___n_a_m_e_2

       ..PPeerrll ..nnrr _v_a_r___n_a_m_e_1 _v_a_r_n_a_m_e_2
              stores both variables as register variables.  _g_p_e_r_l generates
              ..nnrr _v_a_r___n_a_m_e_1 _o_u_t_p_u_t___l_i_n_e_1
              ..nnrr _v_a_r___n_a_m_e_2 _o_u_t_p_u_t___l_i_n_e_2

       ..PPeerrll ..nnrr _v_a_r___n_a_m_e_1 ..ddss _v_a_r___n_a_m_e_2
              stores the 1st argument as _r_e_g_i_s_t_e_r and the second as _s_t_r_i_n_g by
              ..nnrr _v_a_r___n_a_m_e_1 _o_u_t_p_u_t___l_i_n_e_1
              ..ddss _v_a_r___n_a_m_e_2 _o_u_t_p_u_t___l_i_n_e_2

EExxaammppllee
       A possible _P_e_r_l _p_a_r_t in a _r_o_f_f _f_i_l_e could look like that:
              before
              .Perl start
              my $result = 'some data';
              print $result;
              .Perl stop .ds string_var
              after

       This stores  the  result  ””ssoommee  ddaattaa””  into  the  _r_o_f_f  _s_t_r_i_n_g  called
       ssttrriinngg__vvaarr, such that the following line is printed:
              .ds string_var some data
       by _g_p_e_r_l as food for the coming _g_r_o_f_f run.

       A _P_e_r_l _p_a_r_t 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 _g_r_o_f_f strings.  vvaarr11,vvaarr22,vvaarr33.  So
       the following _g_r_o_f_f command lines are created:
              .ds var1 first
              .ds var2 second line
              .nr var3 3

AAuutthhoorrss
       _g_p_e_r_l was written by Bernd Warken.

SSeeee aallssoo
       Man pages related to _g_r_o_f_f are _g_r_o_f_f(1), _g_r_o_f_f(7), and _g_r_o_g(1).

       Documents related to _P_e_r_l are _p_e_r_l(1), _p_e_r_l(7).

groff 1.23.0                      3 June 2025                         _g_p_e_r_l(1)
───────────────────────────────────────────────────────────────────────────────
_g_p_i_n_y_i_n(1)                  General Commands Manual                 _g_p_i_n_y_i_n(1)

NNaammee
       gpinyin - use Hanyu Pinyin Chinese in _g_r_o_f_f documents

SSyynnooppssiiss
       ggppiinnyyiinn [_f_i_l_e ...]

       ggppiinnyyiinn --hh
       ggppiinnyyiinn ----hheellpp

       ggppiinnyyiinn --vv
       ggppiinnyyiinn ----vveerrssiioonn

DDeessccrriippttiioonn
       _g_p_i_n_y_i_n is a preprocessor for _g_r_o_f_f(1) that facilitates  use  of  Hanyu
       Pinyin  in _g_r_o_f_f(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 _i_n_p_u_t_‐_f_i_l_e is a file name or the character “--”  to  indicate  that
       the  standard input stream should be read.  As usual, the argument “----”
       can be used in order to force interpretation of all remaining arguments
       as file names, even if an _i_n_p_u_t_‐_f_i_l_e argument begins with  a  “--”.   --hh
       and ----hheellpp display a usage message, while --vv and ----vveerrssiioonn show version
       information; all exit afterward.

   PPiinnyyiinn sseeccttiioonnss
       Pinyin  sections  in  _g_r_o_f_f  files are enclosed by two ..ppiinnyyiinn requests
       with different arguments.  The starting request is
              .pinyin start
       or
              .pinyin begin
       and the ending request is
              .pinyin stop
       or
              .pinyin end
       .

   SSyyllllaabblleess
       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 _g_r_o_f_f 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 ..ppiinnyyiinn sections, _g_p_i_n_y_i_n supports the form “ue” for
       lowercase and the forms “Ue” and “UE” for uppercase.

   TToonneess
       Each syllable has exactly one of five _t_o_n_e_s.  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 _g_p_i_n_y_i_n 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.

AAuutthhoorrss
       _g_p_i_n_y_i_n was written by Bernd Warken.

SSeeee aallssoo
       Useful documents on the World Wide Web related to Pinyin include
           _P_i_n_y_i_n _t_o _U_n_i_c_o_d_e,
           _O_n_‐_l_i_n_e _C_h_i_n_e_s_e _T_o_o_l_s,
           _P_i_n_y_i_n_._i_n_f_o_: _a _g_u_i_d_e _t_o _t_h_e _w_r_i_t_i_n_g _o_f _M_a_n_d_a_r_i_n _C_h_i_n_e_s_e  _i_n  _r_o_m_a_n_‐
           _i_z_a_t_i_o_n,
           “Where do the tone marks go?”,
           _p_i_n_y_i_n_._t_x_t from the CJK macro package for TeX,
       and
           _p_i_n_y_i_n_._s_t_y from the CJK macro package for TeX.

       _g_r_o_f_f(1) and _g_r_o_g(1) explain how to view _r_o_f_f documents.

       _g_r_o_f_f(7)  and  _g_r_o_f_f___c_h_a_r(7)  are comprehensive references covering the
       language elements of GNU _t_r_o_f_f and the available glyph repertoire,  re‐
       spectively.

groff 1.23.0                      3 June 2025                       _g_p_i_n_y_i_n(1)
───────────────────────────────────────────────────────────────────────────────
_g_r_a_p_2_g_r_a_p_h(1)               General Commands Manual              _g_r_a_p_2_g_r_a_p_h(1)

NNaammee
       grap2graph - convert a _g_r_a_p diagram into a cropped image

SSyynnooppssiiss
       ggrraapp22ggrraapphh [--uunnssaaffee] [--ffoorrmmaatt _o_u_t_p_u_t_‐_f_o_r_m_a_t] [_c_o_n_v_e_r_t_‐_a_r_g_u_m_e_n_t ...]

       ggrraapp22ggrraapphh ----hheellpp

       ggrraapp22ggrraapphh --vv
       ggrraapp22ggrraapphh ----vveerrssiioonn

DDeessccrriippttiioonn
       _g_r_a_p_2_g_r_a_p_h  reads  a _g_r_a_p(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 _n_o_t be wrapped with the ..GG11 and  ..GG22  macros
       that normally guard it within _g_r_o_f_f(1) documents.

       Arguments not recognized by _g_r_a_p_2_g_r_a_p_h are passed to the ImageMagick or
       GraphicsMagick  program  _c_o_n_v_e_r_t(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 _c_o_n_v_e_r_t’s --ttrriimm option to the small‐
       est possible bounding box that contains all the black pixels.

OOppttiioonnss
       ----hheellpp displays a usage message, while --vv and  ----vveerrssiioonn  show  version
       information; all exit afterward.

       --ffoorrmmaatt _o_u_t_p_u_t_‐_f_o_r_m_a_t
              Write  the  image  in _o_u_t_p_u_t_‐_f_o_r_m_a_t, which must be understood by
              _c_o_n_v_e_r_t; the default is PNG.

       --uunnssaaffee
              Run _g_r_o_f_f in _u_n_s_a_f_e mode, enabling the PIC command sshh to execute
              arbitrary Unix shell commands.  The _g_r_o_f_f default is  to  forbid
              this.

EEnnvviirroonnmmeenntt
       _G_R_O_F_F___T_M_P_D_I_R
       _T_M_P_D_I_R
       _T_M_P
       _T_E_M_P   These  environment  variables are searched in the given order to
              determine the directory where temporary files will  be  created.
              If none are set, _/_t_m_p is used.

AAuutthhoorrss
       _g_r_a_p_2_g_r_a_p_h  was  written  by  Eric S. Raymond,  based  on  a recipe for
       _p_i_c_2_g_r_a_p_h(1), by W. Richard Stevens.

SSeeee aallssoo
       _p_i_c_2_g_r_a_p_h(1), _e_q_n_2_g_r_a_p_h(1), _g_r_a_p(1), _p_i_c(1), _g_r_o_f_f(1), _c_o_n_v_e_r_t(1)

groff 1.23.0                      3 June 2025                    _g_r_a_p_2_g_r_a_p_h(1)
───────────────────────────────────────────────────────────────────────────────
_g_r_n(1)                      General Commands Manual                     _g_r_n(1)

NNaammee
       grn - embed Gremlin images in _g_r_o_f_f documents

SSyynnooppssiiss
       ggrrnn [--CC] [--TT _d_e_v] [--MM _d_i_r] [--FF _d_i_r] [_f_i_l_e ...]

       ggrrnn --??
       ggrrnn ----hheellpp

       ggrrnn --vv
       ggrrnn ----vveerrssiioonn

DDeessccrriippttiioonn
       _g_r_n is a preprocessor for including _g_r_e_m_l_i_n pictures in _t_r_o_f_f(1) input.
       _g_r_n writes to standard output, processing only input lines between  two
       that  start  with  ..GGSS  and ..GGEE.  Those lines must contain _g_r_n commands
       (see below).  These macros request a _g_r_e_m_l_i_n file; the picture in  that
       file  is  converted  and  placed in the _t_r_o_f_f input stream.  ..GGSS may be
       called with a CC, LL, or RR argument to center,  left‐,  or  right‐justify
       the  whole  _g_r_e_m_l_i_n  picture (the default is to center).  If no _f_i_l_e is
       mentioned, the standard input is read.  At the end of the picture,  the
       position  on the page is the bottom of the _g_r_e_m_l_i_n picture.  If the _g_r_n
       entry is ended with ..GGFF instead of ..GGEE, the position is left at the top
       of the picture.

       Currently only the _m_e macro package has support for ..GGSS, ..GGEE, and ..GGFF.

       _g_r_n produces drawing escape sequences that use _g_r_o_f_f’s color scheme ex‐
       tension (\\DD''FF ...''), and thus may not work with other _t_r_o_f_fs.

   _gg_rr_nn ccoommmmaannddss
       Each input line between ..GGSS and ..GGEE may have one _g_r_n command.  Commands
       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
       “ddeeffaauulltt”,  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.

       11 _N
       22 _N
       33 _N
       44 _N    Set  _g_r_e_m_l_i_n’s text size number 1 (2, 3, or 4) to _N points.  The
              default is 12 (16, 24, and 36, respectively).

       rroommaann _f
       iittaalliiccss _f
       bboolldd _f
       ssppeecciiaall _f
              Set the roman (italics, bold, or special) font to _t_r_o_f_f’s font _f
              (either a name or number).  The default is R (I, B, and  S,  re‐
              spectively).

       ll _f
       ssttiippppllee _f
              Set the stipple font to _t_r_o_f_f’s stipple font _f (name or number).
              The  command  ssttiippppllee may be abbreviated down as far as “sstt” (to
              avoid confusion with “ssppeecciiaall”).  There is _n_o default for  stip‐
              ples (unless one is set by the “ddeeffaauulltt” command), and it is in‐
              valid  to include a _g_r_e_m_l_i_n picture with polygons without speci‐
              fying a stipple font.

       xx _N
       ssccaallee _N
              Magnify the picture (in addition to any  default  magnification)
              by  _N,  a  floating‐point  number larger than zero.  The command
              ssccaallee may be abbreviated down to “sscc”.

       nnaarrrrooww _N
       mmeeddiiuumm _N
       tthhiicckk _N
              Set the thickness of _g_r_e_m_l_i_n’s narrow (medium and thick, respec‐
              tively) lines to _N 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.

       ppooiinnttssccaallee [ooffff|oonn]
              Scale  text  to  match  the  picture.   Gremlin  text is usually
              printed in the point size specified with the commands 11,  22,  33,
              or 44, regardless of any scaling factors in the picture.  Setting
              ppooiinnttssccaallee  will cause the point sizes to scale with the picture
              (within _t_r_o_f_f’s limitations, of course).  An operand of anything
              but ooffff will turn text scaling on.

       ddeeffaauulltt
              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 _t_r_o_f_f input file, but
              can be used at any time to reset the default settings.

       wwiiddtthh _N
              Force the picture to be _N inches wide.  This overrides any scal‐
              ing factors present in the same picture.  “wwiiddtthh 00” is ignored.

       hheeiigghhtt _N
              Force the picture to be _N inches high, overriding other  scaling
              factors.   If  both  wwiiddtthh and hheeiigghhtt are specified, the tighter
              constraint will determine the scale of the picture.  hheeiigghhtt  and
              wwiiddtthh  commands  are  not  saved with a “ddeeffaauulltt” command.  They
              will, however, affect point size scaling if that option is set.

       ffiillee _n_a_m_e
              Get picture from _g_r_e_m_l_i_n file _n_a_m_e located the current directory
              (or in the library directory; see the --MM option above).  If mul‐
              tiple ffiillee commands are given, the last one controls.   If  _n_a_m_e
              doesn’t  exist, an error message is reported and processing con‐
              tinues from the ..GGEE line.

   UUssaaggee wwiitthh _gg_rr_oo_ff_ff
       Since _g_r_n is a preprocessor, it has no access to elements of  formatter
       state, such as indentation, line length, type size, or register values.
       Consequently,  no  _t_r_o_f_f  input  can  be placed between the ..GGSS and ..GGEE
       macros.  However, _g_r_e_m_l_i_n text elements are subsequently  processed  by
       _t_r_o_f_f,  so anything valid in a single line of _t_r_o_f_f input is valid in a
       line of _g_r_e_m_l_i_n text (barring the dot control character “.” at the  be‐
       ginning  of  a  line).  Thus, it is possible to have equations within a
       _g_r_e_m_l_i_n figure by including in the _g_r_e_m_l_i_n  file  _e_q_n  expressions  en‐
       closed by previously defined delimiters (e.g., “$$”).

       When using _g_r_n along with other preprocessors, it is best to run _t_b_l(1)
       before  _g_r_n,  _p_i_c(1),  and/or  _i_d_e_a_l  to avoid overworking _t_b_l.  _e_q_n(1)
       should always be run last.  _g_r_o_f_f(1) will automatically run  preproces‐
       sors in the correct order.

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

       _g_r_n  uses  _t_r_o_f_f’s registers gg11 through gg99 and sets registers gg11 and gg22
       to the width and height of the _g_r_e_m_l_i_n figure (in device units)  before
       entering  the  ..GGSS  macro  (this is for those who want to rewrite these
       macros).

   GGrreemmlliinn ffiillee ffoorrmmaatt
       There exist two distinct _g_r_e_m_l_i_n 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  _n_o_t  compatible  with the AED version.  As long as a _g_r_e_m_l_i_n
       file does not contain negative coordinates, either format will be  read
       correctly by either version of _g_r_e_m_l_i_n or _g_r_n.  The other difference in
       Sun/X11  format is the use of names for picture objects (e.g., PPOOLLYYGGOONN,
       CCUURRVVEE) 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 _g_r_e_m_l_i_n file contains either the string “ggrreemm‐‐
         lliinnffiillee” (AED) or “ssuunnggrreemmlliinnffiillee” (Sun/X11).

       • The  second line of the file contains an orientation and _x and _y val‐
         ues for a positioning point, separated by spaces.   The  orientation,
         either 00 or 11, is ignored by the Sun/X11 version.  00 means that _g_r_e_m_‐
         _l_i_n  will  display  things in horizontal format (a drawing area wider
         than it is tall, with a menu across the top).  11 means  that  _g_r_e_m_l_i_n
         will display things in vertical format (a drawing area taller than it
         is  wide,  with a menu on the left side).  _x and _y 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 “11 00..0000 00..0000” 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
         “--11”.

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

   EElleemmeenntt ssppeecciiffiiccaattiioonnss
       • The  first line of each element contains a single decimal number giv‐
         ing the type of the element (AED) or its name (Sun/X11).

                    _g_r_e_m_l_i_n File Format: Object Type Specification
               ─────────────────────────────────────────────────────────
               AED Number   Sun/X11 Name           Description
                    00       BBOOTTLLEEFFTT        bottom‐left‐justified text
                    11       BBOOTTRRIIGGHHTT       bottom‐right‐justified text
                    22       CCEENNTTCCEENNTT       center‐justified text
                    33       VVEECCTTOORR         vector
                    44       AARRCC            arc
                    55       CCUURRVVEE          curve
                    66       PPOOLLYYGGOONN        polygon
                    77       BBSSPPLLIINNEE        b‐spline
                    88       BBEEZZIIEERR         Bézier
                   1100       TTOOPPLLEEFFTT        top‐left‐justified text
                   1111       TTOOPPCCEENNTT        top‐center‐justified text
                   1122       TTOOPPRRIIGGHHTT       top‐right‐justified text
                   1133       CCEENNTTLLEEFFTT       left‐center‐justified text
                   1144       CCEENNTTRRIIGGHHTT      right‐center‐justified text
                   1155       BBOOTTCCEENNTT        bottom‐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 “--11..00 --11..00” (AED) or a single asterisk, “**” (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.

                               11   thin dotted lines
                               22   thin dot‐dashed lines
                               33   thick solid lines
                               44   thin dashed lines
                               55   thin solid lines
                               66   medium 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.

                             11   roman (R font in _t_r_o_f_f)
                             22   italics (I font in _t_r_o_f_f)
                             33   bold (B font in _t_r_o_f_f)
                             44   special (S font in _t_r_o_f_f)

         If you’re using _g_r_n to run your pictures through _g_r_o_f_f, 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 (00), followed by exactly one space before the newline.

   CCoooorrddiinnaatteess
       _g_r_e_m_l_i_n was designed for AED terminals, and its coordinates reflect the
       AED coordinate space.  For vertical pictures, _x  values  range  116  to
       511,  and  _y  values  from 0 to 483.  For horizontal pictures, _x values
       range from 0 to 511, and _y 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.
       _g_r_e_m_l_i_n writes out coordinates using the _p_r_i_n_t_f(3) format “%f1.2”; it’s
       probably a good idea to use the same format if you want to  modify  the
       _g_r_n code.

   SSuunn//XX1111 ccoooorrddiinnaatteess
       There  is no restriction on the range of coordinates used to create ob‐
       jects in the Sun/X11 version of _g_r_e_m_l_i_n.  However, files with  negative
       coordinates _w_i_l_l cause problems if displayed on the AED.

OOppttiioonnss
       --?? and ----hheellpp display a usage message, while --vv and ----vveerrssiioonn show ver‐
       sion information; all exit afterward.

       --CC     Recognize  ..GGSS and ..GGEE (and ..GGFF) even when followed by a charac‐
              ter other than space or newline.

       --FF _d_i_r Search _d_i_r for subdirectories _d_e_vname (_n_a_m_e is the name  of  the
              output  driver) for the _D_E_S_C file before the default font direc‐
              tories _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_s_i_t_e_-_f_o_n_t, _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t,
              and _/_u_s_r_/_l_i_b_/_f_o_n_t.

       --MM _d_i_r Prepend _d_i_r to the search path for _g_r_e_m_l_i_n files.   The  default
              search  path is the current directory, the home directory, _/_u_s_r_/
              _s_h_a_r_e_/_g_r_o_f_f_/_s_i_t_e_-_t_m_a_c, and _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c, in that
              order.

       --TT _d_e_v Prepare device output using output driver _d_e_v.  The  default  is
              ppss.  See _g_r_o_f_f(1) for a list of valid devices.

FFiilleess
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_vname_/_D_E_S_C
              describes the output device _n_a_m_e.

AAuutthhoorrss
       David  Slattengren  and Barry Roitblat wrote the original Berkeley _g_r_n.
       Daniel Senderowicz and Werner Lemberg modified it for _g_r_o_f_f.

SSeeee aallssoo
       _g_r_e_m_l_i_n(1), _g_r_o_f_f(1), _p_i_c(1), _i_d_e_a_l(1)

groff 1.23.0                      3 June 2025                           _g_r_n(1)
───────────────────────────────────────────────────────────────────────────────
_g_r_o_d_v_i(1)                   General Commands Manual                  _g_r_o_d_v_i(1)

NNaammee
       grodvi - _g_r_o_f_f output driver for TeX DVI format

SSyynnooppssiiss
       ggrrooddvvii [--ddll] [--FF _d_i_r] [--pp _p_a_p_e_r_‐_f_o_r_m_a_t] [--ww _n] [_f_i_l_e ...]

       ggrrooddvvii ----hheellpp

       ggrrooddvvii --vv
       ggrrooddvvii ----vveerrssiioonn

DDeessccrriippttiioonn
       The GNU _r_o_f_f DVI output driver translates the output of  _t_r_o_f_f(1)  into
       TeX  DVI format.  Normally, _g_r_o_d_v_i is invoked by _g_r_o_f_f(1) when the lat‐
       ter is given the “--TT ddvvii” option.  (In this installation, ppss is the de‐
       fault output device.)  Use _g_r_o_f_f’s --PP option to pass any options  shown
       above  to  _g_r_o_d_v_i.   If no _f_i_l_e arguments are given, or if _f_i_l_e is “-”,
       _g_r_o_d_v_i reads the standard input stream.  Output is written to the stan‐
       dard output stream.

       The DVI file generated by _g_r_o_d_v_i can interpreted by any correctly writ‐
       ten DVI driver.  _t_r_o_f_f drawing primitives are  implemented  using  _t_p_i_c
       version  2  specials.   If the driver does not support these, \\DD escape
       sequences will not produce any output.

       Encapsulated PostScript (EPS) files can be  easily  included;  use  the
       PPSSPPIICC  macro.   _p_s_p_i_c_._t_m_a_c  is  loaded  automatically by _d_v_i_._t_m_a_c.  See
       _g_r_o_f_f___t_m_a_c(5).

       The default color used by the \\mm and  \\MM  escape  sequences  is  black.
       Currently,  the  stroke color for \\DD drawing escape sequences is black;
       fill color values are translated to gray.

       In _g_r_o_f_f, as in AT&T _t_r_o_f_f, the \\NN escape 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,  _g_r_o_d_v_i  emits  the equivalent to TeX’s
       \\ssppeecciiaall{{ppaappeerrssiizzee==_w_i_d_t_h,,_l_e_n_g_t_h}} on the first page; _d_v_i_p_s  (or  another
       DVI  driver)  then  sets the page size accordingly.  If either the page
       width or length is not positive, no ppaappeerrssiizzee special is output.

       A device control escape sequence \\XX''_a_n_y_t_h_i_n_g'' is translated to the same
       DVI file instructions as would be  produced  by  \\ssppeecciiaall{{_a_n_y_t_h_i_n_g}}  in
       TeX; _a_n_y_t_h_i_n_g cannot contain a newline.

   TTyyppeeffaacceess
       _g_r_o_d_v_i  supports  the  standard  four  styles: RR (roman), II (_i_t_a_l_i_c), BB
       (bboolldd), and BBII (_bb_oo_ll_dd_‐‐_ii_tt_aa_ll_ii_cc).  Fonts are grouped into families TT and  HH
       having members in each style.  “CM” abbreviates “Computer Modern”.

              TTRR     CM Roman (cmr10)
              TTII     CM Text Italic (cmti10)
              TTBB     CM Bold Extended Roman (cmbx10)
              TTBBII    CM Bold Extended Text Italic (cmbxti10)
              HHRR     CM Sans Serif (cmss10)
              HHII     CM Slanted Sans Serif (cmssi10)
              HHBB     CM Sans Serif Bold Extended (cmssbx10)
              HHBBII    CM Slanted Sans Serif Bold Extended (cmssbxo10)

       The following fonts are not members of a family.

              CCWW     CM Typewriter Text (cmtt10)
              CCWWII    CM Italic Typewriter Text (cmitt10)

       Special  fonts  include  MMII  (cmmi10), SS (cmsy10), EEXX (cmex10), SSCC (cm‐
       tex10, only for CCWW), and, perhaps surprisingly, TTRR, TTII, and CCWW, because
       TeX places some glyphs in text fonts that  _t_r_o_f_f  generally  does  not.
       For italic fonts, CCWWII is used instead of CCWW.

       Finally,  the  symbol  fonts  of  the American Mathematical Society are
       available as special fonts SSAA (msam10) and SSBB (msbm10).  They  are  are
       not mounted by default.

       The  _t_r_o_f_f  option  --mmeecc loads the _e_c_._t_m_a_c 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 \\[[EEuu]] and per mille
       \\[[%%00]] glyphs.  _e_c_._t_m_a_c must  be  loaded  before  any  language‐specific
       macro  files  because  it does not set up the codes necessary for auto‐
       matic hyphenation.

   FFoonntt ddeessccrriippttiioonn ffiilleess
       Use _t_f_m_t_o_d_i_t(1) to create _g_r_o_f_f font description files  from  TFM  (TeX
       font metrics) files.  The font description file should contain the fol‐
       lowing additional directives, which _t_f_m_t_o_d_i_t generates automatically.

       iinntteerrnnaallnnaammee _n_a_m_e
              The name of the TFM file (without the _._t_f_m extension) is _n_a_m_e.

       cchheecckkssuumm _n
              The checksum in the TFM file is _n.

       ddeessiiggnnssiizzee _n
              The design size in the TFM file is _n.

   DDrraawwiinngg ccoommmmaannddss
       _g_r_o_d_v_i supports an additional drawing command.

       \\DD''RR _d_h _d_v''
              Draw a rule (solid black rectangle) with one corner at the draw‐
              ing  position, and the diagonally opposite corner at the drawing
              position +(_d_h,_d_v), 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 _t_p_i_c spe‐
              cials, unlike the other \\DD commands.

OOppttiioonnss
       ----hheellpp displays a usage message, while --vv and  ----vveerrssiioonn  show  version
       information; all exit afterward.

       --dd     Do  not  use _t_p_i_c specials to implement drawing commands.  Hori‐
              zontal and vertical lines are implemented by rules.  Other draw‐
              ing commands are ignored.

       --FF _d_i_r Prepend directory dir_/_d_e_vname to the search path  for  font  and
              device  description  files; _n_a_m_e is the name of the device, usu‐
              ally ddvvii.

       --ll     Use landscape orientation rather than portrait.

       --pp _p_a_p_e_r_‐_f_o_r_m_a_t
              Set  physical  dimensions  of  output  medium,  overriding   the
              ppaappeerrssiizzee,  ppaappeerrlleennggtthh,  and  ppaappeerrwwiiddtthh directives in the _D_E_S_C
              file.   _p_a_p_e_r_‐_f_o_r_m_a_t  can  be  any  argument  accepted  by   the
              ppaappeerrssiizzee directive; see _g_r_o_f_f___f_o_n_t(5).

       --ww _n   Draw  rules  (lines) with a thickness of _n thousandths of an em.
              The default thickness is 4400 (0.04 em).

EEnnvviirroonnmmeenntt
       _G_R_O_F_F___F_O_N_T___P_A_T_H
              lists directories in which to search for _d_e_v_d_v_i, _g_r_o_d_v_i’s direc‐
              tory of device and font description  files.   See  _t_r_o_f_f(1)  and
              _g_r_o_f_f___f_o_n_t(5).

FFiilleess
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_d_v_i_/_D_E_S_C
              describes the ddvvii output device.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_d_v_i_/F
              describes the font known as _F on device ddvvii.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_d_v_i_._t_m_a_c
              defines  font  mappings,  special characters, and colors for use
              with the ddvvii output  device.   It  is  automatically  loaded  by
              _t_r_o_f_f_r_c when the ddvvii output device is selected.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_e_c_._t_m_a_c
              configures the ddvvii output device to use the EC and TC font fami‐
              lies instead of CM (Computer Modern).

BBuuggss
       DVI  files  produced by _g_r_o_d_v_i 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 _g_r_o_d_v_i.

       When using the --dd option 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.

SSeeee aallssoo
       “What are the EC fonts?”; TeX FAQ: Frequently Asked Question  List  for
       TeX

       _t_f_m_t_o_d_i_t(1),    _g_r_o_f_f(1),    _t_r_o_f_f(1),   _g_r_o_f_f___o_u_t(5),   _g_r_o_f_f___f_o_n_t(5),
       _g_r_o_f_f___c_h_a_r(7), _g_r_o_f_f___t_m_a_c(5)

groff 1.23.0                      3 June 2025                        _g_r_o_d_v_i(1)
───────────────────────────────────────────────────────────────────────────────
_g_r_o_f_f(1)                    General Commands Manual                   _g_r_o_f_f(1)

NNaammee
       groff - front end to the GNU _r_o_f_f document formatting system

SSyynnooppssiiss
       ggrrooffff [--aabbccCCeeEEggGGiijjkkllNNppRRssSSttUUVVXXzzZZ] [--dd _c_t_e_x_t] [--dd _s_t_r_i_n_g==_t_e_x_t]
             [--DD _f_a_l_l_b_a_c_k_‐_e_n_c_o_d_i_n_g] [--ff _f_o_n_t_‐_f_a_m_i_l_y] [--FF _f_o_n_t_‐_d_i_r_e_c_t_o_r_y]
             [--II _i_n_c_l_u_s_i_o_n_‐_d_i_r_e_c_t_o_r_y] [--KK _i_n_p_u_t_‐_e_n_c_o_d_i_n_g] [--LL _s_p_o_o_l_e_r_‐
             _a_r_g_u_m_e_n_t] [--mm _m_a_c_r_o_‐_p_a_c_k_a_g_e] [--MM _m_a_c_r_o_‐_d_i_r_e_c_t_o_r_y] [--nn _p_a_g_e_‐
             _n_u_m_b_e_r] [--oo _p_a_g_e_‐_l_i_s_t] [--PP _p_o_s_t_p_r_o_c_e_s_s_o_r_‐_a_r_g_u_m_e_n_t] [--rr _c_n_u_m_e_r_i_c_‐
             _e_x_p_r_e_s_s_i_o_n] [--rr _r_e_g_i_s_t_e_r==_n_u_m_e_r_i_c_‐_e_x_p_r_e_s_s_i_o_n] [--TT _o_u_t_p_u_t_‐_d_e_v_i_c_e]
             [--ww _w_a_r_n_i_n_g_‐_c_a_t_e_g_o_r_y] [--WW _w_a_r_n_i_n_g_‐_c_a_t_e_g_o_r_y] [_f_i_l_e ...]

       ggrrooffff --hh
       ggrrooffff ----hheellpp

       ggrrooffff --vv [_o_p_t_i_o_n ...] [_f_i_l_e ...]
       ggrrooffff ----vveerrssiioonn [_o_p_t_i_o_n ...] [_f_i_l_e ...]

DDeessccrriippttiioonn
       _g_r_o_f_f is the primary front end to the GNU _r_o_f_f document formatting sys‐
       tem.  GNU _r_o_f_f 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 _f_i_l_e operands are specified, or if _f_i_l_e is “--”, _g_r_o_f_f
       reads the standard input stream.

       A reimplementation and extension of  the  typesetter  from  AT&T  Unix,
       _g_r_o_f_f  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.  _g_r_o_f_f is capable of producing typographically sophisticated
       documents while consuming minimal system resources.

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

OOppttiioonnss
       --hh and ----hheellpp display a usage message and exit.

       Because  _g_r_o_f_f is intended to subsume most users’ direct invocations of
       the _t_r_o_f_f(1) formatter, the two programs share a set of options.   How‐
       ever,  _g_r_o_f_f  has  some  options  that _t_r_o_f_f does not share, and others
       which _g_r_o_f_f interprets differently.  At the same time,  not  all  valid
       _t_r_o_f_f options can be given to _g_r_o_f_f.

   _gg_rr_oo_ff_ff‐‐ssppeecciiffiicc ooppttiioonnss
       The  following  options  either do not exist in GNU _t_r_o_f_f or are inter‐
       preted differently by _g_r_o_f_f.

       --DD _e_n_c Set fallback input encoding used by _p_r_e_c_o_n_v(1) to  _e_n_c;  implies
              --kk.

       --ee     Run _e_q_n(1) preprocessor.

       --gg     Run _g_r_n(1) preprocessor.

       --GG     Run _g_r_a_p(1) preprocessor; implies --pp.

       --II _d_i_r Works as _t_r_o_f_f’s option (see below), but also implies --gg and --ss.
              It  is  passed  to  _s_o_e_l_i_m(1)  and the output driver, and _g_r_n is
              passed an --MM option with _d_i_r as its argument.

       --jj     Run _c_h_e_m(1) preprocessor; implies --pp.

       --kk     Run _p_r_e_c_o_n_v(1) preprocessor.  Refer to its man page for its  be‐
              havior if neither of _g_r_o_f_f’s --KK or --DD options is also specified.

       --KK _e_n_c Set input encoding used by _p_r_e_c_o_n_v(1) to _e_n_c; implies --kk.

       --ll     Send  the output to a spooler program for printing.  The “pprriinntt”
              directive in the device description file specifies  the  default
              command  to be used; see _g_r_o_f_f___f_o_n_t(5).  If no such directive is
              present for the output device, output is piped to  _l_p_r(1).   See
              options --LL and --XX.

       --LL _a_r_g Pass _a_r_g to the print spooler program.  If multiple _a_r_gs are re‐
              quired,  pass  each  with  a separate --LL option.  _g_r_o_f_f does not
              prefix an option dash to _a_r_g before passing it  to  the  spooler
              program.

       --MM     Works  as  _t_r_o_f_f’s  option  (see  below),  but is also passed to
              _e_q_n(1), _g_r_a_p(1), and _g_r_n(1).

       --NN     Prohibit newlines between _e_q_n delimiters: pass --NN to _e_q_n(1).

       --pp     Run _p_i_c(1) preprocessor.

       --PP _a_r_g Pass _a_r_g to the postprocessor.  If multiple _a_r_gs  are  required,
              pass  each  with a separate --PP option.  _g_r_o_f_f does not prefix an
              option dash to _a_r_g before passing it to the postprocessor.

       --RR     Run _r_e_f_e_r(1) preprocessor.  No mechanism is provided for passing
              arguments to _r_e_f_e_r because most _r_e_f_e_r  options  have  equivalent
              language elements that can be specified within the document.

       --ss     Run _s_o_e_l_i_m(1) preprocessor.

       --SS     Operate in “safer” mode; see --UU below for its opposite.  For se‐
              curity reasons, safer mode is enabled by default.

       --tt     Run _t_b_l(1) preprocessor.

       --TT _d_e_v Direct  _t_r_o_f_f  to  format  the  input for the output device _d_e_v.
              _g_r_o_f_f then calls an output driver to convert _t_r_o_f_f’s output to a
              form appropriate for _d_e_v; see subsection “Output devices” below.

       --UU     Operate in unsafe mode: pass the --UU option to _p_i_c and _t_r_o_f_f.

       --vv
       ----vveerrssiioonn
              Write version information for _g_r_o_f_f and all programs run  by  it
              to  the  standard output stream; that is, the given command line
              is processed in the usual way, passing --vv to the  formatter  and
              any pre‐ or postprocessors invoked.

       --VV     Output  the pipeline that _g_r_o_f_f would run to the standard output
              stream, but do not execute it.  If given more than  once,  _g_r_o_f_f
              both writes and runs the pipeline.

       --XX     Use _g_x_d_i_t_v_i_e_w(1) instead of the usual postprocessor to (pre)view
              a  document  on an X11 display.  Combining this option with --TTppss
              uses the font metrics of  the  PostScript  device,  whereas  the
              --TTXX7755 and --TTXX110000 options use the metrics of X11 fonts.

       --ZZ     Disable  postprocessing.   _t_r_o_f_f output will appear on the stan‐
              dard output stream (unless suppressed with --zz); see _g_r_o_f_f___o_u_t(5)
              for a description of this format.

   TTrraannssppaarreenntt ooppttiioonnss
       The following  options  are  passed  as‐is  to  the  formatter  program
       _t_r_o_f_f(1) and described in more detail in its man page.

       --aa     Generate a plain text approximation of the typeset output.

       --bb     Write  a backtrace to the standard error stream on each error or
              warning.

       --cc     Start with color output disabled.

       --CC     Enable AT&T _t_r_o_f_f compatibility mode; implies --cc.

       --dd _c_s
       --dd _n_a_m_e==_s_t_r_i_n_g
              Define string.

       --EE     Inhibit _t_r_o_f_f error messages; implies --WWww.

       --ff _f_a_m Set default font family.

       --FF _d_i_r Search in directory _d_i_r for the selected output device’s  direc‐
              tory of device and font description files.

       --ii     Process standard input after the specified input files.

       --II _d_i_r Search _d_i_r for input files.

       --mm _n_a_m_e
              Process name_._t_m_a_c before input files.

       --MM _d_i_r Search directory _d_i_r for macro files.

       --nn _n_u_m Number the first page _n_u_m.

       --oo _l_i_s_t
              Output only pages in _l_i_s_t.

       --rr _c_n_u_m_e_r_i_c_‐_e_x_p_r_e_s_s_i_o_n
       --rr _r_e_g_i_s_t_e_r==_n_u_m_e_r_i_c_‐_e_x_p_r_e_s_s_i_o_n
              Define register.

       --ww _n_a_m_e
       --WW _n_a_m_e
              Enable  (--ww)  or  inhibit  (--WW) emission of warnings in category
              _n_a_m_e.

       --zz     Suppress formatted device‐independent output of _t_r_o_f_f.

UUssaaggee
       The architecture of the GNU _r_o_f_f system follows that of  other  device‐
       independent _r_o_f_f implementations, comprising preprocessors, macro pack‐
       ages,  output  drivers (or “postprocessors”), a suite of utilities, and
       the formatter _t_r_o_f_f at its heart.  See _r_o_f_f(7) for a survey  of  how  a
       _r_o_f_f system works.

       The  front end programs available in the GNU _r_o_f_f system make it easier
       to use  than  traditional  _r_o_f_fs  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 _r_o_f_f system.  It complements
       _r_o_f_f(7) with _g_r_o_f_f‐specific information.

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

       $ eecchhoo ""HHeelllloo,, wwoorrlldd!!"" || ggrrooffff --TTaasscciiii || sseedd ''//^^$$//dd''
       Hello, world!

       We  used  a _s_e_d command only to eliminate the 65 blank lines that would
       otherwise flood the terminal screen.  (_r_o_f_f 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.

       $ eecchhoo ""HHeelllloo,, wwoorrlldd!!"" || ggrrooffff --TTuuttff88 || sseedd ''//^^$$//dd''

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

       $ eecchhoo ""HHeelllloo,, wwoorrlldd!!"" || ggrrooffff --TTppddff >> hheelllloo..ppddff
       $ eevviinnccee hheelllloo..ppddff
       $ eecchhoo ""HHeelllloo,, wwoorrlldd!!"" || ggrrooffff --TThhttmmll >> hheelllloo..hhttmmll
       $ ffiirreeffooxx hheelllloo..hhttmmll
       $ eecchhoo ""HHeelllloo,, wwoorrlldd!!"" || ggrrooffff --TTddvvii >> hheelllloo..ddvvii
       $ xxddvvii hheelllloo..hhttmmll

   UUssiinngg _gg_rr_oo_ff_ff aass aa RREEPPLL
       Those with a programmer’s bent may be pleased to know that they can use
       _g_r_o_f_f 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 --wwww can aid this goal.

       $ ggrrooffff --wwww --TTuuttff88
       \\## TThhiiss iiss aa ccoommmmeenntt.. LLeett''ss ddeeffiinnee aa rreeggiisstteerr..
       ..nnrr aa 11
       \\## DDoo iinntteeggeerr aarriitthhmmeettiicc wwiitthh ooppeerraattoorrss eevvaalluuaatteedd lleefftt‐‐ttoo‐‐rriigghhtt..
       ..nnrr bb \\nn[[aa]]++55//22
       \\## LLeett''ss ggeett tthhee rreessuulltt oonn tthhee ssttaannddaarrdd eerrrroorr ssttrreeaamm..
       ..ttmm \\nn[[bb]]
       3
       \\## NNooww wwee''llll ddeeffiinnee aa ssttrriinngg..
       ..ddss nnaammee LLeesslliiee\\"" TThhiiss iiss aannootthheerr ffoorrmm ooff ccoommmmeenntt..
       ..nnrr bb ((\\nn[[aa]] ++ ((77//22))))
       \\## CCeenntteerr tthhee nneexxtt ttwwoo tteexxtt iinnppuutt lliinneess..
       ..ccee 22
       HHii,, \\**[[nnaammee]]..
       YYoouurr sseeccrreett nnuummbbeerr iiss \\nn[[bb]]..
       \\## WWee wwiillll sseeee tthhaatt tthhee ddiivviissiioonn rroouunnddeedd ttoowwaarrdd zzeerroo..
       IItt iiss
       \\## HHeerree''ss aann iiff‐‐eellssee ccoonnttrrooll ssttrruuccttuurree..
       ..iiee ((\\nn[[bb]] %% 22)) oodddd..
       ..eell eevveenn..
       \\## TThhiiss ttrriicckk sseettss tthhee ppaaggee lleennggtthh ttoo tthhee ccuurrrreenntt vveerrttiiccaall
       \\## ppoossiittiioonn,, ssoo tthhaatt bbllaannkk lliinneess ddoonn''tt ssppeeww wwhheenn wwee''rree ddoonnee..
       ..ppll \\nn[[nnll]]uu
       _<_C_o_n_t_r_o_l_‐_D_>
                                  Hi, Leslie.
                           Your secret number is 4.
       It is even.

   PPaappeerr ffoorrmmaatt
       In GNU _r_o_f_f, the page dimensions for the formatter _t_r_o_f_f and for output
       devices are handled separately.  In the formatter, requests are used to
       set the page length (..ppll), page offset (or left margin, ..ppoo), and  line
       length  (..llll).  The right margin is not explicitly configured; the com‐
       bination of page offset and line length provides the information neces‐
       sary to derive it.  The _p_a_p_e_r_s_i_z_e macro package,  automatically  loaded
       by _t_r_o_f_f, provides an interface for configuring page dimensions by con‐
       venient  names,  like “letter” or “A4”; see _g_r_o_f_f___t_m_a_c(5).  The format‐
       ter’s default in this installation is “AA44”.

       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
       _D_E_S_C file.  Most output drivers also recognize a command‐line option --pp
       to  override  the  default dimensions and an option --ll to use landscape
       orientation.  See _g_r_o_f_f___f_o_n_t(5) for a description of the ppaappeerrssiizzee  di‐
       rective,  which  takes  an argument of the same form as --pp.  The output
       driver’s man page, such as _g_r_o_p_s(1), may also be helpful.   _g_r_o_f_f  uses
       the command‐line option --PP to 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

   FFrroonntt eenndd
       The _g_r_o_f_f program is a wrapper around the _t_r_o_f_f(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 _r_o_f_f(7) systems can be avoided.
       Use the _g_r_o_g(1) program to infer an appropriate _g_r_o_f_f command  line  to
       format a document.

   LLaanngguuaaggee
       Input  to a _r_o_f_f 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 _r_o_f_f; see  _r_o_f_f(7)  for  background.
       An  overview  of GNU _r_o_f_f language syntax and features, including lists
       of all supported escape sequences, requests, and predefined  registers,
       can  be  found in _g_r_o_f_f(7).  GNU _r_o_f_f extensions to the AT&T _t_r_o_f_f lan‐
       guage, a common subset of _r_o_f_f dialects extant today, are  detailed  in
       _g_r_o_f_f___d_i_f_f(7).

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

              _t_b_l         lays out tables;
              _e_q_n         typesets mathematics;
              _p_i_c         draws diagrams;
              _r_e_f_e_r       processes bibliographic references;
              _s_o_e_l_i_m      preprocesses “sourced” input files;
              _g_r_n         renders _g_r_e_m_l_i_n(1) diagrams;
              _c_h_e_m        draws chemical structural formulæ using _p_i_c;
              _g_p_e_r_l       populates _g_r_o_f_f registers and strings using _p_e_r_l(1);
              _g_l_i_l_y_p_o_n_d   embeds _L_i_l_y_P_o_n_d sheet music; and
              _g_p_i_n_y_i_n     eases Mandarin Chinese input using Hanyu Pinyin.

       A preprocessor unique to GNU _r_o_f_f is _p_r_e_c_o_n_v(1), which converts various
       input encodings to something GNU _t_r_o_f_f 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 _t_r_o_f_f.  The _i_d_e_a_l preprocessor is not yet  avail‐
       able in _g_r_o_f_f.

                ┌──────────────┬─────────────────┬────────────────┐
                │ preprocessor │ starting token  │  ending token  │
                ├──────────────┼─────────────────┼────────────────┤
                │     chem     │     .cstart     │     .cend      │
                │     eqn      │       .EQ       │      .EN       │
                │     grap     │       .G1       │      .G2       │
                │     grn      │       .GS       │      .GE       │
                │    ideal     │       .IS       │      .IE       │
                │              │                 │      .IF       │
                │     pic      │       .PS       │      .PE       │
                │              │                 │      .PF       │
                │              │                 │      .PY       │
                │    refer     │       .R1       │      .R2       │
                │     tbl      │       .TS       │      .TE       │
                ├──────────────┼─────────────────┼────────────────┤
                │  glilypond   │ .lilypond start │ .lilypond stop │
                │    gperl     │   .Perl start   │   .Perl stop   │
                │   gpinyin    │  .pinyin start  │  .pinyin stop  │
                └──────────────┴─────────────────┴────────────────┘

   MMaaccrroo ppaacckkaaggeess
       Macro  files  are  _r_o_f_f input files designed to produce no output them‐
       selves but instead ease the preparation of other _r_o_f_f documents.   When
       a  macro  file is installed at a standard location and suitable for use
       by a general audience, it is termed a _m_a_c_r_o _p_a_c_k_a_g_e.

       Macro packages can be loaded prior to any _r_o_f_f input documents with the
       --mm option.  The GNU _r_o_f_f system implements most well‐known macro  pack‐
       ages  for  AT&T _t_r_o_f_f 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 _n_r_o_f_f and _t_r_o_f_f 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 _s package, much better known as _m_s or even _-_m_s.

       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.

       _a_n     is  used  to compose man pages in the format originating in Ver‐
              sion 7 Unix (1979); see _g_r_o_f_f___m_a_n(7).  It can  be  specified  on
              the command line as --mmaann.

       _d_o_c    is  used  to  compose  man  pages  in  the format originating in
              4.3BSD‐Reno (1990); see _g_r_o_f_f___m_d_o_c(7).  It can be  specified  on
              the command line as --mmddoocc.

       _e      is the Berkeley general‐purpose macro suite, developed as an al‐
              ternative  to AT&T’s _s; see _g_r_o_f_f___m_e(7).  It can be specified on
              the command line as --mmee.

       _m      implements the format used by the second‐generation  AT&T  macro
              suite  for general documents, a successor to _s; see _g_r_o_f_f___m_m(7).
              It can be specified on the command line as --mmmm.

       _o_m     (invariably called “mom”) is a modern package written  by  Peter
              Schaffter  specifically for GNU _r_o_f_f.  Consult the _m_o_m HTML man‐
              ual for extensive documentation.  She—for _m_o_m takes  the  female
              pronoun—can be specified on the command line as --mmoomm.

       _s      is  the  original  AT&T  general‐purpose  document  format;  see
              _g_r_o_f_f___m_s(7).  It can be specified on the command line as --mmss.

       Others are supplemental.  For instance, _a_n_d_o_c is a wrapper package spe‐
       cific to GNU _r_o_f_f that recognizes whether a document uses _m_a_n  or  _m_d_o_c
       format  and loads the corresponding macro package.  It can be specified
       on the command line as --mmaannddoocc.  A _m_a_n(1)  librarian  program  may  use
       this macro file to delegate loading of the correct macro package; it is
       thus  unnecessary  for _m_a_n 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  _r_o_f_f  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
       _g_r_o_f_f___t_m_a_c(5).

   FFoorrmmaatttteerrss
       The formatter, the program that  interprets  _r_o_f_f  language  input,  is
       _t_r_o_f_f(1).   It  provides  the features of the AT&T _t_r_o_f_f and _n_r_o_f_f pro‐
       grams as well as many extensions.  The command‐line option --CC  switches
       _t_r_o_f_f  into  _c_o_m_p_a_t_i_b_i_l_i_t_y  _m_o_d_e,  which tries to emulate AT&T _t_r_o_f_f as
       closely as is practical to enable the formatting of  documents  written
       for the older system.

       A  shell script, _n_r_o_f_f(1), emulates the behavior of AT&T _n_r_o_f_f.  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 --TT option and
       is therefore convenient for use with terminal output devices, described
       in the next subsection.

       GNU  _t_r_o_f_f generates output in a device‐independent, but not device‐ag‐
       nostic, page description language detailed in _g_r_o_f_f___o_u_t(5).

   OOuuttppuutt ddeevviicceess
       _t_r_o_f_f output is formatted for a  particular  _o_u_t_p_u_t  _d_e_v_i_c_e,  typically
       specified by the --TT option to the formatter or a front end.  If neither
       this  option nor the _G_R_O_F_F___T_Y_P_E_S_E_T_T_E_R environment variable is used, the
       default output device is ppss.  An output device may be any of  the  fol‐
       lowing.

       aasscciiii    for terminals using the ISO 646 1991:IRV character set and en‐
                coding, also known as US‐ASCII.

       ccpp11004477   for  terminals  using the IBM code page 1047 character set and
                encoding.

       ddvvii      for TeX DVI format.

       hhttmmll
       xxhhttmmll    for HTML and XHTML output, respectively.

       llaattiinn11   for terminals using the ISO Latin‐1 (ISO 8859‐1) character set
                and encoding.

       llbbpp      for Canon CaPSL printers (LBP‐4 and LBP‐8 series laser  print‐
                ers).

       lljj44      for  HP LaserJet4‐compatible (or other PCL5‐compatible) print‐
                ers.

       ppddff      for PDF output.

       ppss       for PostScript output.

       uuttff88     for terminals using the ISO 10646 (“Unicode”) character set in
                UTF‐8 encoding.

       XX7755      for previewing with _g_x_d_i_t_v_i_e_w using 75 dpi  resolution  and  a
                10‐point base type size.

       XX7755--1122   for  previewing  with  _g_x_d_i_t_v_i_e_w using 75 dpi resolution and a
                12‐point base type size.

       XX110000     for previewing with _g_x_d_i_t_v_i_e_w using 100 dpi resolution  and  a
                10‐point base type size.

       XX110000--1122  for  previewing  with _g_x_d_i_t_v_i_e_w using 100 dpi resolution and a
                12‐point base type size.

   PPoossttpprroocceessssoorrss
       Any program that interprets the output of GNU _t_r_o_f_f is a postprocessor.
       The postprocessors provided by GNU _r_o_f_f are _o_u_t_p_u_t _d_r_i_v_e_r_s, 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   ppoossttpprroo   directive   in   its   device   description  file;  see
       _g_r_o_f_f___f_o_n_t(5).   The  --XX  option  overrides  this  selection,   causing
       _g_x_d_i_t_v_i_e_w to serve as the output driver.

       _g_r_o_d_v_i(1)
              provides ddvvii.

       _g_r_o_h_t_m_l(1)
              provides hhttmmll and xxhhttmmll.

       _g_r_o_l_b_p(1)
              provides llbbpp.

       _g_r_o_l_j_4(1)
              provides lljj44.

       _g_r_o_p_d_f(1)
              provides ppddff.

       _g_r_o_p_s(1)
              provides ppss.

       _g_r_o_t_t_y(1)
              provides aasscciiii, ccpp11004477, llaattiinn11, and uuttff88.

       _g_x_d_i_t_v_i_e_w(1)
              provides  XX7755,  XX7755--1122,  XX110000, and XX110000--1122, and additionally can
              preview ppss.

   UUttiilliittiieess
       GNU _r_o_f_f includes a suite of utilities.

       _g_d_i_f_f_m_k(1)
              marks differences between a pair of _r_o_f_f input files.

       _g_r_o_g(1)
              infers the _g_r_o_f_f command a document requires.

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

       _a_d_d_f_t_i_n_f_o(1)
              adds information to AT&T _t_r_o_f_f font description files to  enable
              their use with GNU _t_r_o_f_f.

       _a_f_m_t_o_d_i_t(1)
              creates font description files for PostScript Type 1 fonts.

       _p_f_b_t_o_p_s(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 _a_f_m_t_o_d_i_t.

       _h_p_f_t_o_d_i_t(1)
              creates font description files for the HP LaserJet 4  family  of
              printers.

       _t_f_m_t_o_d_i_t(1)
              creates font description files for the TeX DVI device.

       _x_t_o_t_r_o_f_f(1)
              creates font description files for X Window System core fonts.

       A  trio of tools transform material constructed using _r_o_f_f preprocessor
       languages into graphical image files.

       _e_q_n_2_g_r_a_p_h(1)
              converts an _e_q_n equation into a cropped image.

       _g_r_a_p_2_g_r_a_p_h(1)
              converts a _g_r_a_p diagram into a cropped image.

       _p_i_c_2_g_r_a_p_h(1)
              converts a _p_i_c diagram into a cropped image.

       Another set of programs works with the bibliographic data files used by
       the _r_e_f_e_r(1) preprocessor.

       _i_n_d_x_b_i_b(1)
              makes inverted indices  for  bibliographic  databases,  speeding
              lookup operations on them.

       _l_k_b_i_b(1)
              searches the databases.

       _l_o_o_k_b_i_b(1)
              interactively searches the databases.

EExxiitt ssttaattuuss
       _g_r_o_f_f  exits  with  a failure status if there was a problem parsing its
       arguments and a successful status if either of the options --hh or ----hheellpp
       was specified.  Otherwise, _g_r_o_f_f runs a pipeline to process its  input;
       if all commands within the pipeline exit successfully, _g_r_o_f_f does like‐
       wise.   If  not,  _g_r_o_f_f’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, _g_r_o_f_f 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 _g_r_o_f_f
       command with the --VV option and break the reported  pipeline  down  into
       separate  stages, inspecting the exit status of and diagnostic messages
       emitted by each command.

EEnnvviirroonnmmeenntt
       Normally, the path separator in environment variables ending with  _P_A_T_H
       is the colon; this may vary depending on the operating system.  For ex‐
       ample, Windows uses a semicolon instead.

       _G_R_O_F_F___B_I_N___P_A_T_H
              This  search  path, followed by _P_A_T_H, is used to locate commands
              executed by _g_r_o_f_f.  If it is not set, the installation directory
              of the GNU _r_o_f_f executables, _/_u_s_r_/_b_i_n, is searched before _P_A_T_H.

       _G_R_O_F_F___C_O_M_M_A_N_D___P_R_E_F_I_X
              GNU _r_o_f_f 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 _t_r_o_f_f, 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 _t_r_o_f_f would be installed as _g_t_r_o_f_f.  Besides _t_r_o_f_f,
              the prefix applies to the  formatter  _n_r_o_f_f;  the  preprocessors
              _e_q_n, _g_r_n, _p_i_c, _r_e_f_e_r, _t_b_l, and _s_o_e_l_i_m; and the utilities _i_n_d_x_b_i_b
              and _l_o_o_k_b_i_b.

       _G_R_O_F_F___E_N_C_O_D_I_N_G
              The  value  of  this  variable  is passed to the _p_r_e_c_o_n_v(1) pre‐
              processor’s --ee option to select the character encoding of  input
              files.   This  variable’s existence implies the _g_r_o_f_f option --kk.
              If set but empty, _g_r_o_f_f calls  _p_r_e_c_o_n_v  without  an  --ee  option.
              _g_r_o_f_f’s --KK option overrides _G_R_O_F_F___E_N_C_O_D_I_N_G.

       _G_R_O_F_F___F_O_N_T___P_A_T_H
              Seek  the  selected output device’s directory of device and font
              description files in this list of directories.  See _t_r_o_f_f(1) and
              _g_r_o_f_f___f_o_n_t(5).

       _G_R_O_F_F___T_M_A_C___P_A_T_H
              Seek macro files in this list of directories.  See _t_r_o_f_f(1)  and
              _g_r_o_f_f___t_m_a_c(5).

       _G_R_O_F_F___T_M_P_D_I_R
              Create  temporary  files in this directory.  If not set, but the
              environment variable _T_M_P_D_I_R is set, temporary files are  created
              there  instead.  On Windows systems, if neither of the foregoing
              are set, the environment variables _T_M_P and _T_E_M_P (in that  order)
              are  checked  also.   Otherwise,  temporary files are created in
              _/_t_m_p.  The _r_e_f_e_r(1), _g_r_o_h_t_m_l(1), and _g_r_o_p_s(1) commands use  tem‐
              porary files.

       _G_R_O_F_F___T_Y_P_E_S_E_T_T_E_R
              Set the default output device.  If empty or not set, ppss is used.
              The --TT option overrides _G_R_O_F_F___T_Y_P_E_S_E_T_T_E_R.

       _S_O_U_R_C_E___D_A_T_E___E_P_O_C_H
              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 _g_m_t_i_m_e(3) and
              _a_s_c_t_i_m_e(3)  when the formatter starts up and stored in registers
              usable by documents and macro packages.

       _T_Z     The time zone to use when converting the current time to  human‐
              readable  form;  see _t_z_s_e_t(3).  If _S_O_U_R_C_E___D_A_T_E___E_P_O_C_H is used, it
              is always converted to human‐readable form using UTC.

EExxaammpplleess
       _r_o_f_f systems are best known for formatting man pages.   Once  a  _m_a_n(1)
       librarian  program  has located a man page, it may execute a _g_r_o_f_f 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 _g_r_o_f_f emits for bold‐
       face, underlining, or italics; see section “Limitations” below.

       To process a _r_o_f_f input file using the preprocessors _t_b_l  and  _p_i_c  and
       the  _m_e  macro package in the way to which AT&T _t_r_o_f_f users were accus‐
       tomed, one would type (or script) a pipeline.

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

       Using _g_r_o_f_f, 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 _g_r_o_g(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 “--” because _g_r_o_f_f passes the arguments as‐is to
       the postprocessor; this permits arbitrary arguments to be  transmitted.
       For  example, to pass a title to the _g_x_d_i_t_v_i_e_w 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.

LLiimmiittaattiioonnss
       When paging output for the aasscciiii, ccpp11004477,  llaattiinn11,  and  uuttff88  devices,
       programs  like  _m_o_r_e(1) and _l_e_s_s(1) may require command‐line options to
       correctly handle some terminal escape sequences; see _g_r_o_t_t_y(1).

       On EBCDIC hosts such as OS/390  Unix,  the  output  devices  aasscciiii  and
       llaattiinn11  aren’t  available.  Conversely, the output device ccpp11004477 is not
       available on systems based on the ISO 646 or ISO 8859 character  encod‐
       ing standards.

IInnssttaallllaattiioonn ddiirreeccttoorriieess
       GNU  _r_o_f_f installs files in varying locations depending on its compile‐
       time configuration.  On this installation, the following locations  are
       used.

       _/_e_t_c_/_X_1_1_/_a_p_p_-_d_e_f_a_u_l_t_s
              Application defaults directory for _g_x_d_i_t_v_i_e_w(1).

       _/_u_s_r_/_b_i_n
              Directory containing _g_r_o_f_f’s executable commands.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_e_i_g_n
              List of common words for _i_n_d_x_b_i_b(1).

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0
              Directory for data files.

       _/_u_s_r_/_d_i_c_t_/_p_a_p_e_r_s_/_I_n_d
              Default index for _l_k_b_i_b(1) and _r_e_f_e_r(1).

       _/_u_s_r_/_s_h_a_r_e_/_d_o_c_/_g_r_o_f_f_-_b_a_s_e
              Documentation directory.

       _/_u_s_r_/_s_h_a_r_e_/_d_o_c_/_g_r_o_f_f_-_b_a_s_e_/_e_x_a_m_p_l_e_s
              Example directory.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t
              Font directory.

       _/_u_s_r_/_s_h_a_r_e_/_d_o_c_/_g_r_o_f_f_-_b_a_s_e_/_h_t_m_l
              HTML documentation directory.

       _/_u_s_r_/_l_i_b_/_f_o_n_t
              Legacy font directory.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_s_i_t_e_-_f_o_n_t
              Local font directory.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_s_i_t_e_-_t_m_a_c
              Local macro package (_t_m_a_c file) directory.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c
              Macro package (_t_m_a_c file) directory.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_o_l_d_f_o_n_t
              Font directory for compatibility with old versions of _g_r_o_f_f; see
              _g_r_o_p_s(1).

       _/_u_s_r_/_s_h_a_r_e_/_d_o_c_/_g_r_o_f_f_-_b_a_s_e_/_p_d_f
              PDF documentation directory.

   _gg_rr_oo_ff_ff mmaaccrroo ddiirreeccttoorryy
       Most macro files supplied with GNU _r_o_f_f are stored in _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/
       _1_._2_3_._0_/_t_m_a_c  for the installation corresponding to this document.  As a
       rule, multiple directories are searched for macro files; see  _t_r_o_f_f(1).
       For a catalog of macro files GNU _r_o_f_f provides, see _g_r_o_f_f___t_m_a_c(5).

   _gg_rr_oo_ff_ff ddeevviiccee aanndd ffoonntt ddeessccrriippttiioonn ddiirreeccttoorryy
       Device  and font description files supplied with GNU _r_o_f_f are stored in
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t for the installation corresponding to this
       document.  As a rule, multiple directories are searched for device  and
       font  description files; see _t_r_o_f_f(1).  For the formats of these files,
       see _g_r_o_f_f___f_o_n_t(5).

AAvvaaiillaabbiilliittyy
       Obtain links to _g_r_o_f_f releases for  download,  its  source  repository,
       discussion  mailing lists, a support ticket tracker, and further infor‐
       mation from the _g_r_o_f_f page of the GNU website.

       A free implementation of the _g_r_a_p preprocessor, written  by  Ted Faber,
       can be found at the _g_r_a_p website.  _g_r_o_f_f supports only this _g_r_a_p.

AAuutthhoorrss
       _g_r_o_f_f (both the front‐end command and the overall system) was primarily
       written  by  James Clark.  Contributors to this document include Clark,
       Trent A. Fisher, Werner Lemberg, Bernd Warken, and G. Branden Robinson.

SSeeee aallssoo
       _G_r_o_f_f_: _T_h_e _G_N_U _I_m_p_l_e_m_e_n_t_a_t_i_o_n _o_f _t_r_o_f_f, by Trent A. Fisher  and  Werner
       Lemberg,  is the primary _g_r_o_f_f manual.  You can browse it interactively
       with “info groff”.

       Introduction, history, and further reading:
              _r_o_f_f(7)

       Viewer for _g_r_o_f_f (and AT&T device‐independent _t_r_o_f_f) documents:
              _g_x_d_i_t_v_i_e_w(1)

       Preprocessors:
              _c_h_e_m(1),  _e_q_n(1),  _n_e_q_n(1),  _g_l_i_l_y_p_o_n_d(1),  _g_r_n(1),  _p_r_e_c_o_n_v(1),
              _g_p_e_r_l(1), _p_i_c(1), _g_p_i_n_y_i_n(1), _r_e_f_e_r(1), _s_o_e_l_i_m(1), _t_b_l(1)

       Macro packages and package‐specific utilities:
              _g_r_o_f_f___h_d_t_b_l(7), _g_r_o_f_f___m_a_n(7), _g_r_o_f_f___m_a_n___s_t_y_l_e(7), _g_r_o_f_f___m_d_o_c(7),
              _g_r_o_f_f___m_e(7),  _g_r_o_f_f___m_m(7),  _g_r_o_f_f___m_m_s_e(7)  (only  in Swedish lo‐
              cales),   _m_m_r_o_f_f(1),   _g_r_o_f_f___m_o_m(7),   _p_d_f_m_o_m(1),   _g_r_o_f_f___m_s(7),
              _g_r_o_f_f___r_f_c_1_3_4_5(7), _g_r_o_f_f___t_r_a_c_e(7), _g_r_o_f_f___w_w_w(7)

       Bibliographic database management tools:
              _i_n_d_x_b_i_b(1), _l_k_b_i_b(1), _l_o_o_k_b_i_b(1)

       Language, conventions, and GNU extensions:
              _g_r_o_f_f(7),     _g_r_o_f_f___c_h_a_r(7),    _g_r_o_f_f___d_i_f_f(7),    _g_r_o_f_f___f_o_n_t(5),
              _g_r_o_f_f___t_m_a_c(5)

       Intermediate output language:
              _g_r_o_f_f___o_u_t(5)

       Formatter program:
              _t_r_o_f_f(1)

       Formatter wrappers:
              _n_r_o_f_f(1), _p_d_f_r_o_f_f(1)

       Postprocessors for output devices:
              _g_r_o_d_v_i(1),   _g_r_o_h_t_m_l(1),   _g_r_o_l_b_p(1),   _g_r_o_l_j_4(1),    _g_r_o_p_d_f(1),
              _g_r_o_p_s(1), _g_r_o_t_t_y(1)

       Font support utilities:
              _a_d_d_f_t_i_n_f_o(1), _a_f_m_t_o_d_i_t(1), _h_p_f_t_o_d_i_t(1), _p_f_b_t_o_p_s(1), _t_f_m_t_o_d_i_t(1),
              _x_t_o_t_r_o_f_f(1)

       Graphics conversion utilities:
              _e_q_n_2_g_r_a_p_h(1), _g_r_a_p_2_g_r_a_p_h(1), _p_i_c_2_g_r_a_p_h(1)

       Difference‐marking utility:
              _g_d_i_f_f_m_k(1)

       “groff guess” utility:
              _g_r_o_g(1)

groff 1.23.0                      3 June 2025                         _g_r_o_f_f(1)
───────────────────────────────────────────────────────────────────────────────
_g_r_o_g(1)                     General Commands Manual                    _g_r_o_g(1)

NNaammee
       grog - “groff guess”—infer the _g_r_o_f_f command a document requires

SSyynnooppssiiss
       ggrroogg [----rruunn] [----lliiggaattuurreess] [_g_r_o_f_f_‐_o_p_t_i_o_n ...] [----] [_f_i_l_e ...]

       ggrroogg --hh
       ggrroogg ----hheellpp

       ggrroogg --vv
       ggrroogg ----vveerrssiioonn

DDeessccrriippttiioonn
       _g_r_o_g  reads  its input and guesses which _g_r_o_f_f(1) options are needed to
       render it.  If no operands are given, or if _f_i_l_e is “--”, _g_r_o_g reads the
       standard input stream.  The corresponding  _g_r_o_f_f  command  is  normally
       written  to the standard output stream.  With the option ----rruunn, the in‐
       ferred command is written to the standard error stream  and  then  exe‐
       cuted.

OOppttiioonnss
       --hh and ----hheellpp display a usage message, whereas --vv and ----vveerrssiioonn display
       version information; all exit afterward.

       ----lliiggaattuurreess
              includes  the  arguments --PP--yy --PPUU in the inferred _g_r_o_f_f command.
              These are supported only by the ppddff output device.

       ----rruunn  writes 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 “--” followed by a letter) are interpreted as  _g_r_o_f_f  options
       or  option  clusters  with or without an option argument.  Such options
       are included in the constructed _g_r_o_f_f command line.

DDeettaaiillss
       _g_r_o_g reads each _f_i_l_e operand, pattern‐matching strings that are statis‐
       tically likely to be characteristic of _r_o_f_f(7) documents.  It tries  to
       guess  which  of  the following _g_r_o_f_f options are required to correctly
       render the input: --ee, --gg, --GG, --jj, --pp, --RR, --tt (preprocessors); and --mmaann,
       --mmddoocc, --mmddoocc--oolldd, --mmee, --mmmm, --mmoomm, and --mmss (macro  packages).   The  in‐
       ferred _g_r_o_f_f command including these options and any _f_i_l_e parameters is
       written to the standard output stream.

       It  is possible to specify arbitrary _g_r_o_f_f options on the command line.
       These are included in the inferred command without change.  Choices  of
       _g_r_o_f_f options include --CC to enable AT&T _t_r_o_f_f compatibility mode and --TT
       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  _g_r_o_f_f
       option  to  run the _p_r_e_c_o_n_v(1) preprocessor is advised; see the --DD, --kk,
       and --KK options of _g_r_o_f_f(1).  For UTF‐8 input, --kk is a good choice.

       _g_r_o_f_f may issue diagnostic messages when an inappropriate --mm option, or
       multiple conflicting ones, are specified.  Consequently, it is best  to
       specify  no  --mm options to _g_r_o_g unless it cannot correctly infer all of
       the --mm arguments a document requires.  A  _r_o_f_f  document  can  also  be
       written  without  recourse  to  any macro package.  In such cases, _g_r_o_g
       will infer a _g_r_o_f_f command without an --mm option.

   LLiimmiittaattiioonnss
       _g_r_o_g presumes that the input does not change the  escape,  control,  or
       no‐break  control characters.  _g_r_o_g does not parse _r_o_f_f input line con‐
       tinuation or control structures (brace escape sequences and  the  “iiff”,
       “iiee”, and “eell” requests) nor _g_r_o_f_f’s “wwhhiillee”.  Thus the input
              .if \
              t .NH 1
              .if n .SH
              Introduction
       will  conceal  the use of the _m_s macros NNHH and SSHH from _g_r_o_g.  Such con‐
       structions are regarded by _g_r_o_g’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.  _p_i_c, for example, requires PPSS, PPEE, and PPFF calls to imme‐
       diately follow the default control character  at  the  beginning  of  a
       line.

       Detection  of  the --ss option (the _s_o_e_l_i_m(1) preprocessor) is tricky; to
       correctly infer its necessity would require _g_r_o_g  to  recursively  open
       all  files  given as arguments to the ..ssoo request under the same condi‐
       tions that _s_o_e_l_i_m itself does so; see its man page.  Recall that _s_o_e_l_i_m
       is necessary only if sourced files need to be preprocessed.  Therefore,
       as a workaround, you may want to run the input through _s_o_e_l_i_m manually,
       piping it to _g_r_o_g, and compare the output to running _g_r_o_g on the  input
       directly.  If the “_s_o_e_l_i_m”ed input causes _g_r_o_g to infer additional pre‐
       processor options, then --ss is likely necessary.

              $ pprriinnttff ""..TTSS\\nnll..\\nnII''mm aa ttaabbllee..\\nn..TTEE\\nn"" >> 33..rrooffff
              $ pprriinnttff ""..ssoo 33..rrooffff\\nn"" >> 22..rrooffff
              $ pprriinnttff ""..XXPP\\nn..ssoo 22..rrooffff\\nn"" >> 11..rrooffff
              $ ggrroogg 11..rrooffff
              groff -ms 1.roff
              $ ssooeelliimm 11..rrooffff || ggrroogg
              groff -t -ms -

       In  the  foregoing  example, we see that this procedure enabled _g_r_o_g to
       detect _t_b_l(1) macros, so we would add --ss as well as the detected --tt op‐
       tion to a revised _g_r_o_g or _g_r_o_f_f command.

              $ ggrroogg --sstt 11..rrooffff
              groff -st -ms 1.roff

EExxiitt ssttaattuuss
       _g_r_o_g exits with error status 11 if a macro package appears to be in  use
       by  the input document, but _g_r_o_g was unable to infer which one, or 22 if
       there were problems handling an option or operand.  It otherwise  exits
       with  status 00.  (If the ----rruunn option is specified, _g_r_o_f_f’s exit status
       is discarded.)  Inferring no preprocessors or macro packages is not  an
       error condition; a valid _r_o_f_f document need not use either.  Even plain
       text is valid input, if one is mindful of the syntax of the control and
       escape characters.

EExxaammpplleess
       Running
              ggrroogg //uussrr//sshhaarree//ddoocc//ggrrooffff--bbaassee//mmeeiinnttrroo..mmee
       at the command line results in
              groff -me /usr/share/doc/groff-base/meintro.me
       because  _g_r_o_g  recognizes  that  the  file  _m_e_i_n_t_r_o_._m_e is written using
       macros from the _m_e package.  The command
              ggrroogg //uussrr//sshhaarree//ddoocc//ggrrooffff--bbaassee//ppiicc..mmss
       outputs
              groff -e -p -t -ms /usr/share/doc/groff-base/pic.ms
       on the other hand.  Besides discerning the _m_s macro package, _g_r_o_g  rec‐
       ognizes  that  the file _p_i_c_._m_s additionally needs the combination of --tt
       for _t_b_l, --ee for _e_q_n, and --pp for _p_i_c.

       Consider a file _d_o_c_/_g_r_n_e_x_a_m_p_l_._m_e, which uses the  _g_r_n  preprocessor  to
       include a _g_r_e_m_l_i_n(1) picture file in an _m_e document.  Let’s say we want
       to  suppress  color  output, produce a DVI file, and get backtraces for
       any errors that _t_r_o_f_f encounters.  The command
              ggrroogg --bbcc --IIddoocc --TTddvvii ddoocc//ggrrnneexxmmppll..mmee
       is processed by _g_r_o_g into
              groff -bc -Idoc -Tdvi -e -g -me doc/grnexmpl.me
       where we can see that _g_r_o_g has inferred the _m_e macro package along with
       the _e_q_n and _g_r_n preprocessors.  (The input file  is  located  in  _/_u_s_r_/
       _s_h_a_r_e_/_d_o_c_/_g_r_o_f_f_-_b_a_s_e if you’d like to try this example yourself.)

AAuutthhoorrss
       _g_r_o_g  was  originally written in Bourne shell by James Clark.  The cur‐
       rent implementation in Perl was written by Bernd Warken and heavily re‐
       vised by G. Branden Robinson.

SSeeee aallssoo
       _g_r_o_f_f(1)

groff 1.23.0                      3 June 2025                          _g_r_o_g(1)
───────────────────────────────────────────────────────────────────────────────
_g_r_o_h_t_m_l(1)                  General Commands Manual                 _g_r_o_h_t_m_l(1)

NNaammee
       grohtml, post-grohtml, pre-grohtml - _g_r_o_f_f output driver for HTML

SSyynnooppssiiss
       pprree--ggrroohhttmmll [--eeppVV] [--aa _a_n_t_i_‐_a_l_i_a_s_i_n_g_‐_t_e_x_t_‐_b_i_t_s] [--DD _i_m_a_g_e_‐_d_i_r_e_c_t_o_r_y]
                   [--FF _f_o_n_t_‐_d_i_r_e_c_t_o_r_y] [--gg _a_n_t_i_‐_a_l_i_a_s_i_n_g_‐_g_r_a_p_h_i_c_‐_b_i_t_s] [--ii
                   _r_e_s_o_l_u_t_i_o_n] [--II _i_m_a_g_e_‐_s_t_e_m] [--oo _i_m_a_g_e_‐_v_e_r_t_i_c_a_l_‐_o_f_f_s_e_t] [--xx
                   _h_t_m_l_‐_d_i_a_l_e_c_t] _t_r_o_f_f_‐_c_o_m_m_a_n_d _t_r_o_f_f_‐_a_r_g_u_m_e_n_t ...

       pprree--ggrroohhttmmll ----hheellpp

       pprree--ggrroohhttmmll --vv
       pprree--ggrroohhttmmll ----vveerrssiioonn

       ppoosstt--ggrroohhttmmll [--bbCCGGhhllnnrrVVyy] [--FF _f_o_n_t_‐_d_i_r_e_c_t_o_r_y] [--jj _o_u_t_p_u_t_‐_s_t_e_m] [--ss
                    _b_a_s_e_‐_p_o_i_n_t_‐_s_i_z_e] [--SS _h_e_a_d_i_n_g_‐_l_e_v_e_l] [--xx _h_t_m_l_‐_d_i_a_l_e_c_t]
                    [_f_i_l_e ...]

       ppoosstt--ggrroohhttmmll ----hheellpp

       ppoosstt--ggrroohhttmmll --vv
       ppoosstt--ggrroohhttmmll ----vveerrssiioonn

DDeessccrriippttiioonn
       The  GNU  _r_o_f_f  system’s  HTML  support  consists  of  a  preprocessor,
       _p_r_e_-_g_r_o_h_t_m_l,  and an output driver, _p_o_s_t_-_g_r_o_h_t_m_l; together, they trans‐
       late _r_o_f_f(7) documents to HTML.  Because a preprocessor  is  (uniquely)
       required  for  this  output driver, users should invoke _g_r_o_h_t_m_l via the
       _g_r_o_f_f(1) command with the --TThhttmmll or --TTxxhhttmmll options.  (In this  instal‐
       lation,  ppss  is  the  default output device.)  Use _g_r_o_f_f’s --PP option to
       pass any options shown above to _g_r_o_h_t_m_l.  If no operands are given,  or
       if  _f_i_l_e  is  “--”,  _g_r_o_h_t_m_l reads the standard input stream.  Output is
       written to the standard output stream.

       _g_r_o_h_t_m_l invokes _g_r_o_f_f twice.   In  the  first  pass,  the  preprocessor
       _p_r_e_-_g_r_o_h_t_m_l  renders pictures, equations, and tables as images in Post‐
       Script format using the ppss output device.  In the second pass, the out‐
       put driver _p_o_s_t_-_g_r_o_h_t_m_l translates the output of _t_r_o_f_f(1) to HTML.

       _g_r_o_h_t_m_l writes output encoded in UTF‐8 and has built‐in  HTML  entities
       for  all non‐composite Unicode characters.  In spite of this, _g_r_o_f_f 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.

   TTyyppeeffaacceess
       _g_r_o_h_t_m_l supports the standard four styles: RR  (roman),  II  (_i_t_a_l_i_c),  BB
       (bboolldd),  and BBII (_bb_oo_ll_dd_‐‐_ii_tt_aa_ll_ii_cc).  Fonts are grouped into families TT and CC
       having members in each style.

              TTRR     Times roman
              TTII     Times italic
              TTBB     Times bold
              TTBBII    Times bold‐italic
              CCRR     Courier roman
              CCII     Courier italic
              CCBB     Courier bold
              CCBBII    Courier bold‐italic

       A special font, SS, is also provided to accommodate _r_o_f_f documents  that
       expect it to always be available.

   FFoonntt ddeessccrriippttiioonn ffiilleess
       The  font  description  files  used  with _g_r_o_h_t_m_l expose the same glyph
       repertoire in their cchhaarrsseett sections.  See _g_r_o_f_f___f_o_n_t(5).

   DDeeppeennddeenncciieess
       _p_r_e_-_g_r_o_h_t_m_l generates an image whenever an _e_q_n equation, _t_b_l table,  or
       _p_i_c  picture  is  encountered  in the input.  _g_r_o_h_t_m_l therefore may run
       several commands as part of its operation.  These  include  the  Netpbm
       tools  _p_n_m_c_r_o_p, _p_n_m_c_u_t, and _p_n_m_t_o_p_n_g; Ghostscript (_g_s); and the PSUtils
       tool _p_s_s_e_l_e_c_t.

OOppttiioonnss
       ----hheellpp displays a usage message, while --vv and  ----vveerrssiioonn  show  version
       information; all exit afterward.

       --aa _a_n_t_i_‐_a_l_i_a_s_i_n_g_‐_t_e_x_t_‐_b_i_t_s
              Number  of  bits  of antialiasing information to be used by text
              when generating PNG images.  The default is 44 but 00,  11,  and  22
              are  also  valid.   Your system’s version of _g_s must support the
              --ddTTeexxttAAllpphhaaBBiittss option in  order  to  exploit  antialiasing.   A
              value  of  00 stops _g_r_o_h_t_m_l from issuing antialiasing commands to
              _g_s.

       --bb     Initialize the background color to white.

       --CC     Suppress output of “CreationDate:” HTML comment.

       --DD _i_m_a_g_e_‐_d_i_r_e_c_t_o_r_y
              Instruct _g_r_o_h_t_m_l to place all image files into directory  _i_m_a_g_e_‐
              _d_i_r_e_c_t_o_r_y.

       --ee     Direct _e_q_n to produce MathML.

              This  option should not be manually specified; it is synthesized
              by _g_r_o_f_f depending on whether it was given the --TThhttmmll or --TTxxhhttmmll
              option.

       --FF _f_o_n_t_‐_d_i_r_e_c_t_o_r_y
              Prepend directory font‐directory_/_d_e_vname to the search path  for
              font  and  device description files; _n_a_m_e is the name of the de‐
              vice, usually hhttmmll.

       --gg _a_n_t_i_‐_a_l_i_a_s_i_n_g_‐_g_r_a_p_h_i_c_‐_b_i_t_s
              Number of bits of antialiasing information to be used by  graph‐
              ics  when generating PNG images.  The default is 44 but 00, 11, and
              22 are also valid.  Your system’s version of _g_s must support  the
              --ddGGrraapphhiiccAAllpphhaaBBiittss  option  in order to exploit antialiasing.  A
              value of 00 stops _g_r_o_h_t_m_l from issuing antialiasing  commands  to
              _g_s.

       --GG     Suppress output of “Creator:” HTML comment.

       --hh     Generate  section headings by using HTML BB elements and increas‐
              ing the font size, rather than HTML HH elements.

       --ii _r_e_s_o_l_u_t_i_o_n
              Set the image resolution in pixels per inch; the default is 110000.

       --II _i_m_a_g_e_‐_s_t_e_m
              Determine the image file name stem.  If  omitted,  _g_r_o_h_t_m_l  uses
              _g_r_o_h_t_m_l_-XXXXX  (where  _X_X_X_X_X  is the process ID).  A dash is ap‐
              pended to the stem to separate it from the following image  num‐
              ber.

       --jj _o_u_t_p_u_t_‐_s_t_e_m
              Instruct  _g_r_o_h_t_m_l  to split the HTML output into multiple files.
              Output is written to a new file at each section heading (but see
              option --SS below) named _o_u_t_p_u_t_‐_s_t_e_m_-n_._h_t_m_l.

       --ll     Turn off the production of automatic section links at the top of
              the document.

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

       --oo _i_m_a_g_e_‐_v_e_r_t_i_c_a_l_‐_o_f_f_s_e_t
              Specify the vertical offset of images in points.

       --pp     Display  page  rendering  progress to the standard error stream.
              _g_r_o_h_t_m_l displays a page number only when an image is required.

       --rr     Turn off the automatic header and footer line (HTML rule).

       --ss _b_a_s_e_‐_t_y_p_e_‐_s_i_z_e
              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  “bbiigg”
              element, and conversely when a decrease of two points is seen, a
              “ssmmaallll” element is emitted.

       --SS _h_e_a_d_i_n_g_‐_l_e_v_e_l
              When  splitting HTML output (see option --jj above), split at each
              nested heading level defined by _h_e_a_d_i_n_g_‐_l_e_v_e_l, or higher).   The
              default is 11.

       --VV     Create  an  XHTML or HTML validator button at the bottom of each
              page of the document.

       --xx _h_t_m_l_‐_d_i_a_l_e_c_t
              Select HTML dialect.  Currently, _h_t_m_l_‐_d_i_a_l_e_c_t should  be  either
              the  digit  44  or  the letter xx, which indicates whether _g_r_o_h_t_m_l
              should generate HTML 4 or XHTML, respectively.

              This option should not be manually specified; it is  synthesized
              by _g_r_o_f_f depending on whether it was given the --TThhttmmll or --TTxxhhttmmll
              option.

       --yy     Produce  a right‐aligned _g_r_o_f_f signature at the end of the docu‐
              ment (only if --VV is also specified).

EEnnvviirroonnmmeenntt
       _G_R_O_F_F___F_O_N_T___P_A_T_H
              lists directories in which to search for _d_e_v_h_t_m_l, _g_r_o_h_t_m_l’s  di‐
              rectory  of device and font description files.  See _t_r_o_f_f(1) and
              _g_r_o_f_f___f_o_n_t(5).

       _S_O_U_R_C_E___D_A_T_E___E_P_O_C_H
              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 _g_m_t_i_m_e(3) and
              _a_s_c_t_i_m_e(3), and recorded in an HTML comment.

       _T_Z     The time zone to use when converting the current time to  human‐
              readable  form;  see _t_z_s_e_t(3).  If _S_O_U_R_C_E___D_A_T_E___E_P_O_C_H is used, it
              is always converted to human‐readable form using UTC.

FFiilleess
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_h_t_m_l_/_D_E_S_C
              describes the hhttmmll output device.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_h_t_m_l_/F
              describes the font known as _F on device hhttmmll.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_h_t_m_l_._t_m_a_c
              defines font mappings, special characters, and  colors  for  use
              with  the  hhttmmll  output  device.   It is automatically loaded by
              _t_r_o_f_f_r_c when either of the hhttmmll or xxhhttmmll output devices  is  se‐
              lected.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_h_t_m_l_-_e_n_d_._t_m_a_c
              finalizes  setup of the hhttmmll output device.  It is automatically
              loaded by _t_r_o_f_f_r_c_-_e_n_d when either of the hhttmmll  or  xxhhttmmll  output
              devices is selected.

       _g_r_o_h_t_m_l  uses  temporary  files.   See _g_r_o_f_f(1) for details about where
       such files are created.

BBuuggss
       _g_r_o_h_t_m_l is still beta code.

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

SSeeee aallssoo
       _g_r_o_f_f(1), _t_r_o_f_f(1), _g_r_o_f_f___f_o_n_t(5)

groff 1.23.0                      3 June 2025                       _g_r_o_h_t_m_l(1)
───────────────────────────────────────────────────────────────────────────────
_g_r_o_l_b_p(1)                   General Commands Manual                  _g_r_o_l_b_p(1)

NNaammee
       grolbp - _g_r_o_f_f output driver for Canon CaPSL printers

SSyynnooppssiiss
       ggrroollbbpp [--ll] [--cc _n_u_m_‐_c_o_p_i_e_s] [--FF _f_o_n_t_‐_d_i_r_e_c_t_o_r_y] [--oo _o_r_i_e_n_t_a_t_i_o_n]
              [--pp _p_a_p_e_r_‐_f_o_r_m_a_t] [--ww _w_i_d_t_h] [_f_i_l_e ...]
       ggrroollbbpp [----ccooppiieess==_n_u_m_‐_c_o_p_i_e_s] [----ffoonnttddiirr==_f_o_n_t_‐_d_i_r_e_c_t_o_r_y] [----llaannddssccaappee]
              [----lliinneewwiiddtthh==_w_i_d_t_h] [----oorriieennttaattiioonn==_o_r_i_e_n_t_a_t_i_o_n]
              [----ppaappeerrssiizzee==_p_a_p_e_r_‐_f_o_r_m_a_t] [_f_i_l_e ...]

       ggrroollbbpp --hh
       ggrroollbbpp ----hheellpp

       ggrroollbbpp --vv
       ggrroollbbpp ----vveerrssiioonn

DDeessccrriippttiioonn
       This GNU _r_o_f_f output driver translates the output of  _t_r_o_f_f(1)  into  a
       CaPSL and VDM format suitable for Canon LBP‐4 and LBP‐8 printers.  Nor‐
       mally,  _g_r_o_l_b_p  is  invoked  by  _g_r_o_f_f(1)  when the latter is given the
       “--TT llbbpp” option.  (In this installation, ppss is the default  output  de‐
       vice.)   Use  _g_r_o_f_f’s  --PP  option  to  pass  any options shown above to
       _g_r_o_l_b_p.  If no _f_i_l_e arguments are given, or  if  _f_i_l_e  is  “-”,  _g_r_o_l_b_p
       reads  the  standard  input  stream.  Output is written to the standard
       output stream.

   TTyyppeeffaacceess
       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
       _g_r_o_f_f font names used to access them.

           ┌───────────────┬─────────┬────────┬──────────┬──────────────┐
           │   TTyyppeeffaaccee    │  RRoommaann  │  BBoolldd  │  IIttaalliicc  │  BBoolldd‐‐IIttaalliicc │
           ├───────────────┼─────────┼────────┼──────────┼──────────────┤
           │ Dutch         │  TR     │  TB    │  TI      │  TBI         │
           ├───────────────┼─────────┼────────┼──────────┼──────────────┤
           │ Swiss         │  HR     │  HB    │  HI      │  HBI         │
           ├───────────────┼─────────┼────────┼──────────┼──────────────┤
           │ Swiss Narrow  │  HNR    │  HNB   │  HNI     │  HNBI        │
           ├───────────────┼─────────┼────────┼──────────┼──────────────┤
           │ Courier       │  CR     │  CB    │  CI      │              │
           ├───────────────┼─────────┼────────┼──────────┼──────────────┤
           │ Elite         │  ER     │  EB    │  EI      │              │
           └───────────────┴─────────┴────────┴──────────┴──────────────┘

   PPaappeerr ffoorrmmaatt,, oorriieennttaattiioonn,, aanndd ddeevviiccee ddeessccrriippttiioonn ffiillee
       _g_r_o_l_b_p supports paper formats “AA44”, “lleetttteerr”, “lleeggaall”, and “eexxeeccuuttiivvee”.
       These are matched case‐insensitively.  The --pp, ----ppaappeerrssiizzee option over‐
       rides  any  setting  in  the  device description file _D_E_S_C.  If neither
       specifies a paper format, A4 is assumed.

       In its _D_E_S_C file, _g_r_o_l_b_p (case‐insensitively) recognizes an oorriieennttaattiioonn
       directive accepting one mandatory argument, ppoorrttrraaiitt or llaannddssccaappee.  The
       first valid orientation directive encountered controls.   The  --ll,  --oo,
       and  ----oorriieennttaattiioonn  command‐line  options override any setting in _D_E_S_C.
       If none of the foregoing specify the orientation, portrait is assumed.

   FFoonntt ddeessccrriippttiioonn ffiilleess
       In addition to the  font  description  file  directives  documented  in
       _g_r_o_f_f___f_o_n_t(5),  _g_r_o_l_b_p  recognizes  llbbppnnaammee,  which maps the _g_r_o_f_f font
       name to the font name used internally by the printer.  Its syntax is as
       follows.
              lbpname _p_r_i_n_t_e_r_‐_f_o_n_t_‐_n_a_m_e
       llbbppnnaammee’s argument is case‐sensitive.  The printer’s font names are en‐
       coded as follows.

       For bitmapped fonts, _p_r_i_n_t_e_r_‐_f_o_n_t___n_a_m_e has the form
              N⟨_b_a_s_e_‐_f_o_n_t_‐_n_a_m_e⟩⟨_f_o_n_t_‐_s_t_y_l_e⟩
       _b_a_s_e_‐_f_o_n_t_‐_n_a_m_e 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.  _f_o_n_t_‐_s_t_y_l_e can be one of the letters RR, II, or BB, 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 _g_r_o_f_f font description file is
              lbpname NeliteI
       You may need to modify _g_r_o_l_b_p 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, _p_r_i_n_t_e_r_‐_f_o_n_t_‐_n_a_m_e 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 _g_r_o_f_f font
       description file _H_B_I for the llbbpp device.

   DDrraawwiinngg ccoommmmaannddss
       For compatibility with _g_r_o_l_j_4(1),  an  additional  drawing  command  is
       available.

       \\DD''RR _d_h _d_v''
              Draw a rule (solid black rectangle) with one corner at the draw‐
              ing  position, and the diagonally opposite corner at the drawing
              position +(_d_h,_d_v).

OOppttiioonnss
       --hh and ----hheellpp display a usage message, while --vv and ----vveerrssiioonn show ver‐
       sion information; all exit afterward.

       --cc _n_u_m_‐_c_o_p_i_e_s
       ----ccooppiieess==_n_u_m_‐_c_o_p_i_e_s
              Produce _n_u_m_‐_c_o_p_i_e_s copies of each page.

       --FF _f_o_n_t_‐_d_i_r_e_c_t_o_r_y
       ----ffoonnttddiirr==_f_o_n_t_‐_d_i_r_e_c_t_o_r_y
              Prepend directory font‐directory_/_d_e_vname to the search path  for
              font  and  device description files; _n_a_m_e is the name of the de‐
              vice, usually llbbpp.

       --ll
       ----llaannddssccaappee
              Format the document in landscape orientation.

       --oo _o_r_i_e_n_t_a_t_i_o_n
       ----oorriieennttaattiioonn==_o_r_i_e_n_t_a_t_i_o_n
              Format the document in the  given  _o_r_i_e_n_t_a_t_i_o_n,  which  must  be
              “ppoorrttrraaiitt” or “llaannddssccaappee”.

       --pp _p_a_p_e_r_‐_f_o_r_m_a_t
       ----ppaappeerrssiizzee==_p_a_p_e_r_‐_f_o_r_m_a_t
              Set  the paper format to _p_a_p_e_r_‐_f_o_r_m_a_t, which must be a valid pa‐
              per format as described above.

       --ww _w_i_d_t_h
       ----lliinneewwiiddtthh==_w_i_d_t_h
              Set the default line thickness to _w_i_d_t_h thousandths  of  an  em;
              the default is 4400 (0.04 em).

EEnnvviirroonnmmeenntt
       _G_R_O_F_F___F_O_N_T___P_A_T_H
              lists  directories in which to seek the selected output device’s
              directory of device and font description  files.   See  _t_r_o_f_f(1)
              and _g_r_o_f_f___f_o_n_t(5).

FFiilleess
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_l_b_p_/_D_E_S_C
              describes the llbbpp output device.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_l_b_p_/F
              describes the font known as _F on device llbbpp.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_l_b_p_._t_m_a_c
              defines  macros for use with the llbbpp output device.  It is auto‐
              matically loaded by _t_r_o_f_f_r_c when the llbbpp output  device  is  se‐
              lected.

SSeeee aallssoo
       _g_r_o_f_f(1), _t_r_o_f_f(1), _g_r_o_f_f___o_u_t(5), _g_r_o_f_f___f_o_n_t(5), _g_r_o_f_f___c_h_a_r(7)

groff 1.23.0                      3 June 2025                        _g_r_o_l_b_p(1)
───────────────────────────────────────────────────────────────────────────────
_g_r_o_l_j_4(1)                   General Commands Manual                  _g_r_o_l_j_4(1)

NNaammee
       grolj4 - _g_r_o_f_f output driver for HP LaserJet 4 and compatible printers

SSyynnooppssiiss
       ggrroolljj44 [--ll] [--cc _n_u_m_‐_c_o_p_i_e_s] [--dd [_n]] [--FF _f_o_n_t_‐_d_i_r_e_c_t_o_r_y] [--pp _p_a_p_e_r_‐
              _f_o_r_m_a_t] [--ww _l_i_n_e_‐_w_i_d_t_h] [_f_i_l_e ...]

       ggrroolljj44 ----hheellpp

       ggrroolljj44 --vv
       ggrroolljj44 ----vveerrssiioonn

DDeessccrriippttiioonn
       This  GNU  _r_o_f_f  output driver translates the output of _t_r_o_f_f(1) into a
       PCL5 format suitable for an HP LaserJet 4 printer.  Normally, _g_r_o_l_j_4 is
       invoked by _g_r_o_f_f(1) when the latter is given the “--TT lljj44” option.   (In
       this  installation,  ppss  is the default output device.)  Use _g_r_o_f_f’s --PP
       option to pass any options shown above to _g_r_o_l_j_4.  If no _f_i_l_e arguments
       are given, or if _f_i_l_e is “-”, _g_r_o_l_j_4 reads the standard  input  stream.
       Output is written to the standard output stream.

   TTyyppeeffaacceess
       _g_r_o_l_j_4  supports  the  standard  four  styles: RR (roman), II (_i_t_a_l_i_c), BB
       (bboolldd), and BBII (_bb_oo_ll_dd_‐‐_ii_tt_aa_ll_ii_cc).  Fonts are grouped into families AA, CC, GG,
       OO, TT, TTNN, UU, and UUCC having members in each style.

              AABB            Arial Bold
              AABBII           Arial Bold Italic
              AAII            Arial Italic
              AARR            Arial Roman
              CCBB            Courier Bold
              CCBBII           Courier Bold Italic
              CCII            Courier Italic
              CCRR            Courier Roman
              GGBB            Garamond Halbfett
              GGBBII           Garamond Kursiv Halbfett
              GGII            Garamond Kursiv
              GGRR            Garamond Antiqua
              OOBB            CG Omega Bold
              OOBBII           CG Omega Bold Italic
              OOII            CG Omega Italic
              OORR            CG Omega Roman
              OOBB            CG Omega Bold
              OOBBII           CG Omega Bold Italic
              OOII            CG Omega Italic
              OORR            CG Omega Roman
              TTBB            CG Times Bold
              TTBBII           CG Times Bold Italic
              TTII            CG Times Italic
              TTRR            CG Times Roman
              TTNNRRBB          M Times Bold
              TTNNRRBBII         M Times Bold Italic
              TTNNRRII          M Times Italic
              TTNNRRRR          M Times Roman
              UUBB            Univers Bold
              UUBBII           Univers Bold Italic
              UUII            Univers Medium Italic
              UURR            Univers Medium
              UUCCBB           Univers Condensed Bold
              UUCCBBII          Univers Condensed Bold Italic
              UUCCII           Univers Condensed Medium Italic
              UUCCRR           Univers Condensed Medium

       The following fonts are not members of a family.

              AALLBBBB          Albertus Extra Bold
              AALLBBRR          Albertus Medium
              AAOOBB           Antique Olive Bold
              AAOOII           Antique Olive Italic
              AAOORR           Antique Olive Roman
              CCLLAARREENNDDOONN     Clarendon
              CCOORROONNEETT       Coronet
              LLGGBB           Letter Gothic Bold
              LLGGII           Letter Gothic Italic
              LLGGRR           Letter Gothic Roman
              MMAARRIIGGOOLLDD      Marigold

       The special font is SS  (PostScript  Symbol);  SSYYMMBBOOLL  (M  Symbol),  and
       WWIINNGGDDIINNGGSS (Wingdings) are also available but not mounted by default.

   PPaappeerr ffoorrmmaatt aanndd ddeevviiccee ddeessccrriippttiioonn ffiillee
       _g_r_o_l_j_4   supports  paper  formats  “AA44”,  “BB55”,  “CC55”,  “ccoomm1100”,  “DDLL”,
       “eexxeeccuuttiivvee”, “lleeggaall”, “lleetttteerr”, and “mmoonnaarrcchh”.  These are matched case‐
       insensitively.  The --pp option overrides any setting in the  device  de‐
       scription  file _D_E_S_C.  If neither specifies a paper format, “letter” is
       assumed.

   FFoonntt ddeessccrriippttiioonn ffiilleess
       _g_r_o_l_j_4 recognizes four font description file directives in addition  to
       those documented in _g_r_o_f_f___f_o_n_t(5).

       ppccllwweeiigghhtt _n
              Set  the  stroke  weight to _n, an integer in the range -7 to +7;
              the default is 0.

       ppccllssttyyllee _n
              Set the style to _n, an integer in the range 0 to 32767; the  de‐
              fault is 0.

       ppccllpprrooppoorrttiioonnaall _n
              Set the proportional spacing Boolean flag to _n, which can be ei‐
              ther 0 or 1; the default is 0.

       ppccllttyyppeeffaaccee _n
              Set  the  typeface  family  to  _n,  an integer in the range 0 to
              65535; the default is 0.

   DDrraawwiinngg ccoommmmaannddss
       An additional drawing command is recognized as an  extension  to  those
       documented in _g_r_o_f_f(7).

       \\DD''RR _d_h _d_v''
              Draw a rule (solid black rectangle) with one corner at the draw‐
              ing  position, and the diagonally opposite corner at the drawing
              position +(_d_h,_d_v), 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
              \\DD commands.

   FFoonnttss
       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 _g_r_o_f_f 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 _P_C_L _5 _C_o_m_p_a_r_i_s_o_n _G_u_i_d_e and the _P_C_L _5 _C_o_m_p_a_r_i_s_o_n  _G_u_i_d_e  _A_d_d_e_n_d_u_m
       (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, _h_p_f_t_o_d_i_t(1)
       searches a list of symbol sets, and selects the first set that contains
       the glyph.  The printing code generated by _h_p_f_t_o_d_i_t 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 _g_r_o_f_f___f_o_n_t(5) for a  complete  descrip‐
       tion  of the font file format; symbol sets are described in greater de‐
       tail in the _P_C_L _5 _P_r_i_n_t_e_r _L_a_n_g_u_a_g_e _T_e_c_h_n_i_c_a_l _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l.

       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 _h_p_f_t_o_d_i_t assume that the  _D_E_S_C  file  contains
       values  of  1200  for  _r_e_s  and  6350 for _u_n_i_t_w_i_d_t_h, or any combination
       (e.g., 2400 and 3175) for which _r_e_s × _u_n_i_t_w_i_d_t_h = 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 ddeevvlljj44
       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  _r_e_s  (and  lesser
       _u_n_i_t_w_i_d_t_h) 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 _e_q_n(1).  A script, located  in  _/_u_s_r_/
       _s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_l_j_4_/_g_e_n_e_r_a_t_e, can be used to adjust the met‐
       rics  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.

OOppttiioonnss
       ----hheellpp displays a usage message, while --vv and  ----vveerrssiioonn  show  version
       information; all exit afterward.

       --cc _n_u_m_‐_c_o_p_i_e_s
              Format _n_u_m_‐_c_o_p_i_e_s copies of each page.

       --dd [_n] Use  duplex  mode  _n: 1 is long‐side binding (default), and 2 is
              short‐side binding.

       --FF _f_o_n_t_‐_d_i_r_e_c_t_o_r_y
              Prepend directory _f_o_n_t_‐_d_i_r_e_c_t_o_r_y/dev_n_a_m_e to the search path  for
              font  and  device description files; _n_a_m_e is the name of the de‐
              vice, usually lljj44.

       --ll     Format the document in landscape orientation.

       --pp _p_a_p_e_r_‐_f_o_r_m_a_t
              Set the paper format to _p_a_p_e_r_‐_f_o_r_m_a_t, which must be a valid  pa‐
              per format as described above.

       --ww _l_i_n_e_‐_w_i_d_t_h
              Set  the  default line thickness to _l_i_n_e_‐_w_i_d_t_h thousandths of an
              em; the default is 4400 (0.04 em).

EEnnvviirroonnmmeenntt
       _G_R_O_F_F___F_O_N_T___P_A_T_H
              lists directories in which to seek the selected output  device’s
              directory  of  device  and font description files.  See _t_r_o_f_f(1)
              and _g_r_o_f_f___f_o_n_t(5).

FFiilleess
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_l_j_4_/_D_E_S_C
              describes the lljj44 output device.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_l_j_4_/F
              describes the font known as _F on device lljj44.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_l_j_4_._t_m_a_c
              defines macros for use with the lljj44 output device.  It is  auto‐
              matically  loaded  by  _t_r_o_f_f_r_c when the lljj44 output device is se‐
              lected.

BBuuggss
       Small dots.

SSeeee aallssoo
       _H_P _P_C_L_/_P_J_L _R_e_f_e_r_e_n_c_e_: _P_C_L _5 _P_r_i_n_t_e_r _L_a_n_g_u_a_g_e _T_e_c_h_n_i_c_a_l _R_e_f_e_r_e_n_c_e  _M_a_n_u_‐
       _a_l_, _P_a_r_t _I

       _h_p_f_t_o_d_i_t(1),    _g_r_o_f_f(1),    _t_r_o_f_f(1),   _g_r_o_f_f___o_u_t(5),   _g_r_o_f_f___f_o_n_t(5),
       _g_r_o_f_f___c_h_a_r(7)

groff 1.23.0                      3 June 2025                        _g_r_o_l_j_4(1)
───────────────────────────────────────────────────────────────────────────────
_g_r_o_p_d_f(1)                   General Commands Manual                  _g_r_o_p_d_f(1)

NNaammee
       gropdf - _g_r_o_f_f output driver for Portable Document Format

SSyynnooppssiiss
       ggrrooppddff [--ddeellss] [--FF _f_o_n_t_‐_d_i_r_e_c_t_o_r_y] [--II _i_n_c_l_u_s_i_o_n_‐_d_i_r_e_c_t_o_r_y] [--pp _p_a_p_e_r_‐
              _f_o_r_m_a_t] [--uu [_c_m_a_p_‐_f_i_l_e]] [--yy _f_o_u_n_d_r_y] [_f_i_l_e ...]

       ggrrooppddff ----hheellpp

       ggrrooppddff --vv
       ggrrooppddff ----vveerrssiioonn

DDeessccrriippttiioonn
       The GNU _r_o_f_f PDF output driver translates the output of  _t_r_o_f_f(1)  into
       Portable Document Format.  Normally, _g_r_o_p_d_f is invoked by _g_r_o_f_f(1) when
       the  latter is given the “--TT ppddff” option.  (In this installation, ppss is
       the default output device.)  Use _g_r_o_f_f’s --PP option to pass any  options
       shown  above  to _g_r_o_p_d_f.  If no _f_i_l_e arguments are given, or if _f_i_l_e is
       “-”, _g_r_o_p_d_f 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 _g_r_o_p_d_f.

OOppttiioonnss
       ----hheellpp displays a usage message, while --vv and  ----vveerrssiioonn  show  version
       information; all exit afterward.

       --dd     Include debug information as comments within the PDF.  Also pro‐
              duces an uncompressed PDF.

       --ee     Forces _g_r_o_p_d_f to embed _a_l_l fonts (even the 14 base PDF fonts).

       --FF _d_i_r Prepend  directory  _d_i_r/dev_n_a_m_e to the search path for font, and
              device description files; _n_a_m_e is the name of the  device,  usu‐
              ally ppddff.

       --II _d_i_r Search  the directory _d_i_r for files named in \\XX''ppddff:: ppddffppiicc'' de‐
              vice control commands.  --II may be specified more than once; each
              _d_i_r is searched in the given order.  To search the current work‐
              ing directory before others, add “--II ..” at the desired place; it
              is otherwise searched last.

       --ll     Orient the document in landscape format.

       --pp _p_a_p_e_r_‐_f_o_r_m_a_t
              Set the physical dimensions of the output  medium.   This  over‐
              rides  the  ppaappeerrssiizzee, ppaappeerrlleennggtthh, and ppaappeerrwwiiddtthh directives in
              the _D_E_S_C file; it accepts the same arguments  as  the  ppaappeerrssiizzee
              directive.  See _g_r_o_f_f___f_o_n_t(5) for details.

       --ss     Append  a  comment  line  to end of PDF showing statistics, i.e.
              number of pages in  document.   Ghostscript’s  ppss22ppddff  complains
              about this line if it is included, but works anyway.

       --uu [_c_m_a_p_‐_f_i_l_e]
              _g_r_o_p_d_f  normally includes a ToUnicode CMap with any font created
              using _t_e_x_t_._e_n_c as the encoding file, this  makes  it  easier  to
              search  for words which contain ligatures.  You can include your
              own CMap by specifying a _c_m_a_p_‐_f_i_l_e or have no  CMap  at  all  by
              omitting the argument.

       --yy _f_o_u_n_d_r_y
              Set the foundry to use for selecting fonts of the same name.

UUssaaggee
       The  input to _g_r_o_p_d_f must be in the format output by _t_r_o_f_f(1).  This is
       described in _g_r_o_f_f___o_u_t(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 ssiizzeessccaallee.  The ppddff
       device uses a resolution of 72000 and a sizescale of 1000.

       The  device  description  file  must  contain a valid paper format; see
       _g_r_o_f_f___f_o_n_t(5).  _g_r_o_p_d_f uses the same Type 1 Adobe PostScript  fonts  as
       the  ggrrooppss  device 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  ggrrooppss  and  all
       PostScript  printers,  but  all the fonts are available since any which
       aren’t supported natively are automatically embedded in the PDF.

       _g_r_o_p_d_f supports the concept of foundries, that is different versions of
       basically the same font.  During install a _F_o_u_n_d_r_y file controls  where
       fonts  are  found and builds _g_r_o_f_f fonts from the files it discovers on
       your system.

       Each font description file must contain a command

              iinntteerrnnaallnnaammee _p_s_n_a_m_e

       which says that the PostScript name  of  the  font  is  _p_s_n_a_m_e.   Lines
       starting with ## and 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  \\NN  escape  se‐
       quence in ttrrooffff to select the character, even if the character does not
       have  a _g_r_o_f_f 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 _g_r_o_p_d_f is currently only able to display the first 256 glyphs
       in any font.  This restriction will be lifted in a later version.

       _g_r_o_p_d_f  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
       _g_r_o_p_d_f  must be listed in the file _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_p_d_f_/
       _d_o_w_n_l_o_a_d; this should consist of lines of the form

              _f_o_u_n_d_r_y _f_o_n_t _f_i_l_e_n_a_m_e

       where _f_o_u_n_d_r_y is the foundry name or blank  for  the  default  foundry.
       _f_o_n_t  is  the  PostScript name of the font, and _f_i_l_e_n_a_m_e is the name of
       the file containing the font; lines beginning with ##  and  blank  lines
       are ignored; fields must be separated by tabs (spaces are nnoott allowed);
       _f_i_l_e_n_a_m_e  is  searched  for  using  the same mechanism that is used for
       _g_r_o_f_f font metric files.  The _d_o_w_n_l_o_a_d 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 _g_h_o_s_t_s_c_r_i_p_t uses when it embeds fonts in a
       PDF file.

       In the default setup there are styles called RR, II, BB, and BBII mounted at
       font positions 1 to 4.  The fonts are grouped into families AA,  BBMM,  CC,
       HH, HHNN, NN, PP, and TT having members in each of these styles:

              AARR     AvantGarde‐Book
              AAII     AvantGarde‐BookOblique
              AABB     AvantGarde‐Demi
              AABBII    AvantGarde‐DemiOblique
              BBMMRR    Bookman‐Light
              BBMMII    Bookman‐LightItalic
              BBMMBB    Bookman‐Demi
              BBMMBBII   Bookman‐DemiItalic
              CCRR     Courier
              CCII     Courier‐Oblique
              CCBB     Courier‐Bold
              CCBBII    Courier‐BoldOblique
              HHRR     Helvetica
              HHII     Helvetica‐Oblique
              HHBB     Helvetica‐Bold
              HHBBII    Helvetica‐BoldOblique
              HHNNRR    Helvetica‐Narrow
              HHNNII    Helvetica‐Narrow‐Oblique
              HHNNBB    Helvetica‐Narrow‐Bold
              HHNNBBII   Helvetica‐Narrow‐BoldOblique
              NNRR     NewCenturySchlbk‐Roman
              NNII     NewCenturySchlbk‐Italic
              NNBB     NewCenturySchlbk‐Bold
              NNBBII    NewCenturySchlbk‐BoldItalic
              PPRR     Palatino‐Roman
              PPII     Palatino‐Italic
              PPBB     Palatino‐Bold
              PPBBII    Palatino‐BoldItalic
              TTRR     Times‐Roman
              TTII     Times‐Italic
              TTBB     Times‐Bold
              TTBBII    Times‐BoldItalic

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

              ZZCCMMII   ZapfChancery‐MediumItalic

       There are also some special fonts called SS for 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  ZZDD;  the “hand pointing left” glyph (\\[[llhh]]) is available
       since it has been defined using the \\XX''ppddff:: xxrreevv'' device  control  com‐
       mand, which reverses the direction of letters within words.

       The default color for \\mm and \\MM is black.

       _g_r_o_p_d_f  understands  some  of  the device control commands supported by
       _g_r_o_p_s(1).

       \\XX''ppss:: iinnvviiss''
              Suppress output.

       \\XX''ppss:: eennddiinnvviiss''
              Stop suppressing output.

       \\XX''ppss:: eexxeecc ggssaavvee ccuurrrreennttppooiinntt 22 ccooppyy ttrraannssllaattee _n rroottaattee nneegg eexxcchh nneegg
       eexxcchh ttrraannssllaattee''
              where _n is the angle of rotation.  This is to support the  aalliiggnn
              command in _p_i_c(1).

       \\XX''ppss:: eexxeecc ggrreessttoorree''
              Used by _p_i_c(1) to restore state after rotation.

       \\XX''ppss:: eexxeecc _n sseettlliinneejjooiinn''
              where _n can be one of the following values.

              0 = Miter join
              1 = Round join
              2 = Bevel join

       \\XX''ppss:: eexxeecc _n sseettlliinneeccaapp''
              where _n can be one of the following values.

              0 = Butt cap
              1 = Round cap, and
              2 = Projecting square cap

       \\XX''ppss:: ... ppddffmmaarrkk''
              All the _p_d_f_m_a_r_k macros installed by using _-_m _p_d_f_m_a_r_k or _-_m _m_s_p_d_f
              (see  documentation  in  _p_d_f_m_a_r_k_._p_d_f).  A subset of these macros
              are installed automatically when you use --TTppddff so you should not
              need to use “--mm ppddffmmaarrkk” to access most PDF functionality.

       _g_r_o_p_d_f  also  supports  a  subset  of  the   commands   introduced   in
       _p_r_e_s_e_n_t_._t_m_a_c.  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 _g_r_o_f_f X commands:‐

       \\XX''ppss:: eexxeecc %%%%%%%%PPAAUUSSEE''
              The section before this is treated as a block and is  introduced
              using the current BBLLOOCCKK transition setting (see “\\XX''ppddff:: ttrraannssii‐‐
              ttiioonn''” below).  Equivalently, ..ppddffppaauussee is available as a macro.

       \\XX''ppss:: eexxeecc %%%%%%%%BBEEGGIINNOONNCCEE''
              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
              _G_R_O_P_D_F___N_O_S_L_I_D_E below, this text is ignored.

       \\XX''ppss:: eexxeecc %%%%%%%%EENNDDOONNCCEE''
              This terminates the block defined by %%%%BEGINONCE.   This  pair
              of commands is what implements the .BLOCKS Once/.BLOCKE commands
              in _p_r_e_s_e_n_t_._t_m_a_c.

       The  _m_o_m  macro package already integrates these extensions, so you can
       build slides with _m_o_m.

       If you use _p_r_e_s_e_n_t_._t_m_a_c with _g_r_o_p_d_f there is no need to run the program
       _p_r_e_s_e_n_t_p_s(1) since the output will already be a presentation PDF.

       All other ppss:: tags are silently ignored.

       One \\XX device control command used by the DVI  driver  is  also  recog‐
       nised.

       \\XX''ppaappeerrssiizzee==_p_a_p_e_r_‐_f_o_r_m_a_t''
              where  the _p_a_p_e_r_‐_f_o_r_m_a_t parameter is the same as that to the ppaa‐‐
              ppeerrssiizzee directive.  See _g_r_o_f_f___f_o_n_t(5).  This means that you  can
              alter the page size at will within the PDF file being created by
              _g_r_o_p_d_f.   If  you do want to change the paper format, it must be
              done before you start creating the page.

       _g_r_o_p_d_f supports several more device control  features  using  the  ppddff::
       tag.  Some have counterpart _c_o_n_v_e_n_i_e_n_c_e _m_a_c_r_o_s that take the same argu‐
       ments and behave equivalently.

       \\XX''ppddff:: ppddffppiicc _f_i_l_e _a_l_i_g_n_m_e_n_t _w_i_d_t_h _h_e_i_g_h_t _l_i_n_e_‐_l_e_n_g_t_h'
              Place an image of the specified _w_i_d_t_h containing the PDF drawing
              from file _f_i_l_e of desired _w_i_d_t_h and _h_e_i_g_h_t (if _h_e_i_g_h_t is missing
              or  zero  then it is scaled proportionally).  If _a_l_i_g_n_m_e_n_t is --LL
              the drawing is left‐aligned.  If it is --CC or  --RR  a  _l_i_n_e_‐_l_e_n_g_t_h
              greater  than  the width of the drawing is required as well.  If
              _w_i_d_t_h is specified as zero then the width is scaled  in  propor‐
              tion to the height.

       \\XX''ppddff:: xxrreevv''
              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.

       \\XX''ppddff:: mmaarrkkssttaarrtt _/_A_N_N_‐_d_e_f_i_n_i_t_i_o_n''
       \\XX''ppddff:: mmaarrkkeenndd''
              Macros that support PDF bookmarks use these calls internally  to
              start  and  stop  (respectively) the placement of the bookmark’s
              _h_o_t _s_p_o_t_; the user will have called “..ppddffhhrreeff LL” with  the  text
              of  the  hot  spot.   Normally, these are never used except from
              within the _p_d_f_m_a_r_k macros.

       \\XX''ppddff:: mmaarrkkssuussppeenndd''
       \\XX''ppddff:: mmaarrkkrreessttaarrtt''
              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 _h_o_t _s_p_o_t 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 ..ppddffmmaarrkkssuussppeenndd
              and ..ppddffmmaarrkkrreessttaarrtt at the start and end of the trap macro,  re‐
              spectively.

       \\XX''ppddff:: ppaaggeennaammee _n_a_m_e''
              Assign  the current page a _n_a_m_e.  All documents bear two default
              names, ‘ttoopp’ and ‘bboottttoomm’.  The convenience macro for this  com‐
              mand is ..ppddffppaaggeennaammee.

       \\XX’’ppddff:: sswwiittcchhttooppaaggee _w_h_e_n _n_a_m_e''
              Normally  each  new page is appended to the end of the document,
              this command allows following pages to be inserted at a  _‘_n_a_m_e_d_’
              position  within  the  document  (see  pagename  command above).
              _‘_w_h_e_n_’ can be either ‘_a_f_t_e_r’ or ‘_b_e_f_o_r_e’.  If it is  omitted  it
              defaults  to ‘_b_e_f_o_r_e’.  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 ..ppddffsswwiittcchhttooppaaggee.

       \\XX''ppddff:: ttrraannssiittiioonn _f_e_a_t_u_r_e _m_o_d_e _d_u_r_a_t_i_o_n _d_i_m_e_n_s_i_o_n _m_o_t_i_o_n _d_i_r_e_c_t_i_o_n
       _s_c_a_l_e _b_o_o_l''
              where  _f_e_a_t_u_r_e  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.

              _m_o_d_e is the transition type between slides:‐

                     SSpplliitt  ‐ 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 _d_i_m_e_n_s_i_o_n and _m_o_t_i_o_n
                     entries, respectively.
                     BBlliinnddss ‐ 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  _d_i_m_e_n_s_i_o_n  entry.   Horizontal
                     lines move downward; vertical lines move to the right.
                     BBooxx  ‐  A rectangular box sweeps inward from the edges of
                     the page or outward from the center, as specified by  the
                     _m_o_t_i_o_n entry, revealing the new page.
                     WWiippee  ‐  A  single line sweeps across the screen from one
                     edge to the other in the direction specified by  the  _d_i_‐
                     _r_e_c_t_i_o_n entry, revealing the new page.
                     DDiissssoollvvee ‐ The old page dissolves gradually to reveal the
                     new one.
                     GGlliitttteerr  ‐  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 _d_i_r_e_c_t_i_o_n entry.
                     RR ‐ The new page simply replaces the old one with no spe‐
                     cial transition effect; the _d_i_r_e_c_t_i_o_n entry shall be  ig‐
                     nored.
                     FFllyy ‐ (PDF 1.5) Changes are flown out or in (as specified
                     by  _m_o_t_i_o_n),  in the direction specified by _d_i_r_e_c_t_i_o_n, to
                     or from a location that is offscreen except  when  _d_i_r_e_c_‐
                     _t_i_o_n is NNoonnee.
                     PPuusshh ‐ (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 _d_i_r_e_c_t_i_o_n.
                     CCoovveerr ‐ (PDF 1.5) The new page slides on to the screen in
                     the direction specified by _d_i_r_e_c_t_i_o_n,  covering  the  old
                     page.
                     UUnnccoovveerr ‐ (PDF 1.5) The old page slides off the screen in
                     the  direction specified by _d_i_r_e_c_t_i_o_n, uncovering the new
                     page in the direction specified by _d_i_r_e_c_t_i_o_n.
                     FFaaddee ‐ (PDF 1.5) The new page gradually  becomes  visible
                     through the old one.

              _d_u_r_a_t_i_o_n is the length of the transition in seconds (default 1).

              _d_i_m_e_n_s_i_o_n  (Optional;  SSpplliitt  and BBlliinnddss transition styles only)
              The dimension in which the specified transition effect shall oc‐
              cur: HH Horizontal, or VV Vertical.

              _m_o_t_i_o_n (Optional; SSpplliitt, BBooxx and FFllyy transition styles only) The
              direction of motion for the specified transition effect:  II  In‐
              ward from the edges of the page, or OO Outward from the center of
              the page.

              _d_i_r_e_c_t_i_o_n (Optional; WWiippee, GGlliitttteerr, FFllyy, CCoovveerr, UUnnccoovveerr and PPuusshh
              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: 00 = Left to right, 9900 = Bottom
              to top (Wipe only), 118800 = Right to left (Wipe only), 227700  =  Top
              to  bottom,  331155  =  Top‐left to bottom‐right (Glitter only) The
              value can be NNoonnee, which is relevant only for the FFllyy transition
              when the value of _s_c_a_l_e is not 1.0.

              _s_c_a_l_e (Optional; PDF 1.5; FFllyy transition style only) The  start‐
              ing or ending scale at which the changes shall be drawn.  If _m_o_‐
              _t_i_o_n  specifies  an  inward transition, the scale of the changes
              drawn shall progress from _s_c_a_l_e to 1.0 over the  course  of  the
              transition.   If  _m_o_t_i_o_n  specifies  an  outward transition, the
              scale of the changes drawn shall progress from 1.0 to _s_c_a_l_e over
              the course of the transition

              _b_o_o_l (Optional; PDF 1.5; FFllyy transition style only) If ttrruuee, the
              area that shall be flown in is rectangular and opaque.

              This command can be used by calling the macro ..ppddffttrraannssiittiioonn us‐
              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.

              NNoottee:: not all PDF Readers support any or all these transitions.

       \\XX''ppddff:: bbaacckkggrroouunndd _c_m_d _l_e_f_t _t_o_p _r_i_g_h_t _b_o_t_t_o_m _w_e_i_g_h_t''
       \\XX''ppddff:: bbaacckkggrroouunndd ooffff''
       \\XX''ppddff:: bbaacckkggrroouunndd ffoooottnnoottee _b_o_t_t_o_m''
              produces a background rectangle on the page, where

              _c_m_d    is the command, which can be any  of  “ppaaggee|ffiillll|bbooxx”  in
                     combination.   Thus,  “ppaaggeeffiillll”  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).  “bbooxx‐‐
                     ffiillll”,  on  the other hand, requires the given dimensions
                     to place the box.  Including “ffiillll” in the  command  will
                     paint the rectangle with the current fill colour (as with
                     \\MM[[]])  and including “bbooxx” will give the rectangle a bor‐
                     der in the current stroke colour (as with \\mm[[]]).

                     _c_m_d may also be “ooffff” on its own,  which  will  terminate
                     drawing  the  current  box.  If you have specified a page
                     colour with “ppaaggeeffiillll”, 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 “ppaaggeeffiillll” box renders
                     the page opaque, so tools that “watermark” PDF pages  are
                     unlikely  to  be successful.  To return the background to
                     transparent, issue an “ooffff” command with no  other  boxes
                     open.

                     Finally,  _c_m_d  may  be “ffoooottnnoottee” followed by a new value
                     for _b_o_t_t_o_m, 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.)

              _l_e_f_t
              _t_o_p
              _r_i_g_h_t
              _b_o_t_t_o_m are the coordinates of the box.  The _t_o_p and _b_o_t_t_o_m coor‐
                     dinates  are  the  minimum and maximum for the box, since
                     the actual start of the box is _g_r_o_f_f’s  drawing  position
                     when  you issue the command, and the bottom of the box is
                     the point where you turn the box “ooffff”.  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.

              _w_e_i_g_h_t provides the line width for the border if  “bbooxx”  is  in‐
                     cluded in the command.

              The  convenience  macro  for  this  escape sequence is ..ppddffbbaacckk‐‐
              ggrroouunndd.   An  _s_b_o_x_e_s  macro  file   is   also   available;   see
              _g_r_o_f_f___t_m_a_c(5).

   MMaaccrrooss
       _g_r_o_p_d_f’s  support  macros in _p_d_f_._t_m_a_c define the convenience macros de‐
       scribed above.  Some features have no  direct  device  control  command
       counterpart.

       ..ppddffiinnffoo //_f_i_e_l_d _c_o_n_t_e_n_t ...
              Define PDF metadata.  _f_i_e_l_d may be be one of TTiittllee, AAuutthhoorr, SSuubb‐‐
              jjeecctt,  KKeeyywwoorrddss,  or another datum supported by the PDF standard
              or your reader.  _f_i_e_l_d must be prefixed with a slash.

   IImmppoorrttiinngg ggrraapphhiiccss
       _g_r_o_p_d_f 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 _g_r_o_f_f and _g_r_o_p_d_f.

       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 _i_n_k_s_c_a_p_e(1) or
       _g_i_m_p(1), for example, make sure the canvas size just fits the image.

       The PDF parser _g_r_o_p_d_f 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 _p_d_f_t_k(1) program.
              pdftk _e_x_i_s_t_i_n_g_‐_f_i_l_e output _n_e_w_‐_f_i_l_e
       You may find that _n_e_w_‐_f_i_l_e imports successfully.

   TTrruueeTTyyppee aanndd ootthheerr ffoonntt ffoorrmmaattss
       _g_r_o_p_d_f  does not yet support any font formats besides Adobe Type 1 (PFA
       or PFB).

FFoonntt iinnssttaallllaattiioonn
       The following is a step‐by‐step font installation guide for _g_r_o_p_d_f_.

       • Convert your font to something _g_r_o_f_f 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 font in PFA format.

       • Convert the AFM file to  a  _g_r_o_f_f  font  description  file  with  the
         _a_f_m_t_o_d_i_t(1) program.  For instance,
                $ aaffmmttooddiitt BBrruusshhSSccrriippttXX--IIttaalliicc..aaffmm tteexxtt..mmaapp BBSSII
         converts  the  Adobe  Font Metric file _B_r_u_s_h_S_c_r_i_p_t_X_-_I_t_a_l_i_c_._a_f_m to the
         _g_r_o_f_f font description file _B_S_I.

         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 RR, BB, II, and BBII,  respec‐
         tively,  as  suffixes to the _g_r_o_f_f font family name to enable _g_r_o_f_f’s
         font family and style selection  features.   An  example  is  _g_r_o_f_f’s
         built‐in support for Times: the font family name is abbreviated as TT,
         and  the  _g_r_o_f_f font names are therefore TTRR, TTBB, TTII, and TTBBII.  In our
         example, however, the BrushScriptX font  is  available  in  a  single
         style only, italic.

       • Install  the  _g_r_o_f_f font description file(s) in a _d_e_v_p_d_f subdirectory
         in the search path that _g_r_o_f_f uses for device and font file  descrip‐
         tions.   See  the  _G_R_O_F_F___F_O_N_T___P_A_T_H  entry in section “Environment” of
         _t_r_o_f_f(1) for the current value of the font search path.  While  _g_r_o_f_f
         doesn’t  directly  use  AFM  files,  it  is a good idea to store them
         alongside its font description files.

       • Register fonts in the _d_e_v_p_d_f_/_d_o_w_n_l_o_a_d file so they can be located for
         embedding in PDF files _g_r_o_p_d_f generates.   Only  the  first  _d_o_w_n_l_o_a_d
         file  encountered in the font search path is read.  If in doubt, copy
         the default _d_o_w_n_l_o_a_d 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 _g_r_o_p_d_f is  stored  in  the  iinntteerrnnaallnnaammee
         field in the _g_r_o_f_f 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 ZZ, we  would  add  the  following
         line to _d_o_w_n_l_o_a_d.
                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

EEnnvviirroonnmmeenntt
       _G_R_O_F_F___F_O_N_T___P_A_T_H
              A  list  of directories in which to seek the selected output de‐
              vice’s directory of device and font description files.   If,  in
              the  _d_o_w_n_l_o_a_d file, the font file has been specified with a full
              path,  no  directories   are   searched.    See   _t_r_o_f_f(1)   and
              _g_r_o_f_f___f_o_n_t(5).

       _G_R_O_P_D_F___N_O_S_L_I_D_E
              If  set  and evaluates to a true value (to Perl), _g_r_o_p_d_f ignores
              commands specific to presentation PDFs, producing a  normal  PDF
              instead.

       _S_O_U_R_C_E___D_A_T_E___E_P_O_C_H
              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
              _g_m_t_i_m_e_(_) function and recorded in a PDF comment.

       _T_Z     The time zone to use when converting the current time to  human‐
              readable  form;  see _t_z_s_e_t(3).  If _S_O_U_R_C_E___D_A_T_E___E_P_O_C_H is used, it
              is always converted to human‐readable form using UTC.

FFiilleess
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_p_d_f_/_D_E_S_C
              describes the ppddff output device.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_p_d_f_/F
              describes the font known as _F on device ppddff.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_p_d_f_/_U_-F
              describes the font from the URW foundry (versus  the  Adobe  de‐
              fault) known as _F on device ppddff.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_p_d_f_/_d_o_w_n_l_o_a_d
              lists  fonts available for embedding within the PDF document (by
              analogy to the ppss device’s downloadable font support).

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_p_d_f_/_F_o_u_n_d_r_y
              is a data file used by the _g_r_o_f_f build system  to  locate  Post‐
              Script Type 1 fonts.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_p_d_f_/_e_n_c_/_t_e_x_t_._e_n_c
              describes  the  encoding  scheme  used by most PostScript Type 1
              fonts; the eennccooddiinngg directive of font description files for  the
              ppddff device refers to it.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_p_d_f_._t_m_a_c
              defines  macros for use with the ppddff output device.  It is auto‐
              matically loaded by _t_r_o_f_f_r_c when the ppddff output  device  is  se‐
              lected.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_p_d_f_p_i_c_._t_m_a_c
              defines the PPDDFFPPIICC macro for embedding images in a document; see
              _g_r_o_f_f___t_m_a_c(5).  It is automatically loaded by _t_r_o_f_f_r_c_.

AAuutthhoorrss
       _g_r_o_p_d_f was written and is maintained by Deri James.

SSeeee aallssoo
       _/_u_s_r_/_s_h_a_r_e_/_d_o_c_/_g_r_o_f_f_-_b_a_s_e_/_s_b_o_x_e_s_/_m_s_b_o_x_e_s_._m_s
       _/_u_s_r_/_s_h_a_r_e_/_d_o_c_/_g_r_o_f_f_-_b_a_s_e_/_s_b_o_x_e_s_/_m_s_b_o_x_e_s_._p_d_f
              “Using PDF boxes with _g_r_o_f_f and the _m_s macros”, by Deri James.

       _p_r_e_s_e_n_t_._t_m_a_c
              is  part  of  _g_p_r_e_s_e_n_t,  a software package by Bob Diertens that
              works with _g_r_o_f_f to produce presentations  (“foils”,  or  “slide
              decks”).

       _a_f_m_t_o_d_i_t(1), _g_r_o_f_f(1), _t_r_o_f_f(1), _g_r_o_f_f___f_o_n_t(5), _g_r_o_f_f___o_u_t(5)

groff 1.23.0                      3 June 2025                        _g_r_o_p_d_f(1)
───────────────────────────────────────────────────────────────────────────────
_g_r_o_p_s(1)                    General Commands Manual                   _g_r_o_p_s(1)

NNaammee
       grops - _g_r_o_f_f output driver for PostScript

SSyynnooppssiiss
       ggrrooppss [--ggllmm] [--bb _b_r_o_k_e_n_n_e_s_s_‐_f_l_a_g_s] [--cc _n_u_m_‐_c_o_p_i_e_s] [--FF _f_o_n_t_‐_d_i_r_e_c_t_o_r_y]
             [--II _i_n_c_l_u_s_i_o_n_‐_d_i_r_e_c_t_o_r_y] [--pp _p_a_p_e_r_‐_f_o_r_m_a_t] [--PP _p_r_o_l_o_g_u_e_‐_f_i_l_e]
             [--ww _r_u_l_e_‐_t_h_i_c_k_n_e_s_s] [_f_i_l_e ...]

       ggrrooppss ----hheellpp

       ggrrooppss --vv
       ggrrooppss ----vveerrssiioonn

DDeessccrriippttiioonn
       The GNU _r_o_f_f PostScript output driver translates the output of _t_r_o_f_f(1)
       into  PostScript.  Normally, _g_r_o_p_s is invoked by _g_r_o_f_f(1) when the lat‐
       ter is given the “--TT ppss” option.  (In this installation, ppss is the  de‐
       fault  output device.)  Use _g_r_o_f_f’s --PP option to pass any options shown
       above to _g_r_o_p_s.  If no _f_i_l_e arguments are given, or  if  _f_i_l_e  is  “-”,
       _g_r_o_t_t_y reads the standard input stream.  Output is written to the stan‐
       dard output stream.

       When called with multiple _f_i_l_e arguments, _g_r_o_p_s 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 _g_r_o_p_s.

OOppttiioonnss
       ----hheellpp displays a usage message, while --vv and  ----vveerrssiioonn  show  version
       information; all exit afterward.

       --bb _n   Work around problems with spoolers, previewers, and older print‐
              ers.     Normally,   _g_r_o_p_s   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 _n determines what _g_r_o_p_s does
              to make its output acceptable to such consumers.   If  _n  is  00,
              _g_r_o_p_s  employs  no  workarounds, which is the default; it can be
              changed by modifying the bbrrookkeenn directive in _g_r_o_p_s’s _D_E_S_C file.

              Add 1 to suppress generation of %%%%BBeeggiinnDDooccuummeennttSSeettuupp and  %%%%EEnndd‐‐
              DDooccuummeennttSSeettuupp  comments;  this  is  needed for early versions of
              TranScript that get confused by anything between the %%%%EEnnddPPrroolloogg
              comment and the first %%%%PPaaggee comment.

              Add 2 to omit lines in included files beginning with  %%!!,  which
              confuse Sun’s _p_a_g_e_v_i_e_w previewer.

              Add  4  to  omit  lines in included files beginning with %%%%PPaaggee,
              %%%%TTrraaiilleerr and %%%%EEnnddPPrroolloogg; this  is  needed  for  spoolers  that
              don’t understand %%%%BBeeggiinnDDooccuummeenntt and %%%%EEnnddDDooccuummeenntt comments.

              Add  8 to write %%!!PPSS--AAddoobbee--22..00 rather than %%!!PPSS--AAddoobbee--33..00 as 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
              %%%%DDooccuummeennttMMeeddiiaa  comment  nor  the sseettppaaggeeddeevviiccee PostScript com‐
              mand).  This was the behavior of _g_r_o_f_f 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.

       --cc _n   Output _n copies of each page.

       --FF _d_i_r Prepend  directory  dir_/_d_e_vname  to the search path for font and
              device description and PostScript prologue files;  _n_a_m_e  is  the
              name of the device, usually ppss.

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

       --II _d_i_r Search the directory _d_i_r for files named  in  \\XX''ppss::  ffiillee''  and
              \\XX''ppss::  iimmppoorrtt'' escape sequences.  --II may be specified more than
              once; each _d_i_r is searched in the given order.   To  search  the
              current  working  directory before others, add “--II ..” at the de‐
              sired place; it is otherwise searched last.

       --ll     Use landscape orientation rather than portrait.

       --mm     Turn on manual feed for the document.

       --pp _f_m_t Set  physical  dimensions  of  output  medium,  overriding   the
              ppaappeerrssiizzee,  ppaappeerrlleennggtthh,  and  ppaappeerrwwiiddtthh directives in the _D_E_S_C
              file.  _f_m_t can be any argument accepted by the ppaappeerrssiizzee  direc‐
              tive; see _g_r_o_f_f___f_o_n_t(5).

       --PP _p_r_o_l_o_g_u_e
              Use  the file _p_r_o_l_o_g_u_e, sought in the _g_r_o_f_f font search path, as
              the PostScript prologue, overriding  the  default  (see  section
              “Files” below) and the environment variable _G_R_O_P_S___P_R_O_L_O_G_U_E_.

       --ww _n   Draw  rules  (lines) with a thickness of _n thousandths of an em.
              The default thickness is 4400 (0.04 em).

UUssaaggee
       The input to _g_r_o_p_s must be in the format output by _t_r_o_f_f(1),  described
       in  _g_r_o_f_f___o_u_t(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 ssiizzeessccaallee.  The device
       description file must contain a valid paper format; see  _g_r_o_f_f___f_o_n_t(5).
       Each font description file must contain a directive
              internalname _p_s_n_a_m_e
       which says that the PostScript name of the font is _p_s_n_a_m_e.

       A font description file may also contain a directive
              encoding _e_n_c_‐_f_i_l_e
       which  says  that the PostScript font should be reencoded using the en‐
       coding described in _e_n_c_‐_f_i_l_e; this file should consist of a sequence of
       lines of the form
              _p_s_c_h_a_r _c_o_d_e
       where _p_s_c_h_a_r is the PostScript name of the character, and _c_o_d_e  is  its
       position  in  the encoding expressed as a decimal integer; valid values
       are in the range 0 to 255.  Lines starting with ## and 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 \\NN  escape  se‐
       quence  in  _t_r_o_f_f  to  select the character, even if it does not have a
       _g_r_o_f_f 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.  _g_r_o_p_s as‐
       sumes  that  a  character with a _g_r_o_f_f name of ssppaaccee is blank (makes no
       marks on the page); it can make use of such  a  character  to  generate
       more efficient and compact PostScript output.

       _g_r_o_p_s  is  able  to  display all glyphs in a PostScript font; it is not
       limited to 256 of them.  _e_n_c_‐_f_i_l_e (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 _g_r_o_p_s produces on the fly.

       _g_r_o_p_s can embed fonts in a document that are necessary  to  render  it;
       this  is  called “downloading”.  Such fonts must be in PFA format.  Use
       _p_f_b_t_o_p_s(1) to convert a Type 1 font in PFB format.  Downloadable  fonts
       must be listed a _d_o_w_n_l_o_a_d file containing lines of the form
              _p_s_n_a_m_e _f_i_l_e
       where  _p_s_n_a_m_e  is the PostScript name of the font, and _f_i_l_e is the name
       of the file containing it; lines beginning with ## and blank  lines  are
       ignored; fields may be separated by tabs or spaces.  _f_i_l_e is sought us‐
       ing  the  same mechanism as that for _g_r_o_f_f font description files.  The
       _d_o_w_n_l_o_a_d 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 _g_r_o_p_s 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 _d_o_w_n_l_o_a_d 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.  _g_r_o_p_s  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  _d_o_w_n_l_o_a_d file.  A downloadable font should not include
       its own name in a %%%%DDooccuummeennttSSuupppplliieeddRReessoouurrcceess comment.

       _g_r_o_p_s does not interpret  %%%%DDooccuummeennttFFoonnttss  comments.   The  %%%%DDooccuummeenntt‐‐
       NNeeeeddeeddRReessoouurrcceess,     %%%%DDooccuummeennttSSuupppplliieeddRReessoouurrcceess,    %%%%IInncclluuddeeRReessoouurrccee,
       %%%%BBeeggiinnRReessoouurrccee,  and  %%%%EEnnddRReessoouurrccee  comments  (or  possibly  the  old
       %%%%DDooccuummeennttNNeeeeddeeddFFoonnttss, %%%%DDooccuummeennttSSuupppplliieeddFFoonnttss, %%%%IInncclluuddeeFFoonntt, %%%%BBeeggiinn‐‐
       FFoonntt, and %%%%EEnnddFFoonntt comments) should be used.

       The  default stroke and fill color is black.  For colors defined in the
       “rgb” color space, sseettrrggbbccoolloorr is used; for “cmy” and “cmyk”,  sseettccmmyykk‐‐
       ccoolloorr;   and   for  “gray”,  sseettggrraayy.   sseettccmmyykkccoolloorr  is  a  PostScript
       LanguageLevel 2 command and thus not available on some older printers.

   TTyyppeeffaacceess
       Styles called RR, II, BB, and BBII mounted at font positions 1 to  4.   Text
       fonts are grouped into families AA, BBMM, CC, HH, HHNN, NN, PP, and TT, each hav‐
       ing members in each of these styles.

              AARR     AvantGarde‐Book
              AAII     AvantGarde‐BookOblique
              AABB     AvantGarde‐Demi
              AABBII    AvantGarde‐DemiOblique
              BBMMRR    Bookman‐Light
              BBMMII    Bookman‐LightItalic
              BBMMBB    Bookman‐Demi
              BBMMBBII   Bookman‐DemiItalic
              CCRR     Courier
              CCII     Courier‐Oblique
              CCBB     Courier‐Bold
              CCBBII    Courier‐BoldOblique
              HHRR     Helvetica
              HHII     Helvetica‐Oblique
              HHBB     Helvetica‐Bold
              HHBBII    Helvetica‐BoldOblique
              HHNNRR    Helvetica‐Narrow
              HHNNII    Helvetica‐Narrow‐Oblique
              HHNNBB    Helvetica‐Narrow‐Bold
              HHNNBBII   Helvetica‐Narrow‐BoldOblique
              NNRR     NewCenturySchlbk‐Roman
              NNII     NewCenturySchlbk‐Italic
              NNBB     NewCenturySchlbk‐Bold
              NNBBII    NewCenturySchlbk‐BoldItalic
              PPRR     Palatino‐Roman
              PPII     Palatino‐Italic
              PPBB     Palatino‐Bold
              PPBBII    Palatino‐BoldItalic
              TTRR     Times‐Roman
              TTII     Times‐Italic
              TTBB     Times‐Bold
              TTBBII    Times‐BoldItalic

       Another text font is not a member of a family.

              ZZCCMMII   ZapfChancery‐MediumItalic

       Special fonts include SS, the PostScript Symbol font; ZZDD, Zapf Dingbats;
       SSSS  (slanted  symbol),  which contains oblique forms of lowercase Greek
       letters derived from Symbol; EEUURROO, which offers a Euro  glyph  for  use
       with  old  devices lacking it; and ZZDDRR, 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 \\NN.  The last three
       are not standard PostScript fonts, but supplied by _g_r_o_f_f and  therefore
       included in the default _d_o_w_n_l_o_a_d file.

   DDeevviiccee ccoonnttrrooll ccoommmmaannddss
       _g_r_o_p_s  recognizes device control commands produced by the \\XX escape se‐
       quence, but interprets only those that begin with a “ppss::” tag.

       \\XX''ppss:: eexxeecc _c_o_d_e''
              Execute the arbitrary PostScript commands _c_o_d_e.  The  PostScript
              _c_u_r_r_e_n_t_p_o_i_n_t  is  set  to the _g_r_o_f_f drawing position when the \\XX
              escape sequence is interpreted before executing _c_o_d_e.  The  ori‐
              gin  is  at  the  top left corner of the page; _x coordinates in‐
              crease to the right, and _y coordinates down the page.  A  proce‐
              dure uu is defined that converts _g_r_o_f_f 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.  _c_o_d_e 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 ddeeff and mmddeeff commands is on top of the dictionary stack.  If
              your code adds definitions to this dictionary, you should  allo‐
              cate  space  for  them  using “\\XX''ppss:: mmddeeff _n''”.  Any definitions
              persist only until the end of the page.  If you use the  \\YY  es‐
              cape  sequence with an argument that names a macro, _c_o_d_e 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 “nnxx”—the only reason to use a register
              while defining the macro “yy”—is to convert a user‐specified  di‐
              mension “11ii” to _g_r_o_f_f basic units which are in turn converted to
              PostScript units with the uu procedure.

              _g_r_o_p_s  wraps  user‐specified  PostScript code into a dictionary,
              nothing more.  In particular, it doesn’t start and end  the  in‐
              serted  code  with ssaavvee and rreessttoorree, respectively.  This must be
              supplied by the user, if necessary.

       \\XX''ppss:: ffiillee _n_a_m_e''
              This is the same as the eexxeecc command except that the  PostScript
              code is read from file _n_a_m_e.

       \\XX''ppss:: ddeeff _c_o_d_e''
              Place a PostScript definition contained in _c_o_d_e in the prologue.
              There should be at most one definition per \\XX command.  Long de‐
              finitions  can  be  split over several \\XX commands; all the _c_o_d_e
              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 eexxeecc command is executed.
              If  you use the \\YY escape sequence with an argument that names a
              macro, _c_o_d_e can extend over multiple lines.

       \\XX''ppss:: mmddeeff _n _c_o_d_e''
              Like ddeeff, except that _c_o_d_e may  contain  up  to  _n  definitions.
              _g_r_o_p_s  needs  to know how many definitions _c_o_d_e contains so that
              it can create an appropriately sized  PostScript  dictionary  to
              contain them.

       \\XX''ppss:: iimmppoorrtt _f_i_l_e _l_l_x _l_l_y _u_r_x _u_r_y _w_i_d_t_h [_h_e_i_g_h_t]''
              Import  a PostScript graphic from _f_i_l_e.  The arguments _l_l_x, _l_l_y,
              _u_r_x, and _u_r_y give the bounding box of the graphic in the default
              PostScript coordinate system.  They should all be integers:  _l_l_x
              and  _l_l_y are the _x and _y coordinates of the lower left corner of
              the graphic; _u_r_x and _u_r_y are the _x and _y coordinates of the  up‐
              per  right  corner of the graphic; _w_i_d_t_h and _h_e_i_g_h_t are integers
              that give the desired width and height in _g_r_o_f_f 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 \\XX command.  If the height
              argument  is  omitted it is scaled uniformly in the _x and _y axes
              so that it has the specified width.

              The contents of the \\XX command are not interpreted by _t_r_o_f_f,  so
              vertical  space  for the graphic is not automatically added, and
              the _w_i_d_t_h and _h_e_i_g_h_t arguments are not allowed to have  attached
              scaling indicators.

              If  the  PostScript file complies with the Adobe Document Struc‐
              turing Conventions and contains a  %%%%BBoouunnddiinnggBBooxx  comment,  then
              the  bounding  box  can  be  automatically extracted from within
              _g_r_o_f_f input by using the ppssbbbb request.

              See _g_r_o_f_f___t_m_a_c(5) for a description of  the  PPSSPPIICC  macro  which
              provides  a  convenient  high‐level  interface  for inclusion of
              PostScript graphics.

       \\XX''ppss:: iinnvviiss''
       \\XX''ppss:: eennddiinnvviiss''
              No output is generated for text and drawing  commands  that  are
              bracketed  with  these \\XX commands.  These commands are intended
              for use  when  output  from  _t_r_o_f_f  is  previewed  before  being
              processed with _g_r_o_p_s; 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 \\XX commands.

              For example, _g_x_d_i_t_v_i_e_w is not able to  display  a  proper  \\[[eemm]]
              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, _g_x_d_i_t_v_i_e_w is unable to display the \\[[eemm]] character
              and draws the line, whereas _g_r_o_p_s prints the \\[[eemm]] character and
              ignores  the  line (this code is already in file _X_p_s_._t_m_a_c, which
              is loaded if a document intended for  _g_r_o_p_s  is  previewed  with
              _g_x_d_i_t_v_i_e_w).

       If  a  PostScript  procedure BBPPhhooookk has been defined via a “ppss:: ddeeff” or
       “ppss:: mmddeeff” device control command, it is executed at the  beginning  of
       every  page  (before anything is drawn or written by _g_r_o_f_f).  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 _g_r_o_p_s, use
              .de XX
              ps: def
              /BPhook { 2 setlinecap 0 setlinejoin } def
              ..
              .devicem XX
       (square linecaps, as opposed to butt linecaps  (“00  sseettlliinneeccaapp”),  give
       true  corners  in  boxed  tables even though the lines are drawn uncon‐
       nected).

   EEnnccaappssuullaatteedd PPoossttSSccrriipptt
       _g_r_o_p_s itself doesn’t emit  bounding  box  information.   The  following
       script, _g_r_o_f_f_2_e_p_s, 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 “ggrrooffff22eeppss ffoooo” to convert file _f_o_o to _f_o_o_._e_p_s.

   TTrruueeTTyyppee aanndd ootthheerr ffoonntt ffoorrmmaattss
       TrueType  fonts  can  be  used with _g_r_o_p_s if converted first to Type 42
       format, a PostScript wrapper equivalent to the PFA format described  in
       _p_f_b_t_o_p_s(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 _g_s(1).

       One  approach  is to use FontForge, a font editor that can convert most
       outline font formats.  Here’s an example of using the Roboto Slab Serif
       font with _g_r_o_f_f.  Several variables are used so that you can more  eas‐
       ily adapt it into your own script.

           MAP=/usr/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"

       _f_o_n_t_f_o_r_g_e  and  _a_f_m_t_o_d_i_t 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 _G_R_O_F_F___F_O_N_T___P_A_T_H in your environ‐
       ment  to  include the directory you keep the generated fonts in so that
       you don’t have to use the --FF option.

FFoonntt iinnssttaallllaattiioonn
       The following is a step‐by‐step font installation guide for _g_r_o_p_s_.

       • Convert your font to something _g_r_o_f_f 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 _g_r_o_f_f’s _p_f_b_t_o_p_s(1)
         program to convert it to PFA.  For TrueType and other  font  formats,
         we  recommend _f_o_n_t_f_o_r_g_e, 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 font in PFA format.

       • Convert the AFM file to  a  _g_r_o_f_f  font  description  file  with  the
         _a_f_m_t_o_d_i_t(1) program.  For instance,
                $ aaffmmttooddiitt BBrruusshhSSccrriippttXX--IIttaalliicc..aaffmm tteexxtt..mmaapp BBSSII
         converts  the  Adobe  Font Metric file _B_r_u_s_h_S_c_r_i_p_t_X_-_I_t_a_l_i_c_._a_f_m to the
         _g_r_o_f_f font description file _B_S_I.

         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 RR, BB, II, and BBII, re‐
         spectively, as suffixes to the  _g_r_o_f_f  font  family  name  to  enable
         _g_r_o_f_f’s  font  family  and  style  selection features.  An example is
         _g_r_o_f_f’s built‐in support for Times: the font family name is  abbrevi‐
         ated  as  TT,  and  the _g_r_o_f_f font names are therefore TTRR, TTBB, TTII, and
         TTBBII.  In our example, however, the BrushScriptX font is available  in
         a single style only, italic.

       • Install the _g_r_o_f_f font description file(s) in a _d_e_v_p_s subdirectory in
         the  search  path  that  _g_r_o_f_f uses for device and font file descrip‐
         tions.  See the _G_R_O_F_F___F_O_N_T___P_A_T_H entry  in  section  “Environment”  of
         _t_r_o_f_f(1)  for the current value of the font search path.  While _g_r_o_f_f
         doesn’t directly use AFM files, it is  a  good  idea  to  store  them
         alongside its font description files.

       • Register  fonts in the _d_e_v_p_s_/_d_o_w_n_l_o_a_d file so they can be located for
         embedding in PostScript files _g_r_o_p_s generates.  Only the first  _d_o_w_n_‐
         _l_o_a_d  file encountered in the font search path is read.  If in doubt,
         copy the default _d_o_w_n_l_o_a_d 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 _g_r_o_p_s is stored in the  iinntteerrnnaallnnaammee
         field in the _g_r_o_f_f font description file.  (This name does not neces‐
         sarily  resemble the font’s file name.)  We add the following line to
         _d_o_w_n_l_o_a_d.
                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

OOlldd ffoonnttss
       _g_r_o_f_f 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
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_o_l_d_f_o_n_t_/_d_e_v_p_s directory.

       To use them, make sure that _g_r_o_p_s finds the fonts  before  the  default
       system  fonts  (with the same names): either give _g_r_o_p_s the --FF command‐
       line option,
              $ ggrrooffff --TTppss --PP--FF --PP//uussrr//sshhaarree//ggrrooffff//11..2233..00//oollddffoonntt ...
       or add the directory to _g_r_o_f_f’s font and device description search path
       environment variable,
              $ GGRROOFFFF__FFOONNTT__PPAATTHH==//uussrr//sshhaarree//ggrrooffff//11..2233..00//oollddffoonntt \\
                     ggrrooffff --TTppss ...
       when the command runs.

EEnnvviirroonnmmeenntt
       _G_R_O_F_F___F_O_N_T___P_A_T_H
              A list of directories in which to seek the selected  output  de‐
              vice’s  directory  of  device  and  font description files.  See
              _t_r_o_f_f(1) and _g_r_o_f_f___f_o_n_t(5).

       _G_R_O_P_S___P_R_O_L_O_G_U_E
              If this is set to _f_o_o, then _g_r_o_p_s uses the file _f_o_o (in the font
              path) instead of the default prologue file _p_r_o_l_o_g_u_e.  The option
              --PP overrides this environment variable.

       _S_O_U_R_C_E___D_A_T_E___E_P_O_C_H
              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 _g_m_t_i_m_e(3) and
              _a_s_c_t_i_m_e(3), and recorded in a PostScript comment.

       _T_Z     The time zone to use when converting the current time to  human‐
              readable  form;  see _t_z_s_e_t(3).  If _S_O_U_R_C_E___D_A_T_E___E_P_O_C_H is used, it
              is always converted to human‐readable form using UTC.

FFiilleess
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_p_s_/_D_E_S_C
              describes the ppss output device.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_p_s_/F
              describes the font known as _F on device ppss.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_p_s_/_d_o_w_n_l_o_a_d
              lists fonts available for embedding within the PostScript  docu‐
              ment (or download to the device).

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_p_s_/_p_r_o_l_o_g_u_e
              is  the  default  PostScript  prologue  prefixed to every output
              file.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_p_s_/_t_e_x_t_._e_n_c
              describes the encoding scheme used by  most  PostScript  Type  1
              fonts;  the eennccooddiinngg directive of font description files for the
              ppss device refers to it.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_p_s_._t_m_a_c
              defines macros for use with the ppss output device.  It  is  auto‐
              matically  loaded  by  _t_r_o_f_f_r_c  when the ppss output device is se‐
              lected.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_p_s_p_i_c_._t_m_a_c
              defines the PPSSPPIICC macro for embedding images in a document;  see
              _g_r_o_f_f___t_m_a_c(5).  It is automatically loaded by _t_r_o_f_f_r_c_.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_p_s_o_l_d_._t_m_a_c
              provides  replacement  glyphs  for text fonts that lack complete
              coverage of the ISO Latin‐1 character set; using it,  _g_r_o_f_f  can
              produce  glyphs like eth (ð) and thorn (þ) that older PostScript
              printers do not natively support.

       _g_r_o_p_s creates temporary files using  the  template  “_g_r_o_p_sXXXXXX”;  see
       _g_r_o_f_f(1) for details on their storage location.

SSeeee aallssoo
       PostScript Language Document Structuring Conventions Specification

       _a_f_m_t_o_d_i_t(1),    _g_r_o_f_f(1),    _t_r_o_f_f(1),    _p_f_b_t_o_p_s(1),    _g_r_o_f_f___c_h_a_r(7),
       _g_r_o_f_f___f_o_n_t(5), _g_r_o_f_f___o_u_t(5), _g_r_o_f_f___t_m_a_c(5)

groff 1.23.0                      3 June 2025                         _g_r_o_p_s(1)
───────────────────────────────────────────────────────────────────────────────
_g_r_o_t_t_y(1)                   General Commands Manual                  _g_r_o_t_t_y(1)

NNaammee
       grotty - _g_r_o_f_f output driver for typewriter‐like (terminal) devices

SSyynnooppssiiss
       ggrroottttyy [--ddffhhoo] [--ii|--rr] [--FF _d_i_r] [_f_i_l_e ...]

       ggrroottttyy --cc [--bbBBddffhhoouuUU] [--FF _d_i_r] [_f_i_l_e ...]

       ggrroottttyy ----hheellpp

       ggrroottttyy --vv
       ggrroottttyy ----vveerrssiioonn

DDeessccrriippttiioonn
       The GNU _r_o_f_f TTY (“Teletype”) output driver translates  the  output  of
       _t_r_o_f_f(1)  into  a  form suitable for typewriter‐like devices, including
       terminal emulators.  Normally, _g_r_o_t_t_y is invoked by _g_r_o_f_f(1)  when  the
       latter  is  given  one  of  the  “--TT  aasscciiii”, “--TT llaattiinn11”, --TTllaattiinn11, or
       “--TT uuttff88” options on systems using ISO character encoding standards, or
       with “--TT ccpp11004477” or “--TT uuttff88” on EBCDIC‐based hosts.  (In this  instal‐
       lation,  ppss  is  the  default output device.)  Use _g_r_o_f_f’s --PP option to
       pass any options shown above to  _g_r_o_t_t_y.   If  no  _f_i_l_e  arguments  are
       given, or if _f_i_l_e is “-”, _g_r_o_t_t_y reads the standard input stream.  Out‐
       put is written to the standard output stream.

       By default, _g_r_o_t_t_y 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 _r_o_f_f documents using eight different
       background and foreground colors.  Following ISO  6429,  the  following
       colors are defined in _t_t_y_._t_m_a_c: 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 --ii option below.

   SSGGRR aanndd OOSSCC ssuuppppoorrtt iinn ppaaggeerrss
       When paging _g_r_o_t_t_y’s output with _l_e_s_s(1), the latter  program  must  be
       instructed  to pass SGR and OSC sequences through to the device; its --RR
       option is one way to achieve this (_l_e_s_s version 566  or  later  is  re‐
       quired  for  OSC  8  support).  Consequently, programs like _m_a_n(1) that
       page _r_o_f_f documents with _l_e_s_s must call it with an appropriate option.

   LLeeggaaccyy oouuttppuutt ffoorrmmaatt
       The --cc option tells _g_r_o_t_t_y to use an output format compatible with  pa‐
       per terminals, like the Teletype machines for which _r_o_f_f and _n_r_o_f_f 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, _g_r_o_t_t_y overstrikes, repre‐
       senting a bold character _c with the sequence “_c BACKSPACE _c”, an italic
       character  _c  with  the sequence “__ BACKSPACE _c”, and bold italics with
       “__ BACKSPACE _c BACKSPACE _c”.  This rendering  is  inherently  ambiguous
       when the character _c is itself the underscore.

       The legacy output format can be rendered on a video terminal (or emula‐
       tor)  by  piping  _g_r_o_t_t_y’s  output through _u_l(1), which may render bold
       italics as reverse video.  Some implementations  of  _m_o_r_e(1)  are  also
       able  to  display these sequences; you may wish to experiment with that
       command’s --bb option.  _l_e_s_s renders legacy bold and italics without  re‐
       quiring  options.   In  contrast to the terminal output drivers of some
       other _r_o_f_f implementations, _g_r_o_t_t_y never outputs  reverse  line  feeds.
       There is therefore no need to filter its output through _c_o_l(1).

   DDeevviiccee ccoonnttrrooll ccoommmmaannddss
       _g_r_o_t_t_y  understands one device control function produced by the _r_o_f_f \\XX
       escape sequence in a document.

       \\XX''ttttyy:: lliinnkk [_u_r_i [_k_e_y==_v_a_l_u_e] ...]''
              Embed a hyperlink using the  OSC  8  terminal  escape  sequence.
              Specifying _u_r_i starts hyperlinked text, and omitting it ends the
              hyperlink.   When  _u_r_i  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 _u_r_i, _k_e_y, or _v_a_l_u_e; they must be represented
              in an alternate form.

   DDeevviiccee ddeessccrriippttiioonn ffiilleess
       If the _D_E_S_C file for the character encoding contains the “uunniiccooddee”  di‐
       rective, _g_r_o_t_t_y 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 _g_r_o_f_f___f_o_n_t(5).

       A font description file may contain a directive “iinntteerrnnaallnnaammee _n”  where
       _n  is  a  decimal integer.  If the 01 bit in _n 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.

   TTyyppeeffaacceess
       _g_r_o_t_t_y  supports  the  standard  four  styles: RR (roman), II (_i_t_a_l_i_c), BB
       (bboolldd), and BBII (_bb_oo_ll_dd_‐‐_ii_tt_aa_ll_ii_cc).  Because the output  driver  operates  in
       _n_r_o_f_f  mode, attempts to set or change the font family or type size are
       ignored.

OOppttiioonnss
       ----hheellpp displays a usage message, while --vv and  ----vveerrssiioonn  show  version
       information; all exit afterward.

       --bb     Suppress  the  use of overstriking for bold characters in legacy
              output format.

       --BB     Use only overstriking for bold‐italic characters in legacy  out‐
              put format.

       --cc     Use _g_r_o_t_t_y’s legacy output format (see subsection “Legacy output
              format” above).  SGR and OSC escape sequences are not emitted.

       --dd     Ignore  all  \\DD  drawing  escape sequences in the input.  By de‐
              fault, _g_r_o_t_t_y renders \\DD''ll...'' escape  sequences  that  have  at
              least  one zero argument (and so are either horizontal or verti‐
              cal) using Unicode box drawing characters (for the uuttff88  device)
              or  the  --, ||, and ++ characters (for all other devices).  _g_r_o_t_t_y
              handles \\DD''pp...'' escape sequences that consist entirely of hori‐
              zontal and vertical lines similarly.

       --ff     Emit a form feed at the end of each page having no output on its
              last line.

       --FF _d_i_r Prepend directory dir_/_d_e_vname to the search path  for  font  and
              device  description  files;  _n_a_m_e  describes the output device’s
              character encoding, one of aasscciiii, llaattiinn11, uuttff88, or ccpp11004477.

       --hh     Use literal horizontal tab characters in the output.   Tabs  are
              assumed to be set every 8 columns.

       --ii     Render  oblique‐styled  fonts  (II and BBII) with the SGR attribute
              for italic text rather than  underlined  text.   Many  terminals
              don’t   support   this   attribute;   however,  _x_t_e_r_m(1),  since
              patch #314 (2014‐12‐28), does.  Ignored if --cc is also specified.

       --oo     Suppress overstriking (other than  for  bold  and/or  underlined
              characters when the legacy output format is in use).

       --rr     Render  oblique‐styled  fonts  (II and BBII) with the SGR attribute
              for reverse video text rather than underlined text.  Ignored  if
              --cc or --ii is also specified.

       --uu     Suppress  the use of underlining for italic characters in legacy
              output format.

       --UU     Use only underlining for bold‐italic characters in legacy output
              format.

EEnnvviirroonnmmeenntt
       _G_R_O_F_F___F_O_N_T___P_A_T_H
              A list of directories in which to seek the selected  output  de‐
              vice’s  directory  of  device  and  font description files.  See
              _t_r_o_f_f(1) and _g_r_o_f_f___f_o_n_t(5).

       _G_R_O_F_F___N_O___S_G_R
              If set, _g_r_o_t_t_y’s legacy output format is used just as if the  --cc
              option  were  specified;  see  subsection “Legacy output format”
              above.

FFiilleess
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_a_s_c_i_i_/_D_E_S_C
              describes the aasscciiii output device.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_a_s_c_i_i_/F
              describes the font known as _F on device aasscciiii.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_c_p_1_0_4_7_/_D_E_S_C
              describes the ccpp11004477 output device.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_c_p_1_0_4_7_/F
              describes the font known as _F on device ccpp11004477.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_l_a_t_i_n_1_/_D_E_S_C
              describes the llaattiinn11 output device.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_l_a_t_i_n_1_/F
              describes the font known as _F on device llaattiinn11.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_u_t_f_8_/_D_E_S_C
              describes the uuttff88 output device.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_u_t_f_8_/F
              describes the font known as _F on device uuttff88.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_t_t_y_._t_m_a_c
              defines macros for use with the aasscciiii, ccpp11004477, llaattiinn11, and  uuttff88
              output  devices.  It is automatically loaded by _t_r_o_f_f_r_c when any
              of those output devices is selected.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_t_t_y_-_c_h_a_r_._t_m_a_c
              defines fallback characters for use with _g_r_o_t_t_y_.  See _n_r_o_f_f(1).

LLiimmiittaattiioonnss
       _g_r_o_t_t_y is intended only for simple documents.

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

       • _r_o_f_f \\DD escape 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 _g_r_o_f_f requests
         and escape sequences that set the stroke and fill colors instead  set
         the foreground and background character cell colors, respectively.

EExxaammpplleess
       The  following _g_r_o_f_f 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.

              $ ggrrooffff --TT aasscciiii _f_i_l_e
              $ ggrrooffff --TT uuttff88 --PP --ii _f_i_l_e
              $ ggrrooffff --TT uuttff88 --PP --cc _f_i_l_e || uull

SSeeee aallssoo
       “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”, Egmont Koblinger.

       _g_r_o_f_f(1), _t_r_o_f_f(1), _g_r_o_f_f___o_u_t(5), _g_r_o_f_f___f_o_n_t(5), _g_r_o_f_f___c_h_a_r(7),  _u_l(1),
       _m_o_r_e(1), _l_e_s_s(1), _m_a_n(1)

groff 1.23.0                      3 June 2025                        _g_r_o_t_t_y(1)
───────────────────────────────────────────────────────────────────────────────
_g_x_d_i_t_v_i_e_w(1)                General Commands Manual               _g_x_d_i_t_v_i_e_w(1)

NNaammee
       gxditview - display _g_r_o_f_f intermediate output files in X11

SSyynnooppssiiss
       ggxxddiittvviieeww [_X_‐_t_o_o_l_k_i_t_‐_o_p_t_i_o_n ...] [--bbaacckkiinnggSSttoorree _b_a_c_k_i_n_g_‐_s_t_o_r_e_‐_t_y_p_e]
                 [--ffiilleennaammee _f_i_l_e] [--ppaaggee _p_a_g_e_‐_n_u_m_b_e_r] [--pprriinnttCCoommmmaanndd _c_o_m_m_a_n_d]
                 [--rreessoolluuttiioonn _r_e_s_o_l_u_t_i_o_n] _f_i_l_e

       ggxxddiittvviieeww --hheellpp
       ggxxddiittvviieeww ----hheellpp

       ggxxddiittvviieeww --vveerrssiioonn
       ggxxddiittvviieeww ----vveerrssiioonn

DDeessccrriippttiioonn
       _g_x_d_i_t_v_i_e_w  interprets  and  displays  the intermediate output format of
       _g_r_o_f_f(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 _g_x_d_i_t_v_i_e_w.

       The intermediate output format of _g_r_o_f_f, documented in _g_r_o_f_f___o_u_t(5), is
       produced  by  _t_r_o_f_f or the --ZZ option to _g_r_o_f_f.  It can be viewed by ex‐
       plicitly calling  “ggxxddiittvviieeww  _f_i_l_e”.   If  the  _f_i_l_e  operand  is  “--”,
       _g_x_d_i_t_v_i_e_w  will read the standard input stream; _f_i_l_e cannot be omitted.
       The intermediate output format of _g_r_o_f_f is device‐independent  but  not
       device‐agnostic.  _g_x_d_i_t_v_i_e_w can view it for all typesetter devices, but
       the quality is device‐dependent.  _g_x_d_i_t_v_i_e_w will not display output for
       terminal (_n_r_o_f_f) devices.

       The  best  results  are achieved with the XX* devices for _g_r_o_f_f’s --TT op‐
       tion, of which there are four: --TTXX7755, --TTXX7755--1122, --TTXX110000, and  --TTXX110000--1122.
       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 _g_x_d_i_t_v_i_e_w.
       When using one of these, _g_r_o_f_f generates the  intermediate  output  for
       this device and calls _g_x_d_i_t_v_i_e_w automatically for viewing.

       --XX  produces  good results only with --TTppss, --TTXX7755, --TTXX7755--1122, --TTXX110000, and
       --TTXX110000--1122.  The default resolution for previewing --TTppss output is 75dpi;
       this can be changed with the --rreessoolluuttiioonn option.

       While _g_x_d_i_t_v_i_e_w is running, the left mouse button brings up a menu with
       several entries.

       NNeexxtt PPaaggee    Display the next page.

       PPrreevviioouuss PPaaggee
                    Display the previous page.

       SSeelleecctt PPaaggee  Select a particular numbered page specified  by  a  dialog
                    box.

       PPrriinntt        Print the _g_r_o_f_f intermediate output using a command speci‐
                    fied  by a dialog box.  The default command initially dis‐
                    played is controlled by the pprriinnttCCoommmmaanndd  application  re‐
                    source, and by the --pprriinnttCCoommmmaanndd option.

       OOppeenn         Open  for  display  a  new file specified by a dialog box.
                    The file should contain _g_r_o_f_f intermediate output.  If the
                    filename starts with a bar or pipe symbol, “||” it will  be
                    interpreted as a command from which to read.

       QQuuiitt         Exit from ggxxddiittvviieeww.

       The  menu  entries correspond to actions with similar but not identical
       names, which can also be accessed with keyboard accelerators.   The  _n,
       _S_p_a_c_e,  _R_e_t_u_r_n,  and _N_e_x_t (_P_g_D_n) keys are bound to the NNeexxttPPaaggee action.
       The _p, _b, _B_a_c_k_S_p_a_c_e, _D_e_l_e_t_e, and _P_r_i_o_r (_P_g_U_p) keys  are  bound  to  the
       PPrreevviioouussPPaaggee action.  The _g key is bound to the SSeelleeccttPPaaggee action.  The
       _o  key is bound to the OOppeennFFiillee action.  The _q key is bound to the QQuuiitt
       action.  The _r key is bound to a RReerraasstteerriizzee action 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 _k and _j keys; horizontal scrolling is bound to the _h  and
       _l  keys.   The arrow keys (_u_p, _d_o_w_n, _l_e_f_t, and _r_i_g_h_t) are also bound to
       the obvious scrolling actions.

       The ppaappeerrlleennggtthh and ppaappeerrwwiiddtthh commands in the _D_E_S_C file  describing  a
       _g_r_o_f_f  output  device  specify the length and width in machine units of
       the virtual page displayed by _g_x_d_i_t_v_i_e_w; see _g_r_o_f_f___f_o_n_t(5).

   XX ddeeffaauullttss
       This program uses the _D_v_i widget from the X  Toolkit.   It  understands
       all of the core resource names and classes as well as:

       wwiiddtthh (class WWiiddtthh)
              Specifies the width of the window.

       hheeiigghhtt (class HHeeiigghhtt)
              Specifies the height of the window.

       ffoorreeggrroouunndd (class FFoorreeggrroouunndd)
              Specifies the default foreground color.

       ffoonntt (class FFoonntt)
              Specifies the font to be used for error messages.

       ffoonnttMMaapp (class FFoonnttMMaapp)
              Specifies  the  mapping  from  _g_r_o_f_f 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 _g_r_o_f_f font
              name, and secondly the XLFD (X Logical Font  Description).   The
              default is shown in subsection “Default font map” below.

   DDeeffaauulltt ffoonntt mmaapp
       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\

OOppttiioonnss
       --hheellpp and ----hheellpp display a usage message, while --vveerrssiioonn and  ----vveerrssiioonn
       show version information; all exit afterward.

       _g_x_d_i_t_v_i_e_w  accepts  all  of the standard X Toolkit command‐line options
       along with the additional options listed below.

       --ppaaggee  This option specifies the page number of the document to be dis‐
              played.

       --bbaacckkiinnggSSttoorree _b_a_c_k_i_n_g_‐_s_t_o_r_e_‐_t_y_p_e
              Because redisplay of the _g_r_o_f_f 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.  _b_a_c_k_i_n_g_‐_s_t_o_r_e_‐_t_y_p_e  can  be  one  of  AAllwwaayyss,
              WWhheennMMaappppeedd or NNoottUUsseeffuull.

       --pprriinnttCCoommmmaanndd _c_o_m_m_a_n_d
              The  default  command  displayed in the dialog box for the PPrriinntt
              menu entry will be _c_o_m_m_a_n_d.

       --rreessoolluuttiioonn _r_e_s
              The _g_r_o_f_f intermediate output file will be displayed at a  reso‐
              lution  of  _r_e_s dots per inch, unless the _D_E_S_C file contains the
              XX1111 command, in which case the device resolution will  be  used.
              This  corresponds  to the _D_v_i widget’s rreessoolluuttiioonn resource.  The
              default is 7755.

       --ffiilleennaammee _s_t_r_i_n_g
              The default filename displayed in the dialog box  for  the  OOppeenn
              menu  entry will be _s_t_r_i_n_g.  This can be either a filename, or a
              command starting with “||”.

       The following standard X Toolkit command‐line  arguments  are  commonly
       used with _g_x_d_i_t_v_i_e_w.

       --bbgg _c_o_l_o_r
              This option specifies the color to use for the background of the
              window.  The default is “wwhhiittee”.

       --bbdd _c_o_l_o_r
              This  option  specifies  the  color to use for the border of the
              window.  The default is “bbllaacckk”.

       --bbww _n_u_m_b_e_r
              This option specifies the width in pixels  of  the  border  sur‐
              rounding the window.

       --ffgg _c_o_l_o_r
              This option specifies the color to use for displaying text.  The
              default is “bbllaacckk”.

       --ffnn _f_o_n_t
              This  option specifies the font to be used for displaying widget
              text.  The default is “ffiixxeedd”.

       --rrvv    This option indicates that reverse video should be simulated  by
              swapping the foreground and background colors.

       --ggeeoommeettrryy _g_e_o_m_e_t_r_y
              This  option  specifies  the  preferred size and position of the
              window.

       --ddiissppllaayy _h_o_s_t::_d_i_s_p_l_a_y
              This option specifies the X server to contact.

       --xxrrmm _r_e_s_o_u_r_c_e_s_t_r_i_n_g
              This option specifies a resource string to be used.

EEnnvviirroonnmmeenntt
       _G_R_O_F_F___F_O_N_T___P_A_T_H
              A list of directories in which to seek the selected  output  de‐
              vice’s  directory  of  device  and  font description files.  See
              _t_r_o_f_f(1) and _g_r_o_f_f___f_o_n_t(5).

FFiilleess
       _/_e_t_c_/_X_1_1_/_a_p_p_-_d_e_f_a_u_l_t_s_/_G_X_d_i_t_v_i_e_w
       _/_e_t_c_/_X_1_1_/_a_p_p_-_d_e_f_a_u_l_t_s_/_G_X_d_i_t_v_i_e_w_-_c_o_l_o_r
              define X application defaults for _g_x_d_i_t_v_i_e_w.  Users can override
              these values in the _._X_d_e_f_a_u_l_t_s file,  normally  located  in  the
              user’s home directory.  See _a_p_p_r_e_s(1) and _x_r_d_b(1).

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_X_1_0_0_/_D_E_S_C
              describes the XX110000 output device.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_X_1_0_0_/F
              describes the font known as _F on device XX110000.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_X_1_0_0_-_1_2_/_D_E_S_C
              describes the XX110000--1122 output device.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_X_1_0_0_-_1_2_/F
              describes the font known as _F on device XX110000--1122.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_X_7_5_/_D_E_S_C
              describes the XX7755 output device.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_X_7_5_/F
              describes the font known as _F on device XX7755.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_X_7_5_-_1_2_/_D_E_S_C
              describes the XX7755--1122 output device.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_X_7_5_-_1_2_/F
              describes the font known as _F on device XX7755--1122.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_X_._t_m_a_c
              defines  macros  for use with the XX110000, XX110000--1122, XX7755, and XX7755--1122
              output devices.  It is automatically loaded by _t_r_o_f_f_r_c when  any
              of those output devices is selected.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_X_p_s_._t_m_a_c
              sets  up  _t_r_o_f_f to use _g_x_d_i_t_v_i_e_w as a previewer for device‐inde‐
              pendent output targeting the ppss output device.  It is  automati‐
              cally  loaded  by _t_r_o_f_f_r_c when _t_r_o_f_f is given the options --XX and
              --TTppss.

EExxaammpplleess
       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 _d_o_c_u_m_e_n_t
       yields acceptable results.

AAuutthhoorrss
       _g_x_d_i_t_v_i_e_w  and  its  predecessor _x_d_i_t_v_i_e_w 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 _x_d_i_t_v_i_e_w; portions of _x_d_i_t_v_i_e_w originated
       in _x_t_r_o_f_f, which was derived from _s_u_n_t_r_o_f_f.

SSeeee aallssoo
       “X Logical Font Description Conventions”, by Jim  Flowers  and  Stephen
       Gildea.

       _X(7), _x_r_d_b(1), _x_d_i_t_v_i_e_w(1), _g_r_o_f_f(1), _g_r_o_f_f___o_u_t(5)

groff 1.23.0                      3 June 2025                     _g_x_d_i_t_v_i_e_w(1)
───────────────────────────────────────────────────────────────────────────────
_h_p_f_t_o_d_i_t(1)                 General Commands Manual                _h_p_f_t_o_d_i_t(1)

NNaammee
       hpftodit - create font description files for use with _g_r_o_f_f and _g_r_o_l_j_4

SSyynnooppssiiss
       hhppffttooddiitt [--aaqqss] [--ii _n] _t_f_m_‐_f_i_l_e _m_a_p_‐_f_i_l_e _f_o_n_t_‐_d_e_s_c_r_i_p_t_i_o_n

       hhppffttooddiitt --dd _t_f_m_‐_f_i_l_e [_m_a_p_‐_f_i_l_e]

       hhppffttooddiitt ----hheellpp

       hhppffttooddiitt --vv
       hhppffttooddiitt ----vveerrssiioonn

DDeessccrriippttiioonn
       _h_p_f_t_o_d_i_t creates a font description file for use with a Hewlett‐Packard
       LaserJet  4‐series  (or newer) printer with the _g_r_o_l_j_4(1) output driver
       of _g_r_o_f_f(1), using data from an HP tagged font metric (TFM) file.  _t_f_m_‐
       _f_i_l_e is the name of the font’s TFM file; Intellifont and  TrueType  TFM
       files  are  supported, but symbol set TFM files are not.  _m_a_p_‐_f_i_l_e is a
       file giving the _g_r_o_f_f special character identifiers for glyphs  in  the
       font; this file should consist of a sequence of lines of the form
              _m _u _c_1 _c_2 ... [# _c_o_m_m_e_n_t]
       where  _m  is  a  decimal  integer giving the glyph’s MSL (Master Symbol
       List) number, _u is a hexadecimal integer giving its  Unicode  character
       code, and _c_1, _c_2, ...  are its _g_r_o_f_f glyph names (see _g_r_o_f_f___c_h_a_r(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 “00xx”, “uu”, or “UU++”.  Unicode  values  corresponding
       to   composite   glyphs   are   decomposed;  that  is  “uu0000CC00”  becomes
       “uu00004411__00330000”.  A glyph without a _g_r_o_f_f special character identifier may
       be named uu_X_X_X_X if the glyph corresponds to a Unicode value,  or  as  an
       unnamed  glyph “------”.  If the given Unicode value is in the Private Use
       Area (PUA) (0xE000–0xF8FF), the glyph is included as an unnamed  glyph.
       Refer  to _g_r_o_f_f___d_i_f_f(1) for additional information about unnamed glyphs
       and how to access them.

       Blank lines and lines beginning with “##” are ignored.  A “##”  following
       one or more _g_r_o_f_f names begins a comment.  Because “##” is a valid _g_r_o_f_f
       name, it must appear first in a list of _g_r_o_f_f 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 “##” is interpreted as the beginning of the comment.

       Output  is  written in _g_r_o_f_f___f_o_n_t(5) format to _f_o_n_t_‐_d_e_s_c_r_i_p_t_i_o_n_, a file
       named for the intended _g_r_o_f_f font name; if this  operand  is  “--”,  the
       font description is written to the standard output stream.

       If  the  --ii  option  is  used,  _h_p_f_t_o_d_i_t 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
       _g_r_o_f_f___f_o_n_t(5)).

OOppttiioonnss
       ----hheellpp  displays  a  usage message, while --vv and ----vveerrssiioonn show version
       information; all exit afterward.

       --aa     Include glyphs in the TFM file that are  not  included  in  _m_a_p_‐
              _f_i_l_e.   A  glyph  with  corresponding Unicode value is given the
              name u_X_X_X_X; 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 --ss option 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,  --aa  should  be  used
              only as a last resort.

       --dd     Dump  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  _m_a_p_‐_f_i_l_e  is  given,
              _g_r_o_f_f  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 --dd option, _m_a_p_‐_f_i_l_e is optional, and _o_u_t_p_u_t_‐_f_o_n_t is ig‐
              nored if given.

       --ii _n   Generate an italic correction for each glyph so that  its  width
              plus  its  italic  correction is equal to _n 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 _n
              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.

       --qq     Suppress 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 _h_p_f_t_o_d_i_t to the standard
              output stream.

       --ss     Add the ssppeecciiaall directive 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.

FFiilleess
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_l_j_4_/_D_E_S_C
              describes the lljj44 output device.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_l_j_4_/F
              describes the font known as _F on device lljj44.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_l_j_4_/_g_e_n_e_r_a_t_e_/_M_a_k_e_f_i_l_e
              is  a  _m_a_k_e(1) script that uses _h_p_f_t_o_d_i_t(1) to prepare the _g_r_o_f_f
              font description files above from HP TFM data; in can be used to
              regenerate them in the event the TFM files are updated.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_l_j_4_/_g_e_n_e_r_a_t_e_/_s_p_e_c_i_a_l_._a_w_k
              is an _a_w_k(1) script that corrects the  Intellifont‐based  height
              metrics  for several glyphs in the SS (special) font for TrueType
              CG Times used in the HP LaserJet 4000 and later.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_l_j_4_/_g_e_n_e_r_a_t_e_/_s_p_e_c_i_a_l_._m_a_p
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_l_j_4_/_g_e_n_e_r_a_t_e_/_s_y_m_b_o_l_._m_a_p
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_l_j_4_/_g_e_n_e_r_a_t_e_/_t_e_x_t_._m_a_p
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_l_j_4_/_g_e_n_e_r_a_t_e_/_w_i_n_g_d_i_n_g_s_._m_a_p
              map MSL indices and HP Unicode PUA assignments to _g_r_o_f_f  special
              character identifiers.

SSeeee aallssoo
       _g_r_o_f_f(1), _g_r_o_f_f___d_i_f_f(1), _g_r_o_l_j_4(1), _g_r_o_f_f___f_o_n_t(5)

groff 1.23.0                      3 June 2025                      _h_p_f_t_o_d_i_t(1)
───────────────────────────────────────────────────────────────────────────────
_i_n_d_x_b_i_b(1)                  General Commands Manual                 _i_n_d_x_b_i_b(1)

NNaammee
       indxbib - make inverted index for bibliographic databases

SSyynnooppssiiss
       iinnddxxbbiibb [--ww] [--cc _c_o_m_m_o_n_‐_w_o_r_d_s_‐_f_i_l_e] [--dd _d_i_r] [--ff _l_i_s_t_‐_f_i_l_e]
               [--hh _m_i_n_‐_h_a_s_h_‐_t_a_b_l_e_‐_s_i_z_e] [--ii _e_x_c_l_u_d_e_d_‐_f_i_e_l_d_s]
               [--kk _m_a_x_‐_k_e_y_s_‐_p_e_r_‐_r_e_c_o_r_d] [--ll _m_i_n_‐_k_e_y_‐_l_e_n_g_t_h] [--nn _t_h_r_e_s_h_o_l_d]
               [--oo _f_i_l_e] [--tt _m_a_x_‐_k_e_y_‐_l_e_n_g_t_h] [_f_i_l_e ...]

       iinnddxxbbiibb ----hheellpp

       iinnddxxbbiibb --vv
       iinnddxxbbiibb ----vveerrssiioonn

DDeessccrriippttiioonn
       _i_n_d_x_b_i_b makes an inverted index for the bibliographic databases in each
       _f_i_l_e for use with _r_e_f_e_r(1), _l_o_o_k_b_i_b(1), and _l_k_b_i_b(1).  Each created in‐
       dex  is named file_._i; writing is done to a temporary file which is then
       renamed to this.  If no _f_i_l_e operands are given on the command line be‐
       cause the --ff option has been used, and no --oo option is given, the index
       will be named _I_n_d_._i.

       Bibliographic databases  are  divided  into  records  by  blank  lines.
       Within  a record, each field starts with a %% character at the beginning
       of a line.  Fields have a one letter name that follows the %% character.

       The values set by the --cc, --ll, --nn, and --tt options 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 --ii option is also stored in the index and will be used
       in verifying records found using the index.

OOppttiioonnss
       ----hheellpp displays a usage message, while --vv and  ----vveerrssiioonn  show  version
       information; all exit afterward.

       --cc _c_o_m_m_o_n_‐_w_o_r_d_s_‐_f_i_l_e
              Read  the list of common words from _c_o_m_m_o_n_‐_w_o_r_d_s_‐_f_i_l_e instead of
              _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_e_i_g_n.

       --dd _d_i_r Use _d_i_r as the name of the directory to store in the index,  in‐
              stead  of  that returned by _g_e_t_c_w_d(2).  Typically, _d_i_r will be a
              symbolic link whose target is the current working directory.

       --ff _l_i_s_t_‐_f_i_l_e
              Read the files to be indexed from _l_i_s_t_‐_f_i_l_e.  If _l_i_s_t_‐_f_i_l_e is --,
              files will be read from the standard input stream.  The  --ff  op‐
              tion can be given at most once.

       --hh _m_i_n_‐_h_a_s_h_‐_t_a_b_l_e_‐_s_i_z_e
              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
              _i_n_d_x_b_i_b to use more memory.  The default hash table size is 997.

       --ii _e_x_c_l_u_d_e_d_‐_f_i_e_l_d_s
              Don’t index the contents of fields whose names are in  _e_x_c_l_u_d_e_d_‐
              _f_i_e_l_d_s.   Field names are one character each.  If this option is
              not present, _i_n_d_x_b_i_b excludes fields XX, YY, and ZZ.

       --kk _m_a_x_‐_k_e_y_s_‐_p_e_r_‐_r_e_c_o_r_d
              Use no more keys per input record than specified  in  the  argu‐
              ment.  If this option is not present, the maximum is 100.

       --ll _m_i_n_‐_k_e_y_‐_l_e_n_g_t_h
              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.

       --nn _t_h_r_e_s_h_o_l_d
              Discard the _t_h_r_e_s_h_o_l_d most common words from  the  common  words
              file.   If this option is not present, the 100 most common words
              are discarded.

       --oo _b_a_s_e_n_a_m_e
              Name the index basename_._i.

       --tt _m_a_x_‐_k_e_y_‐_l_e_n_g_t_h
              Truncate keys to _m_a_x_‐_k_e_y_‐_l_e_n_g_t_h in characters.  If  this  option
              is not present, keys are truncated to 6 characters.

       --ww     Index whole files.  Each file is a separate record.

FFiilleess
       file_._i index for _f_i_l_e

       _I_n_d_._i  default index name

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_e_i_g_n
              contains  the  list  of  common  words.   The  traditional name,
              “_e_i_g_n”, is an abbreviation of “English ignored [word list]”.

       _i_n_d_x_b_i_bXXXXXX
              temporary file

SSeeee aallssoo
       “Some Applications of Inverted Indexes on the Unix System”,  by  M.  E.
       Lesk,  1978,  AT&T Bell Laboratories Computing Science Technical Report
       No. 69.

       _r_e_f_e_r(1), _l_k_b_i_b(1), _l_o_o_k_b_i_b(1)

groff 1.23.0                      3 June 2025                       _i_n_d_x_b_i_b(1)
───────────────────────────────────────────────────────────────────────────────
_l_k_b_i_b(1)                    General Commands Manual                   _l_k_b_i_b(1)

NNaammee
       lkbib - search bibliographic databases

SSyynnooppssiiss
       llkkbbiibb [--nn] [--ii _f_i_e_l_d_s] [--pp _f_i_l_e] ... [--tt _n] _k_e_y ...

       llkkbbiibb ----hheellpp

       llkkbbiibb --vv
       llkkbbiibb ----vveerrssiioonn

DDeessccrriippttiioonn
       _l_k_b_i_b searches bibliographic databases for references  containing  key‐
       words  _k_e_y  and  writes  any  references  found  to the standard output
       stream.  It reads databases given by --pp options and then (unless --nn  is
       given)  a  default  database.   The  default database is taken from the
       _R_E_F_E_R environment variable if it is set,  otherwise  it  is  _/_u_s_r_/_d_i_c_t_/
       _p_a_p_e_r_s_/_I_n_d.   For each database _f_i_l_e to be searched, if an index file_._i
       created by _i_n_d_x_b_i_b(1) exists, then it will be  searched  instead;  each
       index can cover multiple databases.

OOppttiioonnss
       ----hheellpp  displays  a  usage message, while --vv and ----vveerrssiioonn show version
       information; all exit afterward.

       --ii _s_t_r_i_n_g
              When searching files for which no index exists, ignore the  con‐
              tents of fields whose names are in _s_t_r_i_n_g.

       --nn     Suppress search of default database.

       --pp _f_i_l_e
              Search _f_i_l_e.  Multiple --pp options can be used.

       --tt _n   Require  only  the  first _n characters of keys to be given.  The
              default is 6.

EEnnvviirroonnmmeenntt
       _R_E_F_E_R  Default database.

FFiilleess
       _/_u_s_r_/_d_i_c_t_/_p_a_p_e_r_s_/_I_n_d
              Default database to be used if the _R_E_F_E_R environment variable is
              not set.

       file_._i Index files.

SSeeee aallssoo
       “Some Applications of Inverted Indexes on the Unix System”,  by  M.  E.
       Lesk,  1978,  AT&T Bell Laboratories Computing Science Technical Report
       No. 69.

       _r_e_f_e_r(1), _l_o_o_k_b_i_b(1), _i_n_d_x_b_i_b(1)

groff 1.23.0                      3 June 2025                         _l_k_b_i_b(1)
───────────────────────────────────────────────────────────────────────────────
_l_o_o_k_b_i_b(1)                  General Commands Manual                 _l_o_o_k_b_i_b(1)

NNaammee
       lookbib - search bibliographic databases

SSyynnooppssiiss
       llooookkbbiibb [--ii _s_t_r_i_n_g] [--tt _n] _f_i_l_e ...

       llooookkbbiibb ----hheellpp

       llooookkbbiibb --vv
       llooookkbbiibb ----vveerrssiioonn

DDeessccrriippttiioonn
       _l_o_o_k_b_i_b 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
       _f_i_l_e 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  _f_i_l_e to be searched, if an index
       file_._i created by _i_n_d_x_b_i_b(1) exists, then it will be searched  instead;
       each index can cover multiple databases.

OOppttiioonnss
       ----hheellpp  displays  a  usage message, while --vv and ----vveerrssiioonn show version
       information; all exit afterward.

       --ii _s_t_r_i_n_g
              When searching files for which no index exists, ignore the  con‐
              tents of fields whose names are in _s_t_r_i_n_g.

       --tt _n   Require  only  the  first _n characters of keys to be given.  The
              default is 6.

FFiilleess
       file_._i Index files.

SSeeee aallssoo
       “Some Applications of Inverted Indexes on the Unix System”,  by  M.  E.
       Lesk,  1978,  AT&T Bell Laboratories Computing Science Technical Report
       No. 69.

       _r_e_f_e_r(1), _l_k_b_i_b(1), _i_n_d_x_b_i_b(1)

groff 1.23.0                      3 June 2025                       _l_o_o_k_b_i_b(1)
───────────────────────────────────────────────────────────────────────────────
_m_m_r_o_f_f(1)                   General Commands Manual                  _m_m_r_o_f_f(1)

NNaammee
       mmroff - cross‐referencing front end for GNU _r_o_f_f _m_m macro package

SSyynnooppssiiss
       mmmmrrooffff [--xx] _g_r_o_f_f_‐_a_r_g_u_m_e_n_t ...

       mmmmrrooffff ----hheellpp

       mmmmrrooffff ----vveerrssiioonn

DDeessccrriippttiioonn
       _m_m_r_o_f_f is a simple wrapper for _g_r_o_f_f, used to expand  cross  references
       in _m_m; see _g_r_o_f_f___m_m(7).  It runs _g_r_o_f_f with the --mmmm option twice, first
       with  --zz  and  --rrRReeff==11 to 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 PPIICC macro.
       Documents that do not use these features of _g_r_o_f_f _m_m (the  IINNIITTII,  IINNDD,
       IINNDDPP,  IINNIITTRR,  SSEETTRR,  GGEETTHHNN, GGEETTPPNN, GGEETTRR, GGEETTSSTT, and PPIICC macros) do not
       require _m_m_r_o_f_f.

OOppttiioonnss
       ----hheellpp displays a usage message, while ----vveerrssiioonn shows version informa‐
       tion; both exit afterward.

       --xx     Create or update the cross‐reference file and exit.

AAuutthhoorrss
       _m_m_r_o_f_f was written by Jörgen Hägg of Lund, Sweden.

SSeeee aallssoo
       _g_r_o_f_f___m_m(7),  _g_r_o_f_f___m_m_s_e(7)  (only  in  Swedish   locales),   _g_r_o_f_f(1),
       _t_r_o_f_f(1), _t_b_l(1), _p_i_c(1), _e_q_n(1)

groff 1.23.0                      3 June 2025                        _m_m_r_o_f_f(1)
───────────────────────────────────────────────────────────────────────────────
_n_e_q_n(1)                     General Commands Manual                    _n_e_q_n(1)

NNaammee
       neqn - format equations for character‐cell terminal output

SSyynnooppssiiss
       nneeqqnn [_e_q_n_‐_a_r_g_u_m_e_n_t ...]

DDeessccrriippttiioonn
       _n_e_q_n invokes the _e_q_n(1) command with the aasscciiii output device.

       _e_q_n  does not support low‐resolution, typewriter‐like devices, although
       it may work adequately for very simple input.

SSeeee aallssoo
       _e_q_n(1)

groff 1.23.0                      3 June 2025                          _n_e_q_n(1)
───────────────────────────────────────────────────────────────────────────────
_n_r_o_f_f(1)                    General Commands Manual                   _n_r_o_f_f(1)

NNaammee
       nroff - format documents with _g_r_o_f_f for TTY (terminal) devices

SSyynnooppssiiss
       nnrrooffff [--bbccCCEEhhiikkppRRSSttUUVVzz] [--dd _c_t_e_x_t] [--dd _s_t_r_i_n_g==_t_e_x_t] [--KK _f_a_l_l_b_a_c_k_‐
             _e_n_c_o_d_i_n_g] [--mm _m_a_c_r_o_‐_p_a_c_k_a_g_e] [--MM _m_a_c_r_o_‐_d_i_r_e_c_t_o_r_y] [--nn _p_a_g_e_‐
             _n_u_m_b_e_r] [--oo _p_a_g_e_‐_l_i_s_t] [--PP _p_o_s_t_p_r_o_c_e_s_s_o_r_‐_a_r_g_u_m_e_n_t] [--rr _c_n_u_m_e_r_i_c_‐
             _e_x_p_r_e_s_s_i_o_n] [--rr _r_e_g_i_s_t_e_r==_n_u_m_e_r_i_c_‐_e_x_p_r_e_s_s_i_o_n] [--TT _o_u_t_p_u_t_‐_d_e_v_i_c_e]
             [--ww _w_a_r_n_i_n_g_‐_c_a_t_e_g_o_r_y] [--WW _w_a_r_n_i_n_g_‐_c_a_t_e_g_o_r_y] [_f_i_l_e ...]

       nnrrooffff ----hheellpp

       nnrrooffff --vv
       nnrrooffff ----vveerrssiioonn

DDeessccrriippttiioonn
       _n_r_o_f_f formats documents written in  the  _g_r_o_f_f(7)  language  for  type‐
       writer‐like devices such as terminal emulators.  GNU _n_r_o_f_f emulates the
       AT&T   _n_r_o_f_f  command  using  _g_r_o_f_f(1).   _n_r_o_f_f  generates  output  via
       _g_r_o_t_t_y(1), _g_r_o_f_f’s terminal output driver,  which  needs  to  know  the
       character encoding scheme used by the device.  Consequently, acceptable
       arguments  to  the  --TT  option are aasscciiii, llaattiinn11, uuttff88, and ccpp11004477; any
       others are ignored.  If neither the _G_R_O_F_F___T_Y_P_E_S_E_T_T_E_R environment  vari‐
       able  nor  the  --TT command‐line option (which overrides the environment
       variable) specifies a (valid) device, _n_r_o_f_f consults the locale to  se‐
       lect  an  appropriate output device.  It first tries the _l_o_c_a_l_e(1) pro‐
       gram, then checks several  locale‐related  environment  variables;  see
       section  “Environment” below.  If all of the foregoing fail, --TTaasscciiii is
       implied.

       The --bb, --cc, --CC, --dd, --EE, --ii, --mm, --MM, --nn, --oo, --rr, --UU, --ww, --WW, and --zz  op‐
       tions  have  the effects described in _t_r_o_f_f(1).  --cc and --hh imply “--PP--cc”
       and “--PP--hh”, respectively; --cc is also interpreted directly by _t_r_o_f_f.  In
       addition, this implementation ignores the AT&T _n_r_o_f_f  options  --ee,  --qq,
       and  --ss  (which are not implemented in _g_r_o_f_f).  The options --kk, --KK, --pp,
       --PP, --RR, --tt, and --SS are documented in _g_r_o_f_f(1).  --VV causes _n_r_o_f_f to dis‐
       play the constructed _g_r_o_f_f command on the standard output  stream,  but
       does  not  execute it.  --vv and ----vveerrssiioonn show version information about
       _n_r_o_f_f and the programs it runs, while ----hheellpp displays a usage  message;
       all exit afterward.

EExxiitt ssttaattuuss
       _n_r_o_f_f  exits with error status 22 if there was a problem parsing its ar‐
       guments, with status 00 if any of the  options  --VV,  --vv,  ----vveerrssiioonn,  or
       ----hheellpp were specified, and with the status of _g_r_o_f_f otherwise.

EEnnvviirroonnmmeenntt
       Normally,  the path separator in environment variables ending with _P_A_T_H
       is the colon; this may vary depending on the operating system.  For ex‐
       ample, Windows uses a semicolon instead.

       _G_R_O_F_F___B_I_N___P_A_T_H
              is a colon‐separated list of directories in which to search  for
              the  _g_r_o_f_f executable before searching in _P_A_T_H.  If unset, _/_u_s_r_/
              _b_i_n is used.

       _G_R_O_F_F___T_Y_P_E_S_E_T_T_E_R
              specifies the default output device for _g_r_o_f_f.

       _L_C___A_L_L
       _L_C___C_T_Y_P_E
       _L_A_N_G
       _L_E_S_S_C_H_A_R_S_E_T
              are pattern‐matched in this order for contents matching standard
              character encodings supported by _g_r_o_f_f in the event no --TT option
              is given and _G_R_O_F_F___T_Y_P_E_S_E_T_T_E_R is unset, or the values  specified
              are invalid.

FFiilleess
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_t_t_y_-_c_h_a_r_._t_m_a_c
              defines  fallback definitions of _r_o_f_f special characters.  These
              definitions more poorly  optically  approximate  typeset  output
              than those of _t_t_y_._t_m_a_c in favor of communicating semantic infor‐
              mation.  _n_r_o_f_f loads it automatically.

NNootteess
       Pager  programs  like  _m_o_r_e(1) and _l_e_s_s(1) may require command‐line op‐
       tions to correctly handle some output sequences; see _g_r_o_t_t_y(1).

SSeeee aallssoo
       _g_r_o_f_f(1), _t_r_o_f_f(1), _g_r_o_t_t_y(1), _l_o_c_a_l_e(1), _r_o_f_f(7)

groff 1.23.0                      3 June 2025                         _n_r_o_f_f(1)
───────────────────────────────────────────────────────────────────────────────
_p_d_f_m_o_m(1)                   General Commands Manual                  _p_d_f_m_o_m(1)

NNaammee
       pdfmom - produce PDF documents using the _m_o_m macro package for _g_r_o_f_f

SSyynnooppssiiss
       ppddffmmoomm [--TTppddff] [_g_r_o_f_f_‐_o_p_t_i_o_n_s] [_f_i_l_e ...]

       ppddffmmoomm --TTppss [_p_d_f_r_o_f_f_‐_o_p_t_i_o_n_s] [_g_r_o_f_f_‐_o_p_t_i_o_n_s] [_f_i_l_e ...]

       ppddffmmoomm --vv
       ppddffmmoomm ----vveerrssiioonn

DDeessccrriippttiioonn
       _p_d_f_m_o_m is a wrapper around _g_r_o_f_f(1) that facilitates the production  of
       PDF documents from files formatted with the _m_o_m macros.

       _p_d_f_m_o_m  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 _p_s_2_p_d_f(1).

       If called  with  the  --TTppddff  option  (which  is  the  default),  _p_d_f_m_o_m
       processes files using _g_r_o_f_f’s native PDF driver, _g_r_o_p_d_f(1).  If --TTppss is
       given,  processing  is passed over to _p_d_f_r_o_f_f, which uses _g_r_o_f_f’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.

       _p_d_f_m_o_m  accepts  all  the same options as _g_r_o_f_f.  If --TTppss is given, the
       options associated with _p_d_f_r_o_f_f are  accepted  as  well.   When  _p_d_f_m_o_m
       calls  _p_d_f_r_o_f_f,  the  options “--mmppddffmmaarrkk --mmoomm ----nnoo--ttoocc” options are im‐
       plied and should not be given on the command line.  Equally, it is  not
       necessary to supply the --mmoomm or --mm mmoomm options when --TTppss is absent.

       PDF  integration with the _m_o_m macros is discussed in full in the manual
       “Producing PDFs with _g_r_o_f_f and _m_o_m”, which  was  itself  produced  with
       _p_d_f_m_o_m.

       If called with the --vv or ----vveerrssiioonn options, _p_d_f_m_o_m displays its version
       information and exits.

AAuutthhoorrss
       _p_d_f_m_o_m was written by Deri James and Peter Schaffter, and is maintained
       by James.

SSeeee aallssoo
       _/_u_s_r_/_s_h_a_r_e_/_d_o_c_/_g_r_o_f_f_-_b_a_s_e_/_p_d_f_/_m_o_m_-_p_d_f_._p_d_f
              “Producing  PDFs  with  _g_r_o_f_f  and _m_o_m”, by Deri James and Peter
              Schaffter.  This file, together with its source, _m_o_m_-_p_d_f_._m_o_m, is
              part of the _g_r_o_f_f distribution.

       _g_r_o_f_f(1), _g_r_o_p_d_f(1), _p_d_f_r_o_f_f(1), _p_s_2_p_d_f(1)

groff 1.23.0                      3 June 2025                        _p_d_f_m_o_m(1)
───────────────────────────────────────────────────────────────────────────────
_p_d_f_r_o_f_f(1)                  General Commands Manual                 _p_d_f_r_o_f_f(1)

NNaammee
       pdfroff - construct files in Portable Document Format using _g_r_o_f_f

SSyynnooppssiiss
       ppddffrrooffff [_g_r_o_f_f_‐_o_p_t_i_o_n] [----eemmiitt--ppss] [----nnoo--ttoocc--rreellooccaattiioonn]
               [----nnoo--kkiillll--nnuullll--ppaaggeess] [----ssttyylleesshheeeett==_n_a_m_e] [----nnoo--ppddff--oouuttppuutt]
               [----ppddff--oouuttppuutt==_n_a_m_e] [----nnoo--rreeffeerreennccee--ddiiccttiioonnaarryy]
               [----rreeffeerreennccee--ddiiccttiioonnaarryy==_n_a_m_e] [----rreeppoorrtt--pprrooggrreessss]
               [----kkeeeepp--tteemmppoorraarryy--ffiilleess] [_f_i_l_e ...]

       ppddffrrooffff --hh
       ppddffrrooffff ----hheellpp

       ppddffrrooffff --vv [_g_r_o_f_f_‐_o_p_t_i_o_n ...]
       ppddffrrooffff ----vveerrssiioonn [_g_r_o_f_f_‐_o_p_t_i_o_n ...]

       _g_r_o_f_f_‐_o_p_t_i_o_n is any short option supported by _g_r_o_f_f(1) except  for  --hh,
       --TT, and --vv; see section “Usage” below.

DDeessccrriippttiioonn
       _p_d_f_r_o_f_f is a wrapper program for the GNU text processing system, _g_r_o_f_f.
       It  transparently handles the mechanics of multiple pass _g_r_o_f_f process‐
       ing, when applied to suitably marked up _g_r_o_f_f 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 _p_d_f_r_o_f_f, the ultimate  _g_r_o_f_f  output  stream  is
       post‐processed  by  the Ghostscript _g_s(1) interpreter to produce a fin‐
       ished PDF document.

       _p_d_f_r_o_f_f makes no assumptions about, and imposes no restrictions on, the
       use of any _g_r_o_f_f macro packages which the user may choose to employ, in
       order to achieve a desired document format; however,  it  _d_o_e_s  include
       specific  built  in  support  for the _p_d_f_m_a_r_k macro package, should the
       user choose to employ it.  Specifically, if the _p_d_f_h_r_e_f macro,  defined
       in  the _p_d_f_m_a_r_k_._t_m_a_c package, is used to define public reference marks,
       or dynamic links to such reference marks, then _p_d_f_r_o_f_f performs as many
       preformatting _g_r_o_f_f passes as required, up to a maximum limit of  _f_o_u_r,
       in  order to compile a document reference dictionary, to resolve refer‐
       ences, and to expand the dynamically defined content of links.

UUssaaggee
       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  _m_u_s_t  be  specified  independently
       (i.e.,  it  may  _n_o_t 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, _p_d_f_r_o_f_f usage closely mirrors that of _g_r_o_f_f itself.  Indeed,
       with  the  exception  of the --hh, --vv, and --TT _d_e_v short form options, and
       all long form options, which are parsed internally by _p_d_f_r_o_f_f, all  op‐
       tions  and file name arguments specified on the command line are passed
       on to _g_r_o_f_f, to control the formatting of  the  PDF  document.   Conse‐
       quently,  _p_d_f_r_o_f_f  accepts  all  options and arguments, as specified in
       _g_r_o_f_f(1), which may also be considered as the definitive reference  for
       all standard _p_d_f_r_o_f_f options and argument usage.

OOppttiioonnss
       _p_d_f_r_o_f_f  accepts  all of the short form options (i.e., those introduced
       by a single hyphen), which are available with _g_r_o_f_f  itself.   In  most
       cases,  these  are simply passed transparently to _g_r_o_f_f; the following,
       however, are handled specially by _p_d_f_r_o_f_f.

       --hh     Same as ----hheellpp; see below.

       --ii     Process standard input, after all other specified  input  files.
              This  is  passed  transparently  to  _g_r_o_f_f, but, if grouped with
              other options, it _m_u_s_t be the first in  the  group.   Hiding  it
              within  a  group breaks standard input processing, in the multi‐
              ple‐pass _g_r_o_f_f processing context of _p_d_f_r_o_f_f.

       --TT _d_e_v Only --TT ppss is supported by _p_d_f_r_o_f_f.  Attempting to  specify  any
              other device causes _p_d_f_r_o_f_f to abort.

       --vv     Same as ----vveerrssiioonn; see below.

       See  _g_r_o_f_f(1)  for a description of all other short form options, which
       are transparently passed through _p_d_f_r_o_f_f to _g_r_o_f_f.

       All long form options (i.e., those introduced by a double  hyphen)  are
       interpreted locally by _p_d_f_r_o_f_f; they are _n_o_t passed on to _g_r_o_f_f, unless
       otherwise stated below.

       ----hheellpp Causes _p_d_f_r_o_f_f to display a summary of the its usage syntax, and
              supported options, and then exit.

       ----eemmiitt--ppss
              Suppresses  the final output conversion step, causing _p_d_f_r_o_f_f to
              emit PostScript output instead of PDF.  This may  be  useful  to
              capture  intermediate PostScript output when using a specialised
              postprocessor, such as _g_p_r_e_s_e_n_t for example, in place of the de‐
              fault Ghostscript PDF writer.

       ----kkeeeepp--tteemmppoorraarryy--ffiilleess
              Suppresses the deletion of temporary files, which  normally  oc‐
              curs  after  _p_d_f_r_o_f_f 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 _p_d_f_r_o_f_f.

       ----nnoo--ppddff--oouuttppuutt
              May  be  used  with  the ----rreeffeerreennccee--ddiiccttiioonnaarryy==_n_a_m_e option (de‐
              scribed below) to eliminate the overhead of PDF formatting  when
              running  _p_d_f_r_o_f_f  to  create a reference dictionary for use in a
              different document.

       ----nnoo--rreeffeerreennccee--ddiiccttiioonnaarryy
              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 ppddffhhrreeff macro.

       ----nnoo--ttoocc--rreellooccaattiioonn
              May be used to eliminate the extra _g_r_o_f_f 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.

       ----nnoo--kkiillll--nnuullll--ppaaggeess
              While  preparing  for  simulation  of the manual collation step,
              which is traditionally required to relocate a _t_a_b_l_e _o_f  _c_o_n_t_e_n_t_s
              to  the  start  of  a  document, _p_d_f_r_o_f_f 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 _p_d_f_r_o_f_f to leave them in place.

       ----ppddff--oouuttppuutt==_n_a_m_e
              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 _p_d_f_r_o_f_f may use this  option,  to  encode  the
              document name in a generated reference dictionary.

       ----rreeffeerreennccee--ddiiccttiioonnaarryy==_n_a_m_e
              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 _p_d_f_r_o_f_f com‐
              pletes processing of the current document.  This option _m_u_s_t  be
              specified,  if  it  is desired to save the reference dictionary,
              for use in references placed in other PDF documents.

       ----rreeppoorrtt--pprrooggrreessss
              Causes _p_d_f_r_o_f_f to display an informational message  on  standard
              error, at the start of each _g_r_o_f_f processing pass.

       ----ssttyylleesshheeeett==_n_a_m_e
              Specifies the name of an _i_n_p_u_t _f_i_l_e, to be used as a style sheet
              for  formatting of content, which is to be placed _b_e_f_o_r_e the ta‐
              ble of contents, in the formatted PDF document.

       ----vveerrssiioonn
              Causes _p_d_f_r_o_f_f to display a version identification message.  The
              entire command line is then passed transparently to _g_r_o_f_f, in  a
              _o_n_e  pass  operation  _o_n_l_y,  in  order to display the associated
              _g_r_o_f_f version information, before exiting.

EEnnvviirroonnmmeenntt
       The following environment variables may be set, and exported, to modify
       the behaviour of _p_d_f_r_o_f_f.

       _P_D_F_R_O_F_F___C_O_L_L_A_T_E
              Specifies the program to be used for collation of  the  finished
              PDF document.

              This  collation  step may be required to move _t_a_b_l_e_s _o_f _c_o_n_t_e_n_t_s
              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 _P_D_F_R_O_F_F___C_O_L_L_A_T_E,
              (and indeed, are not encouraged  to  do  so).   If  unspecified,
              _p_d_f_r_o_f_f uses _s_e_d(1) by default, which normally suffices.

              If  _P_D_F_R_O_F_F___C_O_L_L_A_T_E  _i_s 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
              _P_D_F_R_O_F_F___P_O_S_T_P_R_O_C_E_S_S_O_R___C_O_M_M_A_N_D,  to produce the finished PDF out‐
              put.

              When specifying _P_D_F_R_O_F_F___C_O_L_L_A_T_E, it  is  normally  necessary  to
              also specify _P_D_F_R_O_F_F___K_I_L_L___N_U_L_L___P_A_G_E_S.

              _P_D_F_R_O_F_F___C_O_L_L_A_T_E  is  ignored,  if  _p_d_f_r_o_f_f  is  invoked with the
              ----nnoo--kkiillll--nnuullll--ppaaggeess option.

       _P_D_F_R_O_F_F___K_I_L_L___N_U_L_L___P_A_G_E_S
              Specifies options to be passed to the _P_D_F_R_O_F_F___C_O_L_L_A_T_E program.

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

              As  in  the  case of _P_D_F_R_O_F_F___C_O_L_L_A_T_E, _P_D_F_R_O_F_F___K_I_L_L___N_U_L_L___P_A_G_E_S is
              ignored, if _p_d_f_r_o_f_f is invoked with the ----nnoo--kkiillll--nnuullll--ppaaggeess op‐
              tion.

       _P_D_F_R_O_F_F___P_O_S_T_P_R_O_C_E_S_S_O_R___C_O_M_M_A_N_D
              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 _f_i_l_e_s _._._. arguments, with
              the special case of “--” representing the standard input stream.

              If unspecified, _P_D_F_R_O_F_F___P_O_S_T_P_R_O_C_E_S_S_O_R___C_O_M_M_A_N_D defaults to
                   gs -dBATCH -dQUIET -dNOPAUSE -dSAFER -sDEVICE=pdfwrite \
                        -sOutputFile=-

       _G_R_O_F_F___T_M_P_D_I_R
              Identifies the directory in which _p_d_f_r_o_f_f should  create  tempo‐
              rary  files.   If  _G_R_O_F_F___T_M_P_D_I_R is _n_o_t specified, then the vari‐
              ables _T_M_P_D_I_R, _T_M_P and _T_E_M_P are considered in  turn  as  possible
              temporary  file  repositories.   If  none of these are set, then
              temporary files are created in the current directory.

       _G_R_O_F_F___G_H_O_S_T_S_C_R_I_P_T___I_N_T_E_R_P_R_E_T_E_R
              Specifies the program to be invoked when _p_d_f_r_o_f_f converts  _g_r_o_f_f
              PostScript  output  to PDF.  If _P_D_F_R_O_F_F___P_O_S_T_P_R_O_C_E_S_S_O_R___C_O_M_M_A_N_D is
              specified, then the command name it specifies is _i_m_p_l_i_c_i_t_l_y  as‐
              signed to _G_R_O_F_F___G_H_O_S_T_S_C_R_I_P_T___I_N_T_E_R_P_R_E_T_E_R, overriding any explicit
              setting      specified      in      the     environment.      If
              _G_R_O_F_F___G_H_O_S_T_S_C_R_I_P_T___I_N_T_E_R_P_R_E_T_E_R is  not  specified,  then  _p_d_f_r_o_f_f
              searches the process _P_A_T_H, looking for a program with any of the
              well  known  names for the Ghostscript interpreter; if no Ghost‐
              script interpreter can be found, _p_d_f_r_o_f_f aborts.

       _G_R_O_F_F___A_W_K___I_N_T_E_R_P_R_E_T_E_R
              Specifies the program to be invoked when _p_d_f_r_o_f_f  is  extracting
              reference  dictionary  entries from a _g_r_o_f_f intermediate message
              stream.  If _G_R_O_F_F___A_W_K___I_N_T_E_R_P_R_E_T_E_R is not specified, then _p_d_f_r_o_f_f
              searches the process _P_A_T_H, looking for any of the preferred pro‐
              grams, _g_a_w_k, _m_a_w_k, _n_a_w_k, and _a_w_k, in  that  order;  if  none  of
              these  are found, _p_d_f_r_o_f_f issues a warning message, and continue
              processing; however, in this case, no  reference  dictionary  is
              created.

       _O_S_T_Y_P_E Typically  defined automatically by the operating system, _O_S_T_Y_P_E
              is used on Microsoft Win32/MS‐DOS platforms _o_n_l_y, to  infer  the
              default _P_A_T_H___S_E_P_A_R_A_T_O_R character, which is used when parsing the
              process _P_A_T_H to search for external helper programs.

       _P_A_T_H___S_E_P_A_R_A_T_O_R
              If  set,  _P_A_T_H___S_E_P_A_R_A_T_O_R overrides the default separator charac‐
              ter, (‘:’ on POSIX/Unix systems, inferred  from  _O_S_T_Y_P_E  on  Mi‐
              crosoft  Win32/MS‐DOS),  which  is used when parsing the process
              _P_A_T_H to search for external helper programs.

       _S_H_O_W___P_R_O_G_R_E_S_S
              If this is set to a non‐empty value, then _p_d_f_r_o_f_f always behaves
              as if the ----rreeppoorrtt--pprrooggrreessss option is specified on  the  command
              line.

FFiilleess
       Input  and  output files for _p_d_f_r_o_f_f 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_._m_s might be an input file  for  formatting  using  the  _m_s  macros
       (_s_._t_m_a_c); normally, the final output file should be named file_._p_d_f.

       Temporary  files created by _p_d_f_r_o_f_f are placed in the file system hier‐
       archy, in or below the directory  specified  by  environment  variables
       (see  section  “Environment”  above).  If _m_k_t_e_m_p(1) is available, it is
       invoked to create a private subdirectory  of  the  nominated  temporary
       files  directory,  (with  subdirectory  name  derived from the template
       _p_d_f_r_o_f_f_-_X_X_X_X_X_X_X_X_X_X); 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
       _p_d_f$$_.*, where _$_$ is  the  standard  shell  variable  representing  the
       process  identifier of the _p_d_f_r_o_f_f process itself, and _* represents any
       of the extensions used by _p_d_f_r_o_f_f to identify the  following  temporary
       and intermediate files.

       _p_d_f$$_._t_m_p
              A  scratch  pad  file, used to capture reference data emitted by
              _g_r_o_f_f, during the _r_e_f_e_r_e_n_c_e _d_i_c_t_i_o_n_a_r_y compilation phase.

       _p_d_f$$_._r_e_f
              The _r_e_f_e_r_e_n_c_e _d_i_c_t_i_o_n_a_r_y, as compiled in the last but  one  pass
              of  the _r_e_f_e_r_e_n_c_e _d_i_c_t_i_o_n_a_r_y compilation phase; (at the start of
              the first pass,  this  file  is  created  empty;  in  successive
              passes,  it  contains  the _r_e_f_e_r_e_n_c_e _d_i_c_t_i_o_n_a_r_y entries, as col‐
              lected in the preceding pass).

              If the ----rreeffeerreennccee--ddiiccttiioonnaarryy=_n_a_m_e option is specified, this in‐
              termediate file becomes permanent, and  is  named  _n_a_m_e,  rather
              than _p_d_f$$_._r_e_f.

       _p_d_f$$_._c_m_p
              Used  to  collect _r_e_f_e_r_e_n_c_e _d_i_c_t_i_o_n_a_r_y entries during the active
              pass of the _r_e_f_e_r_e_n_c_e _d_i_c_t_i_o_n_a_r_y compilation phase.  At the  end
              of any pass, when the content of _p_d_f$$_._c_m_p compares as identical
              to   _p_d_f$$_._r_e_f,   (or   the  corresponding  file  named  by  the
              ----rreeffeerreennccee--ddiiccttiioonnaarryy=_n_a_m_e option), then  _r_e_f_e_r_e_n_c_e  _d_i_c_t_i_o_n_a_r_y
              compilation is terminated, and the _d_o_c_u_m_e_n_t _r_e_f_e_r_e_n_c_e _m_a_p is ap‐
              pended  to  this  intermediate  file, for inclusion in the final
              formatting passes.

       _p_d_f$$_._t_c
              An intermediate _P_o_s_t_S_c_r_i_p_t file, in which  “Table  of  Contents”
              entries  are collected, to facilitate relocation before the body
              text, on ultimate output to the _G_h_o_s_t_s_c_r_i_p_t postprocessor.

       _p_d_f$$_._p_s
              An intermediate _P_o_s_t_S_c_r_i_p_t file, in which the body text is  col‐
              lected  prior  to ultimate output to the _G_h_o_s_t_s_c_r_i_p_t postproces‐
              sor, in the proper sequence, _a_f_t_e_r _p_d_f$$_._t_c.

AAuutthhoorrss
       _p_d_f_r_o_f_f was written by Keith Marshall, who maintains it  at  his _g_r_o_f_f_‐
       _p_d_f_m_a_r_k OSDN site.   _g_r_o_f_f’s  version  may be withdrawn in a future re‐
       lease.

SSeeee aallssoo
       _G_r_o_f_f_: _T_h_e _G_N_U _I_m_p_l_e_m_e_n_t_a_t_i_o_n _o_f _t_r_o_f_f, by Trent A. Fisher  and  Werner
       Lemberg,  is the primary _g_r_o_f_f manual.  You can browse it interactively
       with “info groff”.

       Since _p_d_f_r_o_f_f provides a superset of all _g_r_o_f_f capabilities, the  above
       manual,  or  its terser reference page, _g_r_o_f_f(7) may also be considered
       definitive references to all _s_t_a_n_d_a_r_d  capabilities  of  _p_d_f_r_o_f_f,  with
       this document providing the reference to _p_d_f_r_o_f_f’s extended features.

       While  _p_d_f_r_o_f_f  imposes neither any restriction on, nor any requirement
       for, the use of any specific _g_r_o_f_f macro package, a number of  supplied
       macro  packages,  and  in  particular those associated with the package
       _p_d_f_m_a_r_k_._t_m_a_c, are best suited for use with  _p_d_f_r_o_f_f  as  the  preferred
       formatter.

       _/_u_s_r_/_s_h_a_r_e_/_d_o_c_/_g_r_o_f_f_-_b_a_s_e_/_p_d_f_/_p_d_f_m_a_r_k_._p_d_f_._g_z
              “Portable  Document  Format Publishing with GNU _T_r_o_f_f”, by Keith
              Marshall, offers detailed documentation  on  the  use  of  these
              packages.   This  file, together with its source, _p_d_f_m_a_r_k_._m_s, is
              part of the _g_r_o_f_f distribution.

groff 1.23.0                      3 June 2025                       _p_d_f_r_o_f_f(1)
───────────────────────────────────────────────────────────────────────────────
_p_f_b_t_o_p_s(1)                  General Commands Manual                 _p_f_b_t_o_p_s(1)

NNaammee
       pfbtops - translate PostScript Printer Font  Binary  files  to  Printer
       Font ASCII

SSyynnooppssiiss
       ppffbbttooppss [_p_f_b_‐_f_i_l_e]

       ppffbbttooppss ----hheellpp

       ppffbbttooppss --vv
       ppffbbttooppss ----vveerrssiioonn

DDeessccrriippttiioonn
       _p_f_b_t_o_p_s  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 _p_f_b_‐_f_i_l_e 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 _g_r_o_f_f requires conversion of its metrics (AFM file) to
       a _g_r_o_f_f font description file; see _a_f_m_t_o_d_i_t(1).

       The ----hheellpp option displays a usage message, while --vv and ----vveerrssiioonn show
       version information; all exit afterward.

SSeeee aallssoo
       _g_r_o_p_s(1), _g_r_o_p_d_f(1)

groff 1.23.0                      3 June 2025                       _p_f_b_t_o_p_s(1)
───────────────────────────────────────────────────────────────────────────────
_p_i_c(1)                      General Commands Manual                     _p_i_c(1)

NNaammee
       pic - compile pictures for _t_r_o_f_f or TeX

SSyynnooppssiiss
       ppiicc [--CCnnSSUU] [_f_i_l_e ...]

       ppiicc --tt [--ccCCSSUUzz] [_f_i_l_e ...]

       ppiicc ----hheellpp

       ppiicc --vv
       ppiicc ----vveerrssiioonn

DDeessccrriippttiioonn
       The GNU implementation of _p_i_c is part of the _g_r_o_f_f(1) document  format‐
       ting  system.   _p_i_c is a _t_r_o_f_f(1) preprocessor that translates descrip‐
       tions of diagrammatic pictures embedded in _r_o_f_f(7) or TeX  input  files
       into  the  language understood by TeX or _t_r_o_f_f.  It copies the contents
       of each _f_i_l_e to the standard output stream, except that  lines  between
       ..PPSS and any of ..PPEE, ..PPFF, or ..PPYY are interpreted as picture descriptions
       in  the  _p_i_c language.  End a _p_i_c picture with ..PPEE to leave the drawing
       position at the bottom of the picture, and with ..PPFF or ..PPYY to leave  it
       at  the  top.   Normally, _p_i_c is not executed directly by the user, but
       invoked by specifying the --pp option to _g_r_o_f_f(1).  If no  _f_i_l_e  operands
       are  given  on  the command line, or if _f_i_l_e is “--”, the standard input
       stream is read.

       It is the user’s responsibility to provide appropriate  definitions  of
       the  PPSS,  PPEE,  and  one  or both of the PPFF and PPYY macros.  When a macro
       package does not supply these, obtain simple definitions with the _g_r_o_f_f
       option --mmppiicc; these will center each picture.

       GNU _p_i_c supports PPYY as a synonym of PPFF to work around a name space col‐
       lision with the _m_m macro package, which defines PPFF  as  a  page  footer
       management macro.  Use PPFF preferentially unless a similar problem faces
       your document.

OOppttiioonnss
       ----hheellpp  displays  a  usage message, while --vv and ----vveerrssiioonn show version
       information; all exit afterward.

       --cc     Be more compatible with _t_p_i_c; implies --tt.  Lines beginning  with
              \\  are not passed through transparently.  Lines beginning with ..
              are passed through with the initial .. changed to \\.  A line  be‐
              ginning  with  ..ppss  is  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
              tthhiicckknneessss attribute or by setting the lliinneetthhiicckk variable.

       --CC     Recognize ..PPSS, ..PPEE, ..PPFF, and ..PPYY even when followed by a charac‐
              ter other than space or newline.

       --nn     Don’t use _g_r_o_f_f extensions to the _t_r_o_f_f drawing commands.  Spec‐
              ify  this option if a postprocessor you’re using doesn’t support
              these extensions, described in _g_r_o_f_f___o_u_t(5).  This  option  also
              causes  _p_i_c  not  to use zero‐length lines to draw dots in _t_r_o_f_f
              mode.

       --SS     Operate in _s_a_f_e_r _m_o_d_e_; sshh commands are ignored.  This mode,  en‐
              abled  by default, can be useful when operating on untrustworthy
              input.

       --tt     Produce TeX output.

       --UU     Operate in _u_n_s_a_f_e _m_o_d_e_; sshh commands are interpreted.

       --zz     In TeX mode, draw dots using zero‐length lines.

       The following options supported by other versions of _p_i_c are ignored.

       --DD     Draw all lines using the \D escape  sequence.   GNU  _p_i_c  always
              does this.

       --TT _d_e_v Generate  output  for the _t_r_o_f_f device _d_e_v.  This is unnecessary
              because the _t_r_o_f_f output generated by GNU _p_i_c is device‐indepen‐
              dent.

UUssaaggee
       This section primarily discusses the differences between  GNU  _p_i_c  and
       the  Eighth  Edition Research Unix version of AT&T _p_i_c (1985).  Many of
       these differences also apply to later versions of AT&T _p_i_c.

   TTeeXX mmooddee
       TeX‐compatible output is produced when the --tt option is specified.  You
       must use a TeX driver that supports _t_p_i_c version 2 specials.  (_t_p_i_c was
       a fork of AT&T _p_i_c 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 \\ssppeecciiaall commands it produced
       for TeX.)

       Lines beginning with \\ are passed through transparently; a %%  is  added
       to  the  end  of the line to avoid unwanted spaces.  You can safely use
       this feature to change fonts or the value of  \\bbaasseelliinneesskkiipp.   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 --cc option.

       In  TeX  mode,  _p_i_c  will define a vbox called \\ggrraapphh for each picture.
       Use GNU _p_i_c’s ffiiggnnaammee command 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
       \\vvttoopp) 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 _g_r_a_p_h_i_c_s_._s_t_y, 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 \\ggppiiccbbooxx{{ggrraapphh}} instead of \\bbooxx\\ggrraapphh.

   CCoommmmaannddss
       Several  commands new to GNU _p_i_c accept delimiters, shown in their syn‐
       opses as braces {{ }}.  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.

       ffoorr _v_a_r_i_a_b_l_e == _e_x_p_r_1 ttoo _e_x_p_r_2 [bbyy [**]_e_x_p_r_3] ddoo _X _b_o_d_y _X
              Set _v_a_r_i_a_b_l_e to _e_x_p_r_1.  While the value of _v_a_r_i_a_b_l_e is less than
              or  equal  to _e_x_p_r_2, do _b_o_d_y and increment _v_a_r_i_a_b_l_e by _e_x_p_r_3; if
              bbyy is not given, increment _v_a_r_i_a_b_l_e by 1.  If _e_x_p_r_3 is  prefixed
              by  **  then  _v_a_r_i_a_b_l_e  will instead be multiplied by _e_x_p_r_3.  The
              value of _e_x_p_r_3 can be negative for the additive  case;  _v_a_r_i_a_b_l_e
              is  then  tested  whether  it is greater than or equal to _e_x_p_r_2.
              For the multiplicative case, _e_x_p_r_3 must be  greater  than  zero.
              If  the  constraints aren’t met, the loop isn’t executed.  _X can
              be any character not occurring in _b_o_d_y.

       iiff _e_x_p_r tthheenn _X _i_f_‐_t_r_u_e _X [eellssee _Y _i_f_‐_f_a_l_s_e _Y]
              Evaluate _e_x_p_r; if it is non‐zero then do _i_f_‐_t_r_u_e,  otherwise  do
              _i_f_‐_f_a_l_s_e.   _X  can be any character not occurring in _i_f_‐_t_r_u_e.  _Y
              can be any character not occurring in _i_f_‐_f_a_l_s_e.

       pprriinntt _a_r_g ...
              Concatenate and write arguments to  the  standard  error  stream
              followed  by a newline.  Each _a_r_g must be an expression, a posi‐
              tion, or text.  This is useful for debugging.

       ccoommmmaanndd _a_r_g ...
              Concatenate arguments and pass them as a line to _t_r_o_f_f  or  TeX.
              Each  _a_r_g  must  be an expression, a position, or text.  ccoommmmaanndd
              allows the values of _p_i_c 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 _t_r_o_f_f.

       sshh _X _c_o_m_m_a_n_d _X
              Pass _c_o_m_m_a_n_d to a shell.

       ccooppyy ""_f_i_l_e_n_a_m_e""
              Include _f_i_l_e_n_a_m_e at this point in the file.

       ccooppyy [""_f_i_l_e_n_a_m_e""] tthhrruu _X _b_o_d_y _X [uunnttiill "_w_o_r_d""]
       ccooppyy [""_f_i_l_e_n_a_m_e""] tthhrruu _m_a_c_r_o [uunnttiill "_w_o_r_d""]
              This  construct  does  _b_o_d_y  once for each line of _f_i_l_e_n_a_m_e; the
              line is split into blank‐delimited words, and occurrences of  $$_i
              in _b_o_d_y, for _i between 1 and 9, are replaced by the _i‐th word of
              the  line.   If  _f_i_l_e_n_a_m_e is not given, lines are taken from the
              current input up to ..PPEE.  If an uunnttiill clause is specified, lines
              will be read only until a line the first word of which is  _w_o_r_d;
              that  line  will  then be discarded.  _X can be any character not
              occurring in _b_o_d_y.  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 tthhrruu.  The argument after tthhrruu is
              looked up as a macro name first; if not defined, its first char‐
              acter is interpreted as a delimiter.

       rreesseett
       rreesseett _p_v_a_r_1[,,] _p_v_a_r_2 ...
              Reset predefined variables _p_v_a_r_1, _p_v_a_r_2  ...  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 ssccaallee also
              causes all predefined variables that control  dimensions  to  be
              reset to their default values times the new value of ssccaallee.

       pplloott _e_x_p_r [""_t_e_x_t""]
              This  is  a  text object which is constructed by using _t_e_x_t as a
              format string for sprintf with an argument of _e_x_p_r.  If _t_e_x_t  is
              omitted  a  format  string  of  ""%%gg"" is 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; _p_i_c does
              only very limited checking of the string.  This is deprecated in
              favour of sspprriinnttff.

       _v_a_r ::== _e_x_p_r
              This syntax resembles variable assignment with == except that _v_a_r
              must already be defined, and _e_x_p_r will be assigned to _v_a_r  with‐
              out  creating  a  variable local to the current block.  (By con‐
              trast, == defines _v_a_r in the current block if it is  not  already
              defined  there,  and then changes the value in the current block
              only.)  For example,
                     ..PPSS
                     xx == 33
                     yy == 33
                     [[
                     xx ::== 55
                     yy == 55
                     ]]
                     pprriinntt xx   yy
                     ..PPEE
              writes
                     5 3
              to the standard error stream.

   EExxpprreessssiioonnss
       The syntax for expressions has been significantly extended.

       _x ^^ _y (exponentiation)
       ssiinn((_x))
       ccooss((_x))
       aattaann22((_y,, _x))
       lloogg((_x)) (base 10)
       eexxpp((_x)) (base 10, i.e. 10^_x)
       ssqqrrtt((_x))
       iinntt((_x))
       rraanndd(()) (return a random number between 0 and 1)
       rraanndd((_x)) (return a random number between 1 and _x; deprecated)
       ssrraanndd((_x)) (set the random number seed)
       mmaaxx((_e_1,, _e_2))
       mmiinn((_e_1,, _e_2))
       !!_e
       _e_1 &&&& _e_2
       _e_1 |||| _e_2
       _e_1 ==== _e_2
       _e_1 !!== _e_2
       _e_1 >>== _e_2
       _e_1 >> _e_2
       _e_1 <<== _e_2
       _e_1 << _e_2
       ""_s_t_r_1"" ==== ""_s_t_r_2""
       ""_s_t_r_1"" !!== ""_s_t_r_2""

       String comparison expressions must be parenthesised in some contexts to
       avoid ambiguity.

   OOtthheerr cchhaannggeess
       A bare expression, _e_x_p_r, is acceptable as an attribute; it  is  equiva‐
       lent to _d_i_r _e_x_p_r, where _d_i_r is the current direction.  For example

              lliinnee 22ii

       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
       _s_c_a_l_e variable to an appropriate value.

       The  maximum  width  and height of the picture are taken from the vari‐
       ables mmaaxxppsswwiidd and mmaaxxppsshhtt.  Initially, these have values 8.5 and 11.

       Scientific notation is allowed for numbers.  For example

              xx == 55ee--22

       Text attributes can be compounded.  For example,

              ""ffoooo"" aabboovvee lljjuusstt

       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 rraadd attribute specifies the radius
       of  the quarter‐circles at each corner.  If no rraadd or ddiiaamm attribute is
       given, a radius of bbooxxrraadd is used.  Initially, bbooxxrraadd has 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 xxssllaanntteedd and
       yyssllaanntteedd attributes specify the x and y offset of the box’s upper right
       corner from its default position.

       The ..PPSS line 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 _p_i_c will
       always scale a picture by the same amount vertically as well  as  hori‐
       zontally.  This is different from DWB 2.0 _p_i_c 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 tteexxttwwiidd; 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 tteexxtthhtt.  Initially, tteexxttwwiidd and tteexxtthhtt have a value of 0.

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

              sspprriinnttff((""_f_o_r_m_a_t"",, _a_r_g,, ...))

       can  also  be used; this will produce the arguments formatted according
       to _f_o_r_m_a_t, which should be a string as described in _p_r_i_n_t_f(3) appropri‐
       ate for the number of arguments supplied.  Only the modifiers “##”, “--”,
       “++”, and “ ” [space]), a minimum field width,  an  optional  precision,
       and the conversion specifiers %%ee, %%EE, %%ff, %%gg, %%GG, and %%%% are supported.

       The  thickness  of  the lines used to draw objects is controlled by the
       lliinneetthhiicckk variable.  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  --cc  option,  this  means  use  the line thickness specified by ..ppss
       lines; in _t_r_o_f_f 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 tthhiicckk[nneessss] attribute.  For example,

              cciirrccllee tthhiicckknneessss 11..55

       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 ssccaallee  variable,
       nor by the width or height given in the ..PPSS line.

       Boxes  (including boxes with rounded corners or slanted sides), circles
       and ellipses can be filled by giving them  an  attribute  of  ffiillll[eedd].
       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  ffiillllvvaall  will 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: oouuttlliinnee[dd]
       sets the color of the outline, sshhaaddeedd the fill color, and  ccoolloo[uu]rr[eedd]
       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
       _p_s_._t_m_a_c  declare  color  names; you can define additional ones with the
       ddeeffccoolloorr request (see _g_r_o_f_f(7)).

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

              ..PPSS
              ffiiggnnaammee == ffoooobbaarr;;
              ......
              ..PPEE

       The picture is then available in the box \\ffoooobbaarr.

       _p_i_c 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 aarrrroowwhheeaadd
       is non‐zero and either TeX mode is enabled or the  --nn  option  has  not
       been  given.  Initially, aarrrroowwhheeaadd has a value of 1.  Solid arrow heads
       are always filled with the current outline color.

       The _t_r_o_f_f output of _p_i_c is device‐independent.  The --TT option is there‐
       fore redundant.  All numbers are taken to be  in  inches;  numbers  are
       never interpreted to be in _t_r_o_f_f machine units.

       Objects  can  have  an  aalliiggnneedd  attribute.  This will only work if the
       postprocessor is _g_r_o_p_s(1) or _g_r_o_p_d_f(1).  Any text  associated  with  an
       object having the aalliiggnneedd attribute 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 _ntthh is allowed, ''_e_x_p_r''tthh is also allowed.  “''tthh“ is a
       single token: no space is allowed between the apostrophe and the  “tthh”.
       For example,

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

CCoonnvveerrssiioonn
       To  obtain a stand‐alone picture from a _p_i_c file, enclose your _p_i_c code
       with ..PPSS and ..PPEE requests; _r_o_f_f configuration commands may be added  at
       the beginning of the file, but no _r_o_f_f text.

       It  is  necessary  to feed this file into _g_r_o_f_f without adding any page
       information, so you must check which ..PPSS and ..PPEE requests are  actually
       called.  For example, the _m_m macro package adds a page number, which is
       very annoying.  At the moment, calling standard _g_r_o_f_f without any macro
       package  works.  Alternatively, you can define your own requests, e.g.,
       to do nothing:

              .de PS
              ..
              .de PE
              ..

       _g_r_o_f_f 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 _g_r_o_f_f option  --TTppss.
       Since  this _p_s‐file lacks BoundingBox information it is not very useful
       by itself, but it may be fed into other  conversion  programs,  usually
       named  ppss22_o_t_h_e_r or ppssttoo_o_t_h_e_r or the like.  Moreover, the PostScript in‐
       terpreter Ghostscript (_g_s(1)) has built‐in graphics conversion  devices
       that are called with the option

              ggss --ssDDEEVVIICCEE==_<_d_e_v_n_a_m_e_>

       Call

              ggss ----hheellpp

       for a list of the available devices.

       An  alternative  may be to use the --TTppddff option to convert your picture
       directly into PPDDFF format.  The MediaBox of the  file  produced  can  be
       controlled by passing a --PP--pp papersize to _g_r_o_f_f.

       As the Encapsulated PostScript File Format EEPPSS is 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
       _p_s_2_e_p_s  which  does  the  right  job.   It is much better than the tool
       _p_s_2_e_p_s_i packaged with _g_s.

       For bitmapped graphic formats, you should use  _p_s_t_o_p_n_m;  the  resulting
       (intermediate)  _p_n_m(5)  file  can  be  then  converted to virtually any
       graphics format using the tools of the nneettppbbmm package.

FFiilleess
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_p_i_c_._t_m_a_c
              offers simple definitions of the PPSS, PPEE, PPFF, and PPYY macros.

BBuuggss
       Characters that are invalid as input to GNU _t_r_o_f_f (see the  _g_r_o_f_f  Tex‐
       info manual or _g_r_o_f_f___c_h_a_r(7) for a list) are rejected even in TeX mode.

       The  interpretation  of  ffiillllvvaall  is incompatible with the _p_i_c in Tenth
       Edition Research Unix, which interprets 0 as black and 1 as white.

SSeeee aallssoo
       _/_u_s_r_/_s_h_a_r_e_/_d_o_c_/_g_r_o_f_f_-_b_a_s_e_/_p_i_c_._p_s_._g_z
              “Making Pictures with GNU pic”, by Eric S. Raymond.  This  file,
              together with its source, _p_i_c_._m_s, is part of the _g_r_o_f_f 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

       _p_s_2_e_p_s  is  available  from  CTAN  mirrors,  e.g.,  ftp://ftp.dante.de/
       tex-archive/support/ps2eps/

       W. Richard Stevens, _T_u_r_n_i_n_g _P_I_C _i_n_t_o _H_T_M_L

       W. Richard Stevens, _E_x_a_m_p_l_e_s _o_f pic _M_a_c_r_o_s

       _t_r_o_f_f(1),   _g_r_o_f_f___o_u_t(5),   _t_e_x(1),   _g_s(1),   _p_s_2_e_p_s(1),   _p_s_t_o_p_n_m(1),
       _p_s_2_e_p_s_i(1), _p_n_m(5)

groff 1.23.0                      3 June 2025                           _p_i_c(1)
───────────────────────────────────────────────────────────────────────────────
_p_i_c_2_g_r_a_p_h(1)                General Commands Manual               _p_i_c_2_g_r_a_p_h(1)

NNaammee
       pic2graph - convert a _p_i_c diagram into a cropped image

SSyynnooppssiiss
       ppiicc22ggrraapphh [--uunnssaaffee] [--ffoorrmmaatt _o_u_t_p_u_t_‐_f_o_r_m_a_t] [--eeqqnn _d_e_l_i_m_i_t_e_r_s] [_c_o_n_v_e_r_t_‐
                 _a_r_g_u_m_e_n_t ...]

       ppiicc22ggrraapphh ----hheellpp

       ppiicc22ggrraapphh --vv
       ppiicc22ggrraapphh ----vveerrssiioonn

DDeessccrriippttiioonn
       _p_i_c_2_g_r_a_p_h  reads a _p_i_c(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 _e_q_n(1) constructs, so
       it can be used for generating images of mathematical formulae.

       The input PIC code should _n_o_t be  wrapped  with  the  ..PPSS  and  ..PPEE/..PPFF
       macros that normally guard it within _g_r_o_f_f(1) documents.

       Arguments  not recognized by _p_i_c_2_g_r_a_p_h are passed to the ImageMagick or
       GraphicsMagick program _c_o_n_v_e_r_t(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 _c_o_n_v_e_r_t’s --ttrriimm option to the  small‐
       est possible bounding box that contains all the black pixels.

OOppttiioonnss
       ----hheellpp  displays  a  usage message, while --vv and ----vveerrssiioonn show version
       information; all exit afterward.

       --eeqqnn _d_e_l_i_m_i_t_e_r_s
              Use _d_e_l_i_m_i_t_e_r_s as the opening and closing  characters  that  de‐
              limit  _e_q_n directives; the default is “$$”.  The option argument
              _d_e_l_i_m_i_t_e_r_s should be a two‐character string, but an empty string
              ("") is accepted as a directive to disable _e_q_n processing.

       --ffoorrmmaatt _o_u_t_p_u_t_‐_f_o_r_m_a_t
              Write the image in _o_u_t_p_u_t_‐_f_o_r_m_a_t, which must  be  understood  by
              _c_o_n_v_e_r_t; the default is PNG.

       --uunnssaaffee
              Run _g_r_o_f_f in _u_n_s_a_f_e mode, enabling the PIC command sshh to execute
              arbitrary  Unix  shell commands.  The _g_r_o_f_f default is to forbid
              this.

EEnnvviirroonnmmeenntt
       _G_R_O_F_F___T_M_P_D_I_R
       _T_M_P_D_I_R
       _T_M_P
       _T_E_M_P   These environment variables are searched in the given  order  to
              determine  the  directory where temporary files will be created.
              If none are set, _/_t_m_p is used.

AAuutthhoorrss
       _p_i_c_2_g_r_a_p_h was written by Eric S. Raymond,  based  on  a  recipe  by  W.
       Richard Stevens.

SSeeee aallssoo
       W. Richard Stevens, _T_u_r_n_i_n_g _P_I_C _i_n_t_o _H_T_M_L

       _e_q_n_2_g_r_a_p_h(1), _g_r_a_p_2_g_r_a_p_h(1), _p_i_c(1), _e_q_n(1), _g_r_o_f_f(1), _c_o_n_v_e_r_t(1)

groff 1.23.0                      3 June 2025                     _p_i_c_2_g_r_a_p_h(1)
───────────────────────────────────────────────────────────────────────────────
_p_r_e_c_o_n_v(1)                  General Commands Manual                 _p_r_e_c_o_n_v(1)

NNaammee
       preconv - prepare files for typesetting with _g_r_o_f_f

SSyynnooppssiiss
       pprreeccoonnvv [--ddrr] [--DD _f_a_l_l_b_a_c_k_‐_e_n_c_o_d_i_n_g] [--ee _e_n_c_o_d_i_n_g] [_f_i_l_e ...]

       pprreeccoonnvv --hh
       pprreeccoonnvv ----hheellpp

       pprreeccoonnvv --vv
       pprreeccoonnvv ----vveerrssiioonn

DDeessccrriippttiioonn
       _p_r_e_c_o_n_v  reads  each  _f_i_l_e,  converts  its encoded characters to a form
       _t_r_o_f_f(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 _g_r_o_f_f special character form “\\[[uu_X_X_X_X]]”, where _X_X_X_X is  a
       hexadecimal  number  of  four  to six digits corresponding to a Unicode
       code point.  By default, _p_r_e_c_o_n_v also inserts a _r_o_f_f ..llff request at the
       beginning of each _f_i_l_e, identifying it for the benefit  of  later  pro‐
       cessing  (including diagnostic messages); the --rr option suppresses this
       behavior.

       In typical usage scenarios, _p_r_e_c_o_n_v need not be run  directly;  instead
       it  should  be  invoked with the --kk or --KK options of _g_r_o_f_f.  If no _f_i_l_e
       operands are given on the command line, or if _f_i_l_e is “--”, the standard
       input stream is read.

       _p_r_e_c_o_n_v 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 --ee,
           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 _u_c_h_a_r_d_e_t library is
           available on the system, use it to try to infer the encoding of the
           file.

       5.  If the --DD option specifies an encoding, use it.

       6.  Use the encoding specified by the current locale (_L_C___C_T_Y_P_E), unless
           the locale is “C”, “POSIX”, or empty, in which case assume  Latin‐1
           (ISO 8859‐1).

       The  coding tag and _u_c_h_a_r_d_e_t methods in the above procedure rely upon a
       seekable input stream; when _p_r_e_c_o_n_v 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 _p_r_e_c_o_n_v’s --DD or --ee options, or
       by  configuring  your  locale  appropriately.   _g_r_o_f_f  also  supports a
       _G_R_O_F_F___E_N_C_O_D_I_N_G environment variable, which can be overridden by its  --KK
       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 _i_c_o_n_v library support.

   CCooddiinngg ttaaggss
       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,  _p_r_e_c_o_n_v  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”.

       _p_r_e_c_o_n_v interprets the following syntax if it occurs in a _r_o_f_f  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.
              --**-- [...;;] ccooddiinngg:: _e_n_c_o_d_i_n_g[;; ...] --**--

       The  only  variable  _p_r_e_c_o_n_v interprets is “coding”, which can take the
       values listed below.

       The following list comprises all MIME “charset” parameter values recog‐
       nized, case‐insensitively, by _p_r_e_c_o_n_v.
              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.

   _ii_cc_oo_nn_vv ssuuppppoorrtt
       While _p_r_e_c_o_n_v 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 _i_c_o_n_v support is configured at compile time
       and available at run time, all others are passed to _i_c_o_n_v library func‐
       tions, which may recognize many additional encoding strings.  The  com‐
       mand “pprreeccoonnvv --vv” discloses whether _i_c_o_n_v support is configured.

       The use of _i_c_o_n_v 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,
       _u_c_h_a_r_d_e_t fails to detect an encoding (though the library on your system
       may behave differently) and _p_r_e_c_o_n_v 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 _i_c_o_n_v.  In the last, it is correctly detected and mapped.

   LLiimmiittaattiioonnss
       _p_r_e_c_o_n_v cannot perform any transformation on input that it cannot  see.
       Examples  include files that are interpolated by preprocessors that run
       subsequently, including  _s_o_e_l_i_m(1);  files  included  by  _t_r_o_f_f  itself
       through  “ssoo”  and  similar  requests; and string definitions passed to
       _t_r_o_f_f through its --dd command‐line option.

       _p_r_e_c_o_n_v assumes that its input uses the  default  escape  character,  a
       backslash \\, and writes special character escape sequences accordingly.

OOppttiioonnss
       --hh and ----hheellpp display a usage message, while --vv and ----vveerrssiioonn show ver‐
       sion information; all exit afterward.

       --dd     Emit debugging messages to the standard error stream.

       --DD _f_a_l_l_b_a_c_k_‐_e_n_c_o_d_i_n_g
              Report _f_a_l_l_b_a_c_k_‐_e_n_c_o_d_i_n_g if all detection methods fail.

       --ee _e_n_c_o_d_i_n_g
              Skip detection and assume _e_n_c_o_d_i_n_g; see _g_r_o_f_f’s --KK option.

       --rr     Write files “raw”; do not add ..llff requests.

SSeeee aallssoo
       _g_r_o_f_f(1), _i_c_o_n_v(3), _l_o_c_a_l_e(7)

groff 1.23.0                      3 June 2025                       _p_r_e_c_o_n_v(1)
───────────────────────────────────────────────────────────────────────────────
_r_e_f_e_r(1)                    General Commands Manual                   _r_e_f_e_r(1)

NNaammee
       refer - process bibliographic references for _g_r_o_f_f

SSyynnooppssiiss
       rreeffeerr [--bbCCeennPPRRSS] [--aa _n] [--BB _f_i_e_l_d.._m_a_c_r_o] [--cc _f_i_e_l_d_s] [--ff _n] [--ii _f_i_e_l_d_s]
             [--kk _f_i_e_l_d] [--ll _r_a_n_g_e_‐_e_x_p_r_e_s_s_i_o_n] [--pp _d_a_t_a_b_a_s_e_‐_f_i_l_e] [--ss _f_i_e_l_d_s]
             [--tt _n] [_f_i_l_e ...]

       rreeffeerr ----hheellpp

       rreeffeerr --vv
       rreeffeerr ----vveerrssiioonn

DDeessccrriippttiioonn
       The  GNU  implementation of _r_e_f_e_r is part of the _g_r_o_f_f(1) document for‐
       matting system.  _r_e_f_e_r is a _t_r_o_f_f(1) preprocessor that prepares bibilo‐
       graphic citations by looking up keywords specified in a  _r_o_f_f(7)  input
       document,  obviating  the need to type such annotations, and permitting
       the citation style in formatted output to be altered independently  and
       systematically.   It  copies  the contents of each _f_i_l_e to the standard
       output stream, except that it interprets lines between ..[[ and ..]] as ci‐
       tations to be translated into _g_r_o_f_f input, and lines  between  ..RR11  and
       ..RR22  as instructions regarding how citations are to be processed.  Nor‐
       mally, _r_e_f_e_r is not executed directly by the user, but invoked by spec‐
       ifying the --RR option to _g_r_o_f_f(1).  If no _f_i_l_e operands are given on the
       command line, or if _f_i_l_e is “--”, 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,  _r_e_f_e_r  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
       _g_r_o_f_f(7) language commands that can be used by a macro package to  pro‐
       duce a formatted reference for each citation.  The output of _r_e_f_e_r must
       therefore  be processed using a suitable macro package, such as _m_e, _m_m,
       _m_o_m, or _m_s.  The commands to format a citation’s reference can be  out‐
       put  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 ..RR11 and ..RR22 as  prepreocessor  com‐
       mands  is a feature of GNU _r_e_f_e_r.  Documents making use of this feature
       can still be processed by AT&T _r_e_f_e_r just by adding the lines
              .de R1
              .ig R2
              ..
       to the beginning of the document.  This will cause _t_r_o_f_f(1)  to  ignore
       everything  between  ..RR11 and ..RR22.  The effect of some commands can also
       be achieved by options.  These options are supported mainly for compat‐
       ibility with AT&T _r_e_f_e_r.  It is usually more  convenient  to  use  com‐
       mands.

       _r_e_f_e_r  generates  ..llff  requests  so that file names and line numbers in
       messages produced by commands that read _r_e_f_e_r output will  be  correct;
       it also interprets lines beginning with ..llff so that file names and line
       numbers in the messages and ..llff lines that it produces will be accurate
       even if the input has been preprocessed by a command such as _s_o_e_l_i_m(1).

   BBiibblliiooggrraapphhiicc ddaattaabbaasseess
       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 %% at the beginning of a line.  Each field has a  one  character  name
       that immediately follows the %%.  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:

       %%AA     The  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 %%AA field.  The order is
              significant.   It is a good idea always to supply an %%AA field or
              a %%QQ field.

       %%BB     For an article that is part of a book, the title of the book.

       %%CC     The place (city) of publication.

       %%DD     The 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 %%DD field; if the
              date  is  unknown,  a  value  such as iinn pprreessss or uunnkknnoowwnn can be
              used.

       %%EE     For 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 %%AA fields  and  “,,  ((eedd..))”  or
              “,, ((eeddss..))” should be appended to the last author.

       %%GG     U.S. government ordering number.

       %%II     The publisher (issuer).

       %%JJ     For an article in a journal, the name of the journal.

       %%KK     Keywords to be used for searching.

       %%LL     Label.

       %%NN     Journal issue number.

       %%OO     Other  information.   This  is usually printed at the end of the
              reference.

       %%PP     Page number.  A range of pages can be specified as _m--_n.

       %%QQ     The name of the author, if the author is  not  a  person.   This
              will  only be used if there are no %%AA fields.  There can only be
              one %%QQ field.

       %%RR     Technical report number.

       %%SS     Series name.

       %%TT     Title.  For an article in a book or journal, this should be  the
              title of the article.

       %%VV     Volume number of the journal or book.

       %%XX     Annotation.

       For  all  fields except %%AA and %%EE, 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 _m_s document must call the ..AAMM macro when it
       initializes.  Accent strings should not be quoted:  use  one  \\  rather
       than  two.   Accent strings are an obsolescent feature of the _m_e and _m_s
       macro packages; modern documents should use _g_r_o_f_f special character es‐
       cape sequences instead; see _g_r_o_f_f___c_h_a_r(7).

   CCiittaattiioonnss
       Citations have a characteristic format.
              ..[[_o_p_e_n_i_n_g_‐_t_e_x_t
              _f_l_a_g_s _k_e_y_w_o_r_d_s
              _f_i_e_l_d_s
              ..]]_c_l_o_s_i_n_g_‐_t_e_x_t

       The _o_p_e_n_i_n_g_‐_t_e_x_t, _c_l_o_s_i_n_g_‐_t_e_x_t,  and  _f_l_a_g_s  components  are  optional.
       Only one of the _k_e_y_w_o_r_d_s and _f_i_e_l_d_s components need be specified.

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

       The _f_i_e_l_d_s components specifies additional fields to replace or supple‐
       ment those specified in the reference.  When references are being accu‐
       mulated and the _k_e_y_w_o_r_d_s 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 _o_p_e_n_i_n_g_‐_t_e_x_t and _c_l_o_s_i_n_g_‐_t_e_x_t components specify strings to be used
       to bracket the label instead of those in the bbrraacckkeett--llaabbeell command.  If
       either of these components is non‐empty, the strings specified  in  the
       bbrraacckkeett--llaabbeell  command  will  not be used; this behavior can be altered
       using the [[ and ]] flags.  Leading and trailing spaces  are  significant
       for these components.

       The  _f_l_a_g_s  component  is a list of non‐alphanumeric characters each of
       which modifies the treatment of this particular citation.   AT&T  _r_e_f_e_r
       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.

       ##      Use  the  label specified by the sshhoorrtt--llaabbeell command, instead of
              that specified by the llaabbeell command.  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 “##”  is  supposed
              to be suggestive of a numeric type of label.

       [[      Precede  _o_p_e_n_i_n_g_‐_t_e_x_t  with  the  first  string specified in the
              bbrraacckkeett--llaabbeell command.

       ]]      Follow _c_l_o_s_i_n_g_‐_t_e_x_t with the  second  string  specified  in  the
              bbrraacckkeett--llaabbeell command.

       An  advantage  of  using  the  [[  and ]] flags rather than including the
       brackets in _o_p_e_n_i_n_g_‐_t_e_x_t and _c_l_o_s_i_n_g_‐_t_e_x_t is that you  can  change  the
       style   of   bracket   used  in  the  document  just  by  changing  the
       bbrraacckkeett--llaabbeell command.  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 ..[[ line.  If there is no such line,  then  an  extra
       line will be inserted before the ..[[ line 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 <<>> la‐
       bel    expression,    and    of    the     ssoorrtt--aaddjjaacceenntt--llaabbeellss     and
       aabbbbrreevviiaattee--llaabbeell--rraannggeess  commands.   A  label will not be merged if its
       citation has a non‐empty _o_p_e_n_i_n_g_‐_t_e_x_t or  _c_l_o_s_i_n_g_‐_t_e_x_t.   However,  the
       labels for a citation using the ]] flag and without any _c_l_o_s_i_n_g_‐_t_e_x_t im‐
       mediately followed by a citation using the [[ flag and without any _o_p_e_n_‐
       _i_n_g_‐_t_e_x_t  may  be  sorted  and  merged even though the first citation’s
       _o_p_e_n_i_n_g_‐_t_e_x_t or the second citation’s _c_l_o_s_i_n_g_‐_t_e_x_t is  non‐empty.   (If
       you wish to prevent this, use the dummy character escape sequence \\&& as
       the first citation’s _c_l_o_s_i_n_g_‐_t_e_x_t.)

   CCoommmmaannddss
       Commands are contained between lines starting with ..RR11 and ..RR22.  Recog‐
       nition  of  these  lines can be prevented by the --RR option.  When a ..RR11
       line is recognized any accumulated references are flushed out.  Neither
       ..RR11 nor ..RR22 lines, nor anything between them, is output.

       Commands are separated by newlines or semicolons.  A  number  sign  (##)
       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 ("") 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 “\\”; this works every‐
       where except after a number sign.

       Each command _n_a_m_e that is marked with * has an associated negative com‐
       mand nnoo--_n_a_m_e that undoes the effect of _n_a_m_e.  For example, the  nnoo--ssoorrtt
       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; _f_i_e_l_d
       is used for a single upper or lower case letter naming a field;  _f_i_e_l_d_s
       is used for a sequence of such letters; _m and _n are used for a non‐neg‐
       ative numbers; _s_t_r_i_n_g is used for an arbitrary string; _f_i_l_e is used for
       the name of a file.

       aabbbbrreevviiaattee* _f_i_e_l_d_s _s_t_r_i_n_g_1 _s_t_r_i_n_g_2 _s_t_r_i_n_g_3 _s_t_r_i_n_g_4
              Abbreviate the first names of _f_i_e_l_d_s.  An initial letter will be
              separated  from another initial letter by _s_t_r_i_n_g_1, from the last
              name by _s_t_r_i_n_g_2, and from anything else (such as “von” or  “de”)
              by  _s_t_r_i_n_g_3.  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 _s_t_r_i_n_g_4; 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.

       aabbbbrreevviiaattee--llaabbeell--rraannggeess* _s_t_r_i_n_g
              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 _s_t_r_i_n_g, followed by the last  label.   This  is
              mainly useful with numeric labels.  If _s_t_r_i_n_g is omitted, it de‐
              faults to “--”.

       aaccccuummuullaattee*
              Accumulate  references  instead of writing out each reference as
              it is encountered.  Accumulated references will be  written  out
              whenever a reference of the form
                     ..[[
                     $$LLIISSTT$$
                     ..]]
              is  encountered,  after all input files have been processed, and
              whenever a ..RR11 line is recognized.

       aannnnoottaattee* _f_i_e_l_d _s_t_r_i_n_g
              _f_i_e_l_d is an annotation; print it at the end of the reference  as
              a paragraph preceded by the line

                     .._s_t_r_i_n_g

              If  _s_t_r_i_n_g  is  omitted, it will default to AAPP; if _f_i_e_l_d is also
              omitted it will default to XX.  Only one field can be an  annota‐
              tion.

       aarrttiicclleess _s_t_r_i_n_g ...
              Each  _s_t_r_i_n_g  is a definite or indefinite article, and should be
              ignored at the beginning of TT fields when  sorting.   Initially,
              “a”, “an”, and “the” are recognized as articles.

       bbiibblliiooggrraapphhyy _f_i_l_e ...
              Write  out  all  the  references contained in each bibliographic
              database _f_i_l_e.  This command should  come  last  in  an  ..RR11/..RR22
              block.

       bbrraacckkeett--llaabbeell _s_t_r_i_n_g_1 _s_t_r_i_n_g_2 _s_t_r_i_n_g_3
              In  the  text,  bracket each label with _s_t_r_i_n_g_1 and _s_t_r_i_n_g_2.  An
              occurrence of _s_t_r_i_n_g_2 immediately followed by  _s_t_r_i_n_g_1  will  be
              turned into _s_t_r_i_n_g_3.  The default behavior is as follows.
                     bbrraacckkeett--llaabbeell \\**(([[.. \\**((..]] "",, ""

       ccaappiittaalliizzee _f_i_e_l_d_s
              Convert _f_i_e_l_d_s to caps and small caps.

       ccoommppaattiibbllee*
              Recognize  ..RR11  and  ..RR22 even when followed by a character other
              than space or newline.

       ddaattaabbaassee _f_i_l_e ...
              Search each bibliographic database _f_i_l_e.  For each _f_i_l_e,  if  an
              index  file_._i  created  by  _i_n_d_x_b_i_b(1)  exists,  then it will be
              searched instead; each index can cover multiple databases.

       ddaattee--aass--llaabbeell* _s_t_r_i_n_g
              _s_t_r_i_n_g is a label expression that specifies a string with  which
              to  replace  the DD field 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
              nnoo--llaabbeell--iinn--rreeffeerreennccee command.  For example,
                     ddaattee--aass--llaabbeell DD..++yyDD..yy%%aa**DD..--yy
              would  attach  a disambiguating letter to the year part of the DD
              field in the reference.

       ddeeffaauulltt--ddaattaabbaassee*
              The default database should be searched.  This  is  the  default
              behavior,  so  the negative version of this command is more use‐
              ful.  _r_e_f_e_r determines whether the default  database  should  be
              searched  on  the  first  occasion that it needs to do a search.
              Thus a nnoo--ddeeffaauulltt--ddaattaabbaassee command must be given before then, in
              order to be effective.

       ddiissccaarrdd* _f_i_e_l_d_s
              When the reference is  read,  _f_i_e_l_d_s  should  be  discarded;  no
              string definitions for _f_i_e_l_d_s will be output.  Initially, _f_i_e_l_d_s
              are XXYYZZ.

       eett--aall* _s_t_r_i_n_g _m _n
              Control  use of eett aall.. in the evaluation of @@ expressions in la‐
              bel expressions.  If the number of authors needed  to  make  the
              author sequence unambiguous is _u and the total number of authors
              is  _t  then the last _t-_u authors will be replaced by _s_t_r_i_n_g pro‐
              vided that _t-_u is not less than _m and _t is not less than _n.  The
              default behavior is as follows.
                     eett--aall "" eett aall"" 22 33
              Note the absence of a dot from  the  end  of  the  abbreviation,
              which is arguably not correct.  (_E_t _a_l[.]  is short for _e_t _a_l_l_i,
              as _e_t_c_. is short for _e_t _c_e_t_e_r_a.)

       iinncclluuddee _f_i_l_e
              Include _f_i_l_e and interpret the contents as commands.

       jjooiinn--aauutthhoorrss _s_t_r_i_n_g_1 _s_t_r_i_n_g_2 _s_t_r_i_n_g_3
              Join multiple authors together with _s_t_r_i_n_gs.  When there are ex‐
              actly two authors, they will be joined with _s_t_r_i_n_g_1.  When there
              are  more  than two authors, all but the last two will be joined
              with _s_t_r_i_n_g_2, and the last  two  authors  will  be  joined  with
              _s_t_r_i_n_g_3.   If _s_t_r_i_n_g_3 is omitted, it will default to _s_t_r_i_n_g_1; if
              _s_t_r_i_n_g_2 is also omitted it will also default  to  _s_t_r_i_n_g_1.   For
              example,
                     join-authors " and " ", " ", and "
              will restore the default method for joining authors.

       llaabbeell--iinn--rreeffeerreennccee*
              When  outputting  the  reference, define the string [[FF to be the
              reference’s label.  This is the default behavior, so  the  nega‐
              tive version of this command is more useful.

       llaabbeell--iinn--tteexxtt*
              For  each  reference output a label in the text.  The label will
              be separated from the  surrounding  text  as  described  in  the
              bbrraacckkeett--llaabbeell  command.   This  is  the default behavior, so the
              negative version of this command is more useful.

       llaabbeell _s_t_r_i_n_g
              _s_t_r_i_n_g is a label expression describing how to label each refer‐
              ence.

       sseeppaarraattee--llaabbeell--sseeccoonndd--ppaarrttss _s_t_r_i_n_g
              When merging two‐part labels, separate the second  part  of  the
              second label from the first label with _s_t_r_i_n_g.  See the descrip‐
              tion of the <<>> label expression.

       mmoovvee--ppuunnccttuuaattiioonn*
              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.

       rreevveerrssee* _s_t_r_i_n_g
              Reverse  the  fields whose names are in _s_t_r_i_n_g.  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.

       sseeaarrcchh--iiggnnoorree* _f_i_e_l_d_s
              While searching for keys in databases for which no index exists,
              ignore  the  contents  of _f_i_e_l_d_s.  Initially, fields XXYYZZ are ig‐
              nored.

       sseeaarrcchh--ttrruunnccaattee* _n
              Only require the first _n 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 _n and the length of the key.  Ini‐
              tially, _n is 6.

       sshhoorrtt--llaabbeell* _s_t_r_i_n_g
              _s_t_r_i_n_g is a label expression that specifies an alternative (usu‐
              ally shorter) style of label.  This is used when the ##  flag  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 sshhoorrtt--llaabbeell command will typically be
              used  to  specify  a label containing just a date and possibly a
              disambiguating letter.

       ssoorrtt* _s_t_r_i_n_g
              Sort references according to _s_t_r_i_n_g.  References will  automati‐
              cally  be  accumulated.  _s_t_r_i_n_g should be a list of field names,
              each followed by a number, indicating how many fields  with  the
              name  should  be  used for sorting.  “++” can be used to indicate
              that all the fields with the name should be used.  Also .. can 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.)

       ssoorrtt--aaddjjaacceenntt--llaabbeellss*
              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 aabbbbrreevviiaattee--llaabbeell--rraannggeess command has been given,  or
              if  the  label  expression  contains a <<>> expression.  This will
              have no effect unless references are being accumulated.

   LLaabbeell eexxpprreessssiioonnss
       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 _t_e_n_t_a_t_i_v_e _l_a_b_e_l, is used to gather the  in‐
       formation  that normal evaluation needs to disambiguate the label.  La‐
       bel expressions specified by the ddaattee--aass--llaabbeell and sshhoorrtt--llaabbeell commands
       are not evaluated tentatively.  Normal and tentative evaluation are the
       same for all types of expression other than @@, **,  and  %%  expressions.
       The description below applies to normal evaluation, except where other‐
       wise specified.

       _f_i_e_l_d
       _f_i_e_l_d _n
              The _n‐th part of _f_i_e_l_d.  If _n is omitted, it defaults to 1.

       ''_s_t_r_i_n_g''
              The characters in _s_t_r_i_n_g literally.

       @@      All the authors joined as specified by the jjooiinn--aauutthhoorrss command.
              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 “AA++”), 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 _i‐th author of some
              reference is considered to be ambiguous if there is  some  other
              reference, such that the first _i-1 authors of the references are
              the  same,  the  _i‐th authors are not the same, but the _i‐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
              eett--aall command; this command may also specify additional require‐
              ments  that  must  be  met  before an initial subsequence can be
              used.  @@ tentatively evaluates to a canonical representation  of
              the  authors, such that authors that compare equally for sorting
              purpose will have the same representation.

       %%_n
       %%aa
       %%AA
       %%ii
       %%II     The serial number of the reference formatted  according  to  the
              character  following  the  %%.   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.

       _e_x_p_r**  If  there  is another reference with the same tentative label as
              this reference, then _e_x_p_r, otherwise an empty string.  It tenta‐
              tively evaluates to an empty string.

       _e_x_p_r++_n
       _e_x_p_r--_n The first (++) or last (--) _n upper or lower case letters or  dig‐
              its  of _e_x_p_r.  _r_o_f_f special characters (such as \\((''aa) count as a
              single letter.  Accent strings are retained but do not count to‐
              wards the total.

       _e_x_p_r..ll _e_x_p_r converted to lowercase.

       _e_x_p_r..uu _e_x_p_r converted to uppercase.

       _e_x_p_r..cc _e_x_p_r converted to caps and small caps.

       _e_x_p_r..rr _e_x_p_r reversed so that the last name is first.

       _e_x_p_r..aa _e_x_p_r with first names  abbreviated.   Fields  specified  in  the
              aabbbbrreevviiaattee  command are abbreviated before any labels are evalu‐
              ated.  Thus ..aa is useful only when you want a field to be abbre‐
              viated in a label but not in a reference.

       _e_x_p_r..yy The year part of _e_x_p_r.

       _e_x_p_r..++yy
              The part of _e_x_p_r before the year, or the whole  of  _e_x_p_r  if  it
              does not contain a year.

       _e_x_p_r..--yy
              The part of _e_x_p_r after the year, or an empty string if _e_x_p_r does
              not contain a year.

       _e_x_p_r..nn The last name part of _e_x_p_r.

       _e_x_p_r_1~~_e_x_p_r_2
              _e_x_p_r_1  except  that  if the last character of _e_x_p_r_1 is -- then it
              will be replaced by _e_x_p_r_2.

       _e_x_p_r_1 _e_x_p_r_2
              The concatenation of _e_x_p_r_1 and _e_x_p_r_2.

       _e_x_p_r_1||_e_x_p_r_2
              If _e_x_p_r_1 is non‐empty then _e_x_p_r_1 otherwise _e_x_p_r_2.

       _e_x_p_r_1&&_e_x_p_r_2
              If _e_x_p_r_1 is non‐empty then _e_x_p_r_2 otherwise an empty string.

       _e_x_p_r_1??_e_x_p_r_2::_e_x_p_r_3
              If _e_x_p_r_1 is non‐empty then _e_x_p_r_2 otherwise _e_x_p_r_3.

       <<_e_x_p_r>> The label is in two parts, which are separated by _e_x_p_r.  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
              sseeppaarraattee--llaabbeell--sseeccoonndd--ppaarrttss command (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 sshhoorrtt--llaabbeell command.

       ((_e_x_p_r)) The same as _e_x_p_r.  Used for grouping.

       The above expressions  are  listed  in  order  of  precedence  (highest
       first); && and || have the same precedence.

   MMaaccrroo iinntteerrffaaccee
       Each  reference starts with a call to the macro ]]--.  The string [[FF will
       be  defined  to  be  the  label  for   this   reference,   unless   the
       nnoo--llaabbeell--iinn--rreeffeerreennccee command has been given.  There then follows a se‐
       ries  of  string definitions, one for each field: string [[_X corresponds
       to field _X.  The register [[PP is set to 1 if  the  PP  field  contains  a
       range  of pages.  The [[TT, [[AA and [[OO registers are set to 1 according as
       the TT, AA and OO fields end with any of ..??!! (an  end‐of‐sentence  charac‐
       ter).   The [[EE register will be set to 1 if the [[EE string contains more
       than one name.  The reference is followed by a call to  the  ]][[  macro.
       The  first  argument to this macro gives a number representing the type
       of the reference.  If a reference contains a JJ field, it will be  clas‐
       sified  as  type  1,  otherwise  if  it  contains a BB field, it will be
       type 3, otherwise if it contains a GG or RR field it will be type 4, oth‐
       erwise if it contains an II field it will be type 2, otherwise  it  will
       be type 0.  The second argument is a symbolic name for the type: ootthheerr,
       jjoouurrnnaall--aarrttiiccllee, bbooookk, aarrttiiccllee--iinn--bbooookk, or tteecchh--rreeppoorrtt.  Groups of ref‐
       erences  that have been accumulated or are produced by the bbiibblliiooggrraapphhyy
       command are preceded by a call to the ]]<< macro and followed by  a  call
       to the ]]>> macro.

OOppttiioonnss
       ----hheellpp  displays  a  usage message, while --vv and ----vveerrssiioonn show version
       information; all exit afterward.

       --RR     Don’t recognize lines beginning with ..RR11/..RR22.

       Other options are equivalent to _r_e_f_e_r commands.

       --aa _n            rreevveerrssee AA_n

       --bb              nnoo--llaabbeell--iinn--tteexxtt;; nnoo--llaabbeell--iinn--rreeffeerreennccee

       --BB              See below.

       --cc _f_i_e_l_d_s       ccaappiittaalliizzee _f_i_e_l_d_s

       --CC              ccoommppaattiibbllee

       --ee              aaccccuummuullaattee

       --ff _n            llaabbeell %%_n

       --ii _f_i_e_l_d_s       sseeaarrcchh--iiggnnoorree _f_i_e_l_d_s

       --kk              llaabbeell LL~~%%aa

       --kk _f_i_e_l_d        llaabbeell _f_i_e_l_d~~%%aa

       --ll              llaabbeell AA..nnDD..yy%%aa

       --ll _m            llaabbeell AA..nn++_mDD..yy%%aa

       --ll ,,_n           llaabbeell AA..nnDD..yy--_n%%aa

       --ll _m,,_n          llaabbeell AA..nn++_mDD..yy--_n%%aa

       --nn              nnoo--ddeeffaauulltt--ddaattaabbaassee

       --pp _d_b_‐_f_i_l_e      ddaattaabbaassee _d_b_‐_f_i_l_e

       --PP              mmoovvee--ppuunnccttuuaattiioonn

       --ss _s_p_e_c         ssoorrtt _s_p_e_c

       --SS              llaabbeell ""((AA..nn||QQ)) '',, '' ((DD..yy||DD))"";; bbrraacckkeett‐‐llaabbeell "" (("" )) "";; ""

       --tt _n            sseeaarrcchh--ttrruunnccaattee _n

       The BB option 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 bbiibblliiooggrraapphhyy command instead of in the normal way.

       --BB              aannnnoottaattee XX AAPP;; nnoo--llaabbeell--iinn--rreeffeerreennccee

       --BB _f_i_e_l_d.._m_a_c_r_o  aannnnoottaattee _f_i_e_l_d _m_a_c_r_o;; nnoo--llaabbeell--iinn--rreeffeerreennccee

EEnnvviirroonnmmeenntt
       _R_E_F_E_R  If set, overrides the default database.

FFiilleess
       _/_u_s_r_/_d_i_c_t_/_p_a_p_e_r_s_/_I_n_d
              Default database.

       file_._i Index files.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_r_e_f_e_r_._t_m_a_c
              defines  macros  and strings facilitating integration with macro
              packages that wish to support _r_e_f_e_r.

       _r_e_f_e_r uses temporary files.  See the _g_r_o_f_f(1) man page for  details  of
       where such files are created.

BBuuggss
       In  label  expressions, <<>> expressions are ignored inside .._c_h_a_r expres‐
       sions.

EExxaammpplleess
       We can illustrate the operation of _r_e_f_e_r with  a  sample  bibliographic
       database  containing  one entry and a simple _r_o_f_f document to cite that
       entry.

              $ ccaatt >> mmyy--ddbb--ffiillee
              %%AA DDaanniieell PP..\\&& FFrriieeddmmaann
              %%AA MMaatttthhiiaass FFeelllleeiisseenn
              %%CC CCaammbbrriiddggee,, MMaassssaacchhuusseettttss
              %%DD 11999966
              %%II TThhee MMIITT PPrreessss
              %%TT TThhee LLiittttllee SScchheemmeerr,, FFoouurrtthh EEddiittiioonn
              $ rreeffeerr ‐‐pp mmyy--ddbb--ffiillee
              RReeaadd tthhee bbooookk
              ..[[
              ffrriieeddmmaann
              ..]]
              oonn yyoouurr ssuummmmeerr vvaaccaattiioonn..
              _<_C_o_n_t_r_o_l_+_D_>
              .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 _r_e_f_e_r (a) produces a label “1”; (b)  brack‐
       ets  that label with interpolations of the “[[..”  and “..]]”  strings; (c)
       calls a macro “]]--”; (d) defines strings and  registers  containing  the
       label and bibliographic data for the reference; (e) calls a macro “]][[”;
       and (f) uses the llff request 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 _g_r_o_f_f___m_s(7) to this task.

              $ RREEFFEERR==mmyy--ddbb--ffiillee ggrrooffff --RR --mmss
              ..LLPP
              RReeaadd tthhee bbooookk
              ..[[
              ffrriieeddmmaann
              ..]]
              oonn yyoouurr ssuummmmeerr vvaaccaattiioonn..
              CCoommmmeennttaarryy iiss aavvaaiillaabbllee..\\**{{**\\**}}
              ..FFSS \\**{{**\\**}}
              SSppaaccee rreesseerrvveedd ffoorr ppeenneettrraattiinngg iinnssiigghhtt..
              ..FFEE

       _m_s’s automatic footnote numbering mechanism is not aware of _r_e_f_e_r’s la‐
       bel numbering, so we have manually specified a (superscripted) symbolic
       footnote for our non‐bibliographic aside.

SSeeee aallssoo
       “Some Applications of Inverted Indexes on the Unix System”,  by  M.  E.
       Lesk,  1978,  AT&T Bell Laboratories Computing Science Technical Report
       No. 69.

       _i_n_d_x_b_i_b(1), _l_o_o_k_b_i_b(1), _l_k_b_i_b(1)

groff 1.23.0                      3 June 2025                         _r_e_f_e_r(1)
───────────────────────────────────────────────────────────────────────────────
_s_o_e_l_i_m(1)                   General Commands Manual                  _s_o_e_l_i_m(1)

NNaammee
       soelim - recursively interpolate source requests in _r_o_f_f or other  text
       files

SSyynnooppssiiss
       ssooeelliimm [--CCrrtt] [--II _d_i_r] [_i_n_p_u_t_‐_f_i_l_e ...]

       ssooeelliimm ----hheellpp

       ssooeelliimm --vv
       ssooeelliimm ----vveerrssiioonn

DDeessccrriippttiioonn
       GNU  _s_o_e_l_i_m is a preprocessor for the _g_r_o_f_f(7) document formatting sys‐
       tem.  _s_o_e_l_i_m works as a filter to eliminate source requests in  _r_o_f_f(7)
       input files; that is, it replaces lines of the form “..ssoo _i_n_c_l_u_d_e_d_‐_f_i_l_e”
       within  each text _i_n_p_u_t_‐_f_i_l_e with the contents of _i_n_c_l_u_d_e_d_‐_f_i_l_e, recur‐
       sively.  By default, it writes llff requests as well to record  the  name
       and line number of each _i_n_p_u_t_‐_f_i_l_e and _i_n_c_l_u_d_e_d_‐_f_i_l_e, so that any diag‐
       nostics  produced  by  later processing can be accurately traced to the
       original input.  Options allow this information to be  suppressed  (--rr)
       or supplied in TeX comments instead (--tt).  In the absence of _i_n_p_u_t_‐_f_i_l_e
       arguments,  _s_o_e_l_i_m  reads the standard input stream.  Output is written
       to the standard output stream.

       If the name of a _m_a_c_r_o_‐_f_i_l_e contains a backslash, use \\\\ or \\ee to embed
       it.  To embed a space, write “\\ ” (backslash followed by a space).  Any
       other escape sequence in _m_a_c_r_o_‐_f_i_l_e, including “\\[[rrss]]”, prevents _s_o_e_l_i_m
       from replacing the source request.

       The dot must be at the beginning of a line and must be followed by “ssoo”
       without intervening spaces or tabs for _s_o_e_l_i_m to handle it.  This  con‐
       vention  allows  source  requests  to be “protected” from processing by
       _s_o_e_l_i_m, for instance as part of macro definitions or “iiff” requests.

       There must also be at least one space between “ssoo” and  its  _m_a_c_r_o_‐_f_i_l_e
       argument.  The --CC option overrides this requirement.

       The  foregoing  is the limit of _s_o_e_l_i_m’s understanding of the _r_o_f_f lan‐
       guage; it does not, for example, replace the input line
              .if 1 .so otherfile
       with the contents of _o_t_h_e_r_f_i_l_e.  With its --rr option, therefore,  _s_o_e_l_i_m
       can  be used to process text files in general, to flatten a tree of in‐
       put documents.

       _s_o_e_l_i_m was designed to handle situations where the  target  of  a  _r_o_f_f
       source   request  requires  a  preprocessor  such  as  _e_q_n(1),  _p_i_c(1),
       _r_e_f_e_r(1), or _t_b_l(1).  The usual processing sequence of _g_r_o_f_f(1)  is  as
       follows.

                 input        sourced
                 file          file
                   ⎪             ⎪
                   ↓             ↓
               preprocessor ⎯→ troff ⎯→ postprocessor
                                             ⎪
                                             ↓
                                          output
                                           file

       That  is, files sourced with “ssoo” are normally read _o_n_l_y by the format‐
       ter, _t_r_o_f_f.  _s_o_e_l_i_m is _n_o_t required for _t_r_o_f_f to source files.

       If a file to be sourced should also be preprocessed, it must already be
       read _b_e_f_o_r_e the input file passes through  the  preprocessor.   _s_o_e_l_i_m,
       normally invoked via _g_r_o_f_f’s --ss option, handles this.

                 input
                 file
                   ⎪
                   ↓
                 soelim ⎯→ preprocessor ⎯→ troff ⎯→ postprocessor
                   ↑                                     ⎪
                   ⎪                                     ↓
                sourced                               output
                 file                                  file

OOppttiioonnss
       ----hheellpp  displays  a  usage message, while --vv and ----vveerrssiioonn show version
       information; all exit afterward.

       --CC     Recognize an input line starting with ..ssoo even  if  a  character
              other than a space or newline follows.

       --II _d_i_r Search the directory _d_i_r path for _i_n_p_u_t_‐ and _i_n_c_l_u_d_e_d_‐_f_i_l_e_s_.  --II
              may  be  specified  more  than once; each _d_i_r is searched in the
              given order.  To search the  current  working  directory  before
              others,  add  “--II  ..”  at  the  desired  place;  it is otherwise
              searched last.

       --rr     Write files “raw”; do not add llff requests.

       --tt     Emit TeX comment lines starting with “%%” indicating the  current
              file  and line number, rather than llff requests for the same pur‐
              pose.

       If both --rr and --tt are given, the last one specified controls.

SSeeee aallssoo
       _g_r_o_f_f(1)

groff 1.23.0                      3 June 2025                        _s_o_e_l_i_m(1)
───────────────────────────────────────────────────────────────────────────────
_t_b_l(1)                      General Commands Manual                     _t_b_l(1)

NNaammee
       tbl - prepare tables for _g_r_o_f_f documents

SSyynnooppssiiss
       ttbbll [--CC] [_f_i_l_e ...]

       ttbbll ----hheellpp

       ttbbll --vv
       ttbbll ----vveerrssiioonn

DDeessccrriippttiioonn
       The GNU implementation of _t_b_l is part of the _g_r_o_f_f(1) document  format‐
       ting  system.   _t_b_l is a _t_r_o_f_f(1) preprocessor that translates descrip‐
       tions of tables embedded in _r_o_f_f(7) input files into the  language  un‐
       derstood by _t_r_o_f_f.  It copies the contents of each _f_i_l_e to the standard
       output stream, except that lines between ..TTSS and ..TTEE are interpreted as
       table  descriptions.  While GNU _t_b_l’s input syntax is highly compatible
       with AT&T _t_b_l, the output GNU _t_b_l produces cannot be processed by  AT&T
       _t_r_o_f_f;  GNU _t_r_o_f_f (or a _t_r_o_f_f implementing any GNU extensions employed)
       must be used.  Normally, _t_b_l is not executed directly by the user,  but
       invoked  by  specifying the --tt option to _g_r_o_f_f(1).  If no _f_i_l_e operands
       are given on the command line, or if _f_i_l_e is “--”, _t_b_l reads  the  stan‐
       dard input stream.

   OOvveerrvviieeww
       _t_b_l  expects  to find table descriptions between input lines that begin
       with ..TTSS (table start) and ..TTEE (table end).  Each such _t_a_b_l_e _r_e_g_i_o_n 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 ..TT&&.  This mechanism does not start a new table  region;
       all  table descriptions are treated as part of their ..TTSS/..TTEE enclosure,
       even if they are boxed or have column headings that  repeat  on  subse‐
       quent pages (see below).

       (Experienced  _r_o_f_f users should observe that _t_b_l is not a _r_o_f_f 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  _t_b_l  input  tokens remain as‐is in the output, where they become
       ordinary macro calls.  Macro packages  often  define  TTSS,  TT&&,  and  TTEE
       macros  to  handle issues of table placement on the page.  _t_b_l produces
       _g_r_o_f_f 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 _r_e_g_i_o_n _o_p_t_i_o_n_s_, and must contain one
       or more _t_a_b_l_e _d_e_f_i_n_i_t_i_o_n_s_; each  table  definition  contains  a  _f_o_r_m_a_t
       _s_p_e_c_i_f_i_c_a_t_i_o_n  followed  by  one or more input lines (rows) of _e_n_t_r_i_e_s_.
       These entries comprise the _t_a_b_l_e _d_a_t_a_.

   RReeggiioonn ooppttiioonnss
       The line immediately following the ..TTSS token  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 (;;).

       Any  of  the  aallllbbooxx, bbooxx, ddoouubblleebbooxx, ffrraammee, and ddoouubblleeffrraammee region op‐
       tions makes a table “boxed” for the purpose of later discussion.

       aallllbbooxx Enclose each table entry in a box; implies bbooxx.

       bbooxx    Enclose the entire table region in a box.  As a  GNU  extension,
              the alternative option name ffrraammee is also recognized.

       cceenntteerr Center  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 cceennttrree is also recognized.

       ddeecciimmaallppooiinntt((_c))
              Recognize  character _c as the decimal separator in columns using
              the NN (numeric) classifier (see subsection “Column  classifiers”
              below).  This is a GNU extension.

       ddeelliimm((_x_y))
              Recognize  characters  _x  and _y as start and end delimiters, re‐
              spectively, for _e_q_n(1) input, and ignore input between them.   _x
              and _y need not be distinct.

       ddoouubblleebbooxx
              Enclose  the  entire  table region in a double box; implies bbooxx.
              As a GNU extension, the alternative option name  ddoouubblleeffrraammee  is
              also recognized.

       eexxppaanndd Spread  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 eexxppaanndd applies to a table
              that exceeds the available horizontal space,  column  separation
              is  reduced  as  far  as necessary (even to zero).  _t_b_l produces
              _g_r_o_f_f input that issues a diagnostic if such compression occurs.
              The column modifier xx (see below) overrides this option.

       lliinneessiizzee((_n))
              Draw lines or  rules  (e.g.,  from  bbooxx)  with  a  thickness  of
              _n  points.  The default is the current type size when the region
              begins.  This option is ignored on terminal devices.

       nnookkeeeepp Don’t use _r_o_f_f diversions to manage page breaks.  Normally,  _t_b_l
              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.

       nnoossppaacceess
              Ignore leading and trailing spaces in table entries.  This is  a
              GNU extension.

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

       ttaabb((_c)) Use  the  character  _c instead of a tab to separate entries in a
              row of table data.

   TTaabbllee ffoorrmmaatt ssppeecciiffiiccaattiioonn
       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 _d_e_s_c_r_i_p_t_o_r_s_.
       Each descriptor encodes a _c_l_a_s_s_i_f_i_e_r followed by  zero  or  more  _m_o_d_i_‐
       _f_i_e_r_s_.   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 _r_o_w
       _d_e_f_i_n_i_t_i_o_n_.   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 _c_l_a_s_s_i_f_i_e_r_, 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 “||”, any  classi‐
       fier  can be followed by one or more _m_o_d_i_f_i_e_r_s_; some of these accept an
       argument, which in GNU _t_b_l  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 “..” 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, “CCbbCCbb,,LLRR..” 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 LL classifiers as many times
       as necessary to make the table rectangular.

   CCoolluummnn ccllaassssiiffiieerrss
       The LL, RR, and CC classifiers are the easiest to understand and use.

       AA, aa   Center 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 LL‐
              classified entries, as in “LLLL,,AARR..”.  The  AA  entries  are  often
              termed “sub‐columns” due to their indentation.

       CC, cc   Center entry within the column.

       LL, ll   Left‐align entry within the column.

       NN, nn   Numerically  align  entry  in the column.  _t_b_l 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,  _t_b_l
              centers  the  entry within the column.  The _r_o_f_f dummy character
              \\&& in 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 NN‐classified entries share a column with LL or RR entries,  _t_b_l
              centers the widest NN entry with respect to the widest LL or RR en‐
              try,  preserving the alignment of NN entries with respect to each
              other.

              The appearance of _e_q_n equations within NN‐classified columns  can
              be  troublesome  due to the foregoing textual scan for a decimal
              separator.  Use the ddeelliimm region option to make _t_b_l  ignore  the
              data within _e_q_n delimiters for that purpose.

       RR, rr   Right‐align entry within the column.

       SS, ss   Span previous entry on the left into this column.

       ^^      Span  entry  in  the same column from the previous row into this
              row.

       __, --   Replace table entry with a horizontal rule.  An empty table  en‐
              try  is  expected  to correspond to this classifier; if data are
              found there, _t_b_l issues a diagnostic message.

       ==      Replace table entry with a double horizontal rule.  An empty ta‐
              ble entry is expected to correspond to this classifier; if  data
              are found there, _t_b_l issues a diagnostic message.

       ||      Place 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 || to 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 _t_b_l region, use the ..TT&& token at
       the start of a line.  It is followed by a format specification and  ta‐
       ble data, but _n_o_t 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 SS horizontal 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.

   CCoolluummnn mmooddiiffiieerrss
       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 xx
       is  mutually  exclusive  with  ee and ww, but ee is not mutually exclusive
       with ww; if these are used in combination, xx unsets both ee and ww,  while
       either ee or ww overrides xx.

       bb, BB   Typeset entry in boldface, abbreviating ff((BB)).

       dd, DD   Align  a  vertically spanned table entry to the bottom (“down”),
              instead of the center, of its range.  This is a GNU extension.

       ee, EE   Equalize 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.

       ff, FF   Select  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 _t_r_o_f_f fftt request.)  A  one‐character  argu‐
              ment  not in parentheses must be separated by one or more spaces
              or tabs from what follows.

       ii, II   Typeset entry in an oblique or italic face, abbreviating ff((II)).

       mm, MM   Call a _g_r_o_f_f 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 _g_r_o_f_f requests to
              change text formatting, like  adjustment  or  hyphenation.   The
              macro  is  called  _a_f_t_e_r  the column modifiers bb, ff, ii, pp, and vv
              take effect; it can thus override other column modifiers.

       pp, PP   Set the type size for the table entry.  This  modifier  must  be
              followed  by an integer _n with an optional leading sign.  If un‐
              signed, the type size is set to _n scaled points.  Otherwise, the
              type size is incremented or decremented per the sign by _n scaled
              points.  The use of a signed multi‐digit number is a GNU  exten‐
              sion.   (The parameter corresponds to that accepted by the _t_r_o_f_f
              ppss request.)  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.

       tt, TT   Align a vertically spanned table entry to the  top,  instead  of
              the center, of its range.

       uu, UU   Move  the  column up one half‐line, “staggering” the rows.  This
              is a GNU extension.

       vv, VV   Set the vertical spacing to be used in a text block.  This modi‐
              fier must be followed by an integer _n with an  optional  leading
              sign.   If  unsigned,  the  vertical spacing is set to _n points.
              Otherwise, the vertical spacing is  incremented  or  decremented
              per  the sign by _n points.  The use of a signed multi‐digit num‐
              ber is a GNU extension.  (This parameter corresponds to that ac‐
              cepted by the _t_r_o_f_f vvss request.)  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.

       ww, WW   Set  the column’s minimum width.  This modifier must be followed
              by a number, which is either a unitless integer, or a _r_o_f_f 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.

       xx, XX   Expand the column.  After computing the column widths,  distrib‐
              ute  any  remaining  line length evenly over all columns bearing
              this modifier.  Applying the xx modifier to more than one  column
              is  a GNU extension.  This modifier sets the default line length
              used in a text block.

       zz, ZZ   Ignore 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.

       _n      A numeric suffix on a column descriptor sets the separation dis‐
              tance (in ens) from the succeeding column; the  default  separa‐
              tion is 33nn.  This separation is proportionally multiplied if the
              eexxppaanndd  region  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 _t_b_l.

   TTaabbllee ddaattaa
       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 ttaabb region 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.  _r_o_f_f 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 \\&& _r_o_f_f dummy character.  The table  data  are  inter‐
       rupted  by  a line consisting of the ..TT&& input token, and conclude with
       the line ..TTEE.

       Ordinarily, a table entry is typeset rigidly.  It is not  filled,  bro‐
       ken,  hyphenated, adjusted, or populated with additional inter‐sentence
       space.  _t_b_l instructs the formatter to measure each table entry  as  it
       occurs  in  the input, updating the width required by its corresponding
       column.  If the zz modifier applies to the column, this  measurement  is
       ignored;  if ww applies and its argument is larger than this width, that
       argument is used instead.   In  contrast  to  conventional  _r_o_f_f  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 (__ or ==), a
         single  or  double  horizontal  rule  (line),  respectively, is drawn
         across the table at that point.

       • A table entry containing only __ or == on 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 \\__ or \\== on an otherwise
         populated row, it is replaced by a single or double horizontal  rule,
         respectively, that does _n_o_t (quite) join its neighbors.

       • A table entry consisting of \\RR_x, where _x is any _r_o_f_f ordinary or spe‐
         cial character, is replaced by enough repetitions of the glyph corre‐
         sponding  to  _x to fill the column, albeit without joining its neigh‐
         bors.

       • On any row but the first, a table entry of \\^^ causes 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 __ or == literally and alone in an entry, prefix  or
       suffix  it with the _r_o_f_f dummy character \\&&.  To express \\__, \\==, or \\RR,
       use a _r_o_f_f escape sequence to interpolate the backslash (\\ee or  \\[[rrss]]).
       A reliable way to emplace the \\^^ glyph sequence within a table entry is
       to use a pair of _g_r_o_f_f special character escape sequences (\\[[rrss]]\\[[hhaa]]).

       Rows  of  table  entries  can  be interleaved with _g_r_o_f_f control lines;
       these do not count as table data.  On such lines  the  default  control
       character  (..)  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 _r_o_f_f dummy character \\&&.

   TTeexxtt bblloocckkss
       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 _t_e_x_t _b_l_o_c_k_.

       _t_b_l interprets a table entry beginning with “TT{{” at the end of an input
       line  not  as  table data, but as a token starting a text block.  Simi‐
       larly, “TT}}” 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 TT{{ and following TT}}).  Input lines be‐
       tween these tokens are formatted in a diversion by _t_r_o_f_f.  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 AA,  CC,
       LL,  NN, RR, and SS determine a text block’s _a_l_i_g_n_m_e_n_t within its cell, but
       not its _a_d_j_u_s_t_m_e_n_t_.  Add nnaa or aadd requests 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 ww or xx modifiers are not specified for _a_l_l 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
       _L×_C/(_N+1),  where _L is the current line length, _C the number of columns
       spanned by the text block, and _N the number of columns  in  the  table.
       If necessary, you can also control a text block’s width by including an
       llll  (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 ddnn and ddll, respec‐
       tively.

   _rr_oo_ff_ff iinntteerrffaaccee
       The register TTWW stores the width of the table region in basic units; it
       can’t be used within the region itself, but is defined before  the  ..TTEE
       token  is output so that a _g_r_o_f_f macro named TTEE can make use of it.  TT..
       is a Boolean‐valued register indicating whether the bottom of the table
       is being processed.  The ##TT register marks the top of the table.  Avoid
       using these names for any other purpose.

       _t_b_l also defines a macro TT## to produce the bottom and side lines  of  a
       boxed  table.   While  _t_b_l  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 _t_b_l internally employs register, string, macro, and diversion names
       beginning with the numeral 33.  A document to be preprocessed  with  GNU
       _t_b_l should not use any such identifiers.

   IInntteerraaccttiioonn wwiitthh _ee_qq_nn
       _t_b_l  should  always  be  called before _e_q_n(1).  (_g_r_o_f_f(1) automatically
       arranges preprocessors in the correct order.)  Don’t call the EEQQ and EENN
       macros within tables; instead, set up delimiters in your _e_q_n input  and
       use the ddeelliimm region option so that _t_b_l will recognize them.

   GGNNUU _tt_bb_ll eennhhaanncceemmeennttss
       In  addition to extensions noted above, GNU _t_b_l removes constraints en‐
       dured by users of AT&T _t_b_l.

       • 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 (..TT&&) 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.

   UUssiinngg GGNNUU _tt_bb_ll wwiitthhiinn mmaaccrrooss
       You can embed a table region inside a macro definition.  However, since
       _t_b_l writes its own macro definitions at the beginning of each table re‐
       gion, it is necessary to call end macros instead of ending macro defin‐
       itions with “....”.  Additionally, the escape character must be disabled.

       Not all _t_b_l features can be exercised from such macros because _t_b_l is a
       _r_o_f_f  preprocessor: it sees the input earlier than _t_r_o_f_f does.  For ex‐
       ample, vertically aligning decimal separators fails if the numbers con‐
       taining them occur as macro or string parameters; the alignment is per‐
       formed by _t_b_l itself, which sees only \\$$11, \\$$22, and so on,  and  there‐
       fore  can’t  recognize a decimal separator that only appears later when
       _t_r_o_f_f interpolates a macro or string definition.

       Using _t_b_l macros within conditional input (that is, contingent upon  an
       iiff,  iiee, eell, or wwhhiillee request) can result in misleading line numbers in
       subsequent diagnostics.  _t_b_l unconditionally injects  its  output  into
       the  source  document, but the conditional branch containing it may not
       be taken, and if it is not, the llff requests that _t_b_l injects to restore
       the source line number cannot take effect.  Consider copying the  input
       line  counter register cc.. and restoring its value at a convenient loca‐
       tion after applicable arithmetic.

OOppttiioonnss
       ----hheellpp displays a usage message, while --vv and  ----vveerrssiioonn  show  version
       information; all exit afterward.

       --CC     Enable  AT&T compatibility mode: recognize ..TTSS and ..TTEE even when
              followed by a character other than space or  newline.   Further‐
              more, interpret the uninterpreted leader escape sequence \\aa.

LLiimmiittaattiioonnss
       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  _m_s, _m_m, and _m_e.  To use it, follow the ..TTSS token with a space
       and then “HH”; this will be interpreted by the formatter as a  TTSS  macro
       call  with  an  HH  argument.   Then, within the table data, call the TTHH
       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 TTHH immediately 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
       bbpp request will not cause a page break in a “TTSS  HH”  table.   Define  a
       macro  to wrap bbpp: invoke it normally if there is no current diversion.
       Otherwise, pass the macro call to the  enclosing  diversion  using  the
       transparent  line  escape  sequence  \\!!; 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 _g_r_o_t_t_y(1); single rules
       are used instead.  _g_r_o_t_t_y also ignores half‐line motions, so the uu col‐
       umn modifier has no effect.  On terminal devices (“_n_r_o_f_f mode”),  hori‐
       zontal rules and box borders occupy a full vee of space; this amount is
       doubled for ddoouubblleebbooxx tables.  Tables using these features thus require
       more vertical space in _n_r_o_f_f mode than in _t_r_o_f_f mode: write nnee requests
       accordingly.  Vertical rules between columns are drawn in the space be‐
       tween  columns in _n_r_o_f_f 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 \\aa to put leaders in table entries does not work in GNU _t_b_l,  ex‐
       cept  in  compatibility mode.  This is correct behavior: \\aa is an _u_n_i_n_‐
       _t_e_r_p_r_e_t_e_d leader.  You can still use the _r_o_f_f  leader  character  (Con‐
       trol+A)  or  define a string to use \\aa as 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  ||  in  a  format  specification,  such  as
       “||LLCCRR||..”,  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.

EExxaammpplleess
       It  can  be easier to acquire the language of _t_b_l 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

       ┌────────────────────────────────────────────────────────────────────┐
       │   AAbbiilliittyy                          AApppplliiccaattiioonn                     │
       │ 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 _n_o_t to put tomato in a fruit salad          │
       │ Charisma       sells obligate carnivores tomato‐based fruit salads │
       └────────────────────────────────────────────────────────────────────┘

       The AA and NN column 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

                                DDaaiillyy eenneerrggyy iinnttaakkee ((iinn MMJJ))
                                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 _m_a_n_d_o_c reference
       for its _t_b_l 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 │
                                    │   │ cceenntteerr │   │
                                    │ 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

                                    _nn   _nn××_nn   ddiiffffeerreennccee
                                    1    1
                                    2    4        3
                                    3    9        5
                                    4   16        7
                                    5   25        9
                                    6   36        11

       Some _t_b_l features cannot be illustrated in the limited environment of a
       portable man page.

       We  can  define  a  macro outside of a _t_b_l 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
              ..

SSeeee aallssoo
       “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 _m_a_n_d_o_c’s man page for its _t_b_l
       implementation.

       _g_r_o_f_f(1), _t_r_o_f_f(1)

groff 1.23.0                      3 June 2025                           _t_b_l(1)
───────────────────────────────────────────────────────────────────────────────
_t_f_m_t_o_d_i_t(1)                 General Commands Manual                _t_f_m_t_o_d_i_t(1)

NNaammee
       tfmtodit - adapt TeX Font Metrics files for use with _g_r_o_f_f and _g_r_o_d_v_i

SSyynnooppssiiss
       ttffmmttooddiitt [--ss] [--gg _g_f_‐_f_i_l_e] [--kk _s_k_e_w_‐_c_h_a_r] _t_f_m_‐_f_i_l_e _m_a_p_‐_f_i_l_e _f_o_n_t_‐
                _d_e_s_c_r_i_p_t_i_o_n

       ttffmmttooddiitt ----hheellpp

       ttffmmttooddiitt --vv
       ttffmmttooddiitt ----vveerrssiioonn

DDeessccrriippttiioonn
       _t_f_m_t_o_d_i_t  creates  a  font description file for use with _g_r_o_f_f(1)’s ddvvii
       output device.  _t_f_m_‐_f_i_l_e is the name of the TeX font  metric  file  for
       the font.  _m_a_p_‐_f_i_l_e assigns _g_r_o_f_f ordinary or special character identi‐
       fiers  to glyph indices in the font; it should consist of a sequence of
       lines of the form
              _i _c_1 ... _c_n
       where _i is a position of the glyph in  the  font  in  decimal,  and  _c_1
       through  _c_n  are  glyph  identifiers in the form used by _g_r_o_f_f font de‐
       scriptions.  If a glyph has no _g_r_o_f_f names but exists in  _t_f_m_‐_f_i_l_e_,  it
       is  put in the _g_r_o_f_f font description file as an unnamed glyph.  Output
       is written in _g_r_o_f_f___f_o_n_t(5) format to _f_o_n_t_‐_d_e_s_c_r_i_p_t_i_o_n_,  a  file  named
       for the intended _g_r_o_f_f font name.

       If  the font is “special”, meaning that _g_r_o_f_f should search it whenever
       a glyph is not found in the current font, use the --ss  option  and  name
       _f_o_n_t_‐_d_e_s_c_r_i_p_t_i_o_n  in  the  ffoonnttss  directive in the output device’s _D_E_S_C
       file.

       To do a good job of math typesetting, _g_r_o_f_f requires font metric infor‐
       mation not present in _t_f_m_‐_f_i_l_e_.  This is because TeX has separate  math
       italic fonts, whereas _g_r_o_f_f uses normal italic fonts for math.  The ad‐
       ditional information required by _g_r_o_f_f is given by the two arguments to
       the  mmaatthh__ffiitt  macro  in  the Metafont programs for the Computer Modern
       fonts.  In a text font (a font for which mmaatthh__ffiitt is  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 ccmmbbaassee when creating _c_m_._b_a_s_e.
              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  eexxbbaassee;
       consider patching _e_x_b_a_s_e_._m_f 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
       _c_m_._b_a_s_e  or  _e_x_b_a_s_e_._m_f  should  be  specified with the --gg option, which
       should _n_o_t be given for a font for which mmaatthh__ffiitt is true.

OOppttiioonnss
       ----hheellpp displays a usage message, while --vv and  ----vveerrssiioonn  show  version
       information; all exit afterward.

       --gg _g_f_‐_f_i_l_e
              Use  the  _g_f_‐_f_i_l_e  produced by Metafont containing “ssppeecciiaall” and
              “nnuummssppeecciiaall” commands to obtain additional font metric  informa‐
              tion.

       --kk _s_k_e_w_‐_c_h_a_r
              The skew character of this font is at position _s_k_e_w_‐_c_h_a_r_.  _s_k_e_w_‐
              _c_h_a_r  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 _s_k_e_w_‐_c_h_a_r are ignored.

       --ss     Add the ssppeecciiaall directive to the font description file.

FFiilleess
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_d_v_i_/_D_E_S_C
              describes the ddvvii output device.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_d_v_i_/F
              describes the font known as _F on device ddvvii.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_d_v_i_/_g_e_n_e_r_a_t_e_/_e_c_._m_a_p
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_d_v_i_/_g_e_n_e_r_a_t_e_/_m_s_a_m_._m_a_p
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_d_v_i_/_g_e_n_e_r_a_t_e_/_m_s_b_m_._m_a_p
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_d_v_i_/_g_e_n_e_r_a_t_e_/_t_c_._m_a_p
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_d_v_i_/_g_e_n_e_r_a_t_e_/_t_e_x_b_._m_a_p
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_d_v_i_/_g_e_n_e_r_a_t_e_/_t_e_x_e_x_._m_a_p
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_d_v_i_/_g_e_n_e_r_a_t_e_/_t_e_x_i_._m_a_p
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_d_v_i_/_g_e_n_e_r_a_t_e_/_t_e_x_i_t_t_._m_a_p
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_d_v_i_/_g_e_n_e_r_a_t_e_/_t_e_x_m_i_._m_a_p
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_d_v_i_/_g_e_n_e_r_a_t_e_/_t_e_x_r_._m_a_p
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_d_v_i_/_g_e_n_e_r_a_t_e_/_t_e_x_s_y_._m_a_p
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_d_v_i_/_g_e_n_e_r_a_t_e_/_t_e_x_t_e_x_._m_a_p
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_v_d_v_i_/_g_e_n_e_r_a_t_e_/_t_e_x_t_t_._m_a_p
              map  glyph  indices  in  TeX fonts to _g_r_o_f_f ordinary and special
              character identifiers.  _e_c_._m_a_p is used  for  TTRREECC,  TTIIEECC,  TTBBEECC,
              TTBBIIEECC,  HHRREECC,  HHIIEECC,  HHBBEECC, HHBBIIEECC, CCWWEECC, and CCWWIIEECC; _m_s_a_m_._m_a_p for
              SSAA; _m_s_b_m_._m_a_p for SSBB; _t_c_._m_a_p for TTRRTTCC, TTIITTCC, TTBBTTCC,  TTBBIITTCC,  HHRRTTCC,
              HHIITTCC, HHBBTTCC, HHBBIITTCC, CCWWTTCC, and CCWWIITTCC; _t_e_x_b_._m_a_p for TTBB, HHRR, HHII, HHBB,
              and  HHBBII;  _t_e_x_e_x_._m_a_p for EEXX; _t_e_x_i_._m_a_p for TTII and TTBBII; _t_e_x_i_t_t_._m_a_p
              for CCWWII; _t_e_x_m_i_._m_a_p for MMII; _t_e_x_r_._m_a_p for  TTRR;  _t_e_x_s_y_._m_a_p  for  SS;
              _t_e_x_t_e_x_._m_a_p for SSCC; and _t_e_x_t_t_._m_a_p for CCWW.

SSeeee aallssoo
       _g_r_o_f_f(1), _g_r_o_d_v_i(1), _g_r_o_f_f___f_o_n_t(5)

groff 1.23.0                      3 June 2025                      _t_f_m_t_o_d_i_t(1)
───────────────────────────────────────────────────────────────────────────────
_t_r_o_f_f(1)                    General Commands Manual                   _t_r_o_f_f(1)

NNaammee
       troff - GNU _r_o_f_f typesetter and document formatter

SSyynnooppssiiss
       ttrrooffff [--aabbccCCEEiiRRUUzz] [--dd _c_t_e_x_t] [--dd _s_t_r_i_n_g==_t_e_x_t] [--ff _f_o_n_t_‐_f_a_m_i_l_y]
             [--FF _f_o_n_t_‐_d_i_r_e_c_t_o_r_y] [--II _i_n_c_l_u_s_i_o_n_‐_d_i_r_e_c_t_o_r_y] [--mm _m_a_c_r_o_‐_p_a_c_k_a_g_e]
             [--MM _m_a_c_r_o_‐_d_i_r_e_c_t_o_r_y] [--nn _p_a_g_e_‐_n_u_m_b_e_r] [--oo _p_a_g_e_‐_l_i_s_t]
             [--rr _c_n_u_m_e_r_i_c_‐_e_x_p_r_e_s_s_i_o_n] [--rr _r_e_g_i_s_t_e_r==_n_u_m_e_r_i_c_‐_e_x_p_r_e_s_s_i_o_n]
             [--TT _o_u_t_p_u_t_‐_d_e_v_i_c_e] [--ww _w_a_r_n_i_n_g_‐_c_a_t_e_g_o_r_y] [--WW _w_a_r_n_i_n_g_‐_c_a_t_e_g_o_r_y]
             [_f_i_l_e ...]

       ttrrooffff ----hheellpp

       ttrrooffff --vv
       ttrrooffff ----vveerrssiioonn

DDeessccrriippttiioonn
       GNU  _t_r_o_f_f  transforms _g_r_o_f_f(7) language input into the device‐indepen‐
       dent output format described in _g_r_o_f_f___o_u_t(5); _t_r_o_f_f is thus  the  heart
       of  the  GNU  _r_o_f_f document formatting system.  If no _f_i_l_e operands are
       given on the command line, or if _f_i_l_e is “--”, the standard input stream
       is read.

       GNU _t_r_o_f_f is functionally compatible with the AT&T _t_r_o_f_f typesetter and
       features numerous extensions.  Many people prefer to use  the  _g_r_o_f_f(1)
       command,  a  front end which also runs preprocessors and output drivers
       in the appropriate order and with appropriate options.

OOppttiioonnss
       --hh and ----hheellpp display a usage message, while --vv and ----vveerrssiioonn show ver‐
       sion information; all exit afterward.

       --aa     Generate a plain text approximation of the typeset output.   The
              read‐only  register ..AA is 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 ..ssss
                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 --aa output are subject to change.

       --bb     Write a backtrace reporting the state of _t_r_o_f_f’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 _t_r_o_f_f’s idea of line numbers can be confused by requests
              that append to macros.

       --cc     Start with color output disabled.

       --CC     Enable  AT&T  _t_r_o_f_f  compatibility  mode;   implies   --cc.    See
              _g_r_o_f_f___d_i_f_f(7).

       --dd _c_t_e_x_t
       --dd _s_t_r_i_n_g==_t_e_x_t
              Define  _r_o_f_f  string _c or _s_t_r_i_n_g as _t_e_x_t_.  _c must be one charac‐
              ter; _s_t_r_i_n_g can be of arbitrary length.  Such string assignments
              happen before any macro file is loaded,  including  the  startup
              file.   Due  to  _g_e_t_o_p_t___l_o_n_g(3)  limitations,  _c  cannot be, and
              _s_t_r_i_n_g cannot contain, an equals sign, even  though  that  is  a
              valid character in a _r_o_f_f identifier.

       --EE     Inhibit _t_r_o_f_f error messages; implies --WWww.  This option does _n_o_t
              suppress messages sent to the standard error stream by documents
              or macro packages using ttmm or related requests.

       --ff _f_a_m Use _f_a_m as the default font family.

       --FF _d_i_r Search  in directory _d_i_r for the selected output device’s direc‐
              tory of device and font description files.  See the  description
              of  _G_R_O_F_F___F_O_N_T___P_A_T_H  in  section “Environment” below for the de‐
              fault search locations and ordering.

       --ii     Read the standard input stream after all named input files  have
              been processed.

       --II _d_i_r Search  the  directory _d_i_r for files (those named on the command
              line; in ppssbbbb, ssoo, and ssooqquuiieett  requests;  and  in  “\\XX''ppss::  iimm‐‐
              ppoorrtt''”, “\\XX''ppss:: ffiillee''”, and “\\XX''ppddff:: ppddffppiicc''” device control es‐
              cape  sequences).   --II may be specified more than once; each _d_i_r
              is searched in the given order.  To search the  current  working
              directory  before others, add “--II ..” at the desired place; it is
              otherwise searched last.  --II works similarly to,  and  is  named
              for, the “include” option of Unix C compilers.

       --mm _n_a_m_e
              Process  the  file  name_._t_m_a_c  prior to any input files.  If not
              found, _t_m_a_c_.name is attempted.  _n_a_m_e (in both  arrangements)  is
              presumed   to   be   a   macro  file;  see  the  description  of
              _G_R_O_F_F___T_M_A_C___P_A_T_H in section “Environment” below for  the  default
              search locations and ordering.

       --MM _d_i_r Search  directory  _d_i_r  for macro files.  See the description of
              _G_R_O_F_F___T_M_A_C___P_A_T_H in section “Environment” below for  the  default
              search locations and ordering.

       --nn _n_u_m Begin numbering pages at _n_u_m_.  The default is 11.

       --oo _l_i_s_t
              Output  only  pages  in _l_i_s_t_, which is a comma‐separated list of
              inclusive page ranges; _n means page _n_, _m--_n means every page  be‐
              tween  _m  and _n, --_n means every page up to _n, and _n-- means every
              page from _n on.  _t_r_o_f_f stops processing and exits after  format‐
              ting the last page enumerated in _l_i_s_t_.

       --rr _c_n_u_m_e_r_i_c_‐_e_x_p_r_e_s_s_i_o_n
       --rr _r_e_g_i_s_t_e_r==_n_u_m_e_r_i_c_‐_e_x_p_r_e_s_s_i_o_n
              Define  _r_o_f_f  register  _c  or  _r_e_g_i_s_t_e_r  as  _n_u_m_e_r_i_c_‐_e_x_p_r_e_s_s_i_o_n_.
              _c must be a one‐character name; _r_e_g_i_s_t_e_r  can  be  of  arbitrary
              length.   Such register assignments happen before any macro file
              is loaded, including the startup file.   Due  to  _g_e_t_o_p_t___l_o_n_g(3)
              limitations, _c cannot be, and _r_e_g_i_s_t_e_r cannot contain, an equals
              sign,  even  though  that is a valid character in a _r_o_f_f identi‐
              fier.

       --RR     Don’t load _t_r_o_f_f_r_c and _t_r_o_f_f_r_c_-_e_n_d.

       --TT _d_e_v Prepare output for device _d_e_v_.  The default is ppss; see _g_r_o_f_f(1).

       --UU     Operate in _u_n_s_a_f_e _m_o_d_e_, enabling the ooppeenn, ooppeennaa, ppii,  ppssoo,  and
              ssyy requests, 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 --mm and --MM op‐
              tions above.

       --ww _n_a_m_e
       --WW _n_a_m_e
              Enable (--ww) or inhibit (--WW) warnings in category _n_a_m_e_.  See sec‐
              tion “Warnings” below.

       --zz     Suppress formatted output.

WWaarrnniinnggss
       Warning diagnostics emitted by _t_r_o_f_f are divided into  named,  numbered
       categories.   The name associated with each warning category is used by
       the --ww and --WW options.  Each category is also assigned a power of  two;
       the  sum  of enabled category codes is used by the wwaarrnn request and the
       ..wwaarrnn register.  Warnings of each category are produced under the  fol‐
       lowing circumstances.

              ┌───────────────────────┬─────────────────────────────┐
              │ Bit   Code   Category │ Bit    Code      Category   │
              ├───────────────────────┼─────────────────────────────┤
              │   0      _1   cchhaarr     │  10      _1_0_2_4   rreegg         │
              │   1      _2   nnuummbbeerr   │  11      _2_0_4_8   ttaabb         │
              │   2      _4   bbrreeaakk    │  12      _4_0_9_6   rriigghhtt--bbrraaccee │
              │   3      _8   ddeelliimm    │  13      _8_1_9_2   mmiissssiinngg     │
              │   4     _1_6   eell       │  14     _1_6_3_8_4   iinnppuutt       │
              │   5     _3_2   ssccaallee    │  15     _3_2_7_6_8   eessccaappee      │
              │   6     _6_4   rraannggee    │  16     _6_5_5_3_6   ssppaaccee       │
              │   7    _1_2_8   ssyynnttaaxx   │  17    _1_3_1_0_7_2   ffoonntt        │
              │   8    _2_5_6   ddii       │  18    _2_6_2_1_4_4   iigg          │
              │   9    _5_1_2   mmaacc      │  19    _5_2_4_2_8_8   ccoolloorr       │
              │                       │  20   _1_0_4_8_5_7_6   ffiillee        │
              └───────────────────────┴─────────────────────────────┘

       bbrreeaakk           4   A  filled output line could not be broken such that
                           its length was less than  the  output  line  length
                           \\nn[[..ll]].  This category is enabled by default.

       cchhaarr            1   No  mounted  font defines a glyph for the requested
                           character.  This category is enabled by default.

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

       ddeelliimm           8   The  closing  delimiter  in  an escape sequence was
                           missing or mismatched.

       ddii            256   A ddii, ddaa, bbooxx, or bbooxxaa request was invoked  without
                           an argument when there was no current diversion.

       eell             16   The eell request was encountered with no prior corre‐
                           sponding iiee request.

       eessccaappee      32768   An unsupported escape sequence was encountered.

       ffiillee      1048576   An  attempt  was  made to load a file that does not
                           exist.  This category is enabled by default.

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

       iigg         262144   An  invalid  escape  sequence occurred in input ig‐
                           nored using the iigg request.  This warning  category
                           diagnoses  a condition that is an error when it oc‐
                           curs in non‐ignored input.

       iinnppuutt       16384   An invalid character occurred on the input stream.

       mmaacc           512   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 _n_o_t dereferenced, so it  is  not
                           created if it does not exist.

       mmiissssiinngg      8192   A request was invoked with a mandatory argument ab‐
                           sent.

       nnuummbbeerr          2   An  invalid  numeric  expression  was  encountered.
                           This category is enabled by default.

       rraannggee          64   A numeric expression was out of range for its  con‐
                           text.

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

       rriigghhtt--bbrraaccee  4096   A right brace escape sequence  \\}}  was  encountered
                           where a number was expected.

       ssccaallee          32   A  scaling  unit  inappropriate  to its context was
                           used in a numeric expression.

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

       ssyynnttaaxx        128   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
                           _g_r_o_f_f extension conditional expression operator was
                           used while in compatibility mode.

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

       aallll    All  warning categories except ddii, mmaacc, and rreegg.  This shorthand
              is intended to produce all warnings that are useful  with  macro
              packages  and  documents  written for AT&T _t_r_o_f_f and its descen‐
              dants, which have less fastidious diagnostics than GNU _t_r_o_f_f.

       ww      All warning categories.  Authors of documents and macro packages
              targeting _g_r_o_f_f are encouraged to use this setting.

EEnnvviirroonnmmeenntt
       _G_R_O_F_F___F_O_N_T___P_A_T_H and _G_R_O_F_F___T_M_A_C___P_A_T_H 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 (;).

       _G_R_O_F_F___F_O_N_T___P_A_T_H
              A  list  of directories in which to seek the selected output de‐
              vice’s directory of device and font  description  files.   _t_r_o_f_f
              will scan directories given as arguments to any specified --FF op‐
              tions  before  these,  then  in a site‐specific directory (_/_u_s_r_/
              _s_h_a_r_e_/_g_r_o_f_f_/_s_i_t_e_-_f_o_n_t), a standard  location  (_/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/
              _1_._2_3_._0_/_f_o_n_t),  and a compatibility directory (_/_u_s_r_/_l_i_b_/_f_o_n_t) af‐
              ter them.

       _G_R_O_F_F___T_M_A_C___P_A_T_H
              A list of directories in which to search for macro files.  _t_r_o_f_f
              will scan directories given as arguments to any specified --MM op‐
              tions before these, then the current directory (only if  in  un‐
              safe mode), the user’s home directory, a site‐specific directory
              (_/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_s_i_t_e_-_t_m_a_c),  and  a  standard  location (_/_u_s_r_/
              _s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c) after them.

       _G_R_O_F_F___T_Y_P_E_S_E_T_T_E_R
              Set the default output device.  If empty or not set, ppss is used.
              The --TT option overrides _G_R_O_F_F___T_Y_P_E_S_E_T_T_E_R.

       _S_O_U_R_C_E___D_A_T_E___E_P_O_C_H
              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 _g_m_t_i_m_e(3) and
              _a_s_c_t_i_m_e(3) when the formatter starts up and stored in  registers
              usable by documents and macro packages.

       _T_Z     The  time zone to use when converting the current time to human‐
              readable form; see _t_z_s_e_t(3).  If _S_O_U_R_C_E___D_A_T_E___E_P_O_C_H is  used,  it
              is always converted to human‐readable form using UTC.

FFiilleess
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_t_r_o_f_f_r_c
              is an initialization macro file loaded before any macro packages
              specified with --mm options.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_t_r_o_f_f_r_c_-_e_n_d
              is  an initialization macro file loaded after all macro packages
              specified with --mm options.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/name_._t_m_a_c
              are macro files distributed with _g_r_o_f_f.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_vname_/_D_E_S_C
              describes the output device _n_a_m_e.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_vname_/F
              describes the font _F of device _n_a_m_e_.

       _t_r_o_f_f_r_c and _t_r_o_f_f_r_c_-_e_n_d are sought neither in the current nor the  home
       directory  by  default  for  security reasons, even if the --UU option is
       specified.  Use the --MM command‐line option or the _G_R_O_F_F___T_M_A_C___P_A_T_H envi‐
       ronment variable to add these directories to the search path if  neces‐
       sary.

AAuutthhoorrss
       The GNU version of _t_r_o_f_f was originally written by James Clark; he also
       wrote  the  original  version  of  this  document, which was updated by
       Werner Lemberg, Bernd Warken, and G. Branden Robinson.

SSeeee aallssoo
       _G_r_o_f_f_: _T_h_e _G_N_U _I_m_p_l_e_m_e_n_t_a_t_i_o_n _o_f _t_r_o_f_f, by Trent A. Fisher  and  Werner
       Lemberg,  is the primary _g_r_o_f_f manual.  You can browse it interactively
       with “info groff”.

       _g_r_o_f_f(1)
              offers an overview of the GNU  _r_o_f_f  system  and  describes  its
              front end executable.

       _g_r_o_f_f(7)
              details  the _g_r_o_f_f language, including a short but complete ref‐
              erence of all predefined requests,  registers,  and  escape  se‐
              quences.

       _g_r_o_f_f___c_h_a_r(7)
              explains the syntax of _g_r_o_f_f special character escape sequences,
              and lists all special characters predefined by the language.

       _g_r_o_f_f___d_i_f_f(7)
              enumerates the differences between AT&T device‐independent _t_r_o_f_f
              and _g_r_o_f_f.

       _g_r_o_f_f___f_o_n_t(5)
              covers the format of _g_r_o_f_f device and font description files.

       _g_r_o_f_f___o_u_t(5)
              describes the format of _t_r_o_f_f’s output.

       _g_r_o_f_f___t_m_a_c(5)
              includes information about macro files that ship with _g_r_o_f_f.

       _r_o_f_f(7)
              supplies background on _r_o_f_f systems in general, including point‐
              ers to further related documentation.

groff 1.23.0                      3 June 2025                         _t_r_o_f_f(1)
───────────────────────────────────────────────────────────────────────────────
_x_t_o_t_r_o_f_f(1)                 General Commands Manual                _x_t_o_t_r_o_f_f(1)

NNaammee
       xtotroff - convert X font metrics into _g_r_o_f_f font metrics

SSyynnooppssiiss
       xxttoottrrooffff [--dd _d_e_s_t_i_n_a_t_i_o_n_‐_d_i_r_e_c_t_o_r_y] [--rr _r_e_s_o_l_u_t_i_o_n] [--ss _t_y_p_e_‐_s_i_z_e]
                _f_o_n_t_‐_m_a_p

       xxttoottrrooffff ----hheellpp

       xxttoottrrooffff --vv
       xxttoottrrooffff ----vveerrssiioonn

DDeessccrriippttiioonn
       _x_t_o_t_r_o_f_f  uses  _f_o_n_t_‐_m_a_p to create _g_r_o_f_f(1) font description files from
       X11 fonts.  Each line in _f_o_n_t_‐_m_a_p consists of  a  series  of  lines  of
       paired  _g_r_o_f_f 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 _f_o_n_t_‐_m_a_p file consisting of the line
              TB -adobe-times-bold-r-normal--*-*-*-*-p-*-iso8859-1
       maps the XLFD on the right to the _g_r_o_f_f font  name  TTBB,  conventionally
       “Times bold”.

       _x_t_o_t_r_o_f_f  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 --rr and --ss op‐
       tions.  If a font name is still ambiguous, _x_t_o_t_r_o_f_f aborts.   For  each
       successful  mapping,  _x_t_o_t_r_o_f_f creates a _g_r_o_f_f font description file in
       the current working directory (or that  specified  by  the  ‐‐dd  option)
       named for each _g_r_o_f_f font, and reports the mapping to the standard out‐
       put stream.

OOppttiioonnss
       ----hheellpp  displays  a  usage message, while --vv and ----vveerrssiioonn show version
       information; all exit afterward.

       --dd _d_e_s_t_i_n_a_t_i_o_n_‐_d_i_r_e_c_t_o_r_y
              Write font descriptions to _d_e_s_t_i_n_a_t_i_o_n_‐_d_i_r_e_c_t_o_r_y rather than the
              current working directory.

       --rr _r_e_s_o_l_u_t_i_o_n
              Set the resolution for all font patterns in _f_o_n_t_‐_m_a_p.  The value
              is used for both the horizontal and vertical motion quanta.   If
              not specified, a resolution of 75dpi is assumed.

       --ss _t_y_p_e_‐_s_i_z_e
              Set  the  type size in points for all font patterns in _f_o_n_t_‐_m_a_p.
              If not specified, a size of 10 points is assumed.

FFiilleess
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_F_o_n_t_M_a_p_-_X_1_1
              is the font mapping file used to produce the pre‐generated  font
              description files, supplied with _g_r_o_f_f, of X11 core fonts corre‐
              sponding to the 13 base Type 1 fonts for PostScript level 1.

BBuuggss
       The   only   supported  font  encodings  are  “iso8859-1”  and  “adobe-
       fontspecific”.

SSeeee aallssoo
       “X Logical Font Description Conventions”, by Jim  Flowers  and  Stephen
       Gildea.

       _X(7), _g_r_o_f_f(1), _g_x_d_i_t_v_i_e_w(1), _t_r_o_f_f(1), _g_r_o_f_f___f_o_n_t(5)

groff 1.23.0                      3 June 2025                      _x_t_o_t_r_o_f_f(1)
───────────────────────────────────────────────────────────────────────────────
_g_r_o_f_f___f_o_n_t(5)                 File Formats Manual                _g_r_o_f_f___f_o_n_t(5)

NNaammee
       groff_font - GNU _r_o_f_f device and font description files

DDeessccrriippttiioonn
       The  _g_r_o_f_f font and output device description formats are slight exten‐
       sions of those used by AT&T device‐independent _t_r_o_f_f.   In  distinction
       to  the AT&T implementation, _g_r_o_f_f lacks a binary format; all files are
       text files.  (Plan 9 _t_r_o_f_f has also abandoned the binary format.)   The
       device and font description files for a device _n_a_m_e are stored in a _d_e_‐
       _vname  directory.  The device description file is called _D_E_S_C, and, for
       each font supported by the device, a font description file is called _f_,
       where _f is usually an abbreviation of a font’s name and/or style.   For
       example,  the  ppss  (PostScript) device has _g_r_o_f_f font description files
       for Times roman (TTRR) and Zapf Chancery Medium italic (ZZCCMMII), among many
       others, while the uuttff88 device (for terminal emulators)  has  only  font
       descriptions for the roman, italic, bold, and bold‐italic styles (RR, II,
       BB, and BBII, respectively).

       Device and font description files are read by the formatter, _t_r_o_f_f, and
       by  output  drivers.  The programs typically delegate these files’ pro‐
       cessing to an internal library, _l_i_b_g_r_o_f_f, ensuring their consistent in‐
       terpretation.

_DD_EE_SS_CC ffiillee ffoorrmmaatt
       The _D_E_S_C file contains a series of  directives;  each  begins  a  line.
       Their  order  is not important, with two exceptions: (1) the rreess direc‐
       tive must precede any ppaappeerrssiizzee directive; and (2) the  cchhaarrsseett  direc‐
       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  rreess  directive  last  seen  when
       ppaappeerrssiizzee  is  encountered).  Spaces and/or tabs separate words and are
       ignored at line boundaries.  Comments start with the “##” character  and
       extend to the end of a line.  Empty lines are ignored.

       ffaammiillyy _f_a_m
              The default font family is _f_a_m.

       ffoonnttss _n _F_1 ... _F_n
              Fonts  _F_1,  ...,  _F_n are mounted at font positions _m+1, ..., _m+_n
              where _m is the number of ssttyylleess (see below).  This directive may
              extend over more than one line.  A font name of 00 causes no font
              to be mounted at the corresponding position.

       hhoorr _n  The horizontal motion quantum  is  _n  basic  units.   Horizontal
              quantities are rounded to multiples of _n_.

       iimmaaggee__ggeenneerraattoorr _p_r_o_g_r_a_m
              Use _p_r_o_g_r_a_m to generate PNG images from PostScript input.  Under
              GNU/Linux,  this  is usually _g_s(1), but under other systems (no‐
              tably Cygwin) it might be set to another name.   The  _g_r_o_h_t_m_l(1)
              driver uses this directive.

       ppaappeerrlleennggtthh _n
              The  vertical  dimension  of  the output medium is _n basic units
              (deprecated: use ppaappeerrssiizzee instead).

       ppaappeerrssiizzee _f_o_r_m_a_t_‐_o_r_‐_d_i_m_e_n_s_i_o_n_‐_p_a_i_r_‐_o_r_‐_f_i_l_e_‐_n_a_m_e ...
              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 AA00–AA77, BB00–BB77, CC00–CC77, and DD00–DD77; the U.S. formats lleetttteerr,
              lleeggaall, ttaabbllooiidd, lleeddggeerr, ssttaatteemmeenntt, and eexxeeccuuttiivvee; and the  enve‐
              lope  formats  ccoomm1100,  mmoonnaarrcchh,  and  DDLL.  Matching is performed
              without regard for lettercase.

              Alternatively,  the  argument  can  be  a  custom  paper  format
              _l_e_n_g_t_h,,_w_i_d_t_h  (with  no spaces before or after the comma).  Both
              _l_e_n_g_t_h and _w_i_d_t_h must have a unit appended; valid units are  “ii”
              for inches, “cc” for centimeters, “pp” for points, and “PP” for pi‐
              cas.  Example: “1122cc,,223355pp”.  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., _/_e_t_c_/_p_a_p_e_r_s_i_z_e);
              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.

       ppaappeerrwwiiddtthh _n
              The  horizontal  dimension of the output medium is _n basic units
              (deprecated: use ppaappeerrssiizzee instead).

       ppaassss__ffiilleennaammeess
              Direct  _t_r_o_f_f  to  emit  the  name  of  the  source  file  being
              processed.   This  is achieved with the intermediate output com‐
              mand “xx FF”, which _g_r_o_h_t_m_l interprets.

       ppoossttpprroo _p_r_o_g_r_a_m
              Use _p_r_o_g_r_a_m as the postprocessor.

       pprreepprroo _p_r_o_g_r_a_m
              Use _p_r_o_g_r_a_m as a preprocessor.  The hhttmmll and  xxhhttmmll  output  de‐
              vices use this directive.

       pprriinntt _p_r_o_g_r_a_m
              Use _p_r_o_g_r_a_m as the print spooler.  If omitted, _g_r_o_f_f’s --ll and --LL
              options are ignored.

       rreess _n  The device resolution is _n basic units per inch.

       ssiizzeess _s_1 ... _s_n 00
              The  device  has fonts at _s_1, ..., _s_n scaled points (see below).
              The list of sizes must be terminated by a 00.  Each _s_i  can  also
              be a range of sizes _m–_n.  The list can extend over more than one
              line.

       ssiizzeessccaallee _n
              A  typographical  point is subdivided into _n scaled points.  The
              default is 11.

       ssttyylleess _S_1 ... _S_m
              The first _m font mounting positions are associated  with  styles
              _S_1, ..., _S_m.

       ttccoommmmaanndd
              The  postprocessor  can  handle  the tt and uu intermediate output
              commands.

       uunniiccooddee
              The output device  supports  the  complete  Unicode  repertoire.
              This  directive is useful only for devices which produce charac‐
              ter entities instead of glyphs.

              If uunniiccooddee is present, no cchhaarrsseett section  is  required  in  the
              font  description  files  since  the Unicode handling built into
              _g_r_o_f_f is used.  However, if there are entries in a font descrip‐
              tion file’s cchhaarrsseett section, they either  override  the  default
              mappings  for  those  particular  characters or add new mappings
              (normally for composite characters).

              The uuttff88, hhttmmll, and xxhhttmmll output devices use this directive.

       uunniittwwiiddtthh _n
              Quantities in the font description files are in basic units  for
              fonts whose type size is _n scaled points.

       uunnssccaalleedd__cchhaarrwwiiddtthhss
              Make  the  font  handling  module  always  return unscaled glyph
              widths.  The _g_r_o_h_t_m_l driver uses this directive.

       uussee__cchhaarrnnaammeess__iinn__ssppeecciiaall
              _t_r_o_f_f should encode named glyphs inside device control commands.
              The _g_r_o_h_t_m_l driver uses this directive.

       vveerrtt _n The vertical motion quantum is _n basic units.  Vertical  quanti‐
              ties are rounded to multiples of _n_.

       cchhaarrsseett
              This directive and the rest of the file are ignored.  It is rec‐
              ognized  for compatibility with other _t_r_o_f_f implementations.  In
              GNU _t_r_o_f_f, character set repertoire is described on  a  per‐font
              basis.

       _t_r_o_f_f  recognizes  but  ignores  the  directives  ssppaarree11,  ssppaarree22,  and
       bbiiggggeessttffoonntt.

       The rreess, uunniittwwiiddtthh, ffoonnttss, and ssiizzeess lines are  mandatory.   Directives
       not listed above are ignored by _t_r_o_f_f but may be used by postprocessors
       to obtain further information about the device.

FFoonntt ddeessccrriippttiioonn ffiillee ffoorrmmaatt
       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.  _g_r_o_f_f achieves this using the  precedent  set
       by  AT&T  device‐independent  _t_r_o_f_f: 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,  _g_r_o_f_f’s  llbbpp device uses a uunniittwwiiddtthh of 800.  Its Times
       roman font (“TTRR”) has a ssppaacceewwiiddtthh of 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 llbbpp device 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 _D_E_S_C 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.

       nnaammee _F The name of the font is _F.  “DDEESSCC”  is  an  invalid  font  name.
              Simple integers are valid, but their use is discouraged.  (_g_r_o_f_f
              requests  and escape sequences interpret non‐negative font names
              as mounting positions instead.  Further, a font named “00” cannot
              be automatically mounted by the ffoonnttss directive of a _D_E_S_C file.)

       ssppaacceewwiiddtthh _n
              The width of an unadjusted inter‐word space is _n basic units.

       The directives above must appear in the first section; those below  are
       optional.

       ssllaanntt _n
              The font’s glyphs have a slant of _n degrees; a positive _n slants
              in the direction of text flow.

       lliiggaattuurreess _l_i_g_1 ... _l_i_g_n [00]
              Glyphs _l_i_g_1, ..., _l_i_g_n are ligatures; possible ligatures are ffff,
              ffii, ffll, ffffii, and ffffll.  For compatibility with other _t_r_o_f_f imple‐
              mentations,  the  list  of ligatures may be terminated with a 00.
              The list of ligatures must not extend over more than one line.

       ssppeecciiaall
              The font is _s_p_e_c_i_a_l: 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 _t_r_o_f_f, 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 cchhaarrsseett
       subsection is mandatory unless the associated _D_E_S_C  file  contains  the
       uunniiccooddee directive.  Another subsection, kkeerrnnppaaiirrss, is optional.

       The  directive cchhaarrsseett starts 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.

              _n_a_m_e _m_e_t_r_i_c_s _t_y_p_e _c_o_d_e [_e_n_t_i_t_y_‐_n_a_m_e] [---- _c_o_m_m_e_n_t]

       _n_a_m_e  identifies the glyph: if _n_a_m_e is a printable character _c, it cor‐
       responds to the _t_r_o_f_f ordinary character _c.  If _n_a_m_e is a multi‐charac‐
       ter sequence not beginning with \\, it corresponds to the GNU _t_r_o_f_f spe‐
       cial character escape sequence “\\[[_n_a_m_e]]”.  A name consisting  of  three
       minus  signs,  “------”,  indicates that the glyph is unnamed: such glyphs
       can be accessed only by the \\NN escape sequence  in  _t_r_o_f_f.   A  special
       character  named “------” can still be defined using ..cchhaarr and similar re‐
       quests.  The _n_a_m_e “\\--” defines the minus sign glyph.  Finally, _n_a_m_e can
       be the horizontal motion escape sequences, \\|| and \\^^ (“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  _m_e_t_r_i_c_s field is as follows (on one line; it may be
       broken here for readability).

              _w_i_d_t_h[,,[_h_e_i_g_h_t[,,[_d_e_p_t_h[,,[_i_t_a_l_i_c_‐_c_o_r_r_e_c_t_i_o_n[,,[
              _l_e_f_t_‐_i_t_a_l_i_c_‐_c_o_r_r_e_c_t_i_o_n[,,[_s_u_b_s_c_r_i_p_t_‐_c_o_r_r_e_c_t_i_o_n]]]]]]]]]]

       There must not be any spaces, tabs,  or  newlines  between  these  _s_u_b_‐
       _f_i_e_l_d_s_,  which  are  in basic units expressed as decimal integers.  Un‐
       specified subfields default to 00.  Since there is no associated  binary
       format,  these  values are not required to fit into the C language data
       type cchhaarr as they are in AT&T device‐independent _t_r_o_f_f.

       The _w_i_d_t_h subfield gives the width of the glyph.  The  _h_e_i_g_h_t  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 _d_e_p_t_h 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  _i_t_a_l_i_c_‐_c_o_r_r_e_c_t_i_o_n  is the amount of space that should be
       added after an oblique glyph to be followed immediately by  an  upright
       glyph.   The  _l_e_f_t_‐_i_t_a_l_i_c_‐_c_o_r_r_e_c_t_i_o_n is the amount of space that should
       be added before an oblique glyph to be preceded immediately by  an  up‐
       right  glyph.   The  _s_u_b_s_c_r_i_p_t_‐_c_o_r_r_e_c_t_i_o_n  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 _t_y_p_e 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 \\ww escape
       sequence is interpolated, these values are bitwise or‐ed  together  for
       each  glyph  and  stored  in the cctt register.  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  _c_o_d_e  field gives a numeric identifier that the postprocessor uses
       to render the glyph.  The glyph can be specified to  _t_r_o_f_f  using  this
       code  by  means of the \\NN escape sequence.  The code can be any integer
       (that is, any integer parsable by the C  standard  library’s  _s_t_r_t_o_l(3)
       function).

       The  _e_n_t_i_t_y_‐_n_a_m_e  field  defines  an  identifier for the glyph that the
       postprocessor uses to print the _t_r_o_f_f glyph _n_a_m_e.  This  field  is  op‐
       tional;  it  was introduced so that the _g_r_o_h_t_m_l output driver could en‐
       code its character set.  For example, the glyph \\[[PPoo]] is represented by
       “&&ppoouunndd;;” in HTML 4.0.  For efficiency, these data are now compiled di‐
       rectly into _g_r_o_h_t_m_l.  _g_r_o_p_s uses the field to build sub‐encoding arrays
       for PostScript fonts containing more than 256 glyphs.  Anything on  the
       line after the _e_n_t_i_t_y_‐_n_a_m_e field or “----” is ignored.

       A line in the cchhaarrsseett section can also have the form
              _n_a_m_e ""
       identifying _n_a_m_e as another name for the glyph mentioned in the preced‐
       ing line.  Such aliases can be chained.

       The directive kkeerrnnppaaiirrss starts a list of kerning adjustments to be made
       to  adjacent  glyph  pairs  from  this font.  It contains a sequence of
       lines formatted as follows.
              _g_1 _g_2 _n
       The foregoing means that when glyph _g_1 is  typeset  immediately  before
       _g_2,  the  space  between  them  should be increased by _n.  Most kerning
       pairs should have a negative value for _n.

FFiilleess
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_vname_/_D_E_S_C
              describes the output device _n_a_m_e.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_vname_/F
              describes the font known as _F on device _n_a_m_e.

SSeeee aallssoo
       _G_r_o_f_f_: _T_h_e _G_N_U _I_m_p_l_e_m_e_n_t_a_t_i_o_n _o_f _t_r_o_f_f, by Trent A. Fisher  and  Werner
       Lemberg,  is the primary _g_r_o_f_f 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 _g_r_o_f_f documentation as “AT&T _t_r_o_f_f”.

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

       _g_r_o_f_f(1), subsection “Utilities”, lists programs available for describ‐
       ing fonts in a variety of formats such that _g_r_o_f_f  output  drivers  can
       use them.

       _t_r_o_f_f(1)  documents the default device and font description file search
       path.

       _g_r_o_f_f___o_u_t(5), _a_d_d_f_t_i_n_f_o(1)

groff 1.23.0                      3 June 2025                    _g_r_o_f_f___f_o_n_t(5)
───────────────────────────────────────────────────────────────────────────────
_g_r_o_f_f___o_u_t(5)                  File Formats Manual                 _g_r_o_f_f___o_u_t(5)

NNaammee
       groff_out - GNU _r_o_f_f intermediate output format

DDeessccrriippttiioonn
       The fundamental operation of the _t_r_o_f_f(1) formatter is the  translation
       of  the _g_r_o_f_f(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
       _c_o_m_m_a_n_d refers to this  intermediate  output  language,  never  to  the
       _g_r_o_f_f(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 _g_r_o_f_f(1) is a wrapper that normally  runs
       the  _t_r_o_f_f formatter to generate intermediate output and an output dri‐
       ver (“postprocessor”) to consume it, users normally  do  not  encounter
       this  language.   The _g_r_o_f_f program’s --ZZ option inhibits postprocessing
       such that this intermediate output  is  sent  to  the  standard  output
       stream as when _t_r_o_f_f is run manually.

       _g_r_o_f_f’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 _t_r_o_f_f circa 1980.  Where a
       distinction is necessary, we will say “_t_r_o_f_f output”  to  describe  the
       output  of  GNU _t_r_o_f_f, and “intermediate output” to denote the language
       accepted by the parser implemented in _g_r_o_f_f’s internal C++ library used
       by most of its output drivers.

LLaanngguuaaggee ccoonncceeppttss
       During the run of _t_r_o_f_f, the _r_o_f_f input is cracked down to the informa‐
       tion on what has to be printed at what position on the intended device.
       So the language of the _i_n_t_e_r_m_e_d_i_a_t_e _o_u_t_p_u_t format can be  quite  small.
       Its only elements are commands with or without arguments.  In this doc‐
       ument, the term “command” always refers to the _i_n_t_e_r_m_e_d_i_a_t_e _o_u_t_p_u_t lan‐
       guage,  never to the _r_o_f_f language used for document formatting.  There
       are commands for positioning and text writing, for drawing, and for de‐
       vice controlling.

   SSeeppaarraattiioonn
       _C_l_a_s_s_i_c_a_l _t_r_o_f_f _o_u_t_p_u_t had strange  requirements  on  whitespace.   The
       _g_r_o_f_f  output  parser,  however, is smart about whitespace by making it
       maximally optional.  The whitespace characters, i.e., the  _t_a_b,  _s_p_a_c_e,
       and  _n_e_w_l_i_n_e  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 _s_p_a_c_e or _t_a_b characters is treated as a single  _s_y_n_t_a_c_‐
       _t_i_c_a_l _s_p_a_c_e.  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 _s_y_n_t_a_c_t_i_c_a_l _s_p_a_c_e.

       A line break is a syntactical element, too.  Every command argument can
       be  followed  by whitespace, a comment, or a newline character.  Thus a
       _s_y_n_t_a_c_t_i_c_a_l _l_i_n_e _b_r_e_a_k is defined to consist  of  optional  _s_y_n_t_a_c_t_i_c_a_l
       _s_p_a_c_e  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 _g_r_o_f_f _i_n_t_e_r_m_e_d_i_a_t_e _o_u_t_p_u_t, 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 DD and xx commands were  de‐
       signed  to  request a _s_y_n_t_a_c_t_i_c_a_l _l_i_n_e _b_r_e_a_k after their last argument.
       Only one command, ‘xx XX’ 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.

   AArrgguummeenntt uunniittss
       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 “uu” (basic units), and others use “zz”
       (scaled  points);  These are defined by the parameters specified in the
       device’s _D_E_S_C file; see _g_r_o_f_f___f_o_n_t(5) and, for more on  scaling  units,
       _g_r_o_f_f(7)  and _G_r_o_f_f_: _T_h_e _G_N_U _I_m_p_l_e_m_e_n_t_a_t_i_o_n _o_f _t_r_o_f_f, the _g_r_o_f_f 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 ## character 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.

   DDooccuummeenntt ppaarrttss
       A correct _i_n_t_e_r_m_e_d_i_a_t_e _o_u_t_p_u_t document consists of two parts, the  _p_r_o_‐
       _l_o_g_u_e and the _b_o_d_y.

       The  task of the _p_r_o_l_o_g_u_e is to set the general device parameters using
       three exactly specified commands.  The _g_r_o_f_f _p_r_o_l_o_g_u_e is guaranteed  to
       consist of the following three lines (in that order):

              xx TT _d_e_v_i_c_e
              xx rreess _n _h _v
              xx iinniitt

       with  the  arguments set as outlined in subsection “Device Control Com‐
       mands” below.  However, the parser for the _i_n_t_e_r_m_e_d_i_a_t_e  _o_u_t_p_u_t  format
       is able to swallow additional whitespace and comments as well.

       The _b_o_d_y 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 _p_r_o_l_o_g_u_e.  Processing is terminated as soon as the first  xx ssttoopp
       command  is encountered; the last line of any _g_r_o_f_f _i_n_t_e_r_m_e_d_i_a_t_e _o_u_t_p_u_t
       always contains such a command.

       Semantically, the _b_o_d_y is page oriented.  A new page is  started  by  a
       pp  command.  Positioning, writing, and drawing commands are always done
       within the current page, so they cannot occur before the first  pp  com‐
       mand.   Absolute positioning (by the HH and VV commands) is done relative
       to the current page, all other positioning is done relative to the cur‐
       rent location within this page.

CCoommmmaanndd rreeffeerreennccee
       This section describes all _i_n_t_e_r_m_e_d_i_a_t_e _o_u_t_p_u_t commands, the  classical
       commands as well as the _g_r_o_f_f extensions.

   CCoommmmeenntt ccoommmmaanndd
       ##_a_n_y_t_h_i_n_g⟨line‐break⟩
              A comment.  Ignore any characters from the ## character up to the
              next newline.  Each comment can be preceded by arbitrary _s_y_n_t_a_c_‐
              _t_i_c_a_l _s_p_a_c_e; every command can be terminated by a comment.

   SSiimmppllee ccoommmmaannddss
       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,  _s_y_n_t_a_c_t_i_c_a_l _s_p_a_c_e 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 _s_y_n_t_a_c_t_i_c_a_l _s_p_a_c_e is necessary only when two integer argu‐
       ments would clash or if the preceding argument ends with a string argu‐
       ment.

       CC _i_d⟨white‐space⟩
              Typeset the glyph of the special character _i_d.  Trailing syntac‐
              tical space is necessary to allow special character names of ar‐
              bitrary length.  The drawing position is not advanced.

       cc _c    Typeset  the  glyph  of the ordinary character character _c.  The
              drawing position is not advanced.

       ff _n    Select the font mounted at position _n.  _n cannot be negative.

       HH _n    Horizontally move the drawing position to _n basic units from the
              left edge of the page.  _n cannot be negative.

       hh _n    Move the drawing position right _n basic units.  AT&T  _t_r_o_f_f  al‐
              lowed  negative  _n_;  GNU _t_r_o_f_f does not produce such values, but
              _g_r_o_f_f’s output driver library handles them.

       mm _s_c_h_e_m_e [_c_o_m_p_o_n_e_n_t ...]
              Select the stroke color using the _c_o_m_p_o_n_e_n_ts in the color  space
              _s_c_h_e_m_e.   Each _c_o_m_p_o_n_e_n_t is an integer between 0 and 65536.  The
              quantity of components and their meanings vary with each _s_c_h_e_m_e.
              This command is a _g_r_o_f_f extension.

              mmcc _c_y_a_n _m_a_g_e_n_t_a _y_e_l_l_o_w
                     Use the CMY color scheme with components  cyan,  magenta,
                     and yellow.

              mmdd     Use  the  default  color  (no  components;  black in most
                     cases).

              mmgg _g_r_a_y
                     Use a grayscale color scheme with a component ranging be‐
                     tween 0 (black) and 65536 (white).

              mmkk _c_y_a_n _m_a_g_e_n_t_a _y_e_l_l_o_w _b_l_a_c_k
                     Use the CMYK color scheme with components cyan,  magenta,
                     yellow, and black.

              mmrr _r_e_d _g_r_e_e_n _b_l_u_e
                     Use  the RGB color scheme with components red, green, and
                     blue.

       NN _n    Typeset the glyph with index _n in the current font.  _n  is  nor‐
              mally  a  non‐negative integer.  The drawing position is not ad‐
              vanced.  The hhttmmll and xxhhttmmll devices use this command with  nega‐
              tive  _n to produce unbreakable space; the absolute value of _n is
              taken and interpreted in basic units.

       nn _b _a  Indicate a break.   No  action  is  performed;  the  command  is
              present  to  make the output more easily parsed.  The integers _b
              and _a describe the vertical space amounts before and  after  the
              break,  respectively.  GNU _t_r_o_f_f issues this command but _g_r_o_f_f’s
              output driver library ignores it.  See vv and VV.

       pp _n    Begin a new page, setting its number to _n.  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
              pp command must precede them.

       ss _n    Set type size to _n scaled points (unit zz in  GNU  _t_r_o_f_f).   AT&T
              _t_r_o_f_f used unscaled points (pp) instead; see section “Compatibil‐
              ity” below.

       tt _x_y_z...⟨white‐space⟩
       tt _x_y_z... _d_u_m_m_y_‐_a_r_g⟨white‐space⟩
              Typeset  word  _x_y_z;  that  is, set a sequence of ordinary glyphs
              named _x, _y, _z, ..., 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 CC command to emplace glyphs of spe‐
              cial characters.  The tt command is a _g_r_o_f_f extension and is out‐
              put only for devices whose _D_E_S_C file contains the  ttccoommmmaanndd  di‐
              rective; see _g_r_o_f_f___f_o_n_t(5).

       uu _n _x_y_z...
       uu _x_y_z... _d_u_m_m_y_‐_a_r_g⟨white‐space⟩
              Typeset  word  _x_y_z  with track kerning.  As tt, but after placing
              each glyph, the drawing position is  further  advanced  horizon‐
              tally  by _n basic units.  The uu command is a _g_r_o_f_f extension and
              is output only for devices whose _D_E_S_C file contains the ttccoommmmaanndd
              directive; see _g_r_o_f_f___f_o_n_t(5).

       VV _n    Vertically move the drawing position to _n basic units  from  the
              top edge of the page.  _n cannot be negative.

       vv _n    Move  the  drawing  position down _n basic units.  AT&T _t_r_o_f_f al‐
              lowed negative _n_; GNU _t_r_o_f_f does not produce  such  values,  but
              _g_r_o_f_f’s output driver library handles them.

       ww      Indicate  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 \\~~ or horizontal motion escape sequences are not.
              GNU  _t_r_o_f_f issues this command but _g_r_o_f_f’s output driver library
              ignores it.  See hh and HH.

   GGrraapphhiiccss ccoommmmaannddss
       Each graphics or drawing command in the _i_n_t_e_r_m_e_d_i_a_t_e _o_u_t_p_u_t starts with
       the letter DD followed 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 DD command  may
       not  be followed by another command on the same line (apart from a com‐
       ment), so each DD command is terminated by a _s_y_n_t_a_c_t_i_c_a_l _l_i_n_e _b_r_e_a_k.

       _t_r_o_f_f output follows the classical spacing rules (no space between com‐
       mand and subcommand, all arguments are preceded by a single space char‐
       acter), but the parser allows optional space between the  command  let‐
       ters and makes the space before the first argument optional.  As usual,
       each space can be any sequence of tab and space characters.

       Some  graphics  commands  can  take a variable number of arguments.  In
       this case, they are integers representing  a  size  measured  in  basic
       units uu.  The _h arguments stand for horizontal distances where positive
       means  right,  negative  left.  The _v 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 _g_r_o_f_f \\DD escape sequence; see _g_r_o_f_f(7).

       Unknown  DD  commands  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 _⟨_l_i_n_e_‐_b_r_e_a_k_⟩
       means a _s_y_n_t_a_c_t_i_c_a_l _l_i_n_e _b_r_e_a_k as defined  in  subsection  “Separation”
       above.

       DD~~ _h_1 _v_1 _h_2 _v_2 ... _h_n _v_n⟨line‐break⟩
              Draw  B‐spline from current position to offset (_h_1, _v_1), then to
              offset (_h_2, _v_2) if given, etc., up  to  (_h_n, _v_n).  This  command
              takes  a variable number of argument pairs; the current position
              is moved to the terminal point of the drawn curve.

       DDaa _h_1 _v_1 _h_2 _v_2⟨line‐break⟩
              Draw arc from current position to (_h_1, _v_1)+(_h_2, _v_2) with  center
              at  (_h_1, _v_1);  then move the current position to the final point
              of the arc.

       DDCC _d⟨line‐break⟩
       DDCC _d _d_u_m_m_y_‐_a_r_g⟨line‐break⟩
              Draw a solid circle using the current fill color with diameter _d
              (integer in basic units uu) 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 _g_r_o_f_f extension.

       DDcc _d⟨line‐break⟩
              Draw circle line with diameter _d (integer in basic units uu) with
              leftmost point at the current position; then  move  the  current
              position to the rightmost point of the circle.

       DDEE _h _v⟨line‐break⟩
              Draw a solid ellipse in the current fill color with a horizontal
              diameter of _h and a vertical diameter of _v (both integers in ba‐
              sic  units  uu)  with the leftmost point at the current position;
              then move to the rightmost point of the ellipse.   This  command
              is a _g_r_o_f_f extension.

       DDee _h _v⟨line‐break⟩
              Draw  an  outlined ellipse with a horizontal diameter of _h and a
              vertical diameter of _v (both integers in basic units uu) with the
              leftmost point at current position; then move to  the  rightmost
              point of the ellipse.

       DDFF _c_o_l_o_r_‐_s_c_h_e_m_e [_c_o_m_p_o_n_e_n_t ...]⟨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 mm.  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 _g_r_o_f_f escape sequences \\DD''FF ...’’  and  \\MM  (with  no
              other corresponding graphics commands).  This command is a _g_r_o_f_f
              extension.

              DDFFcc _c_y_a_n _m_a_g_e_n_t_a _y_e_l_l_o_w⟨line‐break⟩
                     Set  fill  color  for solid drawing objects using the CMY
                     color scheme, having the 3  color  components  cyan,  ma‐
                     genta, and yellow.

              DDFFdd ⟨line‐break⟩
                     Set  fill  color for solid drawing objects to the default
                     fill color value (black in most cases).  No component ar‐
                     guments.

              DDFFgg _g_r_a_y⟨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).

              DDFFkk _c_y_a_n _m_a_g_e_n_t_a _y_e_l_l_o_w _b_l_a_c_k⟨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.

              DDFFrr _r_e_d _g_r_e_e_n _b_l_u_e⟨line‐break⟩
                     Set fill color for solid drawing objects  using  the  RGB
                     color  scheme,  having the 3 color components red, green,
                     and blue.

       DDff _n⟨line‐break⟩
              The argument _n must be an integer in the range -32767 to 32767.

              0≤_n≤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
                     DDFFgg.

              _n<0 or _n>1000
                     Set  the filling color to the color that is currently be‐
                     ing used for the text and the  outline,  see  command  mm.
                     For example, the command sequence

                            mg 0 0 65536
                            Df -1

                     sets all colors to blue.

              This command is a _g_r_o_f_f extension.

       DDll _h _v⟨line‐break⟩
              Draw  line  from  current position to offset (_h, _v) (integers in
              basic units uu); then set current position  to  the  end  of  the
              drawn line.

       DDpp _h_1 _v_1 _h_2 _v_2 ... _h_n _v_n⟨line‐break⟩
              Draw  a  polygon  line from current position to offset (_h_1, _v_1),
              from there to offset (_h_2, _v_2), etc., up to offset (_h_n, _v_n),  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 _g_r_o_f_f exten‐
              sion.

       DDPP _h_1 _v_1 _h_2 _v_2 ... _h_n _v_n⟨line‐break⟩
              The same macro as the corresponding DDpp command 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 DDpp.  This command is a _g_r_o_f_f extension.

       DDtt _n⟨line‐break⟩
              Set  the  current  line  thickness  to  _n  (an  integer in basic
              units uu) if _n>0; if  _n=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 _g_r_o_f_f extension.

   DDeevviiccee ccoonnttrrooll ccoommmmaannddss
       Each device control command starts with the  letter  xx  followed  by  a
       space  character  (optional or arbitrary space/tab in _g_r_o_f_f) and a sub‐
       command letter or word; each argument (if any) must be  preceded  by  a
       _s_y_n_t_a_c_t_i_c_a_l _s_p_a_c_e.  All xx commands are terminated by a _s_y_n_t_a_c_t_i_c_a_l _l_i_n_e
       _b_r_e_a_k;  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, _t_r_o_f_f outputs the initialization command xx ii as xx iinniitt and
       the resolution command xx rr as xx rreess.  But writings like  xx ii__lliikkee__ggrrooffff
       and xx rrooffff__iiss__ggrrooffff are accepted as well to mean the same commands.

       In  the  following, the syntax element _⟨_l_i_n_e_‐_b_r_e_a_k_⟩ means a _s_y_n_t_a_c_t_i_c_a_l
       _l_i_n_e _b_r_e_a_k as defined in subsection “Separation” above.

       xxFF _n_a_m_e⟨line‐break⟩
              (_F_i_l_e_n_a_m_e control command)
              Use _n_a_m_e as the intended name for the current file in error  re‐
              ports.   This  is  useful for remembering the original file name
              when _g_r_o_f_f uses an internal piping mechanism.  The input file is
              not changed by this command.  This command is a _g_r_o_f_f extension.

       xxff _n _s⟨line‐break⟩
              (_f_o_n_t control command)
              Mount font position _n (a non‐negative integer) with font named _s
              (a text word); see _g_r_o_f_f___f_o_n_t(5).

       xxHH _n⟨line‐break⟩
              (_H_e_i_g_h_t control command)
              Set  character  height  to  _n  (a  positive  integer  in  scaled
              points  zz).   _C_l_a_s_s_i_c_a_l  _t_r_o_f_f used the unit points (pp) instead;
              see section “Compatibility” below.

       xxii ⟨line‐break⟩
              (_i_n_i_t control command)
              Initialize device.  This is the third command of the _p_r_o_l_o_g_u_e.

       xxpp ⟨line‐break⟩
              (_p_a_u_s_e control command)
              Parsed but ignored.  The classical documentation reads _p_a_u_s_e _d_e_‐
              _v_i_c_e_, _c_a_n _b_e _r_e_s_t_a_r_t_e_d.

       xxrr _n _h _v⟨line‐break⟩
              (_r_e_s_o_l_u_t_i_o_n control command)
              Resolution is _n, while _h is the minimal horizontal motion, and _v
              the minimal vertical motion possible with this device; all argu‐
              ments are positive integers in basic units uu per inch.  This  is
              the second command of the _p_r_o_l_o_g_u_e.

       xxSS _n⟨line‐break⟩
              (_S_l_a_n_t control command)
              Set slant to _n degrees (an integer in basic units uu).

       xxss ⟨line‐break⟩
              (_s_t_o_p control command)
              Terminates  the  processing  of  the current file; issued as the
              last command of any _i_n_t_e_r_m_e_d_i_a_t_e _t_r_o_f_f _o_u_t_p_u_t.

       xxtt ⟨line‐break⟩
              (_t_r_a_i_l_e_r control command)
              Generate trailer information, if any.  In ggrrooffff,  this  is  cur‐
              rently ignored.

       xxTT _x_x_x⟨line‐break⟩
              (_T_y_p_e_s_e_t_t_e_r control command)
              Set  the  name  of  the output driver to _x_x_x, a sequence of non‐
              whitespace characters terminated by  whitespace.   The  possible
              names  correspond  to  those  of _g_r_o_f_f’s --TT option.  This is the
              first command of the prologue.

       xxuu _n⟨line‐break⟩
              (_u_n_d_e_r_l_i_n_e control command)
              Configure underlining of spaces.  If _n is 1,  start  underlining
              of  spaces;  if  _n  is  0,  stop underlining of spaces.  This is
              needed for the ccuu request in nnrrooffff mode and  is  ignored  other‐
              wise.  This command is a _g_r_o_f_f extension.

       xxXX _a_n_y_t_h_i_n_g⟨line‐break⟩
              (_X_‐_e_s_c_a_p_e control command)
              Send  string  _a_n_y_t_h_i_n_g uninterpreted to the device.  If the line
              following this command starts with a ++ character  this  line  is
              interpreted  as a continuation line in the following sense.  The
              ++ is 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  ++ character.  This command is generated by the _g_r_o_f_f
              escape sequence \\XX.  The line‐continuing feature is a _g_r_o_f_f  ex‐
              tension.

   OObbssoolleettee ccoommmmaanndd
       In _c_l_a_s_s_i_c_a_l _t_r_o_f_f 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.

       _d_d_c    Move  right  _d_d (exactly two decimal digits) basic units uu, then
              print glyph with single‐letter name _c.

              In _g_r_o_f_f, arbitrary _s_y_n_t_a_c_t_i_c_a_l _s_p_a_c_e  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 _c_l_a_s_s_i_c_a_l _t_r_o_f_f, 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 _g_r_o_f_f, it is used only for output to the XX7755, XX7755--1122, XX110000,
       and XX110000--1122 devices.  For others, the commands tt and uu provide  greater
       functionality and superior troubleshooting capacity.

PPoossttpprroocceessssiinngg
       The  _r_o_f_f  postprocessors  are programs that have the task to translate
       the _i_n_t_e_r_m_e_d_i_a_t_e _o_u_t_p_u_t 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 _g_r_o_f_f  sys‐
       tem  provides  powerful  means  that make the programming of such post‐
       processors an easy task.

       There is a library function that parses  the  _i_n_t_e_r_m_e_d_i_a_t_e  _o_u_t_p_u_t  and
       sends  the  information  obtained  to the device via methods of a class
       with a common interface for each device.  So a _g_r_o_f_f postprocessor must
       only redefine the methods of this class.  For details, see  the  refer‐
       ence in section “Files” below.

EExxaammppllee
       This  section  presents the _i_n_t_e_r_m_e_d_i_a_t_e _o_u_t_p_u_t generated from the same
       input for three different devices.  The  input  is  the  sentence  _h_e_l_l
       _w_o_r_l_d fed into _g_r_o_f_f on the command line.

       • High‐resolution device _p_s

         shell> eecchhoo ""hheellll wwoorrlldd"" || ggrrooffff --ZZ --TT ppss

         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 _g_r_o_p_s(1) to get its rep‐
       resentation as a PostScript file, or _g_r_o_p_d_f(1) to  output  directly  to
       PDF.

       • Low‐resolution device _l_a_t_i_n_1

         This  is  similar to the high‐resolution device except that the posi‐
         tioning is done at a minor scale.  Some comments (lines starting with
         _#) were added for clarification; they were not generated by the  for‐
         matter.

         sshheellll>> "hell world" | groff -Z -T latin1

         _# _p_r_o_l_o_g_u_e
         x T latin1
         x res 240 24 40
         x init
         _# _b_e_g_i_n _a _n_e_w _p_a_g_e
         p1
         _# _f_o_n_t _s_e_t_u_p
         x font 1 R
         f1
         s10
         _# _i_n_i_t_i_a_l _p_o_s_i_t_i_o_n_i_n_g _o_n _t_h_e _p_a_g_e
         V40
         H0
         _# _w_r_i_t_e _t_e_x_t _'_h_e_l_l_'
         thell
         _# _i_n_f_o_r_m _a_b_o_u_t _a _s_p_a_c_e_, _a_n_d _d_o _i_t _b_y _a _h_o_r_i_z_o_n_t_a_l _j_u_m_p
         wh24
         _# _w_r_i_t_e _t_e_x_t _'_w_o_r_l_d_'
         tworld
         _# _a_n_n_o_u_n_c_e _l_i_n_e _b_r_e_a_k_, _b_u_t _d_o _n_o_t_h_i_n_g _b_e_c_a_u_s_e _._._.
         n40 0
         _# _._._. _t_h_e _e_n_d _o_f _t_h_e _d_o_c_u_m_e_n_t _h_a_s _b_e_e_n _r_e_a_c_h_e_d
         x trailer
         V2640
         x stop

       This  output  can be fed into the postprocessor _g_r_o_t_t_y(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 _i_n_t_e_r_m_e_d_i_a_t_e _o_u_t_p_u_t for the X devices can use the jump‐
         and‐write command with its 2‐digit displacements.

         sshheellll>> "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
         _# _w_r_i_t_e _t_e_x_t _w_i_t_h _o_l_d_‐_s_t_y_l_e _j_u_m_p_‐_a_n_d_‐_w_r_i_t_e _c_o_m_m_a_n_d
         ch07e07l03lw06w11o07r05l03dh7
         n16 0
         x trailer
         V1100
         x stop

       This  output  can  be  fed  into  the  postprocessor  _x_d_i_t_v_i_e_w(1x)   or
       _g_x_d_i_t_v_i_e_w(1) for displaying in X.

       Due  to  the  obsolete jump‐and‐write command, the text clusters in the
       classical output are almost unreadable.

CCoommppaattiibbiilliittyy
       The _i_n_t_e_r_m_e_d_i_a_t_e _o_u_t_p_u_t language of the _c_l_a_s_s_i_c_a_l _t_r_o_f_f was first docu‐
       mented in [CSTR #97].  The _g_r_o_f_f _i_n_t_e_r_m_e_d_i_a_t_e _o_u_t_p_u_t 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
         _g_r_o_f_f devices are also fundamentally different from the ones in _c_l_a_s_‐
         _s_i_c_a_l _t_r_o_f_f.  For example, the classical PostScript device was called
         _p_o_s_t and had a resolution of 720 units per inch, while _g_r_o_f_f’s _p_s 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 _g_r_o_f_f.

       • The B‐spline command DD~~ is correctly handled by the _i_n_t_e_r_m_e_d_i_a_t_e _o_u_t_‐
         _p_u_t  parser,  but  the drawing routines aren’t implemented in some of
         the postprocessor programs.

       • The argument of the commands ss and xx HH has the implicit  unit  scaled
         point zz in _g_r_o_f_f, while _c_l_a_s_s_i_c_a_l _t_r_o_f_f had point (pp).  This isn’t an
         incompatibility,  but a compatible extension, for both units coincide
         for all devices without a _s_i_z_e_s_c_a_l_e parameter, including all  classi‐
         cal  and  the  _g_r_o_f_f  text  devices.   The  few  _g_r_o_f_f 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 DDpp, DDPP, and DDtt is illogical,
         but as old versions of groff used this feature it is kept for compat‐
         ibility reasons.

       The  differences  between  _g_r_o_f_f  and _c_l_a_s_s_i_c_a_l _t_r_o_f_f are documented in
       _g_r_o_f_f___d_i_f_f(7).

FFiilleess
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_f_o_n_t_/_d_e_vname_/_D_E_S_C
              describes the output device _n_a_m_e.

AAuutthhoorrss
       James Clark wrote an early version of this  document,  which  described
       only  the  differences  between  AT&T device‐independent _t_r_o_f_f’s output
       format and that of  GNU  _r_o_f_f.   The  present  version  was  completely
       rewritten in 2001 by Bernd Warken.

SSeeee aallssoo
       _G_r_o_f_f_:  _T_h_e  _G_N_U _I_m_p_l_e_m_e_n_t_a_t_i_o_n _o_f _t_r_o_f_f, by Trent A. Fisher and Werner
       Lemberg, is the primary _g_r_o_f_f 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 _g_r_o_f_f documentation as “AT&T _t_r_o_f_f”.

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

       _g_r_o_f_f(1)
              documents  the  --ZZ option and contains pointers to further _g_r_o_f_f
              documentation.

       _g_r_o_f_f(7)
              describes the _g_r_o_f_f language, including its escape sequences and
              system of units.

       _g_r_o_f_f___f_o_n_t(5)
              details the device scaling parameters of device _D_E_S_C files.

       _t_r_o_f_f(1)
              generates the device‐independent intermediate output  documented
              here.

       _r_o_f_f(7)
              presents  historical  aspects  and the general structure of _r_o_f_f
              systems.

       _g_r_o_f_f___d_i_f_f(7)
              enumerates differences between the intermediate output  produced
              by AT&T _t_r_o_f_f and that of _g_r_o_f_f.

       _g_x_d_i_t_v_i_e_w(1)
              is a viewer for intermediate output.

       _R_o_f_f_._j_s
              ⟨https://github.com/Alhadis/Roff.js/⟩ is a viewer for intermedi‐
              ate output written in JavaScript.

       _g_r_o_d_v_i(1),  _g_r_o_h_t_m_l(1),  _g_r_o_l_b_p(1), _g_r_o_l_j_4(1), _g_r_o_p_d_f(1), _g_r_o_p_s(1), and
       _g_r_o_t_t_y(1) are _g_r_o_f_f postprocessors.

groff 1.23.0                      3 June 2025                     _g_r_o_f_f___o_u_t(5)
───────────────────────────────────────────────────────────────────────────────
_g_r_o_f_f___t_m_a_c(5)                 File Formats Manual                _g_r_o_f_f___t_m_a_c(5)

NNaammee
       groff_tmac - macro files in the GNU _r_o_f_f typesetting system

DDeessccrriippttiioonn
       Definitions of macros, strings, and registers for use in a _r_o_f_f(7) doc‐
       ument can be collected into _m_a_c_r_o _f_i_l_e_s, _r_o_f_f input files  designed  to
       produce  no output themselves but instead ease the preparation of other
       _r_o_f_f documents.  There is no syntactical  difference  between  a  macro
       file  and  any  other _r_o_f_f 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 _m_a_c_r_o _p_a_c_k_a_g_e.  Macro packages can be loaded by supplying
       the --mm option to _t_r_o_f_f(1) or a _g_r_o_f_f front end.

       Each macro package stores its macro, string, and  register  definitions
       in  one or more _t_m_a_c files.  This name originated in early Unix culture
       as an abbreviation of “_t_r_o_f_f macros”.

       A macro file must have a name in the form name_._t_m_a_c (or _t_m_a_c_.name)  and
       be  placed in a “_t_m_a_c directory” to be loadable with the --mm_n_a_m_e option.
       Section “Environment” of _t_r_o_f_f(1) lists  these  directories.   Alterna‐
       tively,  a  _g_r_o_f_f  document requiring a macro file can load it with the
       mmssoo (“macro source”) request.

       Like any other _r_o_f_f document, a macro file can  use  the  “ssoo”  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 _g_r_o_f_f requests.  It
       can even be empty.

MMaaccrroo ppaacckkaaggeess
       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
       _r_o_f_f 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 _g_r_o_f_f 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
       _t_r_o_f_f; _g_r_o_f_f’s support for arbitrarily long identifiers affords few ex‐
       cuses for name collisions, apart from attempts  at  compatibility  with
       the demands of historical documents.

   MMaann ppaaggeess
       _a_n
       _m_a_n    _a_n  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 _g_r_o_f_f___m_a_n(7).

       _d_o_c
       _m_d_o_c   _d_o_c  is  used  to compose man pages in the format originating in
              4.3BSD‐Reno (1990).  It provides many more features than _a_n, but
              is also larger, more complex, and not  as  widely  adopted;  see
              _g_r_o_f_f___m_d_o_c(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.

       _a_n_d_o_c
       _m_a_n_d_o_c This macro file, specific to _g_r_o_f_f, recognizes whether  a  docu‐
              ment  uses  _m_a_n or _m_d_o_c format and loads the corresponding macro
              package.  Multiple man pages, in either format, can be  handled;
              _a_n_d_o_c reloads each macro package as necessary.

   FFuullll‐‐sseerrvviiccee ppaacckkaaggeess
       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.

       _m_e     The classical _m_e macro package; see _g_r_o_f_f___m_e(7).

       _m_m     The semi‐classical _m_m macro package; see _g_r_o_f_f___m_m(7).

       _m_o_m    The _m_o_m 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 _g_r_o_f_f___m_o_m(7).

       _m_s     The classical _m_s macro package; see _g_r_o_f_f___m_s(7).

   LLooccaalliizzaattiioonn ppaacckkaaggeess
       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, _t_r_o_f_f_r_c loads the local‐
       ization file for English.

       _t_r_a_n_s  loads localized strings used by  various  macro  packages  after
              their localized forms have been prepared by a localization macro
              file.

       _g_r_o_f_f provides the following localization files.

       _c_s     Czech;  localizes  _m_a_n, _m_e, _m_m, _m_o_m, and _m_s.  Sets the input en‐
              coding to Latin‐2 by loading _l_a_t_i_n_2_._t_m_a_c.

       _d_e
       _d_e_n    German; localizes _m_a_n, _m_e, _m_m, _m_o_m, and _m_s.  Sets the input  en‐
              coding to Latin‐1 by loading _l_a_t_i_n_1_._t_m_a_c.

              _d_e_._t_m_a_c  selects  hyphenation patterns for traditional orthogra‐
              phy, and _d_e_n_._t_m_a_c does the same for the new orthography (“Recht‐
              schreibreform”).

       _e_n     English.

       _f_r     French; localizes _m_a_n, _m_e, _m_m, _m_o_m, and _m_s.  Sets the input  en‐
              coding to Latin‐9 by loading _l_a_t_i_n_9_._t_m_a_c.

       _i_t     Italian; localizes _m_a_n, _m_e, _m_m, _m_o_m, and _m_s.

       _j_a     Japanese.

       _s_v     Swedish; localizes _m_a_n, _m_e, _m_m, _m_o_m, and _m_s.  Sets the input en‐
              coding to Latin‐1 by loading _l_a_t_i_n_1_._t_m_a_c.  Some of the localiza‐
              tion  of the _m_m package is handled separately; see _g_r_o_f_f___m_m_s_e(7)
              (only in Swedish locales).

       _z_h     Chinese.

   IInnppuutt eennccooddiinnggss
       _l_a_t_i_n_1
       _l_a_t_i_n_2
       _l_a_t_i_n_5
       _l_a_t_i_n_9 are various ISO 8859 input encodings  supported  by  _g_r_o_f_f.   On
              systems  using  ISO character encodings, _g_r_o_f_f loads _l_a_t_i_n_1_._t_m_a_c
              automatically  at  startup.   A  document  that  uses   Latin‐2,
              Latin‐5,  or Latin‐9 can specify one of these alternative encod‐
              ings.

       _c_p_1_0_4_7 provides support for EBCDIC‐based systems.  On those  platforms,
              _g_r_o_f_f loads _c_p_1_0_4_7_._t_m_a_c automatically at startup.

       Because  different input character codes constitute valid GNU _t_r_o_f_f in‐
       put on ISO and EBCDIC systems, the _l_a_t_i_n macro files cannot be used  on
       EBCDIC systems, and _c_p_1_0_4_7 cannot be used on ISO systems.

   AAuuxxiilliiaarryy ppaacckkaaggeess
       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”) _g_r_o_f_f documents.

       _6_2_b_i_t  provides  macros  for  addition, multiplication, and division of
              62‐bit integers (allowing safe multiplication of  signed  31‐bit
              integers, for example).

       _h_d_t_b_l  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 _t_b_l(1).  It works only with the ppss and ppddff output de‐
              vices.  See _g_r_o_f_f___h_d_t_b_l(7).

       _p_a_p_e_r_s_i_z_e
              enables the paper format to be set on the command line by giving
              a “--dd ppaappeerr==_f_o_r_m_a_t” option to _t_r_o_f_f.  Possible values for _f_o_r_m_a_t
              are the ISO and  DIN  formats  “AA00–AA66”,  “BB00–BB66”,  “CC00–CC66”,  and
              “DD00–DD66”;   the   U.S.   formats  “lleetttteerr”,  “lleeggaall”,  “ttaabbllooiidd”,
              “lleeddggeerr”, “ssttaatteemmeenntt”, and “eexxeeccuuttiivvee”; and the envelope formats
              “ccoomm1100”, “mmoonnaarrcchh”, and “DDLL”.  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 _g_r_o_f_f _m_a_n,
              _m_d_o_c, _m_m, _m_o_m, and _m_s packages to  configure  them  accordingly.
              If  you want different margins, you will need to use those pack‐
              ages’ facilities, or _t_r_o_f_f llll and/or ppoo requests to adjust them.
              An output device typically requires command‐line options --pp  and
              --ll  to  override  the  paper dimensions and orientation, respec‐
              tively, defined in its _D_E_S_C file; see subsection “Paper  format”
              of  _g_r_o_f_f(1).   This macro file is normally loaded at startup by
              the _t_r_o_f_f_r_c file when formatting for a typesetting  device  (but
              not a terminal).

       _p_d_f_p_i_c provides  a  single macro, PPDDFFPPIICC, to include a PDF graphic in a
              document using features of the ppddff  output  driver.   For  other
              output  devices, PPDDFFPPIICC calls PPSSPPIICC, with which it shares an in‐
              terface (see below).  This macro  file  is  normally  loaded  at
              startup by the _t_r_o_f_f_r_c file.

       _p_i_c    supplies  definitions  of the macros PPSS, PPEE, and PPFF, usable with
              the _p_i_c(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 _p_i_c macro definitions.  Except
              for _m_a_n and _m_d_o_c, those provided with _g_r_o_f_f already do  so  (ex‐
              ception: _m_m employs the name PPFF for a different purpose).

       _p_s_p_i_c  provides a macro, PPSSPPIICC, that includes a PostScript graphic in a
              document.   The  ppss, ddvvii, hhttmmll, and xxhhttmmll output devices support
              such inclusions; for all other drivers, the  image  is  replaced
              with  a  rectangular  border  of  the  same size.  _p_s_p_i_c_._t_m_a_c is
              loaded at startup by the _t_r_o_f_f_r_c file.

              Its syntax is as follows.

                     ..PPSSPPIICC [--LL|--RR|--CC|--II _n] _f_i_l_e [_w_i_d_t_h [_h_e_i_g_h_t]]

              _f_i_l_e is the name of the PostScript file; _w_i_d_t_h and  _h_e_i_g_h_t  give
              the  desired  width and height of the image.  If neither a _w_i_d_t_h
              nor a _h_e_i_g_h_t 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 _w_i_d_t_h and _h_e_i_g_h_t
              arguments  may  have scaling units attached; the default scaling
              unit is ii.  PPSSPPIICC scales the graphic uniformly in the horizontal
              and vertical directions so that it is no more  than  _w_i_d_t_h  wide
              and  _h_e_i_g_h_t  high.   Option --CC centers the graphic horizontally;
              this is the default.   --LL  and  --RR  left‐  and  right‐align  the
              graphic,  respectively.  --II indents the graphic by _n (with a de‐
              fault scaling unit of mm).

              To use PPSSPPIICC within 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 PPSSPPIICC’s image argument is not  an  error.   (The
              ppssbbbb  request  does  issue an error diagnostic.)  To make such a
              failure fatal, append to the ppssppiicc**eerrrroorr--hhooookk macro.

                     .am pspic*error-hook
                     .  ab
                     ..

       _p_t_x    provides a macro, xxxx, to format permuted index entries  as  pro‐
              duced  by the GNU _p_t_x(1) program.  If your formatting needs dif‐
              fer, copy the macro into your document  and  adapt  it  to  your
              needs.

       _r_f_c_1_3_4_5
              defines  special  character escape sequences named for the glyph
              mnemonics specified in RFC 1345 and the digraph table of the Vim
              text editor.  See _g_r_o_f_f___r_f_c_1_3_4_5(7).

       _s_b_o_x_e_s offers an interface to the “ppddff:: bbaacckkggrroouunndd” device control com‐
              mand supported by _g_r_o_p_d_f(1).  Using this package, _g_r_o_f_f _m_s docu‐
              ments can draw colored rectangles beneath any output.

              ..BBOOXXSSTTAARRTT SSHHAADDEEDD _c_o_l_o_r OOUUTTLLIINNEEDD _c_o_l_o_r IINNDDEENNTT _s_i_z_e WWEEIIGGHHTT _s_i_z_e
                     begins a box, where the argument after SSHHAADDEEDD  gives  the
                     fill  color  and  that  after  OOUUTTLLIINNEEDD the border color.
                     Omit the former to get a borderless filled  box  and  the
                     latter  for  a border with no fill.  The specified WWEEIIGGHHTT
                     is used if the box is OOUUTTLLIINNEEDD.

                     IINNDDEENNTT precedes a value which leaves a  gap  between  the
                     border and the contents inside the box.

                     Each  _c_o_l_o_r  must be a defined _g_r_o_f_f color name, and each
                     _s_i_z_e a valid _g_r_o_f_f 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 BBOOXXSSTTAARRTT, the left
              position is the current indent minus the IINNDDEENNTT in the  command,
              and  the  right position is the left position (calculated above)
              plus the current line length and twice the indent.

              ..BBOOXXSSTTOOPP
                     takes no parameters.  It closes the most recently started
                     box at the current vertical  position  after  adding  its
                     IINNDDEENNTT spacing.

              Your  _g_r_o_f_f  documents  can  conditionally  exercise  the _s_b_o_x_e_s
              macros.  The register GGSSBBOOXX is defined if the package is loaded,
              and interpolates a true value if the ppddff  output  device  is  in
              use.

              _s_b_o_x_e_s furthermore hooks into the _g_r_o_f_f___m_s(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, _s_b_o_x_e_s 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 IINNDDEENNTT.)

              See  “Using PDF boxes with _g_r_o_f_f and the _m_s macros” for a demon‐
              stration.

       _t_r_a_c_e  aids the debugging of _g_r_o_f_f documents by  tracing  macro  calls.
              See _g_r_o_f_f___t_r_a_c_e(7).

       _w_w_w    defines    macros   corresponding   to   HTML   elements.    See
              _g_r_o_f_f___w_w_w(7).

NNaammiinngg
       AT&T _n_r_o_f_f and _t_r_o_f_f were implemented before  the  conventions  of  the
       modern  C  _g_e_t_o_p_t(3)  call  evolved, and used a naming scheme for macro
       packages that looks odd to modern eyes.  Macro packages were  typically
       loaded  using the --mm option 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 _t_m_a_c_._s and loaded with the option --mmss.

       _g_r_o_f_f  commands  permit  space between an option and its argument.  The
       syntax “ggrrooffff --mm ss” 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, _g_r_o_f_f accommodates different users’ expectations by supplying
       wrapper  macro  files  that  load  the  desired file with mmssoo requests.
       Thus, all of “ggrrooffff --mm ss”, “ggrrooffff --mm mmss”, “ggrrooffff --mmss”, and “ggrrooffff --mmmmss”
       serve to load the manuscript macros.

       Wrappers are not provided for packages of  more  recent  vintage,  like
       _w_w_w_._t_m_a_c.

       As  noted  in  passing  above, AT&T _t_r_o_f_f named macro files in the form
       _t_m_a_c_.name.  It has since become conventional in  operating  systems  to
       use a suffixed file name extension to suggest a file type or format.

IInncclluussiioonn
       The  traditional  method of employing a macro package is to specify the
       --mm _p_a_c_k_a_g_e option to the formatter, which then  reads  _p_a_c_k_a_g_e’s  macro
       file  prior  to any input files.  Historically, _p_a_c_k_a_g_e was sought in a
       file named _t_m_a_c_.package (that is, with a “ttmmaacc..”  prefix).   GNU  _t_r_o_f_f
       searches for package_._t_m_a_c in the macro path; if not found, it looks for
       _t_m_a_c_.package instead, and vice versa.

       Alternatively, one could include a macro file by using the request “..ssoo
       _f_i_l_e_‐_n_a_m_e” in the document; _f_i_l_e_‐_n_a_m_e is resolved relative to the loca‐
       tion  of  the  input document.  GNU _t_r_o_f_f offers an improved feature in
       the similar request “mmssoo _p_a_c_k_a_g_e_‐_f_i_l_e_‐_n_a_m_e”, which searches  the  macro
       path  for  _p_a_c_k_a_g_e_‐_f_i_l_e_‐_n_a_m_e.  Because its argument is a file name, its
       “..ttmmaacc” component must be included for the file to be  found;  however,
       as  a  convenience, if opening it fails, mmssoo strips any such suffix and
       tries again with a “ttmmaacc..” prefix, and vice versa.

       If a sourced file requires preprocessing, for example  if  it  includes
       _t_b_l  tables  or _e_q_n equations, the preprocessor _s_o_e_l_i_m(1) must be used.
       This can be achieved with a pipeline or, in _g_r_o_f_f, by specifying the --ss
       option to the formatter (or front end).  _m_a_n(1) librarian programs gen‐
       erally call _s_o_e_l_i_m automatically.  (Macro packages themselves generally
       do not require preprocessing.)

WWrriittiinngg mmaaccrrooss
       A _r_o_f_f(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 _r_o_f_f(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
       \\$$11, ..., \\$$99, \\$$[[...]], \\$$**, and \\$$@@, the name under  which  the  macro
       was  called  is  in  \\$$00,  and  the  number of arguments is in register
       \\nn[[..$$]]; see _g_r_o_f_f(7).

   DDrraafftt mmooddee
       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 ..eeoo and ..eecc requests.  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 _._e_o
       request.

   TTiippss ffoorr mmaaccrroo ddeeffiinniittiioonnss
       •      Start every line with a dot, for example, by using the groff re‐
              quest  ..nnoopp for 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).

   DDiivveerrssiioonnss
       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 ..bbrr requests.  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
       ..bbooxx request.)

       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.

AAuutthhoorrss
       This document was written by Bernd Warken, Werner Lemberg, and G. Bran‐
       den Robinson.

SSeeee aallssoo
       _G_r_o_f_f_: _T_h_e _G_N_U _I_m_p_l_e_m_e_n_t_a_t_i_o_n _o_f _t_r_o_f_f, by Trent A. Fisher  and  Werner
       Lemberg,  is the primary _g_r_o_f_f manual.  You can browse it interactively
       with “info groff”.

       The Filesystem Hierarchy Standard is maintained by  the  Linux  Founda‐
       tion.

       _g_r_o_f_f(1)
              is an overview of the _g_r_o_f_f system.

       _g_r_o_f_f___m_a_n(7),
       _g_r_o_f_f___m_d_o_c(7),
       _g_r_o_f_f___m_e(7),
       _g_r_o_f_f___m_m(7),
       _g_r_o_f_f___m_o_m(7),
       _g_r_o_f_f___m_s(7),
       _g_r_o_f_f___r_f_c_1_3_4_5(7),
       _g_r_o_f_f___t_r_a_c_e(7),
               and
       _g_r_o_f_f___w_w_w(7)
              are _g_r_o_f_f macro packages.

       _g_r_o_f_f(7)
              summarizes the language recognized by GNU _t_r_o_f_f.

       _t_r_o_f_f(1)
              documents the default macro file search path.

groff 1.23.0                      3 June 2025                    _g_r_o_f_f___t_m_a_c(5)
───────────────────────────────────────────────────────────────────────────────
_g_r_o_f_f(7)               Miscellaneous Information Manual               _g_r_o_f_f(7)

NNaammee
       groff - GNU _r_o_f_f language reference

DDeessccrriippttiioonn
       _g_r_o_f_f  is  short  for GNU _r_o_f_f, a free reimplementation of the AT&T de‐
       vice‐independent _t_r_o_f_f typesetting system.  See _r_o_f_f(7) for a survey of
       and background on _r_o_f_f systems.

       This document is intended as a reference.  The  primary  _g_r_o_f_f  manual,
       _G_r_o_f_f_:  _T_h_e  _G_N_U _I_m_p_l_e_m_e_n_t_a_t_i_o_n _o_f _t_r_o_f_f, 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  _/_u_s_r_/_s_h_a_r_e_/_d_o_c_/
       _g_r_o_f_f_-_b_a_s_e.

       _g_r_o_f_f is also a name for an extended dialect of the _r_o_f_f 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 _t_r_o_f_f, installed on this system as _t_r_o_f_f(1), is  the  _f_o_r_m_a_t_t_e_r_:  a
       program that reads device and font descriptions (_g_r_o_f_f___f_o_n_t(5)), inter‐
       prets  the _g_r_o_f_f language expressed in text input files, and translates
       that input into a device‐independent output format (_g_r_o_f_f___o_u_t(5))  that
       is  usually  then  post‐processed  by an output driver to produce Post‐
       Script, PDF, HTML, DVI, or terminal output.

IInnppuutt ffoorrmmaatt
       Input to GNU _t_r_o_f_f 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  _g_r_o_f_f___c_h_a_r(7).   The  _p_r_e_c_o_n_v(1)  preprocessor  transforms
       other encodings, including UTF‐8, to satisfy _t_r_o_f_f’s requirements.

SSyynnttaaxx cchhaarraacctteerrss
       Several input characters are syntactically significant to _g_r_o_f_f.

       .   A dot at the beginning of an input line marks it as a _c_o_n_t_r_o_l _l_i_n_e_.
           It  can also follow the ..eell and ..nnoopp requests, and the condition in
           ..iiff, ..iiee, and ..wwhhiillee requests.  The control character  invokes  re‐
           quests  and  calls macros by the name that follows it.  The ..cccc re‐
           quest can change the control character.

       '   The neutral apostrophe is the _n_o_‐_b_r_e_a_k  _c_o_n_t_r_o_l  _c_h_a_r_a_c_t_e_r_,  recog‐
           nized  where  the  control character is.  It suppresses the (first)
           break implied by the ..bbpp, ..ccff, ..ffii, ..ffll, ..iinn, ..nnff, ..rrjj,  ..sspp,  ..ttii,
           and  ..ttrrff  requests.   The  requested operation takes effect at the
           next break.  It makes ..bbrr nilpotent.  The no‐break control  charac‐
           ter  can  be changed with the ..cc22 request.  When formatted, “''” may
           be typeset as a typographical quotation mark; use the \\[[aaqq]] special
           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 ..ddss, ..ddss11, ..aass, and ..aass11 requests, 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 \\[[ddqq]] special 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 ..eecc request; ..eeoo disables escape sequence
           recognition.  Use the \\[[rrss]] special character  escape  sequence  to
           format  a  backslash glyph, and \\ee to 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.  _g_r_o_f_f 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 _l_e_a_d_e_r (see below).

       Horizontal white space characters are significant to _g_r_o_f_f_, but  trail‐
       ing spaces on text lines are ignored.

       _s_p_a_c_e   Space  characters  separate  arguments  in request invocations,
               macro calls, and string interpolations.  In text, they separate
               words.  Multiple adjacent space characters in text cause  _g_r_o_f_f
               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 ..ssss request.   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 \\~~.  To get
               a  space  of  fixed width, use one of the escape sequences ‘\\ ’
               (the escape character followed by a space), \\00, \\||, \\^^, or  \\hh;
               see section “Escape sequences” below.

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

       _t_a_b     A tab character in text causes the drawing position to  advance
               to the next defined tab stop.

TTaabbss aanndd lleeaaddeerrss
       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 _r_o_f_f(7).  Tabs  and  leaders
       do  not cause breaks and therefore do not interrupt filling.  Tab stops
       can be configured with the ttaa request, and tab and leader  glyphs  with
       the ttcc and llcc requests, respectively.

LLiinnee ccoonnttiinnuuaattiioonn
       When  filling is enabled, input and output line breaks generally do not
       correspond.  The _r_o_f_f language therefore distinguishes input and output
       line continuation.

       A backslash \\ immediately followed by a newline, sometimes discussed as
       \\_n_e_w_l_i_n_e, 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.  \\_n_e_w_l_i_n_e 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 || operator recognizes the new input line, and the input line
       counter register ..cc is incremented.

       The  \\cc escape sequence continues an _o_u_t_p_u_t line.  Nothing on the input
       line after it is formatted.  In contrast to \\_n_e_w_l_i_n_e, a line  after  \\cc
       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  \\cc,
       flushing  out  the  pending output line in the usual way.  The register
       ..iinntt contains a positive value if the last output  line  was  continued
       with \\cc; this datum is associated with the environment.

CCoolloorrss
       _g_r_o_f_f 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  _s_t_r_o_k_e  _c_o_l_o_r_, with which glyphs, rules (lines), and
       geometric objects like circles and polygons are  drawn,  and  the  _f_i_l_l
       _c_o_l_o_r_,  which  can  be used to paint the interior of a closed geometric
       figure.  The ccoolloorr, ddeeffccoolloorr, ggccoolloorr, and ffccoolloorr requests;  \\mm  and  \\MM
       escape  sequences; and ..ccoolloorr, ..mm, and ..MM registers exercise color sup‐
       port.

       Each output device has a color named “ddeeffaauulltt”, which cannot  be  rede‐
       fined.   A  device’s default stroke and fill colors are not necessarily
       the same.  For the ddvvii, hhttmmll, ppddff, ppss, and xxhhttmmll output devices,  _t_r_o_f_f
       automatically  loads a macro file defining many color names at startup.
       By the same mechanism, the devices supported by _g_r_o_t_t_y(1) recognize the
       eight standard ISO 6429/ECMA‐48 color names  (also  known  vulgarly  as
       “ANSI colors”).

MMeeaassuurreemmeennttss
       Numeric  parameters that specify measurements are expressed as integers
       or decimal fractions with an optional _s_c_a_l_i_n_g _u_n_i_t 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  “11ii”  to  a  register.
       The  only  constraint on the basic unit is that it is at least as small
       as any other unit.

       uu      Basic unit.
       ii      Inch; defined as 2.54 centimeters.
       cc      Centimeter.
       pp      Point; a typesetter’s unit used for measuring type size.   There
              are 72 points to an inch.
       PP      Pica;  another  typesetter’s unit.  There are 6 picas to an inch
              and 12 points to a pica.
       ss, zz   Scaled  points  and  multiplication  by  the   output   device’s
              _s_i_z_e_s_c_a_l_e parameter, respectively.
       ff      Multiplication 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.

       mm      Em; an em is equal to the current type size in points.
       nn      En; an en is one‐half em.
       vv      Vee; distance between text baselines.
       MM      Hundredth of an em.

   MMoottiioonn qquuaannttaa
       An  output  device’s  basic  unit uu is not necessarily its smallest ad‐
       dressable length; uu can 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 _m_o_t_i_o_n _q_u_a_n_t_a_, stored
       in the ..HH and ..VV registers, respectively.  Measurements are rounded  to
       applicable motion quanta.  Half‐quantum fractions round toward zero.

   DDeeffaauulltt uunniittss
       A general‐purpose register (one created or updated with the nnrr request;
       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 _t_r_o_f_f’s use of integer arithmetic
       should also be kept in mind; see below.

NNuummeerriicc eexxpprreessssiioonnss
       A _n_u_m_e_r_i_c _e_x_p_r_e_s_s_i_o_n 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

       _t_r_o_f_f  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
       _g_r_o_f_f___t_m_a_c(5) for the _6_2_b_i_t_._t_m_a_c macro package.)

       Arithmetic  infix  operators  perform a function on the numeric expres‐
       sions to their left and right; they are ++ (addition), --  (subtraction),
       ** (multiplication), // (truncating division), and %% (modulus).  _T_r_u_n_c_a_t_‐
       _i_n_g  _d_i_v_i_s_i_o_n 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 -- (negation) and ++ (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 _a and a divisor _b, a quotient  _q  formed
       by “((aa // bb))” and a remainder _r by “((aa %% bb))”, then _q_b + _r = _a.

       GNU _t_r_o_f_f’s scaling operator, used with parentheses as ((_c;;_e)), evaluates
       a  numeric  expression  _e using _c as the default scaling unit.  If _c is
       omitted, scaling units are ignored in the evaluation of _e.   GNU  _t_r_o_f_f
       also  provides  a  pair  of  operators  to  compute  the extrema of two
       operands: >>?? (maximum) and <<?? (minimum).

       Comparison operators comprise << (less than), >> (greater than), <<== (less
       than or equal), >>== (greater than or equal), and ==  (equal).   ====  is  a
       synonym for ==.  When evaluated, a comparison is replaced with “00” if it
       is  false  and  “11” if true.  In the _r_o_f_f language, positive values are
       true, others false.

       We can operate on truth values with the logical  operators  &&  (logical
       conjunction or “and”) and :: (logical disjunction or “or”).  They evalu‐
       ate  as comparison operators do.  A logical complementation (“not”) op‐
       erator, !!,, works only within “iiff”, “iiee”, and  “wwhhiillee”  requests.   Fur‐
       thermore, !! is 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 “nnuummbbeerr” category (see _t_r_o_f_f(1)), and its ex‐
       pression  evaluates  false.  This unfortunate limitation maintains com‐
       patibility with AT&T _t_r_o_f_f.  Test a numeric expression for  falsity  by
       comparing it to a false value.

       The _r_o_f_f language has no operator precedence: expressions are evaluated
       strictly  from  left  to  right, in contrast to schoolhouse arithmetic.
       Use parentheses (( )) to impose a desired precedence upon subexpressions.

       For many requests and escape sequences that cause motion on  the  page,
       the unary operators ++ and -- work 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.

       ++ and -- are also treated differently by the following requests and  es‐
       cape  sequences:  bbpp,  iinn, llll, ppll, ppnn, ppoo, ppss, ppvvss, rrtt, ttii, \\HH, \\RR, and
       \\ss.  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 || operator 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 _i_n_p_u_t line.  By default, tab stops reckon move‐
       ments in this way.  Most escape sequences do not; || tells  them  to  do
       so.  For vertical motions, the || operator specifies a distance from the
       first  text baseline on the page or in the current diversion, using the
       current vertical spacing.

       The \\BB escape 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.

IIddeennttiiffiieerrss
       An _i_d_e_n_t_i_f_i_e_r labels a GNU _t_r_o_f_f 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 _o_r_d_i_n_a_r_y _c_h_a_r_a_c_t_e_r is an input character
       that is not the escape character, a leader, tab, newline, or invalid as
       GNU _t_r_o_f_f input.

       Invalid input characters are subset of  control  characters  (from  the
       sets  “C0 Controls” and “C1 Controls” as Unicode describes them).  When
       _t_r_o_f_f encounters one in an identifier, it produces a warning  in  cate‐
       gory  “iinnppuutt”  (see  section “Warnings” in _t_r_o_f_f(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 00xx0000, 00xx0088, 00xx00BB, 00xx00DD–00xx11FF, and 00xx8800–00xx99FF.
       On an EBCDIC host, they are 00xx0000–00xx0011,  00xx0088,  00xx0099,  00xx00BB,  00xx00DD–00xx1144,
       00xx1177–00xx11FF,  and 00xx3300–00xx33FF.  Some of these code points are used by _t_r_o_f_f
       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  _e_x_‐
       _c_e_p_t with bracket forms.

       If  you  begin  a  macro,  string, or diversion name with either of the
       characters “[” or “]”, you foreclose use of the _r_e_f_e_r(1)  preprocessor,
       which recognizes “.[” and “.]” as bibliographic reference delimiters.

       The  escape  sequence  \\AA tests its argument for validity as an identi‐
       fier.

       How GNU _t_r_o_f_f 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, _t_r_o_f_f emits a  warning
       in  category  “mmaacc”, defines it as empty, and interpolates nothing.  If
       the identifier is interpreted as a register, _t_r_o_f_f emits a  warning  in
       category  “rreegg”,  initializes  it to zero, and interpolates that value.
       See section “Warnings” in _t_r_o_f_f(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.

CCoonnttrrooll cchhaarraacctteerrss
       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 “..” and the no‐break control character “''” can be
       changed with the cccc and cc22 requests, respectively.  Within a macro def‐
       inition, register ..bbrr indicates the control character used to call it.

IInnvvookkiinngg rreeqquueessttss
       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 rrmm request makes it unavailable.  The  aallss  request
       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  _t_r_o_f_f  does
       not allow tabs for argument separation.

       Generally, a space _w_i_t_h_i_n a request argument is not relevant, not mean‐
       ingful, or is supported by bespoke provisions, as with the ttll request’s
       delimiters.   Some  requests,  like  ddss, 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.

CCaalllliinngg mmaaccrrooss
       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 “mmaacc”  is
       emitted.  Calling an undefined macro _d_o_e_s end a macro definition naming
       it as its end macro (see section “Writing macros” below).

       To  embed  spaces _w_i_t_h_i_n a macro argument, enclose the argument in neu‐
       tral double quotes ‘""’.  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 _t_h_o_s_e characters are desired as
       literals.  In GNU _t_r_o_f_f, the special character  escape  sequence  \\[[rrss]]
       produces a backslash and \\[[ddqq]] a neutral double quote.

       In  GNU _t_r_o_f_f’s AT&T compatibility mode, these characters remain avail‐
       able as \\((rrss and \\((ddqq, respectively.  AT&T _t_r_o_f_f did  not  consistently
       define  these  special  characters,  but its descendants can be made to
       support them.  See _g_r_o_f_f___f_o_n_t(5).  If even that is  not  feasible,  see
       the  “Calling  Macros” section of the _g_r_o_f_f Texinfo manual for the com‐
       plex macro argument quoting rules of AT&T _t_r_o_f_f.

UUssiinngg eessccaappee sseeqquueenncceess
       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 \\.  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 _o_n_l_y an arbitrary‐
       length argument.  In the former scheme, a one‐character  argument  fol‐
       lows the function character immediately, an opening parenthesis “((” in‐
       troduces a two‐character argument (no closing parenthesis is used), and
       an  argument  of arbitrary length is enclosed in brackets “[[]]”.  In the
       latter scheme, the user selects a delimiter character.   A  few  escape
       sequences  are idiosyncratic, and support both of the foregoing conven‐
       tions (\\ss), designate their own termination sequence (\\??), consume  in‐
       put until the next newline (\\!!, \\"", \\##), or support an additional modi‐
       fier character (\\ss again, and \\nn).

       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  “eessccaappee” 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 (\\ee).  Requests permit the es‐
       cape mechanism to be deactivated (eeoo) and restored, or the escape char‐
       acter changed (eecc), and to save and restore it (eeccss and eeccrr).

DDeelliimmiitteerrss
       Some escape sequences that require parameters use delimiters.  The neu‐
       tral  apostrophe '' is a popular choice and shown in this document.  The
       neutral double quote "" is 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: \\_s_p_a_c_e, \\%%, \\||, \\^^, \\{{, \\}}, \\'', \\``,  \\--,  \\__,  \\!!,
       \\??, \\)), \\//, \\,,, \\&&, \\::, \\~~, \\00, \\aa, \\cc, \\dd, \\ee, \\EE, \\pp, \\rr, \\tt, and \\uu.
       However,  using  them  this way is discouraged; they can make the input
       confusing to read.

       A few escape sequences, \\AA, \\bb, \\oo, \\ww, \\XX, and \\ZZ, 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 \\DD, \\hh, \\HH, \\ll, \\LL, \\NN, \\RR, \\ss,  \\SS,  \\vv,
       and \\xx prohibit many delimiters.

              • the numerals 0–9 and the decimal point “..”

              • the (single‐character) operators ++--//**%%<<>>==&&::(())

              • any  escape  sequences  other than \\%%, \\::, \\{{, \\}}, \\'', \\``, \\--,
                \\__, \\!!, \\//, \\cc, \\ee, and \\pp

       Delimiter syntax is complex and flexible primarily for historical  rea‐
       sons; the foregoing restrictions need be kept in mind mainly when using
       _g_r_o_f_f in AT&T compatibility mode.  GNU _t_r_o_f_f 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, ''
       works fine.  See section “Implementation differences” in _g_r_o_f_f___d_i_f_f(7).

DDuummmmyy cchhaarraacctteerrss
       As discussed in _r_o_f_f(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.   \\&&  interpolates  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 ttrr request  to  remap  a
       character  to  “nothing”.  \\)) works as \\&& does, except that it does not
       cancel a pending end‐of‐sentence state.

CCoonnttrrooll ssttrruuccttuurreess
       _g_r_o_f_f 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  ..eell  “else”)
       followed  by  a  conditional expression _c_o_n_d_‐_e_x_p_r; the remainder of the
       line, _a_n_y_t_h_i_n_g, 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 _a_n_y_t_h_i_n_g are therefore not seen.  _a_n_y_t_h_i_n_g  ef‐
       fectively  _c_a_n_n_o_t  be  omitted;  if  _c_o_n_d_‐_e_x_p_r  is true and _a_n_y_t_h_i_n_g 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 \\{{ and \\}} perform
       such grouping.  Brace escape sequences outside  of  control  structures
       have no meaning and produce no output.

       \\{{  should  appear  (after optional spaces and tabs) immediately subse‐
       quent to the request’s conditional expression.  \\}} should appear  on  a
       line  with  other  occurrences  of  itself as necessary to match \\{{ se‐
       quences.  It can be preceded by a control character, spaces, and  tabs.
       Input  after any quantity of \\}} sequences on the same line is processed
       only if all the preceding conditions to which they correspond are true.
       Furthermore, a \\}} closing the body of a ..wwhhiillee request must be the last
       such escape sequence on an input line.

   CCoonnddiittiioonnaall eexxpprreessssiioonnss
       The ..iiff, ..iiee, and ..wwhhiillee requests test the truth values of numeric  ex‐
       pressions.  They also support several additional Boolean operators; the
       members  of  this  expanded  class  are termed _c_o_n_d_i_t_i_o_n_a_l _e_x_p_r_e_s_s_i_o_n_s;
       their truth values are as shown below.

       _cc_oo_nn_dd_‐‐_ee_xx_pp_rr...   ......iiss ttrruuee iiff......
       ────────────────────────────────────────────────────────────────────────
            ''_s_1''_s_2''   _s_1 produces the same formatted output as _s_2.
                cc _g   a glyph _g is available.
                dd _m   a string, macro, diversion, or request _m is defined.
                  ee   the current page number is even.
                FF _f   a font named _f is available.
                mm _c   a color named _c is defined.
                  nn   the formatter is in _n_r_o_f_f mode.
                  oo   the current page number is odd.
                rr _n   a register named _n is defined.
                SS _s   a font style named _s is available.
                  tt   the formatter is in _t_r_o_f_f mode.
                  vv   n/a (historical artifact; always false).

       If the first argument to an ..iiff, ..iiee, or ..wwhhiillee request begins  with  a
       non‐alphanumeric  character  apart  from  !! (see below); it performs an
       _o_u_t_p_u_t _c_o_m_p_a_r_i_s_o_n _t_e_s_t_.  Shown first in the  table  above,  the  _o_u_t_p_u_t
       _c_o_m_p_a_r_i_s_o_n  _o_p_e_r_a_t_o_r  interpolates  a true value if formatting its com‐
       parands _s_1 and _s_2 produces the same output commands.  Other  delimiters
       can  be used in place of the neutral apostrophes.  _t_r_o_f_f formats _s_1 and
       _s_2 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 \\?? to avoid formatting them;  this  causes
       them  to be compared character by character, as with string comparisons
       in other programming languages.  Since comparands protected with \\?? are
       read in copy mode, they need not even be valid _g_r_o_f_f 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
       “!!”, not followed immediately by spaces or tabs, complements an expres‐
       sion.  Spaces and tabs are optional immediately  after  the  “cc”,  “dd”,
       “FF”,  “mm”,  “rr”,  and  “SS” operators, but right after “!!”, they end the
       predicate and the conditional evaluates true.  (This  bizarre  behavior
       maintains compatibility with AT&T _t_r_o_f_f.)

SSyynnttaaxx rreeffeerreennccee ccoonnvveennttiioonnss
       In the following request and escape sequence specifications, most argu‐
       ment  names  were  chosen to be descriptive.  A few denotations may re‐
       quire introduction.

              _c         denotes a single input character.
              _f_o_n_t      a font either specified as a font name  or  a  numeric
                        mounting position.
              _a_n_y_t_h_i_n_g  all  characters up to the end of the line, to the end‐
                        ing delimiter for the escape sequence,  or  within  \\{{
                        and \\}}.  Escape sequences may generally be used freely
                        in _a_n_y_t_h_i_n_g, except when it is read in copy mode.
              _m_e_s_s_a_g_e   is  a character sequence to be emitted on the standard
                        error stream.  Special character escape sequences  are
                        _n_o_t interpreted.
              _n         is  a numeric expression that evaluates to a non‐nega‐
                        tive integer.
              _n_p_l       is a numeric expression constituting a count of subse‐
                        quent _p_r_o_d_u_c_t_i_v_e input lines; that is, those that  di‐
                        rectly  produce  formatted output.  Text lines produce
                        output, as do control lines containing  requests  like
                        ..ttll  or escape sequences like \\DD.  Macro calls are not
                        themselves productive, but their interpolated contents
                        can be.
              _±_N        is a numeric expression with a  meaning  dependent  on
                        its sign.

       If  a numeric expression presented as _±_N starts with a ‘++’ sign, an in‐
       crement in the amount of of _N is applied to the value applicable to the
       request or escape sequence.  If it starts with a ‘--’ sign, a  decrement
       of  magnitude _N is applied instead.  Without a sign, _N replaces any ex‐
       isting value.  A leading minus sign in _N 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.

RReeqquueesstt sshhoorrtt rreeffeerreennccee
       Not all details of request behavior are outlined here.  See  the  _g_r_o_f_f
       Texinfo manual or, for features new to GNU _t_r_o_f_f, _g_r_o_f_f___d_i_f_f(7).

       ..aabb       Abort processing; exit with failure status.
       ..aabb _m_e_s_s_a_g_e
                 Abort  processing; write _m_e_s_s_a_g_e to the standard error stream
                 and exit with failure status.
       ..aadd       Enable output line alignment and adjustment  using  the  mode
                 stored in \\nn[[..jj]].
       ..aadd _c     Enable  output  line  alignment  and  adjustment  in  mode  _c
                 (_c=bb,cc,ll,nn,rr).  Sets \\nn[[..jj]].
       ..aaff _r_e_g_i_s_t_e_r _c
                 Assign format _c to _r_e_g_i_s_t_e_r, where _c is “ii”, “II”,  “aa”,  “AA”,
                 or  a  sequence  of decimal digits whose quantity denotes the
                 minimum width in digits to be used when the register  is  in‐
                 terpolated.   “ii”  and  “aa” indicate Roman numerals and basic
                 Latin alphabetics, respectively, in the lettercase specified.
                 The default is 00.
       ..aallnn _n_e_w _o_l_d
                 Create alias (additional  name)  _n_e_w  for  existing  register
                 named _o_l_d.
       ..aallss _n_e_w _o_l_d
                 Create  alias  (additional  name)  _n_e_w  for existing request,
                 string, macro, or diversion _o_l_d.
       ..aamm _m_a_c_r_o Append to _m_a_c_r_o until .... is encountered.
       ..aamm _m_a_c_r_o _e_n_d
                 Append to _m_a_c_r_o until .._e_n_d is called.
       ..aamm11 _m_a_c_r_o
                 Same as ..aamm but with compatibility mode switched  off  during
                 macro expansion.
       ..aamm11 _m_a_c_r_o _e_n_d
                 Same  as  ..aamm but with compatibility mode switched off during
                 macro expansion.
       ..aammii _m_a_c_r_o
                 Append to a macro whose name is contained in the string _m_a_c_r_o
                 until .... is encountered.
       ..aammii _m_a_c_r_o _e_n_d
                 Append to a macro indirectly.   _m_a_c_r_o  and  _e_n_d  are  strings
                 whose  contents  are  interpolated for the macro name and the
                 end macro, respectively.
       ..aammii11 _m_a_c_r_o
                 Same as ..aammii but with compatibility mode switched off  during
                 macro expansion.
       ..aammii11 _m_a_c_r_o _e_n_d
                 Same  as ..aammii but with compatibility mode switched off during
                 macro expansion.
       ..aass _n_a_m_e  Create string _n_a_m_e with empty contents; no operation if  _n_a_m_e
                 already exists.
       ..aass _n_a_m_e _c_o_n_t_e_n_t_s
                 Append _c_o_n_t_e_n_t_s to string _n_a_m_e.
       ..aass11 _s_t_r_i_n_g
       ..aass11 _s_t_r_i_n_g _c_o_n_t_e_n_t_s
                 As  ..aass,  but  with compatibility mode disabled when _c_o_n_t_e_n_t_s
                 interpolated.
       ..aasscciiiiffyy _d_i_v_e_r_s_i_o_n
                 Unformat ASCII characters, spaces, and some escape  sequences
                 in _d_i_v_e_r_s_i_o_n.
       ..bbaacckkttrraaccee
                 Write  the  state  of  the  input stack to the standard error
                 stream.  See the --bb option of _g_r_o_f_f(1).
       ..bbdd _f_o_n_t  Stop emboldening font _f_o_n_t_.
       ..bbdd _f_o_n_t _n
                 Embolden _f_o_n_t by overstriking its glyphs offset by _n-1 units.
                 See register ..bb.
       ..bbdd _s_p_e_c_i_a_l_‐_f_o_n_t _f_o_n_t
                 Stop emboldening _s_p_e_c_i_a_l_‐_f_o_n_t when _f_o_n_t is selected.
       ..bbdd _s_p_e_c_i_a_l_‐_f_o_n_t _f_o_n_t _n
                 Embolden _s_p_e_c_i_a_l_‐_f_o_n_t_, overstriking its glyphs offset by  _n-1
                 units when _f_o_n_t is selected.  See register ..bb.
       ..bbllmm      Unset  blank  line macro (trap).  Restore default handling of
                 blank lines.
       ..bbllmm _n_a_m_e Set blank line macro (trap) to _n_a_m_e.
       ..bbooxx      Stop directing output to current diversion; any pending  out‐
                 put line is discarded.
       ..bbooxx _n_a_m_e Direct  output  to  diversion _n_a_m_e, omitting a partially col‐
                 lected line.
       ..bbooxxaa     Stop appending output to current diversion; any pending  out‐
                 put line is discarded.
       ..bbooxxaa _n_a_m_e
                 Append  output  to  diversion _n_a_m_e, omitting a partially col‐
                 lected line.
       ..bbpp       Break page and start a new one.
       ..bbpp _±_N    Break page, starting a new one numbered _±_N.
       ..bbrr       Break output line.
       ..bbrrpp      Break output line; adjust if applicable.
       ..bbrreeaakk    Break out of a while loop.
       ..cc22       Reset no‐break control character to “''”.
       ..cc22 _o     Recognize ordinary character _o as no‐break control character.
       ..cccc       Reset control character to ‘..’.
       ..cccc _o     Recognize ordinary character _o as the control character.
       ..ccee       Break, center the output of the next  productive  input  line
                 without filling, and break again.
       ..ccee _n_p_l   Break,  center  the  output  of the next _n_p_l productive input
                 lines without filling, then break again.  If _n_p_l  ≤  0,  stop
                 centering.
       ..ccff _f_i_l_e  Copy  contents  of _f_i_l_e without formatting to the (top‐level)
                 diversion.
       ..ccffllaaggss _n _c_1 _c_2 ...
                 Assign properties encoded by _n to characters _c_1, _c_2,  and  so
                 on.
       ..cchh _n_a_m_e  Unplant page location trap _n_a_m_e.
       ..cchh _n_a_m_e _v_p_o_s
                 Change  page  location trap _n_a_m_e planted by ..wwhh by moving its
                 location to _v_p_o_s (default scaling unit vv).
       ..cchhaarr _c _c_o_n_t_e_n_t_s
                 Define ordinary or special character _c as _c_o_n_t_e_n_t_s.
       ..cchhoopp _o_b_j_e_c_t
                 Remove the last character from the macro, string,  or  diver‐
                 sion named _o_b_j_e_c_t.
       ..ccllaassss _n_a_m_e _c_1 _c_2 ...
                 Define  a (character) class _n_a_m_e comprising the characters or
                 range expressions _c_1, _c_2, and so on.
       ..cclloossee _s_t_r_e_a_m
                 Close the _s_t_r_e_a_m.
       ..ccoolloorr    Enable output of color‐related device‐independent output com‐
                 mands.
       ..ccoolloorr _n  If _n is zero, disable output of color‐related device‐indepen‐
                 dent output commands; otherwise, enable them.
       ..ccoommppoossiittee _f_r_o_m _t_o
                 Map glyph name _f_r_o_m to glyph name  _t_o  while  constructing  a
                 composite glyph name.
       ..ccoonnttiinnuuee Finish the current iteration of a while loop.
       ..ccpp       Enable compatibility mode.
       ..ccpp _n     If  _n  is  zero, disable compatibility mode, otherwise enable
                 it.
       ..ccss _f_o_n_t _n _m
                 Set constant character width mode for _f_o_n_t to _n/36  ems  with
                 em _m.
       ..ccuu       Continuously  underline the output of the next productive in‐
                 put line.
       ..ccuu _n_p_l   Continuously underline the output of the next _n_p_l  productive
                 input lines.  If _n_p_l=0, stop continuously underlining.
       ..ddaa       Stop appending output to current diversion.
       ..ddaa _n_a_m_e  Append output to diversion _n_a_m_e.
       ..ddee _m_a_c_r_o Define  or redefine _m_a_c_r_o until “....” occurs at the start of a
                 control line in the current conditional block.
       ..ddee _m_a_c_r_o _e_n_d
                 Define or redefine _m_a_c_r_o until _e_n_d is invoked  or  called  at
                 the start of a control line in the current conditional block.
       ..ddee11 _m_a_c_r_o
                 As  ..ddee,  but  disable compatibility mode during macro expan‐
                 sion.
       ..ddee11 _m_a_c_r_o _e_n_d
                 As “..ddee _m_a_c_r_o _e_n_d”, but  disable  compatibility  mode  during
                 macro expansion.
       ..ddeeffccoolloorr _i_d_e_n_t _s_c_h_e_m_e _c_o_l_o_r_‐_c_o_m_p_o_n_e_n_t ...
                 Define  a color named _i_d_e_n_t_.  _s_c_h_e_m_e identifies a color space
                 and determines the number of  required  _c_o_l_o_r_‐_c_o_m_p_o_n_e_n_ts;  it
                 must  be  one  of  “rrggbb”  (three  components), “ccmmyy” (three),
                 “ccmmyykk” (four), or “ggrraayy” (one).  “ggrreeyy” is accepted as a syn‐
                 onym of “ggrraayy”.  The color components can  be  encoded  as  a
                 single  hexadecimal  value starting with ## or ####.  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  “ff”,
                 which  multiplies  its  value  by  65,536  (but  clamps it at
                 65,535).  Each output device has  a  color  named  “ddeeffaauulltt”,
                 which  cannot  be  redefined.   A device’s default stroke and
                 fill colors are not necessarily the same.
       ..ddeeii _m_a_c_r_o
                 Define macro indirectly.  As ..ddee, but  use  interpolation  of
                 string _m_a_c_r_o as the name of the defined macro.
       ..ddeeii _m_a_c_r_o _e_n_d
                 Define  macro  indirectly.  As ..ddee, but use interpolations of
                 strings _m_a_c_r_o and _e_n_d as the names of  the  defined  and  end
                 macros.
       ..ddeeii11 _m_a_c_r_o
                 As  ..ddeeii,  but disable compatibility mode during macro expan‐
                 sion.
       ..ddeeii11 _m_a_c_r_o _e_n_d
                 As ..ddeeii _m_a_c_r_o _e_n_d,  but  disable  compatibility  mode  during
                 macro expansion.
       ..ddeevviiccee _a_n_y_t_h_i_n_g
                 Write  _a_n_y_t_h_i_n_g,  read in copy mode, to _t_r_o_f_f output as a de‐
                 vice control command.  An initial  neutral  double  quote  is
                 stripped to allow embedding of leading spaces.
       ..ddeevviicceemm _n_a_m_e
                 Write  contents  of macro or string _n_a_m_e to _t_r_o_f_f output as a
                 device control command.
       ..ddii       Stop directing output to current diversion.
       ..ddii _n_a_m_e  Direct output to diversion _n_a_m_e.
       ..ddoo _n_a_m_e ...
                 Interpret the  string,  request,  diversion,  or  macro  _n_a_m_e
                 (along  with any arguments) with compatibility mode disabled.
                 Compatibility mode is restored (only if it was  active)  when
                 the _e_x_p_a_n_s_i_o_n of _n_a_m_e is interpreted.
       ..ddss _n_a_m_e  Create empty string _n_a_m_e.
       ..ddss _n_a_m_e _c_o_n_t_e_n_t_s
                 Create a string _n_a_m_e containing _c_o_n_t_e_n_t_s.
       ..ddss11 _n_a_m_e
       ..ddss11 _n_a_m_e _c_o_n_t_e_n_t_s
                 As  ..ddss,  but  with compatibility mode disabled when _c_o_n_t_e_n_t_s
                 interpolated.
       ..ddtt       Clear diversion trap.
       ..ddtt _v_e_r_t_i_c_a_l_‐_p_o_s_i_t_i_o_n _n_a_m_e
                 Set the diversion trap to  macro  _n_a_m_e  at  _v_e_r_t_i_c_a_l_‐_p_o_s_i_t_i_o_n
                 (default scaling unit vv).
       ..eecc       Recognize \\ as the escape character.
       ..eecc _o     Recognize ordinary character _o as the escape character.
       ..eeccrr      Restore escape character saved with ..eeccss.
       ..eeccss      Save the escape character.
       ..eell _a_n_y_t_h_i_n_g
                 Interpret  _a_n_y_t_h_i_n_g as if it were an input line if the condi‐
                 tional expression of the corresponding ..iiee request was false.
       ..eemm _n_a_m_e  Call macro _n_a_m_e after the end of input.
       ..eeoo       Disable the escape mechanism in interpretation mode.
       ..eevv       Pop environment stack, returning to previous one.
       ..eevv _e_n_v   Push current environment onto stack and switch to _e_n_v.
       ..eevvcc _e_n_v  Copy environment _e_n_v to the current one.
       ..eexx       Exit with successful status.
       ..ffaamm      Set default font family to previous value.
       ..ffaamm _n_a_m_e Set default font family to _n_a_m_e.
       ..ffcc       Disable field mechanism.
       ..ffcc _a     Set field delimiter to _a and pad glyph to space.
       ..ffcc _a _b   Set field delimiter to _a and pad glyph to _b.
       ..ffcchhaarr _c _c_o_n_t_e_n_t_s
                 Define fallback character (or glyph) _c as _c_o_n_t_e_n_t_s.
       ..ffccoolloorr   Restore previous fill color.
       ..ffccoolloorr _c Set fill color to _c.
       ..ffii       Enable filling of output lines; a pending output line is bro‐
                 ken.  Sets \\nn[[..uu]].
       ..ffll       Flush output buffer.
       ..ffpp _p_o_s _i_d
                 Mount font with font description file name _i_d at non‐negative
                 position _n.
       ..ffpp _p_o_s _i_d _f_o_n_t_‐_d_e_s_c_r_i_p_t_i_o_n_‐_f_i_l_e_‐_n_a_m_e
                 Mount font with _f_o_n_t_‐_d_e_s_c_r_i_p_t_i_o_n_‐_f_i_l_e_‐_n_a_m_e as name _i_d at non‐
                 negative position _n.
       ..ffsscchhaarr _f _c _a_n_y_t_h_i_n_g
                 Define fallback character (or glyph) _c for font _f  as  string
                 _a_n_y_t_h_i_n_g.
       ..ffssppeecciiaall _f_o_n_t
                 Reset list of special fonts for _f_o_n_t to be empty.
       ..ffssppeecciiaall _f_o_n_t _s_1 _s_2 ...
                 When the current font is _f_o_n_t, then the fonts _s_1, _s_2, ... are
                 special.
       ..fftt
       ..fftt PP     Select  previous  font  mounting  position (abstract style or
                 font); same as \\ff[[]] or \\ffPP.
       ..fftt _f_o_n_t  Select typeface _f_o_n_t_, which can be a mounting  position,  ab‐
                 stract style, or font name; same as \\ff[[_f_o_n_t]] escape sequence.
                 _f_o_n_t cannot be PP.
       ..ffttrr _f_o_n_t_1 _f_o_n_t_2
                 Translate _f_o_n_t_1 to _f_o_n_t_2.
       ..ffzzoooomm _f_o_n_t
       ..ffzzoooomm _f_o_n_t 00
                 Stop magnifying _f_o_n_t.
       ..ffzzoooomm _f_o_n_t _z
                 Set  zoom  factor  for  _f_o_n_t  to  _z (in thousandths; default:
                 1000).
       ..ggccoolloorr   Restore previous stroke color.
       ..ggccoolloorr _c Set stroke color to _c.
       ..hhcc       Reset the hyphenation character to \\%% (the default).
       ..hhcc _c_h_a_r  Change the hyphenation character to _c_h_a_r.
       ..hhccooddee _c_1 _c_o_d_e_1 [_c_2 _c_o_d_e_2] ...
                 Set the hyphenation code of character _c_1 to _c_o_d_e_1, that of _c_2
                 to _c_o_d_e_2, and so on.
       ..hhllaa _l_a_n_g Set the hyphenation language to _l_a_n_g.
       ..hhllmm _n    Set the maximum quantity of consecutive hyphenated  lines  to
                 _n.
       ..hhppff _p_a_t_t_e_r_n_‐_f_i_l_e
                 Read hyphenation patterns from _p_a_t_t_e_r_n_‐_f_i_l_e.
       ..hhppffaa _p_a_t_t_e_r_n_‐_f_i_l_e
                 Append hyphenation patterns from _p_a_t_t_e_r_n_‐_f_i_l_e.
       ..hhppffccooddee _a _b [_c _d] ...
                 Define  mappings  for  character codes in hyphenation pattern
                 files read with ..hhppff and ..hhppffaa.
       ..hhww _w_o_r_d ...
                 Define hyphenation overrides for each _w_o_r_d_; a hyphen “--”  in‐
                 dicates a hyphenation point.
       ..hhyy       Set automatic hyphenation mode to 11.
       ..hhyy 00     Disable automatic hyphenation; same as ..nnhh.
       ..hhyy _m_o_d_e  Set  automatic hyphenation mode to _m_o_d_e; see section “Hyphen‐
                 ation” below.
       ..hhyymm      Set the (right) hyphenation margin to 00 (the default).
       ..hhyymm _l_e_n_g_t_h
                 Set the (right) hyphenation margin to _l_e_n_g_t_h (default scaling
                 unit mm).
       ..hhyyss      Set the hyphenation space to 00 (the default).
       ..hhyyss _h_y_p_h_e_n_a_t_i_o_n_‐_s_p_a_c_e
                 Suppress automatic hyphenation in adjustment modes “bb” or “nn”
                 if the line can be justified with the addition of up  to  _h_y_‐
                 _p_h_e_n_a_t_i_o_n_‐_s_p_a_c_e  to  each  inter‐word  space (default scaling
                 unit mm).
       ..iiee _c_o_n_d_‐_e_x_p_r _a_n_y_t_h_i_n_g
                 If _c_o_n_d_‐_e_x_p_r is true, interpret _a_n_y_t_h_i_n_g as if it were an in‐
                 put line, otherwise skip to a corresponding ..eell request.
       ..iiff _c_o_n_d_‐_e_x_p_r _a_n_y_t_h_i_n_g
                 If _c_o_n_d_‐_e_x_p_r is true, then interpret _a_n_y_t_h_i_n_g as if  it  were
                 an input line.
       ..iigg       Ignore  input  (except  for side effects of \\RR on auto‐incre‐
                 menting registers) until “....” occurs at the start of  a  con‐
                 trol line in the current conditional block.
       ..iigg _e_n_d   Ignore  input  (except  for side effects of \\RR on auto‐incre‐
                 menting registers) until .._e_n_d is called at  the  start  of  a
                 control line in the current conditional block.
       ..iinn       Set indentation amount to previous value.
       ..iinn _±_N    Set indentation to _±_N (default scaling unit mm).
       ..iitt       Cancel any pending input line trap.
       ..iitt _n_p_l _n_a_m_e
                 Set (or replace) an input line trap in the environment, call‐
                 ing  macro  _n_a_m_e,  after  the next _n_p_l productive input lines
                 have been read.  Lines interrupted with  the  \\cc  escape  se‐
                 quence are counted separately.
       ..iittcc      Cancel any pending input line trap.
       ..iittcc _n_p_l _n_a_m_e
                 As  ..iitt,  except that input lines interrupted with the \\cc es‐
                 cape sequence are not counted.
       ..kkeerrnn     Enable pairwise kerning.
       ..kkeerrnn _n   If _n is zero, disable pairwise kerning, otherwise enable it.
       ..llcc       Unset leader repetition character.
       ..llcc _c     Set leader repetition character to _c (default: “..”).
       ..lleennggtthh _r_e_g _a_n_y_t_h_i_n_g
                 Compute the number of characters of _a_n_y_t_h_i_n_g  and  store  the
                 count in the register _r_e_g.
       ..lliinneettaabbss Enable  line‐tabs  mode  (calculate tab positions relative to
                 beginning of output line).
       ..lliinneettaabbss 00
                 Disable line‐tabs mode.
       ..llff _n     Set number of next input line to _n.
       ..llff _n _f_i_l_e
                 Set number of next input line to _n and  input  file  name  to
                 _f_i_l_e.
       ..llgg _m     Set  ligature  mode to _m (00 = disable, 11 = enable, 22 = enable
                 for two‐letter ligatures only).
       ..llll       Set line length to previous value.  Does not affect a pending
                 output line.
       ..llll _±_N    Set line length to _±_N (default length 6.5ii,  default  scaling
                 unit mm).  Does not affect a pending output line.
       ..llssmm      Unset  the  leading space macro (trap).  Restore default han‐
                 dling of lines with leading spaces.
       ..llssmm _n_a_m_e Set the leading space macro (trap) to _n_a_m_e.
       ..llss       Change to the previous value of additional intra‐line skip.
       ..llss _n     Set additional intra‐line skip value to _n,  i.e.,  _n-1  blank
                 lines are inserted after each text output line.
       ..lltt       Set length of title lines to previous value.
       ..lltt _±_N    Set length of title lines (default length 6.5ii, default scal‐
                 ing unit mm).
       ..mmcc       Cease writing margin character.
       ..mmcc _c     Begin  writing margin character _c to the right of each output
                 line.
       ..mmcc _c _d   Begin writing margin character _c on each output line at  dis‐
                 tance  _d  to  the right of the right margin (default distance
                 10pp, default scaling unit mm).
       ..mmkk       Mark vertical drawing position in an internal  register;  see
                 ..rrtt.
       ..mmkk _r_e_g_i_s_t_e_r
                 Mark vertical drawing position in _r_e_g_i_s_t_e_r.
       ..mmssoo _f_i_l_e As ..ssoo, except that _f_i_l_e is sought in the _t_m_a_c directories.
       ..mmssooqquuiieett _f_i_l_e
                 As ..mmssoo, but no warning is emitted if _f_i_l_e does not exist.
       ..nnaa       Disable output line adjustment.
       ..nnee       Break  page  if  distance  to next page location trap is less
                 than one vee.
       ..nnee _d     Break page if distance to next page  location  trap  is  less
                 than distance _d (default scaling unit vv).
       ..nnff       Disable  filling  of  output  lines; a pending output line is
                 broken.  Clears \\nn[[..uu]].
       ..nnhh       Disable automatic hyphenation; same as “..hhyy 00”.
       ..nnmm       Deactivate output line numbering.
       ..nnmm _±_N
       ..nnmm _±_N _m
       ..nnmm _±_N _m _s
       ..nnmm _±_N _m _s _i
                 Activate output line numbering: number the next  output  line
                 _±_N_, writing numbers every _m lines, with _s numeral widths (\\00)
                 between  the  line number and the output (default 1), and in‐
                 denting the line number by _i numeral widths (default 0).
       ..nnnn       Suppress numbering of the next output  line  to  be  numbered
                 with nnmm.
       ..nnnn _n     Suppress  numbering of the next _n output lines to be numbered
                 with nnmm.  If _n=0, cancel suppression.
       ..nnoopp _a_n_y_t_h_i_n_g
                 Interpret _a_n_y_t_h_i_n_g as if it were an input line.
       ..nnrr _r_e_g _±_N
                 Define or update register _r_e_g with value _N.
       ..nnrr _r_e_g _±_N _I
                 Define or update register _r_e_g with value _N and auto‐increment
                 _I.
       ..nnrrooffff    Make the conditional expressions nn true and tt false.
       ..nnss       Enable _n_o_‐_s_p_a_c_e _m_o_d_e, ignoring ..sspp requests until a glyph  or
                 \\DD primitive is output.  See ..rrss.
       ..nnxx       Immediately jump to end of current file.
       ..nnxx _f_i_l_e  Stop formatting current file and begin reading _f_i_l_e_.
       ..ooppeenn _s_t_r_e_a_m _f_i_l_e
                 Open  _f_i_l_e  for writing and associate the stream named _s_t_r_e_a_m
                 with it.  Unsafe request; disabled by default.
       ..ooppeennaa _s_t_r_e_a_m _f_i_l_e
                 As ..ooppeenn, but append to _f_i_l_e_.  Unsafe  request;  disabled  by
                 default.
       ..ooss       Output vertical distance that was saved by the ..ssvv request.
       ..oouuttppuutt _c_o_n_t_e_n_t_s
                 Emit _c_o_n_t_e_n_t_s directly to intermediate output, allowing lead‐
                 ing  whitespace  if  _s_t_r_i_n_g  starts with "" (which is stripped
                 off).
       ..ppcc       Reset page number character to ‘%%’.
       ..ppcc _c     Page number character.
       ..ppeevv      Report the state of the current environment followed by  that
                 of all other environments to the standard error stream.
       ..ppii _p_r_o_g_r_a_m
                 Pipe  output  to  _p_r_o_g_r_a_m (_n_r_o_f_f only).  Unsafe request; dis‐
                 abled by default.
       ..ppll       Set page length to default 11ii.  The current page  length  is
                 stored in register ..pp.
       ..ppll _±_N    Change page length to _±_N (default scaling unit vv).
       ..ppmm       Report,  to the standard error stream, the names and sizes in
                 bytes of defined macros, strings, and diversions.
       ..ppnn _±_N    Next page number _N.
       ..ppnnrr      Write the names and contents of all defined registers to  the
                 standard error stream.
       ..ppoo       Change  to  previous page offset.  The current page offset is
                 available in register ..oo.
       ..ppoo _±_N    Page offset _N.
       ..ppss       Return to previous type size.
       ..ppss _±_N    Set/increase/decrease the type size to/by _N scaled points  (a
                 non‐positive  resulting  type  size  is set to 1 u); also see
                 \\ss[[_±_N]].
       ..ppssbbbb _f_i_l_e
                 Retrieve the bounding box of the PostScript  image  found  in
                 _f_i_l_e_, which must conform to Adobe’s Document Structuring Con‐
                 ventions (DSC).  See registers llllxx, llllyy, uurrxx, uurryy.
       ..ppssoo _c_o_m_m_a_n_d_‐_l_i_n_e
                 Execute  _c_o_m_m_a_n_d_‐_l_i_n_e  with _p_o_p_e_n(3) and interpolate its out‐
                 put.  Unsafe request; disabled by default.
       ..ppttrr      Report names and positions of all page location traps to  the
                 standard error stream.
       ..ppvvss      Change to previous post‐vertical line spacing.
       ..ppvvss _±_N   Change  post‐vertical  line  spacing according to _±_N (default
                 scaling unit pp).
       ..rrcchhaarr _c_1 _c_2 ...
                 Remove definition of each ordinary or special  character  _c_1,
                 _c_2, ... defined by a ..cchhaarr, ..ffcchhaarr, or ..sscchhaarr request.
       ..rrdd _p_r_o_m_p_t
                 Read insertion.
       ..rreettuurrnn   Return from a macro.
       ..rreettuurrnn _a_n_y_t_h_i_n_g
                 Return  twice, namely from the macro at the current level and
                 from the macro one level higher.
       ..rrffsscchhaarr _f _c_1 _c_2 ...
                 Remove the font‐specific definitions of glyphs  _c_1,  _c_2,  ...
                 for font _f.
       ..rrjj _n_p_l   Break,  right‐align  the  output of the next productive input
                 line without filling, then break again.
       ..rrjj _n_p_l   Break, right‐align the output of the next _n_p_l productive  in‐
                 put  lines  without  filling,  then break again.  If _n_p_l ≤ 0,
                 stop right‐aligning.
       ..rrmm _n_a_m_e  Remove request, macro, diversion, or string _n_a_m_e.
       ..rrnn _o_l_d _n_e_w
                 Rename request, macro, diversion, or string _o_l_d to _n_e_w.
       ..rrnnnn _r_e_g_1 _r_e_g_2
                 Rename register _r_e_g_1 to _r_e_g_2.
       ..rrrr _i_d_e_n_t Remove register _i_d_e_n_t.
       ..rrss       Restore spacing; disable no‐space mode.  See ..nnss.
       ..rrtt       Return _(_u_p_w_a_r_d _o_n_l_y_) to vertical position marked  by  ..mmkk  on
                 the current page.
       ..rrtt _N     Return  _(_u_p_w_a_r_d _o_n_l_y_) to vertical position _N (default scaling
                 unit vv).
       ..sscchhaarr _c _c_o_n_t_e_n_t_s
                 Define global fallback character (or glyph) _c as _c_o_n_t_e_n_t_s.
       ..sshhcc      Reset the soft hyphen character to \\[[hhyy]].
       ..sshhcc _c    Set the soft hyphen character to _c.
       ..sshhiifftt _n  In a macro definition, left‐shift arguments by _n positions.
       ..ssiizzeess _s_1 _s_2 ... _s_n [00]
                 Set available type sizes similarly to the ssiizzeess directive  in
                 a  _D_E_S_C  file.   Each  _si  is  interpreted in units of scaled
                 points (zz).
       ..ssoo _f_i_l_e  Replace the request’s control line with the contents of _f_i_l_e,
                 “sourcing” it.
       ..ssooqquuiieett _f_i_l_e
                 As ..ssoo, but no warning is emitted if _f_i_l_e does not exist.
       ..sspp       Break and move the next text baseline down by one vee, or un‐
                 til springing a page location trap.
       ..sspp _d_i_s_t  Break and move the next text baseline down by _d_i_s_t, or  until
                 springing  a  page location trap (default scaling unit vv).  A
                 negative _d_i_s_t will not reduce the position of the text  base‐
                 line below zero.  Prefixing _d_i_s_t with the || operator moves to
                 a  position  relative to the page top for positive _N, and the
                 bottom if _N is negative; in all cases, one line height  (vee)
                 is added to _d_i_s_t.  _d_i_s_t is ignored inside a diversion.
       ..ssppeecciiaall  Reset global list of special fonts to be empty.
       ..ssppeecciiaall _s_1 _s_2 ...
                 Fonts  _s_1,  _s_2,  etc. are special and are searched for glyphs
                 not in the current font.
       ..sspprreeaaddwwaarrnn
                 Toggle the spread warning on and off  (the  default)  without
                 changing its value.
       ..sspprreeaaddwwaarrnn _N
                 Emit  a  bbrreeaakk  warning  if the additional space inserted for
                 each space between  words  in  an  adjusted  output  line  is
                 greater  than  or  equal to _N.  A negative _N is treated as 0.
                 The default scaling unit is mm.  At  startup,  ..sspprreeaaddwwaarrnn  is
                 inactive and _N is 3 m..
       ..ssss _n     Set  minimal  inter‐word spacing to _n 12ths of current font’s
                 space width.
       ..ssss _n _m   As “..ssss  _n”,  and  set  additional  inter‐sentence  space  to
                 _m 12ths of current font’s space width.
       ..ssttrriinnggddoowwnn _s_t_r_i_n_g_v_a_r
                 Replace each byte in the string named _s_t_r_i_n_g_v_a_r with its low‐
                 ercase version.
       ..ssttrriinngguupp _s_t_r_i_n_g_v_a_r
                 Replace  each byte in the string named _s_t_r_i_n_g_v_a_r with its up‐
                 percase version.
       ..ssttyy _n _s_t_y_l_e
                 Associate abstract _s_t_y_l_e with font position _n.
       ..ssuubbssttrriinngg _s_t_r _s_t_a_r_t [_e_n_d]
                 Replace the string named _s_t_r with its  substring  bounded  by
                 the indices _s_t_a_r_t and _e_n_d, inclusive.  Negative indices count
                 backwards from the end of the string.
       ..ssvv       As ..nnee, but save 1 v for output with ..ooss request.
       ..ssvv _d     As ..nnee, but save distance _d for later output with ..ooss request
                 (default scaling unit vv).
       ..ssyy _c_o_m_m_a_n_d_‐_l_i_n_e
                 Execute  _c_o_m_m_a_n_d_‐_l_i_n_e  with  _s_y_s_t_e_m(3).  Unsafe request; dis‐
                 abled by default.
       ..ttaa _n_1 _n_2 ... _nn TT _r_1 _r_2 ... _rn
                 Set tabs at positions _n_1, _n_2,  ...,  _nn,  then  set  tabs  at
                 _nn+_m×_rn+_r_1  through _nn+_m×_rn+_rn, where _m increments from 0, 1,
                 2, ... to the output line length.  Each  _n  argument  can  be
                 prefixed  with  a  “++” to place the tab stop _n_i at a distance
                 relative to the previous, _n(_i-1).  Each argument _n_i or _r_i can
                 be suffixed with a letter to align text within the tab column
                 bounded by tab stops _i and _i+1; “LL” for left‐aligned (the de‐
                 fault), “CC” for centered, and “RR” for right‐aligned.
       ..ttaagg
       ..ttaaggaa     Reserved for internal use.
       ..ttcc       Unset tab repetition character.
       ..ttcc _c     Set tab repetition character to _c (default: none).
       ..ttii _±_N    Temporarily indent next output line (default scaling unit mm).
       ..ttkkff _f_o_n_t _s_1 _n_1 _s_2 _n_2
                 Enable track kerning for _f_o_n_t.
       ..ttll ''_l_e_f_t''_c_e_n_t_e_r''_r_i_g_h_t''
                 Format three‐part title.
       ..ttmm _m_e_s_s_a_g_e
                 Write _m_e_s_s_a_g_e_, followed by a newline, to the  standard  error
                 stream.
       ..ttmm11 _m_e_s_s_a_g_e
                 As ..ttmm, but an initial neutral double quote in _m_e_s_s_a_g_e is re‐
                 moved, allowing it to contain leading spaces.
       ..ttmmcc _m_e_s_s_a_g_e
                 As ..ttmm11, without emitting a newline.
       ..ttrr _a_b_c_d...
                 Translate  ordinary or special characters _a to _b, _c to _d, and
                 so on prior to output.
       ..ttrrff _f_i_l_e Transparently output the contents of _f_i_l_e_.  Unlike  ..ccff,  in‐
                 valid input characters in _f_i_l_e are rejected.
       ..ttrriinn _a_b_c_d...
                 As  ..ttrr,  except that ..aasscciiiiffyy ignores the translation when a
                 diversion is interpolated.
       ..ttrrnntt _a_b_c_d...
                 As ..ttrr, except that translations are suppressed in the  argu‐
                 ment to \\!!.
       ..ttrrooffff    Make the conditional expressions tt true and nn false.
       ..uuff _f_o_n_t  Set underline font used by ..uull to _f_o_n_t_.
       ..uull       Underline  (italicize  in  _t_r_o_f_f mode) the output of the next
                 productive input line.
       ..uull _n_p_l   Underline (italicize in _t_r_o_f_f mode) the output  of  the  next
                 _n_p_l productive input line.  If _n_p_l=0, stop underlining.
       ..uunnffoorrmmaatt _d_i_v_e_r_s_i_o_n
                 Unformat  space  characters and tabs in _d_i_v_e_r_s_i_o_n, preserving
                 font information.
       ..vvpptt      Enable vertical position traps.
       ..vvpptt 00    Disable vertical position traps.
       ..vvss       Change to previous vertical spacing.
       ..vvss _±_N    Set vertical spacing to _±_N (default scaling unit pp).
       ..wwaarrnn     Enable all warning categories.
       ..wwaarrnn 00   Disable all warning categories.
       ..wwaarrnn _n   Enable warnings in categories  whose  codes  sum  to  _n;  see
                 _t_r_o_f_f(1).
       ..wwaarrnnssccaallee _s_u
                 Set scaling unit used in certain warnings to _s_u (one of uu, ii,
                 cc, pp, or PP; default: ii).
       ..wwhh _v_p_o_s  Remove  visible  page  location trap at _v_p_o_s (default scaling
                 unit vv).
       ..wwhh _v_p_o_s _n_a_m_e
                 Plant macro _n_a_m_e as page location trap at _v_p_o_s (default scal‐
                 ing unit vv), removing any visible trap already there.
       ..wwhhiillee _c_o_n_d_‐_e_x_p_r _a_n_y_t_h_i_n_g
                 Repeatedly execute _a_n_y_t_h_i_n_g unless and until _c_o_n_d_‐_e_x_p_r evalu‐
                 ates false.
       ..wwrriittee _s_t_r_e_a_m _a_n_y_t_h_i_n_g
                 Write _a_n_y_t_h_i_n_g to the stream named _s_t_r_e_a_m.
       ..wwrriitteecc _s_t_r_e_a_m _a_n_y_t_h_i_n_g
                 Similar to ..wwrriittee without emitting a final newline.
       ..wwrriitteemm _s_t_r_e_a_m _x_x
                 Write contents of macro or string  _x_x  to  the  stream  named
                 _s_t_r_e_a_m.

EEssccaappee sseeqquueennccee sshhoorrtt rreeffeerreennccee
       The  escape  sequences  \\"", \\##, \\$$, \\**, \\??, \\aa, \\ee, \\nn, \\tt, \\gg, \\VV, and
       \\_n_e_w_l_i_n_e are interpreted even in copy mode.

       \\""     Comment.  Everything up to the end of the line is ignored.
       \\##     Comment.  Everything up to and including the next newline is ig‐
              nored.
       \\**_s    Interpolate string with one‐character name _s.
       \\**((_s_t  Interpolate string with two‐character name _s_t.
       \\**[[_s_t_r_i_n_g]]
              Interpolate string with name _s_t_r_i_n_g (of arbitrary length).
       \\**[[_s_t_r_i_n_g _a_r_g ...]]
              Interpolate string with name _s_t_r_i_n_g (of arbitrary length),  tak‐
              ing _a_r_g ... as arguments.
       \\$$00    Interpolate name by which currently executing macro was invoked.
       \\$$_n    Interpolate macro or string parameter numbered _n (1≤_n≤9).
       \\$$((_n_n  Interpolate macro or string parameter numbered _n_n (01≤_n_n≤99).
       \\$$[[_n_n_n]]
              Interpolate macro or string parameter numbered _n_n_n (_n_n_n≥1).
       \\$$**    Interpolate  concatenation  of  all  macro or string parameters,
              separated by spaces.
       \\$$@@    Interpolate concatenation of all  macro  or  string  parameters,
              with each surrounded by double quotes and separated by spaces.
       \\$$^^    Interpolate  concatenation  of all macro or string parameters as
              if they were arguments to the ..ddss request.
       \\''     is a synonym for \\[[aaaa]], the acute accent special character.
       \\``     is a synonym for \\[[ggaa]], the grave accent special character.
       \\--     is a synonym for \\[[--]], the minus sign special character.
       \\__     is a synonym for \\[[uull]], the underrule special character.
       \\%%     Control hyphenation.
       \\!!     Transparent 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).
       \\??_a_n_y_t_h_i_n_g\\??
              Transparently embed _a_n_y_t_h_i_n_g, read in copy mode, in a diversion,
              or unformatted as an output comparand in a  conditional  expres‐
              sion.
       \\_s_p_a_c_e Move right one word space.
       \\~~     Insert an unbreakable, adjustable space.
       \\00     Move right by the width of a numeral in the current font.
       \\||     Move one‐sixth em to the right on typesetters.
       \\^^     Move one‐twelfth em to the right on typesetters.
       \\&&     Interpolate a dummy character.
       \\))     Interpolate a dummy character that is transparent to end‐of‐sen‐
              tence recognition.
       \\//     Apply  italic  correction.   Use between an immediately adjacent
              oblique glyph on the left and an upright glyph on the right.
       \\,,     Apply left italic correction.  Use between an immediately  adja‐
              cent  upright  glyph  on  the  left  and an oblique glyph on the
              right.
       \\::     Non‐printing break point (similar to \\%%, but  never  produces  a
              hyphen glyph).
       \\_n_e_w_l_i_n_e
              Continue current input line on the next.
       \\{{     Begin conditional input.
       \\}}     End conditional input.
       \\((_g_l   Interpolate glyph with two‐character name _g_l.
       \\[[_g_l_y_p_h]]
              Interpolate glyph with name _g_l_y_p_h (of arbitrary length).
       \\[[_b_a_s_e_‐_c_h_a_r _c_o_m_p ...]]
              Interpolate  composite glyph constructed from _b_a_s_e_‐_c_h_a_r and each
              component _c_o_m_p.
       \\[[cchhaarr_n_n_n]]
              Interpolate glyph of  eight‐bit  encoded  character  _n_n_n,  where
              0≤_n_n_n≤255.
       \\[[uu_n_n_n_n[_n[_n]]]]
              Interpolate   glyph   of   Unicode  character  with  code  point
              _n_n_n_n[_n[_n]] in uppercase hexadecimal.
       \\[[uu_b_a_s_e_‐_c_h_a_r[___c_o_m_b_i_n_i_n_g_‐_c_o_m_p_o_n_e_n_t]...]]
              Interpolate composite glyph from Unicode character _b_a_s_e_‐_c_h_a_r and
              _c_o_m_b_i_n_i_n_g_‐_c_o_m_p_o_n_e_n_t_s.
       \\aa     Interpolate a leader in copy mode.
       \\AA''_a_n_y_t_h_i_n_g''
              Interpolate 1 if _a_n_y_t_h_i_n_g is a valid identifier,  and  0  other‐
              wise.
       \\bb''_s_t_r_i_n_g''
              Build  bracket:  pile a sequence of glyphs corresponding to each
              character in _s_t_r_i_n_g vertically, and center it vertically on  the
              output line.
       \\BB''_a_n_y_t_h_i_n_g''
              Interpolate  1  if _a_n_y_t_h_i_n_g is a valid numeric expression, and 0
              otherwise.
       \\cc     Continue output line at next input line.
       \\CC''_g_l_y_p_h''
              As \\[[_g_l_y_p_h]], but compatible with other _t_r_o_f_f implementations.
       \\dd     Move downward ½ em on typesetters.
       \\DD''_d_r_a_w_i_n_g_‐_c_o_m_m_a_n_d''
              See subsection “Drawing commands” below.
       \\ee     Interpolate the escape character.
       \\EE     As \\ee, but not interpreted in copy mode.
       \\ffPP    Select previous font mounting position (abstract style or font);
              same as “..fftt” or “..fftt PP”.
       \\ff_F    Select font mounting position, abstract style, or font with one‐
              character name or one‐digit position _F.  _F cannot be PP.
       \\ff((_f_t  Select font mounting position, abstract style, or font with two‐
              character name or two‐digit position _f_t.
       \\ff[[_f_o_n_t]]
              Select font mounting position, abstract style, or font with  ar‐
              bitrarily long name or position _f_o_n_t.  _f_o_n_t cannot be PP.
       \\ff[[]]   Select previous font mounting position (abstract style or font).
       \\FF_f    Set default font family to that with one‐character name _f.
       \\FF((_f_m  Set default font family to that with two‐character name _f_m.
       \\FF[[_f_a_m]]
              Set default font family to that with arbitrarily long name _f_a_m.
       \\FF[[]]   Set default font family to previous value.
       \\gg_r    Interpolate format of register with one‐character name _r.
       \\gg((_r_g  Interpolate format of register with two‐character name _r_g.
       \\gg[[_r_e_g]]
              Interpolate format of register with arbitrarily long name _r_e_g.
       \\hh''_N''  Horizontally  move  the  drawing position by _N ems (or specified
              units); || may be used.  Positive motion is rightward.
       \\HH''_N''  Set height of current font to  _N  scaled  points  (or  specified
              units).
       \\kk_r    Mark horizontal position in one‐character register name _r.
       \\kk((_r_g  Mark horizontal position in two‐character register name _r_g.
       \\kk[[_r_e_g]]
              Mark  horizontal  position  in  register  with  arbitrarily long
              name _r_e_g.
       \\ll''_N[_c]''
              Draw horizontal line of length  _N  with  character  cc  (default:
              \\[[rruu]]; default scaling unit mm).
       \\LL''_N[_c]''
              Draw vertical line of length _N with character cc (default: \\[[bbrr]];
              default scaling unit vv).
       \\mm_c    Set stroke color to that with one‐character name _c.
       \\mm((_c_l  Set stroke color to that with two‐character name _c_l.
       \\mm[[_c_o_l_o_r]]
              Set stroke color to that with arbitrarily long name _c_o_l_o_r.
       \\mm[[]]   Restore previous stroke color.
       \\MM_c    Set fill color to that with one‐character name _c.
       \\MM((_c_l  Set fill color to that with two‐character name _c_l.
       \\MM[[_c_o_l_o_r]]
              Set fill color to that with arbitrarily long name _c_o_l_o_r.
       \\MM[[]]   Restore previous fill color.
       \\nn_r    Interpolate contents of register with one‐character name _r.
       \\nn((_r_g  Interpolate contents of register with two‐character name _r_g.
       \\nn[[_r_e_g]]
              Interpolate contents of register with arbitrarily long name _r_e_g.
       \\NN''_n''  Interpolate glyph with index _n in the current font.
       \\oo''_a_b_c...''
              Overstrike centered glyphs of characters _a, _b, _c, and so on.
       \\OO00    At  the  outermost suppression level, disable emission of glyphs
              and geometric objects to the output driver.
       \\OO11    At the outermost suppression level, enable  emission  of  glyphs
              and geometric objects to the output driver.
       \\OO22    At  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 \\OO escape  sequence,
              the page offset, line length, image file name (if any), horizon‐
              tal and vertical device motion quanta, and input file name.
       \\OO33    Begin a nested suppression level.
       \\OO44    End a nested suppression level.
       \\OO[[55_P_f_i_l_e]]
              At  the  outermost suppression level, write the name _f_i_l_e to the
              standard error stream at position _P, which must be one of ll,  rr,
              cc, or ii.
       \\pp     Break output line at next word boundary; adjust if applicable.
       \\rr     Move “in reverse” (upward) 1 em.
       \\RR''_n_a_m_e _±_N''
              Set, increment, or decrement register _n_a_m_e by _N.
       \\ss_±_N   Set/increase/decrease  the  type  size to/by _N scaled points.  _N
              must be a single digit; 0 restores the previous type size.   (In
              compatibility  mode  only,  a  non‐zero  _N  must be in the range
              4–39.)  Otherwise, as ..ppss request.
       \\ss((_±_N
       \\ss_±((_N  Set/increase/decrease the type size to/by _N scaled points; _N  is
              a two‐digit number ≥1.  As ..ppss request.
       \\ss[[_±_N]]
       \\ss_±[[_N]]
       \\ss''_±_N''
       \\ss_±''_N'' Set/increase/decrease  the  type size to/by _N scaled points.  As
              ..ppss request.
       \\SS''_N''  Slant output glyphs by _N degrees; the direction of text flow  is
              positive.
       \\tt     Interpolate a tab in copy mode.
       \\uu     Move upward ½ em on typesetters.
       \\vv''_N''  Vertically  move  the  drawing  position by _N vees (or specified
              units); || may be used.  Positive motion is downward.
       \\VV_e    Interpolate contents of environment variable with  one‐character
              name _e.
       \\VV((_e_v  Interpolate  contents of environment variable with two‐character
              name _e_v.
       \\VV[[_e_n_v]]
              Interpolate contents of environment  variable  with  arbitrarily
              long name _e_n_v.
       \\ww''_a_n_y_t_h_i_n_g''
              Interpolate width of _a_n_y_t_h_i_n_g, formatted in a dummy environment.
       \\xx''_N''  Increase  vertical  spacing of pending output line by _N vees (or
              specified units; negative before, positive after).
       \\XX''_a_n_y_t_h_i_n_g''
              Write _a_n_y_t_h_i_n_g to _t_r_o_f_f output  as  a  device  control  command.
              Within _a_n_y_t_h_i_n_g, the escape sequences \\&&, \\)), \\%%, and \\:: are ig‐
              nored;  \\_s_p_a_c_e  and \\~~ are converted to single space characters;
              and \\\\ has its escape character stripped.   So  that  the  basic
              Latin  subset  of  the Unicode character set can be reliably en‐
              coded in _a_n_y_t_h_i_n_g_, the special character  escape  sequences  \\--,
              \\[[aaqq]], \\[[ddqq]], \\[[ggaa]], \\[[hhaa]], \\[[rrss]], and \\[[ttii]] are mapped to basic
              Latin  characters;  see _g_r_o_f_f___c_h_a_r(7).  For this transformation,
              character translations and special character definitions are ig‐
              nored.
       \\YY_n    Write contents of macro or string _n to _t_r_o_f_f output as a  device
              control command.
       \\YY((_n_m  Write contents of macro or string _n_m to _t_r_o_f_f output as a device
              control command.
       \\YY[[_n_a_m_e]]
              Write  contents of macro or string _n_a_m_e to _t_r_o_f_f output as a de‐
              vice control command.
       \\zz_c    Format character _c with zero width—without advancing the drawing
              position.
       \\ZZ''_a_n_y_t_h_i_n_g''
              Save the drawing position, format _a_n_y_t_h_i_n_g, then restore it.

   DDrraawwiinngg ccoommmmaannddss
       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 _t_r_o_f_f draws stroked (outlined) ob‐
       jects with the stroke color, and  shades  filled  ones  with  the  fill
       color.  See section “Colors” above.  Coordinates _h and _v 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 mm; for vertical ones, vv.

       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 \\DD''tt'').

       \\DD''~~ _h_1 _v_1 ... _h_n _v_n''
              Draw  B‐spline  to each point in sequence, leaving drawing posi‐
              tion at (_h_n, _v_n).
       \\DD''aa _h_c _v_c _h _v''
              Draw circular arc centered at (_h_c, _v_c) counterclockwise from the
              drawing position to a point  (_h,  _v)  relative  to  the  center.
              (_h_c,  _v_c) is adjusted to the point nearest the perpendicular bi‐
              sector of the arc’s chord.
       \\DD''cc _d''
              Draw circle of diameter _d with its leftmost point at the drawing
              position.
       \\DD''CC _d''
              As \\DD''CC'', but the circle is filled.
       \\DD''ee _h _v''
              Draw ellipse of width _h and height _v with its leftmost point  at
              the drawing position.
       \\DD''EE _h _v''
              As \\DD''ee'', but the ellipse is filled.
       \\DD''ll _h _v''
              Draw line from the drawing position to (_h, _v).
       \\DD''pp _h_1 _v_1 ... _h_n _v_n''
              Draw polygon with vertices at drawing position and each point in
              sequence.   GNU  _t_r_o_f_f closes the polygon by drawing a line from
              (_h_n, _v_n) back to the initial drawing position.   Afterward,  the
              drawing position is left at (_h_n, _v_n).
       \\DD''PP _h_1 _v_1 ... _h_n _v_n''
              As \\DD''pp'', but the polygon is filled.
       \\DD''tt _n''
              Set  stroke  thickness of geometric objects to to _n basic units.
              A zero _n selects the minimal supported thickness.  A negative  _n
              selects  a  thickness proportional to the type size; this is the
              default.

   DDeevviiccee ccoonnttrrooll ccoommmmaannddss
       The ..ddeevviiccee and ..ddeevviicceemm requests, and \\XX and \\YY escape sequences,  en‐
       able  documents to pass information directly to a postprocessor.  These
       are useful for exercising device‐specific capabilities that  the  _g_r_o_f_f
       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.

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

       \*[..TT]    Contains  the  name of the output device (for example, “uuttff88”
                 or “ppddff”))..

       The ..ddss request creates a string with a specified  name  and  contents.
       If  the  identifier named by ..ddss already exists as an alias, the target
       of the alias is redefined.  If ..ddss is called with  only  one  argument,
       the  named string becomes empty.  Otherwise, _t_r_o_f_f stores the remainder
       of the control line in copy mode; see subsection “Copy mode” below.

       The \\** escape 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 “mmaacc” is emitted.  See  sec‐
       tion  “Warnings” in _t_r_o_f_f(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  ]]  occurs in a string argument, that argument must be enclosed
       in double quotes.  \\** is 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 "" in the string contents is stripped to
       allow  embedding  of leading spaces.  Any other "" is interpreted liter‐
       ally, but it is wise to use the special character escape sequence \\[[ddqq]]
       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.  \\_n_e_w_l_i_n_e works just as it does elsewhere.
       The resulting string is stored _w_i_t_h_o_u_t 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 \\**
       to interpolate a macro instead.

       The ..aass request is similar to ..ddss but appends to a  string  instead  of
       redefining  it.   If ..aass is 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  _t_r_o_f_f compatibility mode enablement when interpolated; see
       section “Compatibility mode” below.  The ..ddss11 request defines a  string
       that suspends compatibility mode when the string is later interpolated.
       ..aass11 is likewise similar to ..aass, with compatibility mode suspended when
       the appended portion of the string is later interpolated.

       CCaauuttiioonn::  Unlike  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  (..lleennggtthh)  and  modified  (..cchhoopp,  ..ssuubbssttrriinngg,
       ..ssttrriinngguupp, ..ssttrriinnggddoowwnn), and their names can be manipulated through re‐
       naming, removal, and aliasing (..rrnn, ..rrmm, ..aallss))..

       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 rrmm request on its name
       first.

RReeggiisstteerrss
       In the _r_o_f_f language, numbers can be stored in _r_e_g_i_s_t_e_r_s_.  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 nnrr request or the \\RR
       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 ..nnrr request, and a special  interpo‐
       lation  syntax,  \\nn_±  is used to alter and then retrieve the register’s
       value.  Together, these features are called _a_u_t_o_‐_i_n_c_r_e_m_e_n_t.   (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 \\nn[[_n_a_m_e]] is used to refer to  a
       register  _n_a_m_e to clearly distinguish it from a string or request _n_a_m_e.
       The register name space  is  separate  from  that  used  for  requests,
       macros,  strings,  and  diversions.  Bear in mind that the symbols \\nn[[]]
       are _n_o_t part of the register name.

   RReeaadd‐‐oonnllyy rreeggiisstteerrss
       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[..$$]         Count of  arguments  passed  to  currently  interpolated
                      macro or string.
       \n[..aa]         Amount of extra post‐vertical line space; see \\xx.
       \n[..AA]         Approximate  output is being formatted (Boolean‐valued);
                      see _t_r_o_f_f --aa option.
       \n[..bb]         Font emboldening offset; see ..bbdd.
       \n[..bbrr]        The normal control character was used to call  the  cur‐
                      rently interpolated macro (Boolean‐valued).
       \n[..cc]         Input line number; see ..llff and register “cc..”.
       \n[..CC]         Compatibility mode is enabled (Boolean‐valued); see ..ccpp.
                      Always false when processing ..ddoo; see register ..ccpp.
       \n[..ccddpp]       Depth  of last glyph formatted in the environment; posi‐
                      tive if glyph extends below the baseline.
       \n[..ccee]        Count of output lines remaining to be centered.
       \n[..cchhtt]       Height of last glyph formatted in the environment; posi‐
                      tive if glyph extends above the baseline.
       \n[..ccoolloorr]     Color output is enabled (Boolean‐valued).
       \n[..ccpp]        Within ..ddoo, the saved value of compatibility  mode;  see
                      register ..CC.
       \n[..ccsskk]       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[..dd]         Vertical drawing position in diversion.
       \n[..eevv]        Name of environment (string‐valued).
       \n[..ff]         Mounting position of selected font; see ..fftt and \\ff.
       \n[..FF]         Name of input file (string‐valued); see ..llff.
       \n[..ffaamm]       Name of default font family (string‐valued).
       \n[..ffnn]        Resolved name of selected font (string‐valued); see  ..fftt
                      and \\ff.
       \n[..ffpp]        Next non‐zero free font mounting position index.
       \n[..gg]         Always true in GNU _t_r_o_f_f (Boolean‐valued).
       \n[..hh]         Text baseline high‐water mark on page or in diversion.
       \n[..HH]         Horizontal  motion  quantum  of  output  device in basic
                      units.
       \n[..hheeiigghhtt]    Font height; see \\HH.
       \n[..hhllaa]       Hyphenation language in environment (string‐valued).
       \n[..hhllcc]       Count of immediately  preceding  consecutive  hyphenated
                      lines in environment.
       \n[..hhllmm]       Maximum quantity of consecutive hyphenated lines allowed
                      in environment.
       \n[..hhyy]        Automatic hyphenation mode in environment.
       \n[..hhyymm]       Hyphenation margin in environment.
       \n[..hhyyss]       Hyphenation space adjustment threshold in environment.
       \n[..ii]         Indentation amount; see ..iinn.
       \n[..iinn]        Indentation  amount  applicable  to  the  pending output
                      line; see ..ttii.
       \n[..iinntt]       Previous output line was “interrupted” or continued with
                      \\cc (Boolean‐valued).
       \n[..jj]         Adjustment mode encoded as an integer; see ..aadd and  ..nnaa.
                      Do not interpret or perform arithmetic on its value.
       \n[..kk]         Horizontal drawing position relative to indentation.
       \n[..kkeerrnn]      Pairwise kerning is enabled (Boolean‐valued).
       \n[..ll]         Line length; see ..llll.
       \n[..LL]         Line spacing; see ..llss.
       \n[..llgg]        Ligature mode.
       \n[..lliinneettaabbss]  Line‐tabs mode is enabled (Boolean‐valued).
       \n[..llll]        Line length applicable to the pending output line.
       \n[..lltt]        Title length.
       \n[..mm]         Stroke color (string‐valued); see ..ggccoolloorr and \\mm.  Empty
                      if the stroke color is the default.
       \n[..MM]         Fill  color  (string‐valued); see ..ffccoolloorr and \\MM.  Empty
                      if the fill color is the default.
       \n[..nn]         Length of formatted output on previous output line.
       \n[..nnee]        Amount of vertical  space  required  by  last  ..nnee  that
                      caused a trap to be sprung; also see register ..ttrruunncc.
       \n[..nnmm]        Output line numbering is enabled (Boolean‐valued).
       \n[..nnnn]        Count  of  output lines remaining to have numbering sup‐
                      pressed.
       \n[..nnss]        No‐space mode is enabled (Boolean‐valued).
       \n[..oo]         Page offset; see ..ppoo.
       \n[..OO]         Output suppression nesting level; see \\OO.
       \n[..pp]         Page length; see ..ppll.
       \n[..PP]         The page is selected for  output  (Boolean‐valued);  see
                      _t_r_o_f_f --oo option.
       \n[..ppee]        Page ejection is in progress (Boolean‐valued).
       \n[..ppnn]        Number of the next page.
       \n[..ppss]        Type size in scaled points.
       \n[..ppssrr]       Most  recently requested type size in scaled points; see
                      ..ppss and \\ss.
       \n[..ppvvss]       Post‐vertical line spacing.
       \n[..RR]         Count of available unused registers;  always  10,000  in
                      GNU _t_r_o_f_f.
       \n[..rrjj]        Count of lines remaining to be right‐aligned.
       \n[..ss]         Type  size  in points as a decimal fraction (string‐val‐
                      ued); see ..ppss and \\ss.
       \n[..ssllaanntt]     Slant of font in degrees; see \\SS.
       \n[..ssrr]        Most recently requested type size in points as a decimal
                      fraction (string‐valued); see ..ppss and \\ss.
       \n[..ssss]        Size of minimal inter‐word  space  in  twelfths  of  the
                      space width of the selected font.
       \n[..ssssss]       Size  of  additional inter‐sentence space in twelfths of
                      the space width of the selected font.
       \n[..ssttyy]       Selected abstract style (string‐valued); see ..fftt and \\ff.
       \n[..tt]         Distance to next vertical position  trap;  see  ..wwhh  and
                      ..cchh.
       \n[..TT]         An  output  device was explicitly selected (Boolean‐val‐
                      ued); see _t_r_o_f_f --TT option.
       \n[..ttaabbss]      Representation of tab settings suitable for use as argu‐
                      ment to ..ttaa (string‐valued).
       \n[..ttrruunncc]     Amount of vertical space truncated by the most  recently
                      sprung  vertical  position  trap,  or,  if  the trap was
                      sprung by an ..nnee, minus the amount  of  vertical  motion
                      produced by ..nnee; also see register ..nnee.
       \n[..uu]         Filling is enabled (Boolean‐valued); see ..ffii and ..nnff.
       \n[..UU]         Unsafe  mode  is  enabled (Boolean‐valued); see _t_r_o_f_f --UU
                      option.
       \n[..vv]         Vertical line spacing; see ..vvss.
       \n[..VV]         Vertical motion quantum of the output  device  in  basic
                      units.
       \n[..vvpptt]       Vertical position traps are enabled (Boolean‐valued).
       \n[..ww]         Width of previous glyph formatted in the environment.
       \n[..wwaarrnn]      Sum of the numeric codes of enabled warning categories.
       \n[..xx]         Major version number of the running _t_r_o_f_f formatter.
       \n[..yy]         Minor version number of the running _t_r_o_f_f formatter.
       \n[..YY]         Revision number of the running _t_r_o_f_f formatter.
       \n[..zz]         Name  of  diversion (string‐valued).  Empty if output is
                      directed to the top‐level diversion.
       \n[..zzoooomm]      Zoom multiplier of current font (in thousandths; zero if
                      no magnification); see ..ffzzoooomm.

   WWrriittaabbllee pprreeddeeffiinneedd rreeggiisstteerrss
       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
       _l_o_c_a_l_t_i_m_e(3) when the formatter launches.  This initialization  can  be
       overridden  by  _S_O_U_R_C_E___D_A_T_E___E_P_O_C_H  and _T_Z; see section “Environment” of
       _g_r_o_f_f(1).

       \n[$$$$]         Process ID of _t_r_o_f_f.
       \n[%%]          Page number.
       \n[cc..]         Input line number.
       \n[cctt]         Union of character types of  each  glyph  rendered  into
                      dummy environment by \\ww.
       \n[ddll]         Width of last closed diversion.
       \n[ddnn]         Height of last closed diversion.
       \n[ddww]         Day of the week (1–7; 1 is Sunday).
       \n[ddyy]         Day of the month (1–31).
       \n[hhoouurrss]      Count of hours elapsed since midnight (0–23).
       \n[hhpp]         Horizontal  drawing  position relative to start of input
                      line.
       \n[llllxx]        Lower‐left _x coordinate (in PostScript units)  of  Post‐
                      Script image; see ..ppssbbbb.
       \n[llllyy]        Lower‐left  _y  coordinate (in PostScript units) of Post‐
                      Script image; see ..ppssbbbb.
       \n[llnn]         Output line number; see ..nnmm.
       \n[llssnn]        Count of leading spaces on input line.
       \n[llssss]        Amount of  horizontal  space  corresponding  to  leading
                      spaces on input line.
       \n[mmiinnuutteess]    Count of minutes elapsed in the hour (0–59).
       \n[mmoo]         Month of the year (1–12).
       \n[nnll]         Vertical drawing position.
       \n[ooppmmaaxxxx]
       \n[ooppmmaaxxyy]
       \n[ooppmmiinnxx]
       \n[ooppmmiinnyy]     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 \\OO00
                      or \\OO11.
       \n[rrssbb]        As register ssbb, adding maximum glyph height to  measure‐
                      ment.
       \n[rrsstt]        As  register  sstt, adding maximum glyph depth to measure‐
                      ment.
       \n[ssbb]         Maximum displacement of text baseline below its original
                      position after rendering into dummy environment by \\ww.
       \n[sseeccoonnddss]    Count of seconds elapsed in the minute (0–60).
       \n[sskkww]        Skew of last glyph rendered into  dummy  environment  by
                      \\ww.
       \n[sslliimmiitt]     The  maximum  depth of _t_r_o_f_f’s internal input stack.  If
                      ≤0, there is no  limit:  recursion  can  continue  until
                      available memory is exhausted.  The default is 1,000.
       \n[sssscc]        Subscript  correction  of last glyph rendered into dummy
                      environment by \\ww.
       \n[sstt]         Maximum displacement of text baseline above its original
                      position after rendering into dummy environment by \\ww.
       \n[ssyyssttaatt]     Return value of _s_y_s_t_e_m_(_) function; see ..ssyy.
       \n[uurrxx]        Upper‐right _x coordinate (in PostScript units) of  Post‐
                      Script image; see ..ppssbbbb.
       \n[uurryy]        Upper‐right  _y coordinate (in PostScript units) of Post‐
                      Script image; see ..ppssbbbb.
       \n[yyeeaarr]       Gregorian year.
       \n[yyrr]         Gregorian year minus 1900.

UUssiinngg ffoonnttss
       In digital typography, a _f_o_n_t 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 _g_r_o_f_f lljj44 device’s
       Lineprinter, and llbbpp’s Courier and Elite faces.)  A _r_o_f_f formatter  can
       change  typefaces  at any point in the text.  The basic faces are a set
       of _s_t_y_l_e_s combining upright and slanted shapes with  normal  and  heavy
       stroke  weights:  “RR”,  “II”, “BB”, and “BBII”—these stand for _r_o_m_a_n_, _b_o_l_d_,
       _i_t_a_l_i_c_, and _b_o_l_d_‐_i_t_a_l_i_c_.  For linguistic text, GNU _t_r_o_f_f  groups  type‐
       faces  into  _f_a_m_i_l_i_e_s containing each of these styles.  (Font designers
       prepare families such that the styles share  esthetic  properties.)   A
       _t_e_x_t _f_o_n_t is thus often a family combined with a style, but it need not
       be:  consider  the  ppss  and  ppddff  devices’  ZZCCMMII  (Zapf Chancery Medium
       italic)—often, no other style of Zapf Chancery Medium is provided.   On
       typesetting devices, at least one _s_p_e_c_i_a_l _f_o_n_t is available, comprising
       _u_n_s_t_y_l_e_d glyphs for mathematical operators and other purposes.

       Like AT&T _t_r_o_f_f_, GNU _t_r_o_f_f does not itself load or manipulate a digital
       font  file;  instead it works with a _f_o_n_t _d_e_s_c_r_i_p_t_i_o_n _f_i_l_e that charac‐
       terizes it, including its glyph repertoire and the _m_e_t_r_i_c_s (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 _m_o_u_n_t_i_n_g _p_o_s_i_t_i_o_n_, 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 _t_r_o_f_f 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 _r_e_s_o_l_v_e_d _f_o_n_t _n_a_m_e_.

       Fonts often have trademarked names, and even Free  Software  fonts  can
       require  renaming upon modification.  _g_r_o_f_f maintains a convention that
       a device’s serif font family is given the name TT (“Times”),  its  sans‐
       serif  family HH (“Helvetica”), and its monospaced family CC (“Courier”).
       Historical inertia has driven _g_r_o_f_f’s font identifiers to short  upper‐
       case  abbreviations  of font names, as with TTRR, TTBB, TTII, TTBBII, and a spe‐
       cial font SS.

       The default family used with abstract styles  can  be  changed  at  any
       time;  initially,  it is TT.  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 11 (RR).  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 _g_r_a_p_h_i_c _r_e_n_d_i_t_i_o_n_s (character cell attributes).

HHyypphheennaattiioonn
       When  filling,  _g_r_o_f_f  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 \\%%  and  non‐printing
       break  point \\:: escape sequences may be used to control the hyphenation
       and breaking of individual words.  The ..hhww  request  sets  user‐defined
       hyphenation  points  for  specified words at any subsequent occurrence.
       Otherwise, _g_r_o_f_f determines hyphenation  points  automatically  by  de‐
       fault.

       Several  requests influence automatic hyphenation.  Because conventions
       vary, a variety of hyphenation modes is available to the  ..hhyy  request;
       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 “11” for  his‐
       torical  reasons,  but this is not an appropriate value for the English
       hyphenation patterns used by _g_r_o_f_f; localization macro files loaded  by
       _t_r_o_f_f_r_c and macro packages often override it.

       00      disables hyphenation.

       11      enables  hyphenation  except after the first and before the last
              character of a word.

       The remaining values “imply” 11; that is, they enable hyphenation  under
       the  same  conditions  as  “..hhyy 11”, and then apply or lift restrictions
       relative to that basis.

       22      disables 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.)

       44      disables hyphenation before the last two characters of a word.

       88      disables hyphenation after the first two characters of a word.

       1166     enables hyphenation before the last character of a word.

       3322     enables hyphenation after the first character of a word.

       Apart  from  value  2, restrictions imposed by the hyphenation mode are
       _n_o_t respected for words whose hyphenations have been specified with the
       hyphenation character (“\\%%” by default) or the ..hhww request.

       Nonzero values are additive.  For example, mode 12 causes _g_r_o_f_f 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 (..hhllaa, ..hhppff, and ..hhppffaa) and lettercase
       relationships (..hhccooddee and ..hhppffccooddee).   Furthermore,  hyphenation  of  a
       word might be suppressed due to a limit on consecutive hyphenated lines
       (..hhllmm), a minimum line length threshold (..hhyymm), or because the line can
       instead be adjusted with additional inter‐word space (..hhyyss).

LLooccaalliizzaattiioonn
       The set of hyphenation patterns is associated with the hyphenation lan‐
       guage  set by the ..hhllaa request.  The ..hhppff request is usually invoked by
       a localization file loaded by the _t_r_o_f_f_r_c file.  _g_r_o_f_f provides  local‐
       ization files for several languages; see _g_r_o_f_f___t_m_a_c(5).

WWrriittiinngg mmaaccrrooss
       The  ..ddee  request 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.  _t_r_o_f_f enters “copy mode” (see below), storing
       subsequent input lines as the definition.  If the optional second argu‐
       ment  is  not specified, the definition ends with the control line “....”
       (two dots).  Alternatively, a second argument names a macro whose  call
       syntax  ends  the definition; this “end macro” is then called normally.
       Spaces or tabs are permitted after the first control character  in  the
       line  containing this ending token, but a tab immediately after the to‐
       ken 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  de‐
       fined  until it is called.  This fact enables a nested macro definition
       to begin inside one macro and end inside another.

       Variants of ..ddee disable compatibility mode and/or indirect the names of
       the macros specified for definition or  termination:  these  are  ..ddee11,
       ..ddeeii, and ..ddeeii11.  Append to macro definitions with ..aamm, ..aamm11, ..aammii, and
       ..aammii11.  The ..aallss, ..rrmm, and ..rrnn requests create an alias of, remove, and
       rename  a  macro, respectively.  ..rreettuurrnn stops the execution of a macro
       immediately, returning to the enclosing context.

   PPaarraammeetteerrss
       Macro call and string interpolation parameters can  be  accessed  using
       escape  sequences  starting  with  “\\$$”.  The \\nn[[..$$]] read‐only register
       stores the count of parameters available to  a  macro  or  string;  its
       value  can  be changed by the ..sshhiifftt request, which dequeues parameters
       from the current list.  The \\$$00 escape sequence interpolates  the  name
       by  which a macro was called.  Applying string interpolation to a macro
       does not change this name.

   CCooppyy mmooddee
       When _t_r_o_f_f processes certain requests, most importantly those which de‐
       fine or append to a macro or string, it does so in _c_o_p_y _m_o_d_e: it copies
       the characters of the definition into a dedicated storage  region,  in‐
       terpolating  the  escape sequences \\nn, \\gg, \\$$, \\**, \\VV, and \\?? normally;
       interpreting \\_n_e_w_l_i_n_e immediately; discarding comments \\"" and  \\##;  in‐
       terpolating  the  current leader, escape, or tab character with \\aa, \\ee,
       and \\tt, respectively; and storing all other escape sequences in an  en‐
       coded  form.   The  complement of copy mode—a _r_o_f_f 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 _i_n_t_e_r_p_r_e_‐
       _t_a_t_i_o_n _m_o_d_e.

       The escape character, \\ by default, can escape  itself.   This  enables
       you  to  control  whether  a given \\nn, \\gg, \\$$, \\**, \\VV, or \\?? escape se‐
       quence is interpreted at the time the macro containing it  is  defined,
       or later when the macro is called.

       You  can think of \\\\ as a “delayed” backslash; it is the escape charac‐
       ter followed by a backslash from which the escape character has removed
       its special meaning.  Consequently, \\\\ is not an escape sequence in the
       usual sense.  In any escape sequence \\_X that _t_r_o_f_f does not  recognize,
       the  escape  character is ignored and _X is output.  An unrecognized es‐
       cape sequence causes a warning in category “eessccaappee”,  with  two  excep‐
       tions,  \\\\ being one.  The other is \\.., 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.  _r_o_f_f  documents  should
       not  use  the  \\\\  or \\.. character sequences outside of copy mode; they
       serve only to obfuscate the input.  Use  \\ee  to  represent  the  escape
       character,  \\[[rrss]]  to  obtain  a backslash glyph, and \\&& before .. and ''
       where _t_r_o_f_f expects them as control characters if you mean to use  them
       literally.

       Macro  definitions can be nested to arbitrary depth.  In “\\\\”, 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 \\nn, \\gg, \\$$, \\**, \\VV, and  \\??  at
       each  nesting  level.  An alternative is to use \\EE, which represents an
       escape character that is not interpreted in copy mode.  Because  \\..  is
       not  a true escape sequence, we can’t use \\EE to keep “....” from ending a
       macro definition prematurely.  If the multiplicity of backslashes  com‐
       plicates maintenance, use end macros.

TTrraappss
       _T_r_a_p_s  are  locations  in  the output, or conditions on the input that,
       when reached or fulfilled, call a specified macro.  A _v_e_r_t_i_c_a_l _p_o_s_i_t_i_o_n
       _t_r_a_p 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 (..wwhh, ..cchh); at a
       given location in the current diversion (..ddtt)—together, these are known
       as vertical position  traps,  which  can  be  disabled  and  re‐enabled
       (..vvpptt).

       A diversion is not formatted in the context of a page, so it lacks page
       location  traps; instead it can have a _d_i_v_e_r_s_i_o_n _t_r_a_p_.  There can exist
       at most one such vertical position trap per diversion.

       Other kinds of trap can be planted at a blank line (..bbllmm);  at  a  line
       with leading space characters (..llssmm); after a certain number of produc‐
       tive  input  lines  (..iitt,  ..iittcc); or at the end of input (..eemm).  Macros
       called by traps are passed no arguments.  Setting a trap is also called
       _p_l_a_n_t_i_n_g one.  It is said that a trap is _s_p_r_u_n_g  if  its  condition  is
       fulfilled.

       Registers  associated  with  trap  management include vertical position
       trap enablement status (\\nn[[..vvpptt]]), distance to the next trap  (\\nn[[..tt]]),
       amount of needed (..nnee‐requested) space that caused the most recent ver‐
       tical  position  trap  to  be  sprung (\\nn[[..nnee]]), amount of needed space
       truncated from the amount requested (\\nn[[..ttrruunncc]]), page ejection  status
       (\\nn[[..ppee]]),  and  leading  space count (\\nn[[..llssnn]]) with its corresponding
       amount of motion (\\nn[[..llssss]]).

   PPaaggee llooccaattiioonn ttrraappss
       A _p_a_g_e _l_o_c_a_t_i_o_n _t_r_a_p is a vertical position trap that  applies  to  the
       page;  that is, to undiverted output.  Many can be present; manage them
       with the wwhh and cchh requests.   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  _v_i_s_i_b_l_e  trap (see below) at the same location is removed; this is
       ..wwhh’s sole function if its second argument is missing.

       A trap is sprung only if it is _v_i_s_i_b_l_e_, 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 _c_u_r_r_e_n_t page length; they are not converted to an absolute ver‐
       tical position.  Use ..ppttrr to dump page location traps to  the  standard
       error stream; their positions are reported in basic units.

   TThhee iimmpplliicciitt ppaaggee ttrraapp
       An  _i_m_p_l_i_c_i_t  _p_a_g_e  _t_r_a_p  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  wwhh or cchh requests.  You cannot hide it by
       placing another trap at its location, and can move it only by  redefin‐
       ing  the page length with ..ppll.  Its operation is suppressed when verti‐
       cal page traps are disabled with the vvpptt request.

DDiivveerrssiioonnss
       In _r_o_f_f systems it is possible to format text as if for output, but in‐
       stead of writing it immediately, one can _d_i_v_e_r_t 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  _d_i_v_e_r_‐
       _s_i_o_n_s 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 _u_n_f_o_r_m_a_t_t_e_d  input  text,
       and the latter capture _f_o_r_m_a_t_t_e_d 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 _t_r_o_f_f is in the
       _t_o_p_‐_l_e_v_e_l _d_i_v_e_r_s_i_o_n 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 mmaacc to be emitted.   (see  section
       “Warnings” in _t_r_o_f_f(1)).  A diversion does not exist for the purpose of
       testing  with  the  dd conditional operator until its initial definition
       ends (see subsection “Conditional expressions” above).

       The ddii request creates a diversion, including any  partially  collected
       line.   ddaa  appends 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.
       bbooxx and bbooxxaa works 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 ..dd, ..zz, ddnn, and ddll report  in‐
       formation about the current (or last closed) diversion.  ..hh is meaning‐
       ful in diversions, including the top level.

       The  \\!!   and \\??  escape sequences and oouuttppuutt request escape from a di‐
       version, the first two to the enclosing level and the last to  the  top
       level.  This facility is termed _t_r_a_n_s_p_a_r_e_n_t _e_m_b_e_d_d_i_n_g.

       The aasscciiiiffyy and uunnffoorrmmaatt requests reprocess diversions.

PPuunnnniinngg nnaammeess
       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  \\\\ can 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.

EEnnvviirroonnmmeennttss
       Environments store most of the parameters that control text processing.
       A default environment named “00” exists when _t_r_o_f_f starts up; it is mod‐
       ified 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
       _s_t_a_c_k_, 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 ppeevv request; 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  ..ccddpp,
         ..cchhtt, ..ccsskk, ..nn, ..ww)

       • 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 eevv request pushes to and pops from the environment stack, while eevvcc
       copies a named environment’s contents to the current one.

UUnnddeerrlliinniinngg
       In _R_U_N_O_F_F (see _r_o_f_f(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
       _g_r_o_f_f  request  ..uull (see above) that underlines subsequent source lines
       on terminal devices, but on typesetters,  it  selects  an  italic  font
       style  instead.   The _m_s macro package (see _g_r_o_f_f___m_s(7)) offers a macro
       ..UULL, but it too produces the desired effect only  on  typesetters,  and
       has other limitations.

       One  could  adapt  _m_s’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 _d_o_c_l_i_f_t_e_r(1) makes trouble, change the  macro  name  UUNNDDEERRLLIINNEE  into
       some 2‐letter word, like UUll.  Moreover, change the form of the font se‐
       lection escape sequence from \\ff[[PP]] to \\ffPP.

   UUnnddeerrlliinniinngg wwiitthhoouutt mmaaccrroo ddeeffiinniittiioonnss
       If  one  does  not  want to use macro definitions, e.g., when _d_o_c_l_i_f_t_e_r
       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 _d_o_c_l_i_f_t_e_r, it might be necessary to change syntax forms such
       as \\[[xxyy]] and \\**[[xxyy]] to those supported by AT&T _t_r_o_f_f: \\**((xxyy  and  \\((xxyy,
       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

   UUnnddeerrlliinniinngg bbyy oovveerrssttrriikkiinngg wwiitthh \\((uull
       The \\zz escape sequence writes a glyph without advancing the drawing po‐
       sition,  enabling overstriking.  Thus, \\zz_c\\((uull formats _c 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 _n_r_o_f_f and _t_r_o_f_f modes.

       Long  words  may  then look intimidating in the input; a clarifying ap‐
       proach might be to use the  input  line  continuation  escape  sequence
       \\_n_e_w_l_i_n_e  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
              :: $${{_v_a_ro_p__v_a_l_u_e}}
       as output.

CCoommppaattiibbiilliittyy mmooddee
       The differences between the _r_o_f_f language recognized by GNU  _t_r_o_f_f  and
       that of AT&T _t_r_o_f_f, as well as the device, font, and device‐independent
       intermediate  output  formats  described  by CSTR #54 are documented in
       _g_r_o_f_f___d_i_f_f(7).  _g_r_o_f_f provides an AT&T compatibility mode.  The ..ccpp re‐
       quest and registers ..CC and ..ccpp set and  test  the  enablement  of  this
       mode.

DDeebbuuggggiinngg
       Preprocessors  use  the  ..llff request to preserve the identities of line
       numbers and names of input files.  _g_r_o_f_f emits a variety of error diag‐
       nostics and supports several categories of warning; the output of these
       can be selectively suppressed with ..wwaarrnn (and see the --EE,  --ww,  and  --WW
       options  of  _t_r_o_f_f(1)).   A  trace  of the formatter’s input processing
       stack can be  emitted  when  errors  or  warnings  occur  by  means  of
       _t_r_o_f_f(1)’s  --bb  option,  or  produced on demand with the ..bbaacckkttrraaccee re‐
       quest.  ..ttmm, ..ttmmcc, and ..ttmm11 can be used to emit  customized  diagnostic
       messages  or  for  instrumentation  while troubleshooting.  ..eexx and ..aabb
       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—(..ppmm);  environments
       (..ppeevv), registers (..ppnnrr), and page location traps (..ppttrr) to  the  stan‐
       dard error stream.

AAuutthhoorrss
       This document was written by by Trent A. Fisher, Werner Lemberg, and G.
       Branden Robinson.  Section “Underlining” was primarily written by Bernd
       Warken.

SSeeee aallssoo
       _G_r_o_f_f_:  _T_h_e  _G_N_U _I_m_p_l_e_m_e_n_t_a_t_i_o_n _o_f _t_r_o_f_f, by Trent A. Fisher and Werner
       Lemberg, is the primary _g_r_o_f_f 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 _g_r_o_f_f documentation as “AT&T _t_r_o_f_f”.

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

       _g_r_o_f_f(1)
              is the preferred interface to the _g_r_o_f_f system; it  manages  the
              pipeline  that  carries a source document through preprocessors,
              the _t_r_o_f_f formatter, and an output driver to viewable or  print‐
              able  form.   It  also exhaustively lists the man pages provided
              with the GNU _r_o_f_f system.

       _g_r_o_f_f___c_h_a_r(7)
              discusses character encoding issues, escape sequences that  pro‐
              duce glyphs, and enumerates _g_r_o_f_f’s predefined special character
              escape sequences.

       _g_r_o_f_f___d_i_f_f(7)
              covers  differences  between the GNU _t_r_o_f_f formatter, its device
              and font description file formats, its device‐independent output
              format, and those of AT&T _t_r_o_f_f, whose design it reimplements.

       _g_r_o_f_f___f_o_n_t(5)
              describes the formats of the files that describe devices  (_D_E_S_C)
              and fonts.

       _g_r_o_f_f___t_m_a_c(5)
              surveys  macro packages provided with _g_r_o_f_f, 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.

       _r_o_f_f(7)
              presents  a detailed history of _r_o_f_f systems and summarizes con‐
              cepts common to them.

groff 1.23.0                      3 June 2025                         _g_r_o_f_f(7)
───────────────────────────────────────────────────────────────────────────────
_g_r_o_f_f___c_h_a_r(7)          Miscellaneous Information Manual          _g_r_o_f_f___c_h_a_r(7)

NNaammee
       groff_char - GNU _r_o_f_f special character and glyph repertoire

DDeessccrriippttiioonn
       The GNU _r_o_f_f typesetting system has a large glyph  repertoire  suitable
       for  production of varied literary, professional, technical, and mathe‐
       matical documents.  _g_r_o_f_f works with _c_h_a_r_a_c_t_e_r_s_; an output device  ren‐
       ders _g_l_y_p_h_s_.  _g_r_o_f_f’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 _g_r_o_f_f_, these are termed _o_r_d_i_n_a_r_y _c_h_a_r_a_c_t_e_r_s_.   Often,  many
       more are desired in output.

       AT&T _t_r_o_f_f in the 1970s faced a similar problem: the available typeset‐
       ter’s  glyph  repertoire  differed from that of the computers that con‐
       trolled it.  _t_r_o_f_f’s solution was a form of escape sequence known as  a
       _s_p_e_c_i_a_l  _c_h_a_r_a_c_t_e_r  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 \\((aaaa encoded  an
       acute accent and \\((sscc a section sign.

       _g_r_o_f_f  has lifted historical _r_o_f_f limitations on special character name
       lengths, but recognizes and retains compatibility with  the  historical
       names.   _g_r_o_f_f expands the lexicon of glyphs available by name and per‐
       mits users to define their own special character escape sequences  with
       the  cchhaarr  request.  Special character names are _g_r_o_f_f identifiers; see
       section “Identifiers” in  _g_r_o_f_f(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 _g_r_o_f_f’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 uuttff88 using font RR.

       A few escape sequences that are not _g_r_o_f_f special characters also  pro‐
       duce  glyphs;  these  exist for syntactical or historical reasons.  \\'',
       \\``, \\--, and \\__ are translated on input to the special character  escape
       sequences  \\[[aaaa]], \\[[ggaa]], \\[[--]], and \\[[uull]], respectively.  Others include
       \\\\, \\.. (backslash‐dot), and \\ee; see _g_r_o_f_f(7).  A small number  of  spe‐
       cial characters represent glyphs that are not encoded in Unicode; exam‐
       ples include the baseline rule \\[[rruu]] and the Bell System logo \\[[bbss]]..

       In  _g_r_o_f_f,  you can test output device support for any character (ordi‐
       nary or special) with the conditional expression operator “cc”.
              .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 _g_r_o_f_f are known to also support UTF‐8.

       While  _g_r_o_f_f  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  _g_r_o_f_f  for  internal  purposes,
       which is one reason it does not support UTF‐8 natively.

   FFuunnddaammeennttaall cchhaarraacctteerr sseett
       The ordinary characters catalogued above, plus the space, tab, newline,
       and  leader  (Control+A),  form the fundamental character set for _g_r_o_f_f
       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 _t_r_o_f_f 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 _t_r_o_f_f 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  _r_o_f_f
       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  _r_o_f_f
       language  also  uses it to quote macro arguments, _g_r_o_f_f 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  _t_r_o_f_f  required  in  that  context.
       (Some requests, like ddss, also treat "" non‐literally.)  Furthermore, not
       all  of  the  special  character  escape sequences are portable to AT&T
       _t_r_o_f_f and all of its descendants; these _g_r_o_f_f extensions are  presented
       using  its special character form \\[[]], whereas portable special charac‐
       ter escape sequences are shown in the traditional \\(( form.  \\--  and  \\ee
       are  portable  to all known _t_r_o_f_fs.  \\ee means “the glyph of the current
       escape character”; it therefore can produce unexpected output if the eecc
       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 _n_o_t 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 _r_o_f_f systems, use the “--” char‐
       acter in input outside an escape sequence _o_n_l_y 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 \\-- (or \\[[--]] in _g_r_o_f_f if you find it helps
       the clarity of the source document).  (Another minus sign, for  use  in
       mathematical  equations,  is available as \\[[mmii]]).  AT&T _t_r_o_f_f supported
       em‐dashes as \\((eemm, as does _g_r_o_f_f.

       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 _t_r_o_f_f 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  _t_r_o_f_f 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 _t_r_o_f_f input          recommended _g_r_o_f_f 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.  _r_o_f_f systems have special characters for  drawing  horizontal
       and vertical lines; see subsection “Rules and lines” below.  Preproces‐
       sors like _t_b_l(1) and _p_i_c(1) draw boxes and will produce the best possi‐
       ble output for the device, falling back to basic Latin glyphs only when
       necessary.

   EEiigghhtt‐‐bbiitt eennccooddiinnggss aanndd LLaattiinn‐‐11 ssuupppplleemmeenntt
       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 _g_r_o_f_f input.

       Two  Latin‐1  supplement  characters  are  handled  specially on input.
       _t_r_o_f_f never produces them as output.

       NBSP   encodes a no‐break space; it is mapped  to  \\~~,  the  adjustable
              non‐breaking space escape sequence.

       SHY    encodes  a soft hyphen; it is mapped to \\%%, 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 _r_o_f_f 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

   SSppeecciiaall cchhaarraacctteerr eessccaappee ffoorrmmss
       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 _t_r_o_f_f special character es‐
       cape sequences.  Predefined glyph names use only characters in the  ba‐
       sic Latin repertoire.

       \\((_g_l   is  a  special  character escape sequence for the glyph with the
              two‐character name _g_l.  This is the original  syntax  form  sup‐
              ported by AT&T _t_r_o_f_f.  The acute accent, \\((aaaa, is an example.

       \\CC''_g_l_y_p_h_‐_n_a_m_e''
              is a special character escape sequence for _g_l_y_p_h_‐_n_a_m_e, which can
              be  of arbitrary length.  The delimiter, shown here as a neutral
              apostrophe, can be any character not  occurring  in  _g_l_y_p_h_‐_n_a_m_e.
              This  syntax  form  was introduced in later versions of AT&T de‐
              vice‐independent _t_r_o_f_f.  The foregoing acute accent example  can
              be expressed as \\CC''aaaa''.

       \\[[_g_l_y_p_h_‐_n_a_m_e]]
              is a special character escape sequence for _g_l_y_p_h_‐_n_a_m_e, which can
              be  of  arbitrary  length  but must not contain a closing square
              bracket “]]”.  (No glyph names predefined by _g_r_o_f_f  employ  “]]”.)
              The  foregoing acute accent example can be expressed in _g_r_o_f_f as
              \\[[aaaa]].

       \\CC''_c'' and \\[[_c]] are not synonyms for the ordinary character “_c”, but re‐
       quest the special character named “\\_c”.  For  example,  “\\[[aa]]”  is  not
       “a”,  but rather a special character with the internal glyph name (used
       in font description files and diagnostic messages) \\aa, which  is  typi‐
       cally  undefined.  The only such glyph name _g_r_o_f_f predefines is the mi‐
       nus sign, which can therefore be accessed as \\CC''--'' or \\[[--]].

       \\[[_b_a_s_e_‐_c_h_a_r _c_o_m_p_o_s_i_t_e_‐_1 _c_o_m_p_o_s_i_t_e_‐_2 ... _c_o_m_p_o_s_i_t_e_‐_n]]
              is a composite glyph.  Glyphs like a lowercase “e” with an acute
              accent, as in the word “café”, can be expressed as \\[[ee aaaa]].  See
              subsection “Accents” below for a table of combining glyph names.

       Unicode encodes far more characters than _g_r_o_f_f  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 _a_d _h_o_c
       with the cchhaarr request; see _g_r_o_f_f(7).

       \\[[uu_n_n_n_n[_n[_n]]]]
              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,  \\[[uu0022DDAA]] accesses the (spacing) ring accent, pro‐
              ducing “˚”.

       Unicode code points can be composed as well; when they are,  GNU  _t_r_o_f_f
       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 _t_r_o_f_f that accepts  UTF‐8  input  di‐
       rectly.)   Thus,  GNU  _t_r_o_f_f  accepts  “caf\\[[''ee]]”,  “caf\\[[ee  aaaa]]”,  and
       “caf\\[[uu00006655__00330011]]”, as ways to input “café”.  (Due to its legacy  8‐bit
       encoding compatibility, at present it also accepts “caf\\[[uu0000EE99]]” on ISO
       Latin‐1 systems.)

       \\[[uu_b_a_s_e_‐_c_h_a_r[___c_o_m_b_i_n_i_n_g_‐_c_o_m_p_o_n_e_n_t]...]
              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   (__)   separating   each   component.    Thus,
              \\[[uu000066EE__00330033]] produces “ñ”.

       \\[[cchhaarr_n_n_n]]
              expresses an eight‐bit code point where _n_n_n 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  ttrriinn  re‐
              quest in macro files loaded by _g_r_o_t_t_y(1).

GGllyypphh ttaabblleess
       In  this section, _g_r_o_f_f’s glyph name repertoire is presented in tabular
       form.  The meanings of the columns are as follows.

       OOuuttppuutt  shows 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), _g_r_o_f_f attempts reasonable equivalency on all out‐
               put devices.

       IInnppuutt   shows the _g_r_o_f_f character (ordinary or special)  that  normally
               produces  the  glyph.   Some  code  points  have multiple glyph
               names.

       UUnniiccooddee is 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 _g_r_o_f_f’s uu_n_n_n_n is equivalent to
               Unicode’s U+_n_n_n_n.

       NNootteess   describes  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 _t_r_o_f_f user’s manual, CSTR #54 (1992 revision).  When using
               the  AT&T special character syntax \\((_x_x, 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 _s_p_e_c_i_a_l font  (see  _g_r_o_f_f___f_o_n_t(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”).

   BBaassiicc LLaattiinn
       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 \\[[bbaa]] and \\[[oorr]] escape 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

   SSuupppplleemmeennttaarryy LLaattiinn lleetttteerrss
       Historically, \\[[ssss]] could be considered a ligature of “sz”.  An  upper‐
       case form is available as \\[[uu11EE99EE]], but in the German language it is of
       specialized  use;  ß  does  _n_o_t 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

   LLiiggaattuurreess aanndd ddiiggrraapphhss
       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

   AAcccceennttss
       Normally,  the  formatting  of a special character advances the drawing
       position as an ordinary character does.  _g_r_o_f_f’s ccoommppoossiittee request des‐
       ignates a special character as  combining.   The  _c_o_m_p_o_s_i_t_e_._t_m_a_c  macro
       file,  loaded  automatically by the default _t_r_o_f_f_r_c, 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 “ccaaff\\[[ee aaaa]]” and “ccaaff\\[[aaaa]]ee”).

       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

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

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

   PPuunnccttuuaattiioonn
       The Unicode name for U+00B7 is “middle  dot”,  which  is  unfortunately
       confusable  with the _g_r_o_f_f 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 +

   BBrraacckkeettss
       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 _n_o_t font‐in‐
       variant; _g_r_o_f_f maps them rather arbitrarily to U+23AA  (“curly  bracket
       extension”).  In AT&T _t_r_o_f_f, only one glyph was available to vertically
       extend brackets, braces, and parentheses: \\((bbvv.

       Not  all devices supply bracket pieces that can be piled up with \\bb due
       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 _t_r_o_f_f can be used for other mathematical symbols
       as well, for example \\((llff and \\((rrff, which provide the  floor  operator.
       Some  output  devices,  such as ddvvii, don’t unify such glyphs.  For this
       reason, the glyphs \\[[llff]], \\[[rrff]], \\[[llcc]], and \\[[rrcc]] are not unified  with
       similar‐looking  bracket pieces.  In _g_r_o_f_f, 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

   AArrrroowwss
       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

   RRuulleess aanndd lliinneess
       On  typesetting  devices,  the  font‐invariant  glyphs  (see subsection
       “Brackets” above) \\[[bbrr]], \\[[uull]], and \\[[rrnn]] form 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 __ always accesses the underscore glyph in  a  font;
       \\[[uull]], by contrast, may be font‐invariant on typesetting devices.

       The  baseline  rule  \\[[rruu]]  is a font‐invariant glyph, namely a rule of
       one‐half em.

       In AT&T _t_r_o_f_f, \\[[rrnn]] also served as a one en extension  of  the  square
       root  symbol.   _g_r_o_f_f favors \\[[rraaddiiccaalleexx]] for 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

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

   LLeeggaall ssyymmbboollss
       The Bell System logo is not supported in _g_r_o_f_f.

       Output   Input   Unicode   Notes
       ────────────────────────────────────────────────────────────────────────
       ©        \[co]   u00A9     copyright sign +
       ®        \[rg]   u00AE     registered sign +
       ™        \[tm]   u2122     trade mark sign
                \[bs]   ‐‐‐       Bell System logo +

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

   UUnniittss
       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

   LLooggiiccaall ssyymmbboollss
       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 \\[[bbaa]] and \\[[oorr]].

       Output   Input    Unicode   Notes
       ────────────────────────────────────────────────────────────────────────
       ∧        \[AN]    u2227     logical and
       ∨        \[OR]    u2228     logical or
       ¬        \[no]    u00AC     logical not + ***
       ¬        \[tno]   u00AC     text variant of \\[[nnoo]]
       ∃        \[te]    u2203     there exists
       ∀        \[fa]    u2200     for all
       ∋        \[st]    u220B     such that
       ∴        \[3d]    u2234     therefore
       ∴        \[tf]    u2234     therefore
       |        |        u007C     bar
       |        \[or]    u007C     bitwise or +

   MMaatthheemmaattiiccaall ssyymmbboollss
       \\[[FFnn]]  also  appears in subsection “Supplementary Latin letters” above.
       Observe the two varieties of the plus‐minus, multiplication, and  divi‐
       sion signs; \\[[++--]], \\[[mmuu]], and \\[[ddii]] are 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  _t_r_o_f_f, \\((rrnn (“root en extender”) served as the horizontal ex‐
       tension of the radical (square root) sign, \\((ssrr, 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 _g_r_o_f_f, you can instead use \\[[rraaddiiccaalleexx]]  to  continue  the
       radical  sign \\[[ssrr]]; these special characters are intended for use with
       text fonts.  \\[[ssqqrrtt]] and \\[[ssqqrrtteexx]] are 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 \\[[++--]]
       ⋅        \[md]          u22C5        multiplication dot
       ×        \[mu]          u00D7        multiplication sign + ***
       ×        \[tmu]         u00D7        text variant of \\[[mmuu]]
       ⊗        \[c*]          u2297        circled times
       ⊕        \[c+]          u2295        circled plus
       ÷        \[di]          u00F7        division sign + ***
       ÷        \[tdi]         u00F7        text variant of \\[[ddii]]
       ⁄        \[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

   GGrreeeekk ggllyypphhss
       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 +

   PPllaayyiinngg ccaarrdd ssyymmbboollss
       Output   Input   Unicode   Notes
       ────────────────────────────────────────────────────────────────────────
       ♣        \[CL]   u2663     solid club suit
       ♠        \[SP]   u2660     solid spade suit
       ♥        \[HE]   u2665     solid heart suit
       ♦        \[DI]   u2666     solid diamond suit

HHiissttoorryy
       A consideration of the typefaces originally available to AT&T _n_r_o_f_f and
       _t_r_o_f_f  illuminates  many  conventions that one might regard as idiosyn‐
       cratic fifty years afterward.  (See section “History”  of  _r_o_f_f(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
       ("") served as a dieresis accent and neutral double quotation mark; dec‐
       imal 39 ('') as an acute accent, apostrophe, and closing (right)  single
       quotation mark; decimal 45 (--) as a hyphen and a minus sign; decimal 94
       (^^)  as a circumflex accent and caret; decimal 96 (``) as a grave accent
       and opening (left) single quotation mark; and  decimal  126  (~~)  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
       _k_b_d(VII) man page of the (First Edition) _U_n_i_x _P_r_o_g_r_a_m_m_e_r_’_s _M_a_n_u_a_l_.

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

           ┌───────────────────────────────────────────────────────────┐
           │ _α _β _γ _δ _ε _ζ _η _θ _ι _κ _λ _μ _ν _ξ _ο _π _ρ _σ _ς _τ _υ _ϕ _χ _ψ _ω         │
           │ Γ Δ Θ Λ Ξ Π Σ Υ Φ Ψ Ω                                     │
           │ " ´ \ ^ _ ` ~ / < > { } # @ + − = ∗                       │
           │ ≥ ≤ ≡ ≈ ∼ ≠ ↑ ↓ ← → × ÷ ± ∞ ∂ ∇ ¬ ∫ ∝ √ ‾ ∪ ∩ ⊂ ⊃ ⊆ ⊇ ∅ ∈ │
           │ § ‡ ☜ ☞ | ○ ⎧ ⎩ ⎫ ⎭ ⎨ ⎬ ⎪ ⌊ ⌋ ⌈ ⌉                         │
           └───────────────────────────────────────────────────────────┘

       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 \\[[bbrr]], brace vertical extension \\[[bbvv]], and “or” operator \\[[oorr]]
       were used as contextually appropriate.

       Devices supported by AT&T device‐independent _t_r_o_f_f exhibited some  dif‐
       ferences  in  glyph detail.  For example, on the Autologic APS‐5 photo‐
       typesetter, the square \\((ssqq became filled in the Times bold face.

FFiilleess
       The files below are loaded automatically by the default _t_r_o_f_f_r_c.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_c_o_m_p_o_s_i_t_e_._t_m_a_c
              assigns alternate mappings for identifiers after the first in  a
              composite  special  character  escape  sequence.  See subsection
              “Accents” above.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_f_a_l_l_b_a_c_k_s_._t_m_a_c
              defines fallback mappings for Unicode code points  such  as  the
              increment sign (U+2206) and upper‐ and lowercase Roman numerals.

AAuutthhoorrss
       This document was written by James Clark, with additions by Werner Lem‐
       berg  and  Bernd Warken,  revised to use _t_b_l(1) by Eric S. Raymond, and
       largely rewritten by G. Branden Robinson.

SSeeee aallssoo
       _G_r_o_f_f_: _T_h_e _G_N_U _I_m_p_l_e_m_e_n_t_a_t_i_o_n _o_f _t_r_o_f_f, by Trent A. Fisher  and  Werner
       Lemberg,  is  the primary _g_r_o_f_f manual.  Section “Using Symbols” may be
       of particular  note.   You  can  browse  it  interactively  with  “info
       '(groff) Using Symbols'”.

       “An extension to the _t_r_o_f_f character set for Europe”, E.G. Keizer, K.J.
       Simonsen, J. Akkerhuis; EUUG Newsletter, Volume 9, No. 2, Summer 1989

       The Unicode Standard

       “7‐bit Character Sets”  by Tuomas Salste documents the inherent ambigu‐
       ity and configurable 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 _r_o_f_f”
       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  _t_r_o_f_f
       users.

       _g_r_o_f_f___r_f_c_1_3_4_5(7)  describes  an  alternative  set  of special character
       glyph names, which extends and in some cases overrides the  definitions
       listed above.

       _g_r_o_f_f(1), _t_r_o_f_f(1), _g_r_o_f_f(7)

groff 1.23.0                      3 June 2025                    _g_r_o_f_f___c_h_a_r(7)
───────────────────────────────────────────────────────────────────────────────
_g_r_o_f_f___d_i_f_f(7)          Miscellaneous Information Manual          _g_r_o_f_f___d_i_f_f(7)

NNaammee
       groff_diff - differences between GNU _r_o_f_f and AT&T _t_r_o_f_f

DDeessccrriippttiioonn
       The  GNU  _r_o_f_f  text  processing system, _g_r_o_f_f, is an extension of AT&T
       _t_r_o_f_f, the typesetting system originating in Unix systems of the 1970s.
       _g_r_o_f_f removes many arbitrary limitations and adds features, both to the
       input language and to the page description language output by the _t_r_o_f_f
       formatter.  Differences arising from  _g_r_o_f_f’s  implementation  of  AT&T
       _t_r_o_f_f features are also noted.  See _r_o_f_f(7) for background.

LLaanngguuaaggee
       GNU _t_r_o_f_f 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.

   LLoonngg nnaammeess
       GNU _t_r_o_f_f introduces many new requests; with three exceptions (ccpp,  ddoo,
       rrjj),  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 _t_r_o_f_f
       supports a parameterized escape sequence that uses an opening parenthe‐
       sis “(” to introduce a two‐character argument, _g_r_o_f_f supports a square‐
       bracketed form “[]” where the  argument  within  can  be  of  arbitrary
       length.

   FFoonntt ffaammiilliieess,, aabbssttrraacctt ssttyylleess,, aanndd ttrraannssllaattiioonn
       GNU _t_r_o_f_f can group text typefaces into _f_a_m_i_l_i_e_s containing each of the
       styles “RR”, “II”, “BB”, and “BBII”.  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 _r_e_s_o_l_v_e_d _f_o_n_t
       _n_a_m_e_.  A document can _t_r_a_n_s_l_a_t_e_, or remap, fonts with the ffttrr request.

       Applying the requests ccss, bbdd, ttkkff, uuff, or ffssppeecciiaall to an abstract style
       affects the member of the default family corresponding to  that  style.
       The  default  family can be set with the ffaamm request or --ff command‐line
       option.  The ssttyylleess directive in the output device’s _D_E_S_C file controls
       which mounting positions (if any) are  initially  associated  with  ab‐
       stract  styles  rather  than fonts, and the ssttyy request can update this
       association.

   CCoolloorrss
       _g_r_o_f_f 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 _s_t_r_o_k_e _c_o_l_o_r_, with which  glyphs,  rules  (lines),  and
       geometric figures are drawn, and the _f_i_l_l _c_o_l_o_r_, which paints the inte‐
       rior  of  filled  geometric  figures.  The ccoolloorr, ddeeffccoolloorr, ggccoolloorr, and
       ffccoolloorr requests; \\mm and \\MM escape sequences; and  ..ccoolloorr,  ..mm,  and  ..MM
       registers exercise color support.

   FFrraaccttiioonnaall ttyyppee ssiizzeess aanndd nneeww ssccaalliinngg uunniittss
       AT&T  _t_r_o_f_f 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 _t_r_o_f_f, 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 _s_c_a_l_e_d _p_o_i_n_t is equal to 1/_s_i_z_e_s_c_a_l_e points, where _s_i_z_e_s_c_a_l_e is spec‐
       ified in the device description file, _D_E_S_C,  and  defaults  to  1;  see
       _g_r_o_f_f___f_o_n_t(5).   Requests  and  escape sequences in GNU _t_r_o_f_f interpret
       arguments that represent a type size in  points,  which  the  formatter
       multiplies  by _s_i_z_e_s_c_a_l_e and converts to an integer.  Arguments treated
       in this way comprise those to the escape sequences \\HH and  \\ss,  to  the
       request  ppss,  the  third argument to the ccss request, and the second and
       fourth arguments to the ttkkff request.  Scaled points  may  be  specified
       explicitly  with the zz scaling unit.  In GNU _t_r_o_f_f, the register \\nn[[..ss]]
       can interpolate a non‐integral type size.  The register \\nn[[..ppss]]  inter‐
       polates the type size in scaled points.

       For  example,  if  _s_i_z_e_s_c_a_l_e  is 1000, then a scaled point is one thou‐
       sandth of a point.  Consequently, “..ppss 1100..55” is  synonymous  with  “..ppss
       1100..55zz”; both set the type size to 10,500 scaled points, or 10.5 points.

       It  makes  no sense to use the “zz” scaling unit in a numeric expression
       whose default scaling unit is neither “uu” nor “zz”, so GNU _t_r_o_f_f  disal‐
       lows  this.   Similarly,  it is nonsensical to use a scaling unit other
       than “zz” or “uu” in a numeric  expression  whose  default  scaling  unit
       is “zz”, so GNU _t_r_o_f_f disallows this as well.

       Another  new scaling unit, “ss”, multiplies by the number of basic units
       in a scaled point.  Thus, “\\nn[[..ppss]]ss” is equal to  “11mm”  by  definition.
       Do not confuse the “ss” and “zz” scaling units.

       Output  devices  may be limited in the type sizes they can employ.  The
       ..ss and ..ppss registers represent the type size as selected by the  output
       driver  as  it  understands  a device’s capability.  The last _r_e_q_u_e_s_t_e_d
       type size is interpolated in scaled points by  the  read‐only  register
       ..ppssrr and in points as a decimal fraction by the read‐only string‐valued
       register  ..ssrr.  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 ssiizzeess request (or by the ssiizzeess or ssiizzeessccaallee directives in
       the device’s _D_E_S_C file) is 11 points, the output driver uses the latter
       value.

       A further two new measurement units available in _g_r_o_f_f are  “MM”,  which
       indicates  hundredths  of  an  em, and “ff”, which multiplies by 65,536.
       The latter provides convenient fractions for color definitions with the
       ddeeffccoolloorr request.  For example, 0.5f equals 32768u.

   NNuummeerriicc eexxpprreessssiioonnss
       GNU _t_r_o_f_f permits spaces in a numeric  expression  within  parentheses,
       and offers three new operators.

       _e_1>>??_e_2 Interpolate the greater of _e_1 and _e_2.

       _e_1<<??_e_2 Interpolate the lesser of _e_1 and _e_2.

       ((_c;;_e))  Evaluate _e using _c as the default scaling unit, ignoring scaling
              units in _e if _c is empty.

   CCoonnddiittiioonnaall eexxpprreessssiioonnss
       More conditions can be tested with the “iiff” and iiee requests, as well as
       the new “wwhhiillee” request.

       cc _c_h_r  True  if  a character _c_h_r is available, where _c_h_r is an ordinary
              character (Unicode basic Latin excluding control characters  and
              the space), a special character, or \\NN''_i_n_d_e_x''.

       dd _n_a_m  True if a string, macro, diversion, or request _n_a_m is defined.

       FF _f_n_t  True if a font _f_n_t is available; _f_n_t can be an abstract style or
              a  font name.  _f_n_t is handled as if it were accessed with the fftt
              request (that is, abstract styles and font translation  are  ap‐
              plied),  but  _f_n_t  cannot be a mounting position, and no font is
              mounted.

       mm _c_o_l  True if a color _c_o_l is defined.

       rr _r_e_g  True if a register _r_e_g is defined.

       SS _s_t_y  True if a style _s_t_y is registered.  Font translation applies.

       vv      Always false.  This condition is for compatibility with  certain
              other  _t_r_o_f_f  implementations  only.   (This refers to _v_t_r_o_f_f, a
              translator that would convert the C/A/T output  from  early‐vin‐
              tage  AT&T _t_r_o_f_f to a form suitable for Versatec and Benson‐Var‐
              ian plotters.)

   DDrraawwiinngg ccoommmmaannddss
       GNU _t_r_o_f_f 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, \\DD''tt'').

   EEssccaappee sseeqquueenncceess
       _g_r_o_f_f introduces several new escape sequences and extends the syntax of
       a  few AT&T _t_r_o_f_f escape sequences (namely, \\DD, \\ff, \\kk, \\nn, \\ss, \\$$, and
       \\**).  In the following list, escape sequences are  collated  alphabeti‐
       cally at first, and then by symbol roughly in Unicode code point order.

       \\AA''_a_n_y_t_h_i_n_g''
              Interpolate  1  if  _a_n_y_t_h_i_n_g 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  \\AA  to validate a macro argument before using it to
              construct another escape sequence or identifier.

       \\BB''_a_n_y_t_h_i_n_g''
              Interpolate 1 if _a_n_y_t_h_i_n_g is a valid numeric expression,  and  0
              otherwise.  You might use \\BB along with the “iiff” request to fil‐
              ter out invalid macro arguments.

       \\DD''CC _d''
              Draw  filled circle of diameter _d with its leftmost point at the
              drawing position.

       \\DD''EE _h _v''
              Draw filled ellipse with _h and _v as the axes  and  the  leftmost
              point at the drawing position.

       \\DD''pp _h_1 _v_1 ... _h_n _v_n''
              Draw polygon with vertices at drawing position and each point in
              sequence.   GNU  _t_r_o_f_f closes the polygon by drawing a line from
              (_h_n, _v_n) back to the initial drawing position; DWB and  Heirloom
              _t_r_o_f_fs  do  not.   Afterward,  the  drawing  position is left at
              (_h_n, _v_n).

       \\DD''PP _h_1 _v_1 ... _h_n _v_n''
              As \\DD''pp'', but the polygon is filled.

       \\DD''tt _n''
              Set line thickness of geometric objects to to _n basic units.   A
              zero  _n  selects  the minimal supported thickness.  A negative _n
              selects a thickness proportional to the type size; this  is  the
              default.

       \\EE     Embed  an  escape character that is not interpreted in copy mode
              (compare with \\aa and \\tt).  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.

       \\ff[[_f_o_n_t]]
              Select _f_o_n_t, which may be a mounting position,  abstract  style,
              or  font  name,  to  choose the typeface.  \\ff[[]] and \\ffPP are syn‐
              onyms; we recommend the former.

       \\FF_f
       \\FF((_f_m
       \\FF[[_f_a_m_i_l_y]]
              Select default font family.  \\FF[[]] makes the previous font family
              the default.  \\FFPP is unlike \\ffPP; it selects font family  “P”  as
              the default.  See the ffaamm request below.

       \\kk((_r_g
       \\kk[[_r_e_g]]
              Mark  horizontal  drawing  position  in  two‐character  register
              name _r_g or arbitrary register name _r_e_g.

       \\mm_c
       \\mm((_c_l
       \\mm[[_c_o_l]]
              Set the stroke color.  \\mm[[]] restores the previous stroke  color,
              or the default if there is none.

       \\MM_c
       \\MM((_c_l
       \\MM[[_c_o_l]]
              Set  the  fill color.  \\MM[[]] restores the previous fill color, or
              the default if there is none.

       \\nn[[_r_e_g]]
              Interpolate register _r_e_g.

       \\OO_n
       \\OO[[_n]]  Suppress _t_r_o_f_f output of glyphs and geometric objects.  The  se‐
              quences  \\OO22, \\OO33, \\OO44, and \\OO55 are intended for internal use by
              _g_r_o_h_t_m_l(1).

              \\OO00
              \\OO11    Disable and enable, respectively, the emission of  glyphs
                     and geometric objects to the output driver, provided that
                     this  sequence  occurs at the outermost suppression level
                     (see \\OO33 and \\OO44).  Horizontal motions  corresponding  to
                     non‐overstruck glyph widths still occur.  These sequences
                     also  reset the registers ooppmmiinnxx, ooppmmiinnyy, ooppmmaaxxxx, and oopp‐‐
                     mmaaxxyy to -1.  These four registers mark the top  left  and
                     bottom right hand corners of a box encompassing all writ‐
                     ten or drawn output.

              \\OO22    At  the  outermost  suppression level, enable emission of
                     glyphs and geometric objects, and write to  the  standard
                     error  stream  the  page  number  and  values of the four
                     aforementioned  registers  encompassing  glyphs   written
                     since the last interpolation of a \\OO sequence, as well as
                     the  page  offset, line length, image file name (if any),
                     horizontal and vertical device motion quanta,  and  input
                     file name.  Numeric values are in basic units.

              \\OO33
              \\OO44    Begin  and  end a nested suppression level, respectively.
                     _g_r_o_h_t_m_l uses this mechanism to create  images  of  output
                     preprocessed  with  _p_i_c, _e_q_n, and _t_b_l.  At startup, _t_r_o_f_f
                     is at the outermost suppression level.  _p_r_e_-_g_r_o_h_t_m_l  gen‐
                     erates  these sequences when processing the document, us‐
                     ing _t_r_o_f_f with the ppss output device, Ghostscript, and the
                     PNM tools to produce images in  PNG  format.   These  se‐
                     quences  start  a  new  page if the device is not hhttmmll or
                     xxhhttmmll, to reduce the number of  images  crossing  a  page
                     boundary.

              \\OO55[[_P_f_i_l_e]]
                     At  the  outermost suppression level, write the name _f_i_l_e
                     to the standard error stream at position _P, which must be
                     one of ll, rr, cc, or ii, corresponding to left, right,  cen‐
                     tered, and inline alignments within the document, respec‐
                     tively.  _f_i_l_e is is a name associated with the production
                     of the next image.

       \\RR''_n_a_m_e _±_n''
              Synonymous with “..nnrr _n_a_m_e _±_n”.

       \\ss[[_±_n]]
       \\ss_±[[_n]]
       \\ss''_±_n''
       \\ss_±''_n'' Set  the type size to, or increment or decrement it by, _n scaled
              points.

       \\VV_e
       \\VV((_e_v
       \\VV[[_e_n_v]]
              Interpolate contents of the environment  variable  _e_n_v,  as  re‐
              turned by _g_e_t_e_n_v(3).  \\VV is interpreted even in copy mode.

       \\XX''_a_n_y_t_h_i_n_g''
              Within \\XX arguments, the escape sequences \\&&, \\)), \\%%, and \\:: are
              ignored; \\_s_p_a_c_e and \\~~ are converted to single space characters;
              and  \\\\  is reduced to \\.  So that the basic Latin subset of the
              Unicode character set (that is, ISO 646:1991‐IRV or,  popularly,
              “US‐ASCII”)  can  be  reliably  encoded in _a_n_y_t_h_i_n_g_, the special
              character escape  sequences  \\--,  \\[[aaqq]],  \\[[ddqq]],  \\[[ggaa]],  \\[[hhaa]],
              \\[[rrss]],  and  \\[[ttii]]  are  mapped  to  basic Latin characters; see
              _g_r_o_f_f___c_h_a_r(7).  For this transformation, character  translations
              and  definitions  are  ignored.   Other escape sequences are not
              supported.

              If the uussee__cchhaarrnnaammeess__iinn__ssppeecciiaall directive appears in the  output
              device’s  _D_E_S_C  file,  the  use  of special character escape se‐
              quences is _n_o_t an error; they are simply output  verbatim  (with
              the exception of the seven mapped to Unicode basic Latin charac‐
              ters,  discussed  above).  uussee__cchhaarrnnaammeess__iinn__ssppeecciiaall is currently
              employed only by _g_r_o_h_t_m_l(1).

       \\YY_m
       \\YY((_m_a
       \\YY[[_m_a_c]]
              Interpolate a macro as a device control command.  This is  simi‐
              lar  to  \\XX''\\**[[_m_a_c]]'',  except the contents of _m_a_c are not inter‐
              preted, and _m_a_c can  be  a  macro  and  thus  contain  newlines,
              whereas  the  argument to \\XX cannot.  This inclusion of newlines
              requires an extension to the AT&T _t_r_o_f_f output format, and  will
              confuse postprocessors that do not know about it.

       \\ZZ''_a_n_y_t_h_i_n_g''
              Save  the  drawing  position,  format _a_n_y_t_h_i_n_g, then restore it.
              Tabs and leaders in the argument are ignored with an error diag‐
              nostic.

       \\##     Everything up to and including  the  next  newline  is  ignored.
              This  escape  sequence  is interpreted even in copy mode.  \\## is
              like \\"", except that \\"" does not ignore a  newline;  the  latter
              therefore  cannot  be used by itself for a whole‐line comment—it
              leaves a blank line on the input stream.

       \\$$00    Interpolate the name by which the macro  being  interpreted  was
              called.  In GNU _t_r_o_f_f this name can vary; see the aallss request.

       \\$$((_n_n
       \\$$[[_n_n_n]]
              In  a  macro or string definition, interpolate the _n_nth or _n_n_nth
              argument.  Macros and strings can have an  unlimited  number  of
              arguments.

       \\$$**    In  a  macro or string definition, interpolate the catenation of
              all arguments, separated by spaces.

       \\$$@@    In a macro or string definition, interpolate the  catenation  of
              all  arguments,  with each surrounded by double quotes and sepa‐
              rated by spaces.

       \\$$^^    In a macro or string definition, interpolate the  catenation  of
              all  arguments constructed in a form suitable for passage to the
              ddss request.

       \\))     Interpolate a _t_r_a_n_s_p_a_r_e_n_t dummy character—one that is ignored by
              end‐of‐sentence detection.  It behaves as \\&&, except that \\&&  is
              treated as letters and numerals normally are after “.”, “?”, and
              “!”; \\&& cancels end‐of‐sentence detection, and \\)) does not.

       \\**[[_s_t_r_i_n_g [_a_r_g ...]]]
              Interpolate _s_t_r_i_n_g_, passing it _a_r_g ... as arguments.

       \\//     Apply  an _i_t_a_l_i_c _c_o_r_r_e_c_t_i_o_n: modify the spacing of the preceding
              glyph so that the distance between it and the following glyph is
              correct if the latter is of upright shape.  For example,  if  an
              italic “f” is followed immediately by a roman right parenthesis,
              then in many fonts the top right portion of the “f” overlaps the
              top  left of the right parenthesis, which is ugly.  Inserting \\//
              between them avoids this  problem.   Use  this  escape  sequence
              whenever  an oblique glyph is immediately followed by an upright
              glyph without any intervening space.

       \\,,     Apply a _l_e_f_t _i_t_a_l_i_c _c_o_r_r_e_c_t_i_o_n: 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 \\,, between them avoids this problem.  Use  this
              escape  sequence  whenever  an upright glyph is followed immedi‐
              ately by an oblique glyph without any intervening space.

       \\::     Insert a non‐printing break point.  That is, a  word  can  break
              there,  but  the  soft  hyphen character does not mark the break
              point if it does (in contrast to “\\%%”).  This escape sequence is
              an input word boundary, so the remainder of the word is  subject
              to hyphenation as normal.

       \\??_a_n_y_t_h_i_n_g\\??
              When  used in a diversion, this transparently embeds _a_n_y_t_h_i_n_g in
              the diversion.  _a_n_y_t_h_i_n_g is read in copy mode.  When the  diver‐
              sion  is reread, _a_n_y_t_h_i_n_g is interpreted.  _a_n_y_t_h_i_n_g may not con‐
              tain newlines; use \\!! if you want to embed newlines in a  diver‐
              sion.   The  escape  sequence \\?? is also recognized in copy mode
              and becomes an internal code; it is this  code  that  terminates
              _a_n_y_t_h_i_n_g.  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 44.

       \\[[_c_h_a_r]]
              Typeset the special character _c_h_a_r.

       \\[[_b_a_s_e_‐_c_h_a_r _c_o_m_b_i_n_i_n_g_‐_c_o_m_p_o_n_e_n_t ...]]
              Typeset  a composite glyph consisting of _b_a_s_e_‐_c_h_a_r overlaid with
              one or more _c_o_m_b_i_n_i_n_g_‐_c_o_m_p_o_n_e_n_ts.  For example, “\\[[AA hhoo]]”  is  a
              capital  letter  “A”  with  a  “hook  accent” (ogonek).  See the
              ccoommppoossiittee request below; _G_r_o_f_f_: _T_h_e _G_N_U _I_m_p_l_e_m_e_n_t_a_t_i_o_n _o_f _t_r_o_f_f,
              the _g_r_o_f_f Texinfo manual, for details of  composite  glyph  name
              construction; and _g_r_o_f_f___c_h_a_r(7) for a list of components used in
              composite glyph names.

       \\~~     Insert  an unbreakable space that is adjustable like an ordinary
              space.  It is discarded from the end of  an  output  line  if  a
              break is forced.

   RReessttrriicctteedd rreeqquueessttss
       To  mitigate  risks  from  untrusted input documents, the ppii and ssyy re‐
       quests are disabled by default.  _t_r_o_f_f(1)’s --UU option enables the  for‐
       matter’s  “unsafe  mode”,  restoring their function (and enabling addi‐
       tional _g_r_o_f_f extension requests, ooppeenn, ooppeennaa, and ppssoo).

   NNeeww rreeqquueessttss
       ..aallnn _n_e_w _o_l_d
              Create alias _n_e_w for existing register named  _o_l_d,  causing  the
              names to refer to the same stored value.  If _o_l_d is undefined, a
              warning  in  category  “rreegg” is generated and the request is ig‐
              nored.  To remove a register alias, invoke rrrr on  its  name.   A
              register’s  contents  do not become inaccessible until it has no
              more names.

       ..aallss _n_e_w _o_l_d
              Create alias _n_e_w for existing request, string, macro, or  diver‐
              sion  named  _o_l_d,  causing the names to refer to the same stored
              object.  If _o_l_d is undefined, a warning  in  category  “mmaacc”  is
              produced,  and  the request is ignored.  The “aamm”, “aass”, ddaa, ddee,
              ddii, and ddss requests (together with their variants) create a  new
              object  only  if  the name of the macro, diversion, or string is
              currently undefined or if it is defined as a request;  normally,
              they  modify  the  value  of  an  existing object.  To remove an
              alias, invoke rrmm on 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  rrmm
              request on its name first.

       ..aamm11 _n_a_m_e [_e_n_d_‐_n_a_m_e]
              As “aamm”, but compatibility mode is disabled while the appendment
              to _n_a_m_e is interpreted: a “compatibility save” token is inserted
              at  its  beginning,  and  a “compatibility restore” token at its
              end.  As a consequence, the requests “aamm”, aamm11, ddee, and ddee11  can
              be intermixed freely since the compatibility save/restore tokens
              affect only the parts of the macro populated by aamm11 and ddee11.

       ..aammii _n_a_m_e [_e_n_d_‐_n_a_m_e]
              Append to macro indirectly.  See ddeeii below.

       ..aammii11 _n_a_m_e [_e_n_d_‐_n_a_m_e]
              As aammii, but compatibility mode is disabled during interpretation
              of the appendment.

       ..aass11 _n_a_m_e [_c_o_n_t_e_n_t_s]
              As “aass”, but compatibility mode is disabled while the appendment
              to _n_a_m_e is interpreted: a “compatibility save” token is inserted
              at  the beginning of _c_o_n_t_e_n_t_s, and a “compatibility restore” to‐
              ken after it.  As a consequence, the requests “aass”, aass11, ddss, and
              ddss11 can be intermixed freely since  the  compatibility  save/re‐
              store  tokens  affect only the portions of the strings populated
              by aass11 and ddss11.

       ..aasscciiiiffyy _d_i_v
              _U_n_f_o_r_m_a_t the diversion _d_i_v in a  way  such  that  Unicode  basic
              Latin  (ASCII)  characters,  characters translated with the ttrriinn
              request, space characters, and some escape sequences, that  were
              formatted  in  the diversion _d_i_v are treated like ordinary input
              characters when _d_i_v is reread.  Doing so can be useful  in  con‐
              junction  with the wwrriitteemm request.  aasscciiiiffyy can be also used for
              gross hacks; for example, the following sets register nn to 1.

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

              aasscciiiiffyy cannot return all items in a diversion to  their  source
              equivalent:  nodes such as those produced by \\NN[[...]] will remain
              nodes, so the result cannot be guaranteed to be a  pure  string.
              See  section  “Copy mode” in _g_r_o_f_f(7).  Glyph parameters such as
              the type face and  size  are  not  preserved;  use  uunnffoorrmmaatt  to
              achieve that.

       ..bbaacckkttrraaccee
              Write  backtrace  of  input  stack to the standard error stream.
              See the --bb option of _t_r_o_f_f(1).

       ..bbllmm [_n_a_m_e]
              Set a blank line macro (trap).  If a blank line  macro  is  thus
              defined,  _g_r_o_f_f  executes _m_a_c_r_o 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.

       ..bbooxx [_n_a_m_e]
       ..bbooxxaa [_n_a_m_e]
              Divert  (or  append)  output to _n_a_m_e_, similarly to the ddii and ddaa
              requests, respectively.  Any pending output line is _n_o_t included
              in the diversion.  Without an argument, stop  diverting  output;
              any pending output line inside the diversion is discarded.

       ..bbrreeaakk Exit  a  “wwhhiillee” loop.  Do not confuse this request with a typo‐
              graphical break or the bbrr request.  See “ccoonnttiinnuuee”.

       ..bbrrpp   Break and adjust line; this is the AT&T _t_r_o_f_f escape sequence \\pp
              in request form.

       ..ccffllaaggss _n _c_1 _c_2 ...
              Assign properties encoded by the number _n to characters _c_1,  _c_2,
              and so on.  Ordinary and special characters have certain associ‐
              ated properties.  (Glyphs don’t: to GNU _t_r_o_f_f, like AT&T device‐
              independent  _t_r_o_f_f,  a glyph is an identifier corresponding to a
              rectangle with some metrics; see _g_r_o_f_f___f_o_n_t(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 _c_n arguments are optional.  Any argument _c_n
              can be a character class defined with the ccllaassss  request  rather
              than an individual character.

              The  non‐negative  integer _n is the sum of any of the following.
              Some combinations are nonsensical, such as “3333” (1 + 32).

              1      Recognize the character as ending a sentence if  followed
                     by  a newline or two spaces.  Initially, characters “..??!!”
                     have this property.

              2      Enable breaks before the character.  A line is not broken
                     at a character with this property unless  the  characters
                     on  each side both have non‐zero hyphenation codes.  This
                     exception can be overridden by adding 64.  Initially,  no
                     characters have this property.

              4      Enable  breaks after the character.  A line is not broken
                     at a character with this property unless  the  characters
                     on  each side both have non‐zero hyphenation codes.  This
                     exception can be overridden  by  adding  64.   Initially,
                     characters “--\\[[hhyy]]\\[[eemm]]” have this property.

              8      Mark the glyph associated with this character as overlap‐
                     ping  other instances of itself horizontally.  Initially,
                     characters  “\\[[uull]]\\[[rrnn]]\\[[rruu]]\\[[rraaddiiccaalleexx]]\\[[ssqqrrtteexx]]”   have
                     this property.

              16     Mark the glyph associated with this character as overlap‐
                     ping  other  instances  of itself vertically.  Initially,
                     the character “\\[[bbrr]]” 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
                     “''""))]]**\\[[ddgg]]\\[[dddd]]\\[[rrqq]]\\[[ccqq]]” 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 ccffllaaggss value is inserting “\\::”
                     right after the hyphen at the places that really  need  a
                     break point.

              The  remaining  values  were implemented for East Asian language
              support; those who use alphabetic scripts exclusively can 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.

       ..cchhaarr _c _c_o_n_t_e_n_t_s
              Define  the  ordinary  or special character _c as _c_o_n_t_e_n_t_s, which
              can be empty.  More precisely, cchhaarr defines a _g_r_o_f_f  object  (or
              redefines  an  existing one) that is accessed with the name _c on
              input, and produces _c_o_n_t_e_n_t_s on output.  Every time _c is  to  be
              formatted,  _c_o_n_t_e_n_t_s is processed in a temporary environment and
              the result is wrapped up into a  single  object.   Compatibility
              mode  is  turned  off and the escape character is set to \\ while
              _c_o_n_t_e_n_t_s is processed.  Any emboldening,  constant  spacing,  or
              track  kerning is applied to this object as a whole, not to each
              character in _c_o_n_t_e_n_t_s.

              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 ttrr request; it can be made  the
              tab  or  leader  fill character with the ttcc and llcc requests; se‐
              quences of it can be drawn with the \\ll and \\LL escape  sequences;
              and,  if  the hhccooddee request is used on _c, it is subject to auto‐
              matic hyphenation.

              To prevent infinite recursion, occurrences of _c within  its  own
              definition are treated normally (as if it were not being defined
              with  cchhaarr).   The  ttrr and ttrriinn requests take precedence if cchhaarr
              both apply to _c.  A character definition can be removed with the
              rrcchhaarr request.

       ..cchhoopp _o_b_j_e_c_t
              Remove the last character from the macro, string,  or  diversion
              _o_b_j_e_c_t.  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  _o_b_j_e_c_t;  see  section
              “gtroff  Internals”  in  _G_r_o_f_f_: _T_h_e _G_N_U _I_m_p_l_e_m_e_n_t_a_t_i_o_n _o_f _t_r_o_f_f,
              the _g_r_o_f_f Texinfo manual, for discussion of  nodes  inserted  by
              _g_r_o_f_f.

       ..ccllaassss _n_a_m_e _c_1 _c_2 ...
              Define a character class (or simply “class”) _n_a_m_e comprising the
              characters or range expressions _c_1, _c_2, and so on.

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

              In  the request’s simplest form, each _c_n 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 “[[”
              and “]]”, respectively, to avoid collisions with existing charac‐
              ter names defined by _g_r_o_f_f or the user (with  cchhaarr  and  related
              requests).   This  practice  applies  the presence of “]]” in the
              class name to prevent the usage of the special character  escape
              form “\\[[...]]”, thus you must use the \\CC escape to access a class
              with such a name.

              You  can  also  use a character range expression consisting of a
              start character followed by “--” and then an end character.   In‐
              ternally,  GNU  _t_r_o_f_f converts these two character names to Uni‐
              code code points (according to  the  _g_r_o_f_f  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 “[[pprreeppuunnccttxx]]” thus contains the contents of the class
              “[[pprreeppuunncctt]]” and characters in the range U+2013–U+2016.

              If you want to include “--” in a class,  it  must  be  the  first
              character  value  in the argument list, otherwise it gets 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 ccllaassss request is to  control  line‐breaking
              and hyphenation rules as defined by the ccffllaaggss request.  For ex‐
              ample, to inhibit line breaks before the characters belonging to
              the “[[pprreeppuunnccttxx]]” class defined in the previous example, you can
              write the following.
                     .cflags 2 \C'[prepunctx]'

       ..cclloossee _s_t_r_e_a_m
              Close the stream named _s_t_r_e_a_m, invalidating it as an argument to
              the wwrriittee request.  See ooppeenn.

       ..ccoommppoossiittee _c_1 _c_2
              Map  character name _c_1 to character name _c_2 when _c_1 is a combin‐
              ing component in a composite glyph.  Typically,  this  remaps  a
              spacing glyph to a combining one.

       ..ccoonnttiinnuuee
              Skip  the remainder of a “wwhhiillee” loop’s body, immediately start‐
              ing the next iteration.  See bbrreeaakk.

       ..ccoolloorr _n
              If _n is non‐zero or missing, enable colors (the default), other‐
              wise disable them.

       ..ccpp _n  If _n 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.

       ..ddeeffccoolloorr _i_d_e_n_t _s_c_h_e_m_e _c_o_l_o_r_‐_c_o_m_p_o_n_e_n_t ...
              Define a color named _i_d_e_n_t_.  _s_c_h_e_m_e identifies a color space and
              determines  the  number of required _c_o_l_o_r_‐_c_o_m_p_o_n_e_n_ts; it must be
              one of  “rrggbb”  (three  components),  “ccmmyy”  (three  components),
              “ccmmyykk”  (four components), or “ggrraayy” (one component).  “ggrreeyy” is
              accepted as a synonym of “ggrraayy”.  The color  components  can  be
              encoded  as a hexadecimal value starting with ## or ####.  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 “ff”,
              which multiplies its value by 65,536 (but clamps it at 65,535).

              Each output device has a color named “ddeeffaauulltt”, which cannot  be
              redefined.   A  device’s  default stroke and fill colors are not
              necessarily the same.

       ..ddee11 _n_a_m_e [_e_n_d_‐_n_a_m_e]
              Define a macro to be interpreted with  compatibility  mode  dis‐
              abled.   When _n_a_m_e is called, compatibility mode enablement sta‐
              tus is saved; it is restored when the call completes.

       ..ddeeii _n_a_m_e [_e_n_d_‐_n_a_m_e]
              Define macro indirectly, with the name of the macro  to  be  de‐
              fined  in  string _n_a_m_e and the name of the end macro terminating
              its definition in string _e_n_d_‐_n_a_m_e.

       ..ddeeii11 _n_a_m_e [_e_n_d_‐_n_a_m_e]
              As ddeeii, but compatibility mode is disabled while the  definition
              of the macro named in string _n_a_m_e is interpreted.

       ..ddeevviiccee _a_n_y_t_h_i_n_g
              Write  _a_n_y_t_h_i_n_g,  read in copy mode, to _t_r_o_f_f output as a device
              control command.  An initial neutral double quote is stripped to
              allow the embedding of leading spaces.

       ..ddeevviicceemm _n_a_m_e
              Write contents of macro or string _n_a_m_e to _t_r_o_f_f output as a  de‐
              vice control command.

       ..ddoo _n_a_m_e [_a_r_g ...]
              Interpret  the  string, request, diversion, or macro _n_a_m_e (along
              with any arguments) with compatibility mode disabled.   Compati‐
              bility  mode is restored (only if it was active) when the _e_x_p_a_n_‐
              _s_i_o_n of _n_a_m_e is interpreted; that is, the restored compatibility
              state applies to the contents of the macro, string, or diversion
              _n_a_m_e as well as data read from files or pipes if _n_a_m_e is any  of
              the ssoo, ssooqquuiieett, mmssoo, mmssooqquuiieett, or ppssoo requests.

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

       ..ddss11 _n_a_m_e _c_o_n_t_e_n_t_s
              As  ddss,  but compatibility mode is disabled while _n_a_m_e is inter‐
              preted: a “compatibility save” token is inserted at  the  begin‐
              ning of _c_o_n_t_e_n_t_s, and a “compatibility restore” token after it.

       ..eeccrr   Restore the escape character saved with eeccss, or set escape char‐
              acter to “\\” if none has been saved.

       ..eeccss   Save the current escape character.

       ..eevvcc _e_n_v
              Copy  the  properties of environment _e_n_v 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 \\cc escape sequence);

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

              • the activation status of temporary indentation;

              • input traps and their associated data;

              • the  activation status of line numbering (which can be reacti‐
                vated with “..nnmm ++00”); and

              • the count of consecutive hyphenated lines (set to zero).

       ..ffaamm [_f_a_m_i_l_y]
              Set default font family to _f_a_m_i_l_y.  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
              _g_r_o_f_f___f_o_n_t(5).  The default font family is associated  with  the
              environment.  See \\FF.

       ..ffcchhaarr _c _c_o_n_t_e_n_t_s
              Define fallback character _c as _c_o_n_t_e_n_t_s.  The syntax of this re‐
              quest  is the same as the cchhaarr request; the difference is that a
              character defined with cchhaarr hides a glyph with the same name  in
              the  selected  font,  whereas  characters defined with ffcchhaarr are
              checked only if _c isn’t found in the selected font.   This  test
              happens before special fonts are searched.

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

       ..ffsscchhaarr _f _c _c_o_n_t_e_n_t_s
              Define fallback special character _c for font _f as  _c_o_n_t_e_n_t_s.   A
              character  defined  by ffsscchhaarr is located after the list of fonts
              declared with ffssppeecciiaall is searched  but  before  those  declared
              with the “ssppeecciiaall” request.

       ..ffssppeecciiaall _f _s_1 _s_2 ...
              When  font  _f is selected, fonts _s_1, _s_2, ... are treated as spe‐
              cial; that is, they are searched for glyphs not found in _f.  Any
              fonts specified in the “ssppeecciiaall” request are searched after  _s_1,
              _s_2, and so on.  Without _s arguments, ffssppeecciiaall clears the list of
              fonts treated as special when _f is selected.

       ..ffttrr _f _g
              Translate  font  _f to _g.  Whenever a font named _f is referred to
              in an \\ff escape sequence, in the FF and SS conditional  expression
              operators, or in the fftt, uull, bbdd, ccss, ttkkff, ssppeecciiaall, ffssppeecciiaall, ffpp,
              or  ssttyy  requests, font _g is used.  If _g is missing or identical
              to _f, then font _f is not translated.

       ..ffzzoooomm _f _z_o_o_m
              Set zoom factor _z_o_o_m for font _f.  _z_o_o_m 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.  _f must be a
              resolved font name, not an abstract style.

       ..ggccoolloorr _c_o_l_o_r
              Set the stroke color to _c_o_l_o_r.  Without an argument, the  previ‐
              ous stroke color is selected.

       ..hhccooddee _c_1 _c_o_d_e_1 [_c_2 _c_o_d_e_2] ...
              Set the hyphenation code of character _c_1 to _c_o_d_e_1, that of _c_2 to
              _c_o_d_e_2,  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, _g_r_o_f_f 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.
              hhccooddee  extends 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.

       ..hhllaa _l_a_n_g
              Set the hyphenation language to  _l_a_n_g.   Hyphenation  exceptions
              specified  with  the hhww request and hyphenation patterns and ex‐
              ceptions specified with the hhppff and hhppffaa requests are associated
              with the hyphenation language.  The hhllaa request is  usually  in‐
              voked  by  a  localization  file, which is in turn loaded by the
              _t_r_o_f_f_r_c or _t_r_o_f_f_r_c_-_e_n_d file; see the hhppff request below.  The hy‐
              phenation language is associated with the environment.

       ..hhllmm [_n]
              Set the maximum number of consecutive hyphenated lines to _n.  If
              _n is negative, there is no maximum.  If omitted, _n is -1.   This
              value  is  associated  with  the environment.  Only lines output
              from a given environment count towards  the  maximum  associated
              with  that  environment.  Hyphens resulting from \\%% are counted;
              explicit hyphens are not.

       ..hhppff _p_a_t_t_e_r_n_‐_f_i_l_e
              Read hyphenation  patterns  from  _p_a_t_t_e_r_n_‐_f_i_l_e.   This  file  is
              sought in the same way that macro files are with the mmssoo request
              or the --mm_n_a_m_e command‐line option to _g_r_o_f_f(1) and _t_r_o_f_f(1).

              The  _p_a_t_t_e_r_n_‐_f_i_l_e  should  have  the same format as (simple) TeX
              pattern files.  The following scanning rules are implemented.

              • A percent sign starts a comment (up to the end  of  the  line)
                even if preceded by a backslash.

              • “Digraphs” like \\$$ are not supported.

              • “^^^^_x_x”  (where  each  _x is 0–9 or a–f) and ^^^^_c (character _c in
                the code point range 0–127 decimal) are recognized; other uses
                of ^^ cause an error.

              • No macro expansion is performed.

              • hhppff checks for the expression  \\ppaatttteerrnnss{{...}}  (possibly  with
                whitespace  before  or  after the braces).  Everything between
                the braces is taken as  hyphenation  patterns.   Consequently,
                “{{” and “}}” are not allowed in patterns.

              • Similarly,  \\hhyypphheennaattiioonn{{...}}  gives a list of hyphenation ex‐
                ceptions.

              • \\eennddiinnppuutt is recognized also.

              • For backwards compatibility,  if  \\ppaatttteerrnnss  is  missing,  the
                whole  file  is treated as a list of hyphenation patterns (but
                the “%%” character is still recognized as the start of  a  com‐
                ment).

              Use  the hhppffccooddee request (see below) to map the encoding used in
              hyphenation pattern files to _g_r_o_f_f’s input encoding.

              The set of hyphenation patterns is associated with  the  hyphen‐
              ation  language set by the hhllaa request.  The hhppff request is usu‐
              ally invoked by a localization file loaded by the _t_r_o_f_f_r_c  file.
              By  default,  _t_r_o_f_f_r_c  loads  the localization file for English.
              (As of _g_r_o_f_f 1.23.0, localization files for Czech  (_c_s),  German
              (_d_e),  English  (_e_n),  French (_f_r), Japanese (_j_a), Swedish (_s_v),
              and Chinese (_z_h) exist.)  For Western languages,  the  localiza‐
              tion  file  sets the hyphenation mode and loads hyphenation pat‐
              terns and exceptions.

              A second call to hhppff (for the same language)  replaces  the  old
              patterns with the new ones.

              Invoking  hhppff  causes  an  error if there is no hyphenation lan‐
              guage.

              If no hhppff request is specified (either in  the  document,  in  a
              file  loaded at startup, or in a macro package), GNU _t_r_o_f_f won’t
              automatically hyphenate at all.

       ..hhppffaa _p_a_t_t_e_r_n_‐_f_i_l_e
              As hhppff, except that the hyphenation patterns and exceptions from
              _p_a_t_t_e_r_n_‐_f_i_l_e are appended to the patterns already applied to the
              hyphenation language of the environment.

       ..hhppffccooddee _a _b [_c _d] ...
              Define mapping values for  character  codes  in  pattern  files.
              This  is  an older mechanism no longer used by _g_r_o_f_f’s own macro
              files; for its successor, see hhccooddee above.  hhppff  or  hhppffaa  apply
              the  mapping  after  reading  or appending to the active list of
              patterns.  Its arguments are pairs of  character  codes—integers
              from  0  to  255.   The request maps character code _a to code _b,
              code _c to code _d, and so on.  Character codes that would  other‐
              wise  be  invalid  in _g_r_o_f_f 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”.

       ..hhyymm [_l_e_n_g_t_h]
              Set the (right) hyphenation margin to _l_e_n_g_t_h.  If the adjustment
              mode is not “bb” or “nn”, the line is  not  hyphenated  if  it  is
              shorter  than  _l_e_n_g_t_h.  Without an argument, the default hyphen‐
              ation margin is reset to its  default  value,  0.   The  default
              scaling  unit is “mm”.  The hyphenation margin is associated with
              the environment.  A negative  argument  resets  the  hyphenation
              margin to zero, emitting a warning in category “rraannggee”.

       ..hhyyss [_h_y_p_h_e_n_a_t_i_o_n_‐_s_p_a_c_e]
              Suppress hyphenation of the line in adjustment modes “bb” or “nn”,
              if  it can be justified by adding no more than _h_y_p_h_e_n_a_t_i_o_n_‐_s_p_a_c_e
              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  “mm”.   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
              “rraannggee”.

       ..iittcc _n _n_a_m_e
              As “iitt”, but lines interrupted with the \\cc escape  sequence  are
              not applied to the line count.

       ..kkeerrnn _n
              If  _n  is  non‐zero or missing, enable pairwise kerning (the de‐
              fault), otherwise disable it.

       ..lleennggtthh _r_e_g _a_n_y_t_h_i_n_g
              Compute the number of characters  in  _a_n_y_t_h_i_n_g  and  return  the
              count in the register _r_e_g.  If _r_e_g doesn’t exist, it is created.
              _a_n_y_t_h_i_n_g is read in copy mode.

                     ..ddss xxxxxx aabbccdd\\hh''33ii''eeffgghh
                     ..lleennggtthh yyyyyy \\**[[xxxxxx]]
                     \\nn[[yyyyyy]]
                     14

       ..lliinneettaabbss _n
              If  _n  is  non‐zero or missing, enable line‐tabs mode, otherwise
              disable it (the default).  In this mode, tab stops are  computed
              relative to the start of the pending output line, instead of the
              drawing  position  corresponding to the start of the input line.
              Line‐tabs mode is a property of the environment.

              For example, the following

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

       ..llssmm [_n_a_m_e]
              Set the leading space macro (trap) to _n_a_m_e.  If there are  lead‐
              ing  space  characters on an input line, _n_a_m_e is invoked in lieu
              of the usual _r_o_f_f behavior; the leading spaces are removed.  The
              count of leading spaces on an input line is stored  in  \\nn[[llssnn]],
              and  the  amount  of corresponding horizontal motion in \\nn[[llssss]],
              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 _n_a_m_e.  If no argument is  sup‐
              plied, the default leading space behavior is (re‐)established.

       ..mmssoo _f_i_l_e
              As  “ssoo”,  except that _f_i_l_e is sought in the same directories as
              arguments to the _g_r_o_f_f(1) and _t_r_o_f_f(1)  --mm  command‐line  option
              are  (the “tmac path”).  If the file name to be interpolated has
              the form _n_a_m_e..ttmmaacc and it isn’t  found,  mmssoo  tries  to  include
              ttmmaacc.._n_a_m_e  instead  and  vice  versa.  If _f_i_l_e does not exist, a
              warning in category “ffiillee” is emitted and  the  request  has  no
              other effect.

       ..mmssooqquuiieett _f_i_l_e
              As mmssoo, but no warning is emitted if _f_i_l_e does not exist.

       ..nnoopp _a_n_y_t_h_i_n_g
              Interpret  _a_n_y_t_h_i_n_g  as if it were an input line.  nnoopp resembles
              “..iiff 11”; it puts a break on the output  if  _a_n_y_t_h_i_n_g  is  empty.
              Unlike  “iiff”, it cannot govern conditional blocks.  Its applica‐
              tion is to maintain consistent indentation within macro  defini‐
              tions even when producing text lines.

       ..nnrrooffff Make  the  nn  conditional  expression evaluate true and tt false.
              See ttrrooffff.

       ..ooppeenn _s_t_r_e_a_m _f_i_l_e
              Open _f_i_l_e for writing and associate _s_t_r_e_a_m with it.   See  wwrriittee
              and cclloossee.

       ..ooppeennaa _s_t_r_e_a_m _f_i_l_e
              As  ooppeenn, but if _f_i_l_e exists, append to it instead of truncating
              it.

       ..oouuttppuutt _c_o_n_t_e_n_t_s
              Emit _c_o_n_t_e_n_t_s, which are read in copy  mode,  to  the  formatter
              output;  this  is similar to \\!! used in the top‐level diversion.
              An initial neutral double quote in _c_o_n_t_e_n_t_s is stripped to allow
              the embedding of leading spaces.

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

       ..ppnnrr   Write the names and values of all currently defined registers to
              the standard error stream.

       ..ppssbbbb _f_i_l_e
              Get the bounding box of a PostScript image _f_i_l_e.  This file must
              conform to Adobe’s Document Structuring Conventions; the request
              attempts to extract the bounding box values from a %%%%BBoouunnddiinnggBBooxx
              comment.   After  invocation,  the _x and _y coordinates (in Post‐
              Script units) of the lower left and upper right corners  can  be
              found  in  the registers \\nn[[llllxx]], \\nn[[llllyy]], \\nn[[uurrxx]], and \\nn[[uurryy]],
              respectively.  If an error occurs, these four registers are  set
              to zero.

       ..ppssoo _c_o_m_m_a_n_d
              As “ssoo”, except that input comes from the standard output stream
              of _c_o_m_m_a_n_d.

       ..ppttrr   Report  the  names  and  vertical positions of all page location
              traps to the standard error stream.  Empty slots in the list are
              shown as well, because they can affect the visibility of  subse‐
              quently planted traps.

       ..ppvvss _±_n
              Set  the  post‐vertical  line spacing to _n; default scaling unit
              is “pp”.  With no argument, the post‐vertical line space  is  set
              to its previous value.

              In  GNU  _t_r_o_f_f,  the distance between text baselines consists of
              the extra pre‐vertical line spacing set by the most negative  \\xx
              argument  on the pending output line, the vertical spacing (vvss),
              the extra post‐vertical line spacing set by the most positive \\xx
              argument on the pending output line, and the post‐vertical  line
              spacing set by this request.

       ..rrcchhaarr _c ...
              Remove definition of each ordinary or special character _c, undo‐
              ing  the  effect  of  a  cchhaarr, ffcchhaarr, or sscchhaarr request.  Glyphs,
              which are defined by font description files, cannot be  removed.
              Spaces and tabs may separate _c arguments.

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

       ..rrffsscchhaarr _f _c ...
              Remove each fallback special character _c for font _f.  Spaces and
              tabs may separate _c arguments.  See ffsscchhaarr.

       ..rrjj [_n]
              Right‐align the next _n input lines.  Without an argument, right‐
              align the next input line.  rrjj implies “..ccee 00”, and  ccee  implies
              “..rrjj 00”.

       ..rrnnnn _r_1 _r_2
              Rename  register  _r_1 to _r_2.  If _r_1 doesn’t exist, the request is
              ignored.

       ..sscchhaarr _c _c_o_n_t_e_n_t_s
              Define global fallback character _c as _c_o_n_t_e_n_t_s.  See  cchhaarr;  the
              distinction  is  that  a character defined with sscchhaarr is located
              after the list of fonts declared with the  ssppeecciiaall  request  but
              before any mounted special fonts.

       ..sshhcc [_c]
              Set  the  soft hyphen character, inserted when a word is hyphen‐
              ated automatically or at a hyphenation character, to _c.  If _c is
              omitted, the soft hyphen character is set to the default, \\[[hhyy]].
              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  (cchhaarr and similar) nor
              translations (ttrr and similar) are considered when assigning  the
              soft hyphen character.

       ..sshhiifftt _n
              In  a  macro, shift the arguments by _n positions: argument _i be‐
              comes argument _i-_n; arguments 1 to _n are  no  longer  available.
              If  _n  is missing, arguments are shifted by 1.  No effect other‐
              wise.

       ..ssiizzeess _s_1 _s_2 ... _s_n [00]
              Set the available type sizes to _s_1, _s_2, ...  _s_n  scaled  points.
              The list of sizes can be terminated by an optional “00”.  Each _s_i
              can  also be a range _m–_n.  In contrast to the device description
              file directive of the same name (see _g_r_o_f_f___f_o_n_t(5)),  the  argu‐
              ment list can’t extend over more than one line.

       ..ssooqquuiieett _f_i_l_e
              As “ssoo”, but no warning is emitted if _f_i_l_e does not exist.

       ..ssppeecciiaall _f ...
              Declare  each  font  _f  as  special, searching it for glyphs not
              found in the selected font.  Without  arguments,  this  list  of
              special fonts is made empty.

       ..sspprreeaaddwwaarrnn [_l_i_m_i_t]
              Emit  a  bbrreeaakk warning if the additional space inserted for each
              space between words in an output line adjusted to  both  margins
              with “..aadd bb” is larger than or equal to _l_i_m_i_t.  A negative value
              is  treated  as  zero; an absent argument toggles the warning on
              and off without changing _l_i_m_i_t.  The default scaling unit is  mm.
              At startup, sspprreeaaddwwaarrnn is inactive and _l_i_m_i_t is 3 m.

              For  example, “..sspprreeaaddwwaarrnn 00..22mm” causes a warning if bbrreeaakk warn‐
              ings are not suppressed and _t_r_o_f_f must add 0.2  m  or  more  for
              each inter‐word space in a line.

       ..ssttrriinnggddoowwnn _s_t_r
       ..ssttrriinngguupp _s_t_r
              Alter  the  string named _s_t_r by replacing each of its bytes with
              its lowercase (ddoowwnn) or uppercase (uupp) version (if one  exists).
              Special  characters  (see _g_r_o_f_f___c_h_a_r(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.

                     ..ddss rreessuummee RR\\[[''ee]]ssuumm\\[[''ee]]\\""
                     \\**[[rreessuummee]]
                     ..ssttrriinnggddoowwnn rreessuummee
                     \\**[[rreessuummee]]
                     ..ssttrriinngguupp rreessuummee
                     \\**[[rreessuummee]]
                     Résumé résumé RÉSUMÉ

       ..ssttyy _n _s
              Associate abstract style _s with font mounting position _n.

       ..ssuubbssttrriinngg _s_t_r_i_n_g _s_t_a_r_t [_e_n_d]
              Replace the string named _s_t_r_i_n_g with its  substring  bounded  by
              the  indices _s_t_a_r_t and _e_n_d, inclusively.  The first character in
              the string has index 0.  If _e_n_d 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.

                     ..ddss xxxxxx aabbccddeeffgghh
                     ..ssuubbssttrriinngg xxxxxx 11 --44
                     \\**[[xxxxxx]]
                     bcde
                     ..ssuubbssttrriinngg xxxxxx 22
                     \\**[[xxxxxx]]
                     de

       ..ttkkff _f _s_1 _n_1 _s_2 _n_2
              Enable track kerning for font _f.  When the current font is _f the
              width of every glyph is increased by an amount  between  _n_1  and
              _n_2;  when  the current type size is less than or equal to _s_1 the
              width is increased by _n_1; when it is greater than or equal to _s_2
              the width is increased by _n_2; when the type size is greater than
              or equal to _s_1 and less than or equal  to  _s_2  the  increase  in
              width is a linear function of the type size.

       ..ttmm11 _m_e_s_s_a_g_e
              As  ttmm  request,  but strips a leading neutral double quote from
              _m_e_s_s_a_g_e to allow the embedding of leading spaces.

       ..ttmmcc _m_e_s_s_a_g_e
              As ttmm11 request, but does not append a newline.

       ..ttrrff _f_i_l_e
              Transparently output the contents of file _f_i_l_e.   Each  line  is
              output  as if preceded by \\!!; however, the lines are not subject
              to copy‐mode interpretation.  If the file does not  end  with  a
              newline,  then  a newline is added.  Unlike ccff, _f_i_l_e cannot con‐
              tain characters that are invalid as input to GNU _t_r_o_f_f.

              For example, you can define a macro _x containing the contents of
              file _f, using

                     .di x
                     .trf f
                     .di

       ..ttrriinn _a_b_c_d
              This is the same as the ttrr request except that the  aasscciiiiffyy  re‐
              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 ttrr, the result would be “x x”.

       ..ttrrnntt _a_b_c_d
              This is the same as the ttrr request except that the  translations
              do not apply to text that is transparently throughput into a di‐
              version with \\!!.  For example,

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

              prints bb; if ttrrnntt is used instead of ttrr it prints aa.

       ..ttrrooffff Make  the  tt  conditional  expression evaluate true and nn false.
              See nnrrooffff.

       ..uunnffoorrmmaatt _d_i_v
              Unformat the diversion _d_i_v.  Unlike  aasscciiiiffyy,  uunnffoorrmmaatt  handles
              only  tabs  and spaces between words, the latter usually arising
              from spaces or newlines in the input.  Tabs are treated as input
              tokens, and spaces become adjustable again.  The vertical  sizes
              of  lines  are  not preserved, but glyph information (font, type
              size, space width, and so on) is retained.

       ..vvpptt _n If _n is non‐zero or missing, enable vertical position traps (the
              default), otherwise disable them.  Vertical position  traps  are
              those set by the cchh, wwhh, and ddtt requests.

       ..wwaarrnn [_n]
              Select  the  categories, or “types”, of reported warnings.  _n 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  _t_r_o_f_f(1).   For  example, “..wwaarrnn 00” disables all
              warnings, and “..wwaarrnn 11” disables all warnings except those about
              missing glyphs.  If no argument is given, all warning categories
              are enabled.

       ..wwaarrnnssccaallee _s_i
              Set the scaling unit used in warnings to _s_i.  Valid  values  for
              _s_i are uu, ii (the default), cc, pp, and PP.

       ..wwhhiillee _c_o_n_d_‐_e_x_p_r _a_n_y_t_h_i_n_g
              Evaluate  the  conditional  expression _c_o_n_d_‐_e_x_p_r, and repeatedly
              execute _a_n_y_t_h_i_n_g unless and  until  _c_o_n_d_‐_e_x_p_r  evaluates  false.
              _a_n_y_t_h_i_n_g_,  which is often a conditional block, is referred to as
              the wwhhiillee request’s _b_o_d_y_.

              _t_r_o_f_f treats the body of a wwhhiillee request similarly to that of  a
              ddee request (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 wwhhiillee request can slow signif‐
              icantly if the wwhhiillee body is large.  Each time the macro is exe‐
              cuted, the wwhhiillee body is parsed and stored again.  An often bet‐
              ter  solution—and  one  that  is more portable, since AT&T _t_r_o_f_f
              lacked the wwhhiillee request—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 sslliimmiitt
              register.  See section “Debugging” below.

              If a wwhhiillee body begins with a  conditional  block,  its  closing
              brace must end an input line.

              The  bbrreeaakk  and  ccoonnttiinnuuee  requests alter a wwhhiillee loop’s flow of
              control.

       ..wwrriittee _s_t_r_e_a_m _a_n_y_t_h_i_n_g
              Write _a_n_y_t_h_i_n_g to _s_t_r_e_a_m, which must previously  have  been  the
              subject  of an ooppeenn request, followed by a newline.  _a_n_y_t_h_i_n_g is
              read in copy mode.  An initial neutral double quote in  _a_n_y_t_h_i_n_g
              is stripped to allow the embedding of leading spaces.

       ..wwrriitteecc _s_t_r_e_a_m _a_n_y_t_h_i_n_g
              As wwrriittee, but without a trailing newline.

       ..wwrriitteemm _s_t_r_e_a_m _n_a_m_e
              Write  the contents of the macro or string _n_a_m_e to _s_t_r_e_a_m, which
              must previously have been the subject of an ooppeenn request.   _n_a_m_e
              is read in copy mode.

   EExxtteennddeedd rreeqquueessttss
       ..ccff _f_i_l_e
              In  a  diversion, embed an object which, when reread, will cause
              the contents of _f_i_l_e to be copied verbatim to  the  output.   In
              AT&T  _t_r_o_f_f,  the contents of _f_i_l_e 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.

       ..ddee _n_a_m_e [_e_n_d_‐_n_a_m_e]
       ..aamm _n_a_m_e [_e_n_d_‐_n_a_m_e]
       ..ddss _n_a_m_e [_c_o_n_t_e_n_t_s]
       ..aass _n_a_m_e [_c_o_n_t_e_n_t_s]
              In  compatibility  mode, these requests behave similarly to ddee11,
              aamm11, ddss11, and aass11, 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.

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

       ..ssss _w_o_r_d_‐_s_p_a_c_e_‐_s_i_z_e [_a_d_d_i_t_i_o_n_a_l_‐_s_e_n_t_e_n_c_e_‐_s_p_a_c_e_‐_s_i_z_e]
              A second argument sets the amount of additional space separating
              sentences on the same output line.  If omitted, this  amount  is
              set  to _w_o_r_d_‐_s_p_a_c_e_‐_s_i_z_e.  Both arguments are in twelfths of cur‐
              rent font’s space width (typically one‐fourth  to  one‐third  em
              for  Western  scripts; see _g_r_o_f_f___f_o_n_t(5)).  The default for both
              parameters is 12.  Negative values are erroneous.

       ..ttaa [[_n_1 _n_2 ... _n_n ]TT _r_1 _r_2 ... _r_n]
              _g_r_o_f_f supports an extended syntax to specify repeating tab stops
              after the “TT” 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 _g_r_o_f_f.

              The  syntax  summary  above instructs _g_r_o_f_f to set tabs at posi‐
              tions _n_1, _n_2, ..., _n_n, then at _n_n+_r_1, _n_n+_r_2, ..., _n_n+_r_n, then at
              _n_n+_r_n+_r_1, _n_n+_r_n+_r_2, ..., _n_n+_r_n+_r_n, and so on.

   NNeeww rreeggiisstteerrss
       GNU _t_r_o_f_f exposes more formatter state via many  new  read‐only  regis‐
       ters.  Their names often correspond to the requests that affect them.

       \\nn[[..bbrr]]     Within  a  macro call, interpolate 1 if the macro is called
                   with the “normal” control character (“.” by default), and 0
                   otherwise.  This facility allows the reliable  modification
                   of requests.  Using this register outside of a macro 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
                          ..

       \\nn[[..CC]]      Interpolate  1 if compatibility mode is in effect, 0 other‐
                   wise.  See ccpp.

       \\nn[[..ccddpp]]    Interpolate depth of last glyph added to  the  environment.
                   It is positive if the glyph extends below the baseline.

       \\nn[[..ccee]]     Interpolate number of input lines remaining to be centered.

       \\nn[[..cchhtt]]    Interpolate  height of last glyph added to the environment.
                   It is positive if the glyph extends above the baseline.

       \\nn[[..ccoolloorr]]  Interpolate 1 if colors are enabled, 0 otherwise.

       \\nn[[..ccpp]]     Within a “ddoo” request, interpolate the saved value of  com‐
                   patibility mode (see \\nn[[..CC]] above).

       \\nn[[..ccsskk]]    Interpolate  skew  of  last glyph added to the environment.
                   The _s_k_e_w 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.

       \\nn[[..eevv]]     Interpolate name of current environment.  This is a string‐
                   valued register.

       \\nn[[..ffaamm]]    Interpolate name of default font family.  This is a string‐
                   valued register.

       \\nn[[..ffnn]]     Interpolate resolved name of the selected font.  This is  a
                   string‐valued register.

       \\nn[[..ffpp]]     Interpolate next free font mounting position.

       \\nn[[..gg]]      Interpolate  1.   Test with “iiff” or iiee to check whether GNU
                   _t_r_o_f_f is the formatter.

       \\nn[[..hheeiigghhtt]] Interpolate font height.  See \\HH.

       \\nn[[..hhllaa]]    Interpolate hyphenation language of the environment.   This
                   is a string‐valued register.

       \\nn[[..hhllcc]]    Interpolate  count of immediately preceding consecutive hy‐
                   phenated lines in the environment.

       \\nn[[..hhllmm]]    Interpolate maximum number of consecutive hyphenated  lines
                   allowed in the environment.

       \\nn[[..hhyy]]     Interpolate hyphenation mode of the environment.

       \\nn[[..hhyymm]]    Inteprolate hyphenation margin of the environment.

       \\nn[[..hhyyss]]    Interpolate  hyphenation  space adjustment threshold of the
                   environment.

       \\nn[[..iinn]]     Interpolate indentation amount applicable  to  the  pending
                   output line.

       \\nn[[..iinntt]]    Interpolate  1  if the previous output line was interrupted
                   (ended with \\cc), 0 otherwise.

       \\nn[[..kkeerrnn]]   Interpolate 1 if pairwise kerning is enabled, 0 otherwise.

       \\nn[[..llgg]]     Interpolate ligature mode.

       \\nn[[..lliinneettaabbss]]
                   Interpolate 1 if line‐tabs mode is enabled, 0 otherwise.

       \\nn[[..llll]]     Interpolate line length applicable to  the  pending  output
                   line.

       \\nn[[..lltt]]     Interpolate title line length.

       \\nn[[..mm]]      Interpolate  name  of the selected stroke color.  This is a
                   string‐valued register.

       \\nn[[..MM]]      Interpolate name of the selected fill  color.   This  is  a
                   string‐valued register.

       \\nn[[..nnee]]     Interpolate  amount of space demanded by the most recent nnee
                   request that caused a page location trap to be sprung.  See
                   \\nn[[..ttrruunncc]].

       \\nn[[..nnmm]]     Interpolate 1 if output line numbering is enabled (even  if
                   temporarily suppressed), 0 otherwise.

       \\nn[[..nnss]]     Interpolate 1 if no‐space mode is enabled, 0 otherwise.

       \\nn[[..OO]]      Interpolate output suppression level.  See \\OO.

       \\nn[[..PP]]      Interpolate  1  if the current page is selected for output.
                   See --oo command‐line option to _t_r_o_f_f(1).

       \\nn[[..ppee]]     Interpolate 1 during page ejection, 0 otherwise.

       \\nn[[..ppnn]]     Interpolate next page number (either that  set  by  ppnn,  or
                   that of the current page plus 1).

       \\nn[[..ppss]]     Interpolate type size in scaled points.

       \\nn[[..ppssrr]]    Interpolate  most  recently  requested  type size in scaled
                   points.

       \\nn[[..ppvvss]]    Interpolate post‐vertical line spacing amount.

       \\nn[[..rrjj]]     Interpolate number of input lines remaining  to  be  right‐
                   aligned.

       \\nn[[..ssllaanntt]]  Interpolate font slant.  See \\SS.

       \\nn[[..ssrr]]     Interpolate  most recently requested type size in points as
                   a decimal fraction.  This is a string‐valued register.

       \\nn[[..ssss]]
       \\nn[[..ssssss]]    Interpolate values of minimal inter‐word  space  and  addi‐
                   tional  inter‐sentence  space, respectively, in twelfths of
                   the space width of the selected font.

       \\nn[[..ssttyy]]    Interpolate selected abstract font style, if any.  This  is
                   a string‐valued register.

       \\nn[[..ttaabbss]]   Interpolate  representation  of  the tab stop settings in a
                   form suitable for passage to the ttaa request.

       \\nn[[..ttrruunncc]]  Interpolate amount of vertical space truncated by the  most
                   recently  sprung  page  location  trap, or, if the trap was
                   sprung by an nnee request, minus the amount of  vertical  mo‐
                   tion  produced  by  the nnee request.  In other words, at the
                   point a trap is sprung, \\nn[[..ttrruunncc]] represents  the  differ‐
                   ence  of what the vertical position would have been but for
                   the trap, and what the vertical position actually is.   See
                   \\nn[[..nnee]].

       \\nn[[..UU]]      Interpolate  1 if in unsafe mode, 0 otherwise.  See --UU com‐
                   mand‐line option to _t_r_o_f_f(1).

       \\nn[[..vvpptt]]    Interpolate 1  if  vertical  position  traps  are  enabled,
                   0 otherwise.

       \\nn[[..wwaarrnn]]   Interpolate   warning  mode.   See  section  “Warnings”  of
                   _t_r_o_f_f(1).

       \\nn[[..xx]]      Interpolate major version number of the running _t_r_o_f_f  for‐
                   matter.  For example, if the version number is 1.23.0, then
                   \\nn[[..xx]] contains 1.

       \\nn[[..yy]]      Interpolate  minor version number of the running _t_r_o_f_f for‐
                   matter.  For example, if the version number is 1.23.0, then
                   \\nn[[..yy]] contains 23.

       \\nn[[..YY]]      Interpolate revision number of the running _t_r_o_f_f formatter.
                   For example, if the version number is 1.23.0,  then  \\nn[[..YY]]
                   contains 0.

       \\nn[[..zzoooomm]]   Interpolate  magnification of font, in thousandths, or 0 if
                   magnification unused.  See ffzzoooomm.

       The following (writable) registers are set by the ppssbbbb request.

       \\nn[[llllxx]]
       \\nn[[llllyy]]
       \\nn[[uurrxx]]
       \\nn[[uurryy]]
              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 \\ww escape sequence.

       \\nn[[rrsstt]]
       \\nn[[rrssbb]] Like \\nn[[sstt]] and \\nn[[ssbb]], 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 \\ww escape sequence, doing what AT&T _t_r_o_f_f doc‐
               umented \\nn[[sstt]] and \\nn[[ssbb]] as doing.

       \\nn[[sssscc]] The  amount of horizontal space (possibly negative) that should
               be added to the last glyph before a subscript.

       \\nn[[sskkww]] How far to right of the center of the last glyph in the \\ww  ar‐
               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 _l_o_c_a_l_t_i_m_e(3) at formatter startup.

       \\nn[[cc..]]      Interpolate input line number.  \\nn[[..cc]] is a read‐only alias
                   of this register.

       \\nn[[hhoouurrss]]   Interpolate number of hours elapsed since midnight.

       \\nn[[hhpp]]      Interpolate  horizontal  position  relative  to that at the
                   start of the input line.

       \\nn[[llssnn]]
       \\nn[[llssss]]     Interpolate count of  leading  spaces  on  input  line  and
                   amount of corresponding horizontal motion, respectively.

       \\nn[[mmiinnuutteess]] Interpolate number of minutes elapsed in the hour.

       \\nn[[sseeccoonnddss]] Interpolate number of seconds elapsed in the minute.

       \\nn[[ssyyssttaatt]]  Interpolate  return value of _s_y_s_t_e_m(3) function executed by
                   most recent ssyy request.

       \\nn[[sslliimmiitt]]  Interpolates maximum quantity of objects on _t_r_o_f_f’s  inter‐
                   nal input stack (default: 1000).  If non‐positive, there is
                   no  limit:  recursion  can continue until program memory is
                   exhausted.

       \\nn[[yyeeaarr]]    Interpolate Gregorian year.  AT&T  _t_r_o_f_f’s  \\[[yyrr]]  interpo‐
                   lates the Gregorian year minus 1900.

   MMiisscceellllaanneeoouuss
       GNU  _t_r_o_f_f  predefines one string, ..TT, containing the argument given to
       the --TT command‐line option, namely the output device (for example,  ppddff
       or  uuttff88).   The (read‐only) _r_e_g_i_s_t_e_r ..TT interpolates 1 if GNU _t_r_o_f_f is
       run with the --TT command‐line option, and 0 otherwise.

       A font not listed in the output device’s _D_E_S_C file’s ffoonnttss directive is
       automatically mounted at the next available font position  when  it  is
       selected.   If  you  mount  a  font explicitly with the ffpp request, you
       should do so on the first unused position, which can be  found  in  the
       ..ffpp register.

       Unparameterized  string interpolation does not conceal the arguments to
       a macro being interpreted.  Thus, in a macro definition,  the  call  of
       another macro with the existing argument list,
              .._x_x \\\\$$@@
       is more efficiently done with
              \\\\**[[_x_x]]\\\\
       (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 _g_r_o_f_f(7).

       If  a  font  description  file  contains  pairwise kerning information,
       glyphs from that font are kerned.  Kerning between two  glyphs  can  be
       inhibited by placing a dummy character \\&& between them.

       GNU  _t_r_o_f_f keeps track of the nesting depth of escape sequence interpo‐
       lations and other uses of delimiters, as in the ttll request and the out‐
       put comparison operator (that is, input like ''ffoooo''bbaarr'' as 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, '' works fine.  Use visible char‐
       acters as delimiters in GNU _t_r_o_f_f, not “ASCII” controls like BEL  (Con‐
       trol+G).  The implementation of \\$$@@ ensures 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  \\ff[[ZZCCMMII]],,  a right bracket ]] does not end the sequence
       unless it occurs at the same interpolation depth as the opening  [[,  so
       input like
              \f[\*[my‐family]\*[my‐style]]
       works  as  desired.  In compatibility mode, no attention is paid to the
       interpolation depth.

       In GNU _t_r_o_f_f, the ttrr request can  map  characters  to  the  unbreakable
       space  escape  sequence \\~~ as a special case (ttrr normally operates only
       on _c_h_a_r_a_c_t_e_r_s).  This feature replaces the odd‐parity ttrr mapping  trick
       used  in  AT&T _t_r_o_f_f documents, where a character, often ~~, 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 _t_r_o_f_f_, which supported the \\_s_p_a_c_e escape sequence by  1976.)
       Often,  it  makes  more sense to use GNU _t_r_o_f_f’s \\~~ escape sequence in‐
       stead, which has been adopted by every other active  _t_r_o_f_f  implementa‐
       tion  except  that  of  Illumos,  as  well  as by the non_‐_t_r_o_f_f _m_a_n_d_o_c.
       Translation of a character to \\~~ is unnecessary.

       GNU _t_r_o_f_f 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'.
              .  .
              .\}

FFoorrmmaatttteerr oouuttppuutt
       The page description language output by GNU _t_r_o_f_f is modeled after that
       used by AT&T _t_r_o_f_f once the latter  adopted  a  device‐independent  ap‐
       proach  in  the early 1980s.  Only the differences are documented here.
       For a fuller discussion, see _g_r_o_f_f___o_u_t(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 _t_r_o_f_f, drivers need not search  special  fonts  to  find  a
       glyph.

   UUnniittss
       The  argument  to the ss command is in scaled points (units of points/_n,
       where _n is the argument to the ssiizzeessccaallee command  in  the  _D_E_S_C  file).
       The argument to the “xx HH” command is also in scaled points.

   SSiimmppllee ccoommmmaannddss
       If  the ttccoommmmaanndd directive is present in the output device’s _D_E_S_C file,
       GNU _t_r_o_f_f employs the following two commands.

       tt _x_y_z...
              Typeset word _x_y_z; that is, set a  sequence  of  ordinary  glyphs
              named  _x,  _y,  _z,  ..., 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 CC command to emplace glyphs of spe‐
              cial characters.

       uu _n _x_y_z...
              Typeset  word  _x_y_z  with track kerning.  As tt, but after placing
              each glyph, the drawing position is  further  advanced  horizon‐
              tally by _n basic units.

       New commands implement color support.

       mmcc _c_y_a_n _m_a_g_e_n_t_a _y_e_l_l_o_w
       mmdd
       mmgg _g_r_a_y
       mmkk _c_y_a_n _m_a_g_e_n_t_a _y_e_l_l_o_w _b_l_a_c_k
       mmrr _r_e_d _g_r_e_e_n _b_l_u_e
              Set  the  components of the stroke color with respect to various
              color spaces.  mmdd resets the stroke color to the default  value.
              The arguments are integers in the range 0 to 65535.

       A new device control subcommand is available.

       xx uu _n  If  _n is 1, start underlining of spaces.  If _n is 0, stop under‐
              lining of spaces.  This facility is needed for the ccuu request in
              _n_r_o_f_f mode and is ignored otherwise.

   EExxtteennddeedd ddrraawwiinngg ccoommmmaannddss
       GNU _p_i_c does not produce _t_r_o_f_f escape sequences employing these  exten‐
       sions if its --nn option is given.

       DDff _n   Set the shade of gray used to fill geometric objects to _n, which
              must  be  an integer.  0 corresponds to white and 1000 to black.
              A grayscale ramp spans the two.  A value outside this range uses
              the stroke color as the fill color.  The fill color  is  opaque.
              Normally  the  default  is black, but some drivers may provide a
              way of changing this.  DDff is obsolete since 2002, superseded  by
              DDFFgg below.

              The  corresponding \\DD''ff'' escape 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 _n.

       DDCC _d   Draw a filled circle of diameter _d with its  leftmost  point  at
              the drawing position.

       DDEE _h _v Draw a filled ellipse, of horizontal axis _h and vertical axis _v,
              with its leftmost point at the drawing position.

       DDpp _d_x1_d_y1..._d_x_n_d_y_n
              Draw  a  polygon  with,  for  _i=1,...,_n+1, its _ith vertex at the
              drawing position +_i_j−=Σ11(_d_x_j,_d_y_j).  _g_r_o_f_f output drivers  automati‐
              cally  close  polygons,  drawing  a  line from (_d_x_n,_d_y_n) back to
              (_d_x1,_d_y1).  The drawing position is left at the  last  _s_p_e_c_i_f_i_e_d
              vertex,  but  this  may change in a future version of GNU _t_r_o_f_f.
              Heirloom Doctools _t_r_o_f_f, like DWB _t_r_o_f_f,  by  default  does  not
              close  the  polygon.   In its _g_r_o_f_f compatibility mode, Heirloom
              closes the polygon but leaves the  drawing  position  _u_n_c_h_a_n_g_e_d—
              that is, at the polygon’s _i_n_i_t_i_a_l drawing position.

              At the moment, GNU _p_i_c uses this command only to generate trian‐
              gles and rectangles.

       DDPP _d_x1_d_y1..._d_x_n_d_y_n
              As DDpp, but draw a filled rather than a stroked polygon.

       DDtt _n   Set the line thickness to _n basic units.  AT&T _t_r_o_f_f output dri‐
              vers  use a thickness proportional to the type size; this is the
              GNU _t_r_o_f_f default.  A negative _n requests this explicitly.  An _n
              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  _g_r_n and _p_i_c does not depend on it.
       Given a drawing command of the form DD_z _x1_y1..._x_n_y_n, where _z is not cc or
       ee, AT&T _t_r_o_f_f treats each _x_i as a horizontal motion, each _y_i as a  ver‐
       tical  one, and therefore assumes that the width of the drawn object is
       _i_n=Σ1_x_i, and its height is _i_n=Σ1_y_i.  (Verify its assumption about height by
       examining the sstt and ssbb registers after using such a drawing command in
       a \\ww escape sequence).  For the sake of compatibility, GNU  _t_r_o_f_f  also
       follows  this  rule, even though it frustrates extensions to the DD com‐
       mand that set drawing parameters rather than rendering objects, produc‐
       ing ugly results in the case of DDtt and DDff, or otherwise  don’t  parame‐
       terize  objects as a series of vertices, as with GNU _t_r_o_f_f’s filled el‐
       lipse,  DDEE.   Thus  after  executing  a  DD  command  of  the  form   DD_z
       _x1_y1..._x_n_y_n, the drawing position should be increased by (_i_n=Σ1_x_i,_i_n=Σ1_y_i).
       In  a  future release, GNU _t_r_o_f_f 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.

       DDFFcc _c_y_a_n _m_a_g_e_n_t_a _y_e_l_l_o_w
       DDFFdd
       DDFFgg _g_r_a_y
       DDFFkk _c_y_a_n _m_a_g_e_n_t_a _y_e_l_l_o_w _b_l_a_c_k
       DDFFrr _r_e_d _g_r_e_e_n _b_l_u_e
              Set the components of the fill color as described under  the  \\MM
              escape  sequence  above.  DDFFdd restores the device’s default fill
              color.  The drawing position is not updated, in contrast to DDff.

   DDeevviiccee ccoonnttrrooll ssyynnttaaxx eexxtteennssiioonn
       GNU _t_r_o_f_f introduces a line continuation convention, permitting the ar‐
       gument to the xx XX command to contain newlines.  A newline in the  input
       is  transformed  to  the sequence “_n_e_w_l_i_n_e++”.  When interpreting an xx XX
       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  xx  XX
       command.  A newline _n_o_t followed by a plus sign terminates the xx XX com‐
       mand.  An application of this feature is the embedding of PostScript or
       PDF language command streams into _t_r_o_f_f output.

       GNU  _t_r_o_f_f guarantees that the first three output commands it emits are
       as follows.

              x T _d_e_v_i_c_e
              x res _n _h _v
              x init

DDeebbuuggggiinngg
       In addition to AT&T _t_r_o_f_f’s debugging features, GNU  _t_r_o_f_f  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 wwaarrnn.  Also see the --EE, --ww, and  --WW  options  of  _t_r_o_f_f(1).
       Backtraces  can be automatically produced when errors or warnings occur
       (the --bb option of _t_r_o_f_f(1)) or generated on demand (bbaacckkttrraaccee).

       _g_r_o_f_f also adds more flexible diagnostic output requests (ttmmcc and ttmm11).
       More aspects of formatter state can  be  examined  with  requests  that
       write  lists  of  defined registers (ppnnrr), environments (ppeevv), and page
       location traps (ppttrr) to the standard error stream.

IImmpplleemmeennttaattiioonn ddiiffffeerreenncceess
       GNU _t_r_o_f_f’s features sometimes cause incompatibilities  with  documents
       written  assuming old implementations of _t_r_o_f_f.  Some GNU extensions to
       _t_r_o_f_f are supported by other implementations.

       When adjusting to both margins, AT&T  _t_r_o_f_f  at  first  adjusts  spaces
       starting  from  the right; GNU _t_r_o_f_f begins from the left.  Both imple‐
       mentations adjust spaces from opposite ends on alternating output lines
       to prevent “rivers” in the text.

       GNU _t_r_o_f_f does not always hyphenate words as AT&T _t_r_o_f_f does.  The AT&T
       implementation uses a set of hard‐coded rules specific to U.S. English,
       while GNU _t_r_o_f_f uses language‐specific hyphenation  pattern  files  de‐
       rived  from  TeX.  In some versions of _t_r_o_f_f there was limited space to
       store hyphenation exceptions (arguments to the hhww request);  GNU  _t_r_o_f_f
       has no such restriction.

       Long  names may be GNU _t_r_o_f_f’s most obvious innovation.  AT&T _t_r_o_f_f in‐
       terprets “..ddssaabbccdd” as defining a string “aabb” with contents “ccdd”.   Nor‐
       mally,  GNU  _t_r_o_f_f interprets this as a call of a macro named “ddssaabbccdd”.
       AT&T _t_r_o_f_f also interprets \\**[[ and \\nn[[ as an interpolation of a  string
       or  register, respectively, called “[[”.  In GNU _t_r_o_f_f, however, the “[[”
       is normally interpreted as beginning the enclosure of  a  long  identi‐
       fier.   In compatibility mode, GNU _t_r_o_f_f interprets names in the tradi‐
       tional way, which means that they are limited to one or two characters.
       See the --CC option in _t_r_o_f_f(1) and, above, the ..CC and ..ccpp registers, and
       ccpp and “ddoo” requests, for more on compatibility mode.

       The register \\nn[[..ccpp]] is specialized and may require a statement of  ra‐
       tionale.   When  writing macro packages or documents that use GNU _t_r_o_f_f
       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 “ssoo” or mmssoo requests—you may desire correct operation regardless
       of compatibility mode enablement in the surrounding  context.   It  may
       occur  to you to save the existing value of \\nn((..CC into a register, say,
       __CC, at the beginning of your file, turn  compatibility  mode  off  with
       “..ccpp   00”,  then  restore  it  from  that  register  at  the  end  with
       “..ccpp \\nn((__CC”.  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  _t_r_o_f_f is confining and mnemonically challenging; you may wish
       to use GNU _t_r_o_f_f’s more capacious name space.  However, attempting “..nnrr
       __mmyy__ssaavveedd__CC \\nn((..CC” will not work in compatibility  mode;  the  register
       name  is  too long.  “This is exactly what ..ddoo is for,” you think, “..ddoo
       nnrr __mmyy__ssaavveedd__CC \\nn((..CC”.  The foregoing will always  save  zero  to  your
       register, because “ddoo” turns compatibility mode _o_f_f 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 ..TT string is a common  feature  of  post‐CSTR  #54
       _t_r_o_f_fs—DWB  3.3,  Solaris, Heirloom Doctools, and Plan 9 _t_r_o_f_f all sup‐
       port it—but valid values are specific to each implementation.  The  be‐
       havior  of  the ..TT register in GNU _t_r_o_f_f differs from AT&T _t_r_o_f_f, which
       interpolated 1 only if _n_r_o_f_f was the formatter and was called with --TT.

       The llff request sets the number of the _c_u_r_r_e_n_t input line in AT&T _t_r_o_f_f,
       and the _n_e_x_t in GNU _t_r_o_f_f.

       AT&T _t_r_o_f_f had only environments named  “00”,  “11”,  and  “22”.   In  GNU
       _t_r_o_f_f,  any  number  of environments may exist, using any valid identi‐
       fiers for their names.

       GNU _t_r_o_f_f 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 \\ff, \\HH, \\mm, \\MM, \\RR, \\ss, and
       \\SS are transparent at the beginning of an input line for the purpose of
       recognizing a control character, because they  modify  formatter  state
       (\\RR)  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  _t_r_o_f_f  request  names  unrecognized by other _t_r_o_f_f implementations
       will likely be ignored; escape sequences that are GNU _t_r_o_f_f  extensions
       are  liable  to format their function selector character.  For example,
       the adjustable, non‐breaking space escape sequence \\~~ is also supported
       by Heirloom  Doctools  _t_r_o_f_f  050915  (September  2005),  _m_a_n_d_o_c  1.9.5
       (2009‐09‐21),  _n_e_a_t_r_o_f_f (commit 1c6ab0f6e, 2016‐09‐13), and Plan 9 from
       User Space _t_r_o_f_f  (commit  93f8143600,  2022‐08‐12),  but  not  by  So‐
       laris/Illumos _t_r_o_f_fs, which will render it as ~~.

       GNU  _t_r_o_f_f  does  not allow the use of the escape sequences \\||, \\^^, \\&&,
       \\{{, \\}}, \\_s_p_a_c_e, \\'', \\``, \\--, \\__, \\!!, \\%%,  or  \\cc  in  identifiers;  AT&T
       _t_r_o_f_f  does.  The \\AA escape sequence (see subsection “Escape sequences”
       above) may be helpful in avoiding their use.

       Normally, the syntax form \\ss_n accepts only a single character (a digit)
       for _n, consistently with other forms that  originated  in  AT&T  _t_r_o_f_f,
       like  \\**,  \\$$,  \\ff,  \\gg, \\kk, \\nn, and \\zz.  In compatibility mode only, a
       non‐zero _n must be in the range 4–39.  Legacy  documents  relying  upon
       this  quirk  of  parsing should be migrated to another \\ss form.  [Back‐
       ground: The Graphic Systems C/A/T phototypesetter (the original  device
       target  for AT&T _t_r_o_f_f) 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
       _t_r_o_f_f the ppss request ignores scaling units and thus “..ppss 1100uu” sets  the
       type  size  to 10 points, whereas in GNU _t_r_o_f_f it sets the type size to
       10 _s_c_a_l_e_d points, which may be a much smaller measurement.  See subsec‐
       tion “Fractional type sizes and new scaling units” above.

       The aabb request differs from AT&T _t_r_o_f_f: GNU _t_r_o_f_f 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 bbpp request differs from AT&T _t_r_o_f_f: GNU _t_r_o_f_f  does  not  accept  a
       scaling  unit on the argument, a page number; the former (somewhat use‐
       lessly) does.

       In AT&T _t_r_o_f_f the ppmm request reports macro, string, and diversion sizes
       in units of 128‐byte blocks, and an argument reduces the  report  to  a
       sum  of  the  above in the same units.  GNU _t_r_o_f_f ignores any arguments
       and reports the sizes in bytes.

       Unlike AT&T _t_r_o_f_f, GNU _t_r_o_f_f does not ignore the ssss request 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  _t_r_o_f_f  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 bbdd, ccss, ttkkff, ttrr, or ffpp requests.  Normally, glyphs are
       constructed from characters immediately before the glyph is added to an
       output line.  Macros, diversions, and strings are  all,  in  fact,  the
       same  type  of  object; they contain a sequence of intermixed character
       and glyph nodes.  Special characters transform from one to  the  other:
       before being added to the output, they behave as characters; afterward,
       they  are  glyphs.   A glyph node does not behave like a character node
       when it is processed by a macro: it does not inherit any of the special
       properties that the character from which it was constructed might  have
       had.  For example, the input
              .di x
              \\\\
              .br
              .di
              .x
       produces “\\\\” in GNU _t_r_o_f_f.  Each pair of backslashes becomes one back‐
       slash  _g_l_y_p_h_; the resulting backslashes are thus not interpreted as es‐
       cape _c_h_a_r_a_c_t_e_r_s when they are reread as the diversion is output.   AT&T
       _t_r_o_f_f _w_o_u_l_d interpret them as escape characters when rereading them and
       end up printing one “\\”.

       One  way  to format a backslash in most documents is with the \\ee escape
       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 _t_r_o_f_f and AT&T _t_r_o_f_f.  (Naturally, if  you’ve  changed  the  escape
       character,  you  need  to prefix the “ee” 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 _r_o_f_f escape character—perhaps in discussion  of
       character  sets  or other programming languages—is the character escape
       \\((rrss or \\[[rrss]], for “reverse solidus”,  from  its  name  in  the  ECMA‐6
       (ISO/IEC  646) standard.  [This escape sequence is not portable to AT&T
       _t_r_o_f_f, but is to its lineal descendant, Heirloom Doctools _t_r_o_f_f, as  of
       its 060716 release (July 2006).]

       To store an escape sequence in a diversion that is interpreted when the
       diversion  is  reread, either use the traditional \\!! transparent output
       facility, or, if this is unsuitable, the new \\?? escape  sequence.   See
       subsection  “Escape  sequences”  above  and  sections  “Diversions” and
       “gtroff Internals” in _G_r_o_f_f_: _T_h_e _G_N_U _I_m_p_l_e_m_e_n_t_a_t_i_o_n _o_f _t_r_o_f_f, the _g_r_o_f_f
       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 _t_r_o_f_f will output the partially
       collected line at the end of input; GNU _t_r_o_f_f will not.

   FFoorrmmaatttteerr oouuttppuutt iinnccoommppaattiibbiilliittiieess
       Its  extensions  notwithstanding,  the _g_r_o_f_f intermediate output format
       has some incompatibilities with that of AT&T _t_r_o_f_f, 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  _t_r_o_f_f  practice.   Other  implementations have diverged on this
         point as well.

       • The output cannot be easily rescaled to other devices as AT&T _t_r_o_f_f’s
         could.

AAuutthhoorrss
       This document was written by James Clark, Werner Lemberg, Bernd Warken,
       and G. Branden Robinson.

SSeeee aallssoo
       _G_r_o_f_f_: _T_h_e _G_N_U _I_m_p_l_e_m_e_n_t_a_t_i_o_n _o_f _t_r_o_f_f, by Trent A. Fisher  and  Werner
       Lemberg,  is the primary _g_r_o_f_f 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 _g_r_o_f_f documentation as AT&T _t_r_o_f_f.

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

       _g_r_o_f_f(1), _g_r_o_f_f(7), _r_o_f_f(7)

groff 1.23.0                      3 June 2025                    _g_r_o_f_f___d_i_f_f(7)
───────────────────────────────────────────────────────────────────────────────
_g_r_o_f_f___h_d_t_b_l(7)         Miscellaneous Information Manual         _g_r_o_f_f___h_d_t_b_l(7)

NNaammee
       groff_hdtbl - Heidelberger table macros for GNU _r_o_f_f

DDeessccrriippttiioonn
       The _h_d_t_b_l 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 _h_d_t_b_l is that the
       tables  are constructed without calling a preprocessor; this means that
       _g_r_o_f_f(7)’s full macro capabilities are available.  On the  other  hand,
       table  processing  with _h_d_t_b_l is much slower than using the _t_b_l(1) pre‐
       processor.  A further advantage is that the HTML‐like syntax  of  _h_d_t_b_l
       will be easily converted to HTML; this is not implemented yet.

UUssaaggee
       In  this and the next section, we present examples to help users under‐
       stand the basic workflow of _h_d_t_b_l.  First of all,  you  must  load  the
       _h_d_t_b_l_._t_m_a_c  file.  As with nearly all other _g_r_o_f_f macro packages, there
       are two possibilities to do so: Either add the line

              .mso hdtbl.tmac

       to your _r_o_f_f file before using any macros of the _h_d_t_b_l package, or  add
       the option

              -m hdtbl

       to  the  command line of groff (before the document file which contains
       _h_d_t_b_l 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 _h_d_t_b_l currently only supports
       the ppss and ppddff output 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
              _c_o_n_t_e_n_t_s _o_f _t_h_e _t_a_b_l_e _c_e_l_l
              .ETB

       A terminal representation is

              +------------------------------------------------------+
              | _c_o_n_t_e_n_t_s_-_o_f_-_t_h_e_-_t_a_b_l_e_-_c_e_l_l                           |
              +------------------------------------------------------+

       Equivalent to the above is the following notation.

              .TBL .TR .TD "_c_o_n_t_e_n_t_s _o_f _t_h_e _t_a_b_l_e _c_e_l_l" .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 ‘_r_o_w_‐_n_u_m_b_e_r*_c_o_l_u_m_n_‐_n_u_m_b_e_r’ 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=_m’ 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.

MMaaccrrooss aanndd aarrgguummeennttss
       The order of macro calls and other tokens follows the HTML  model.   In
       the  following  list,  valid  predecessors  and successors of all _h_d_t_b_l
       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=_v_a_l_u_e

       or

              key='_v_a_l_u_e_1 [_v_a_l_u_e_2 [...]]'

       with the only exception of the optional argument  of  the  macro  .ETB,
       which is the string ‘hold’.  Another possible form is

              "key=_v_a_l_u_e_1 [_v_a_l_u_e_2 [...]]"

       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 _c are colors predefined by _g_r_o_f_f  or
       colors  defined  by the user with the .defcolor request.  Argument val‐
       ues _d are decimal numbers with or without decimal point.  Argument val‐
       ues _m are natural numbers.  Argument values _n are numerical values with
       the usual _g_r_o_f_f 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.

       ..TTBBLL [_a_r_g_s]
              Begin a new table.

              pprreeddeecceessssoorr:: .TD, .TH, .ETB, cell contents
              ssuucccceessssoorr:: .CPTN, .TR
              aarrgguummeennttss::
                     border=[_n]
                            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.
                            DDeeffaauulltt:: ‘border=.1n’ (register ‘t*b’).
                     bc=_c   Border color.
                            DDeeffaauulltt:: ‘bc=red4’ (string ‘t*bc’).
                     cols=_m Number of table columns.  This argument is  neces‐
                            sary  if  more than one column is in the table and
                            no ‘width’ arguments are present.
                            DDeeffaauulltt:: ‘cols=1’ (register ‘t*cols’).
                     cpd=_n  Cell padding, i.e., the extra  space  between  the
                            cell space border and the cell contents.
                            DDeeffaauulltt:: ‘cpd=.5n’ (register ‘t*cpd’).
                     csp=_n  Cell  spacing,  i.e.,  the extra space between the
                            table border or vertical or horizontal  lines  be‐
                            tween cells and the cellspace.
                            DDeeffaauulltt:: ‘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.
                            DDeeffaauulltt:: ‘tal=l’ (register ‘t*tal’).
                     width='_w_1 [_w_2 [...]]'
                            Widths  of  table  cells.   _w_1, _w_2, ... are either
                            numbers of type _n  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.
                            DDeeffaauulltt:: The table width  equals  the  outer  line
                            length  or  column  length; the columns have equal
                            widths.
                     height=_n
                            Height of the table.  If the table with  its  con‐
                            tents  is  lower than _n, the last row is stretched
                            to this value.

       ..CCPPTTNN [_a_r_g_s]
              Text of caption.

              The (optionally numbered) table caption.  .CPTN is optional.

              pprreeddeecceessssoorr:: .TBL
              ssuucccceessssoorr:: .TR
              aarrgguummeennttss::
                     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.
                            DDeeffaauulltt:: ‘val=t’ (string ‘t*cptn’).

       ..TTRR [_a_r_g_s]
              Begin a new table row.

              pprreeddeecceessssoorr:: .TBL, .CPTN, .TD, .TH, .ETB, cell contents
              ssuucccceessssoorr:: .TD, .TH
              aarrgguummeennttss::
                     height=_n
                            The  height  of  the row.  If a cell in the row is
                            higher than _n, this value  is  ignored;  otherwise
                            the row height is stretched to _n.

       ..TTDD [_a_r_g_s [_c_e_l_l _c_o_n_t_e_n_t_s]]
              Begin a table data cell.
       ..TTHH [_a_r_g_s [_c_e_l_l _c_o_n_t_e_n_t_s]]
              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.

              pprreeddeecceessssoorr:: .TR, .TD, .TH, .ETB, cell contents
              ssuucccceessssoorr:: .TD, .TH, .TR, .ETB, cell contents
              aarrgguummeennttss::
                     colspan=_m
                            The width of this cell is the sum of the widths of
                            the _m cells above and below this row.
                     rowspan=_m
                            The  height of this cell is the sum of the heights
                            of the _m cells left and right of this column.

                            RReemmaarrkk:: Overlapping 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 ccoollssppaann is

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

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

       ..EETTBB [hhoolldd]
              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.

              pprreeddeecceessssoorr:: .TD, .TH, .ETB, cell contents
              ssuucccceessssoorr:: .TBL, .TR, .TD, .TH, .ETB, cell contents
              aarrgguummeennttss::
                     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.

       ..tt**ffrreeee [_n]
              Free  the  next  held table or _n held tables.  Call this utility
              macro to print tables which are held by using the  ‘hold’  argu‐
              ment of the .ETB macro.

   AArrgguummeennttss ccoommmmoonn ttoo ..TTBBLL,, ..TTRR,, ..TTDD,, aanndd ..TTHH
       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=[_c]
              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.
              DDeeffaauulltt:: ‘bgc=bisque’ (string ‘t*bgc’).
       fgc=_c  The foreground color of the cell contents.
              DDeeffaauulltt:: ‘fgc=red4’ (string ‘t*fgc’).
       ff=_n_a_m_e
              The  font  family  for  the  table.  _n_a_m_e is a _g_r_o_f_f font family
              identifier, such as A for Avant Garde or HN for  Helvetica  Nar‐
              row.
              DDeeffaauulltt:: The font family found before the table (string ‘t*ff’).
       fst=_s_t_y_l_e
              The  font style for the table.  One of R, B, I, or BI for roman,
              bboolldd, _i_t_a_l_i_c, or _bb_oo_ll_dd _ii_tt_aa_ll_ii_cc, respectively.  As with _r_o_f_f’s  ..fftt
              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’.
              DDeeffaauulltt:: The font style in use right before  the  table  (string
              ‘t*fst’).
       fsz='_d_1 [_d_2]'
              A  decimal  or fractional factor _d_1, by which the point size for
              the table is changed, and _d_2, by which the vertical line spacing
              is changed.  If _d_2 is omitted, value _d_1 is taken for both.
              DDeeffaauulltt:: ‘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.
              DDeeffaauulltt:: ‘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.
              DDeeffaauulltt:: ‘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.

              RReemmaarrkk:: Together 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.
              DDeeffaauulltt:: ‘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.
              DDeeffaauulltt:: ‘vl=s’ (string ‘t*vl’).

_hh_dd_tt_bb_ll ccuussttoommiizzaattiioonn
       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 _/_u_s_r_/_s_h_a_r_e_/_d_o_c_/_g_r_o_f_f_-_b_a_s_e_/_e_x_a_m_p_l_e_s_/_h_d_t_b_l_/_c_o_m_m_o_n_._r_o_f_f  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 _m_s 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 _m_s package.

BBuuggss aanndd ssuuggggeessttiioonnss
       Please  send your comments to the _g_r_o_f_f mailing list or directly to the
       author.

AAuutthhoorrss
       The _h_d_t_b_l macro package was written by Joachim Walsdorff.

SSeeee aallssoo
       _g_r_o_f_f(1)
              provides an overview of GNU _r_o_f_f and details how to invoke _g_r_o_f_f
              at the command line.

       _g_r_o_f_f(7)
              summarizes the _r_o_f_f language and GNU extensions to it.

       _t_b_l(1) describes the traditional _r_o_f_f preprocessor for tables.

groff 1.23.0                      3 June 2025                   _g_r_o_f_f___h_d_t_b_l(7)
───────────────────────────────────────────────────────────────────────────────
_g_r_o_f_f___m_a_n(7)           Miscellaneous Information Manual           _g_r_o_f_f___m_a_n(7)

NNaammee
       groff_man - compose manual pages with GNU _r_o_f_f

SSyynnooppssiiss
       ggrrooffff --mmaann [_o_p_t_i_o_n ...] [_f_i_l_e ...]
       ggrrooffff --mm mmaann [_o_p_t_i_o_n ...] [_f_i_l_e ...]

DDeessccrriippttiioonn
       The GNU implementation of the _m_a_n macro package is part  of  the  _g_r_o_f_f
       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  _g_r_o_f_f
       users  should  consult  _g_r_o_f_f___m_a_n___s_t_y_l_e(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 _g_r_o_f_f typesetting system.

       Macro   Meaning                      Subsection
       ───────────────────────────────────────────────────────────────
       ..BB      Bold                         Font style macros
       ..BBII     Bold, italic alternating     Font style macros
       ..BBRR     Bold, roman alternating      Font style macros
       ..EEEE     Example end                  Document structure macros
       ..EEXX     Example begin                Document structure macros
       ..II      Italic                       Font style macros
       ..IIBB     Italic, bold alternating     Font style macros
       ..IIPP     Indented paragraph           Paragraphing macros
       ..IIRR     Italic, roman alternating    Font style macros
       ..LLPP     Begin paragraph              Paragraphing macros
       ..MMEE     Mail‐to end                  Hyperlink macros
       ..MMRR     Man page cross reference     Hyperlink macros
       ..MMTT     Mail‐to start                Hyperlink macros
       ..PP      Begin paragraph              Paragraphing macros
       ..PPPP     Begin paragraph              Paragraphing macros
       ..RRBB     Roman, bold alternating      Font style macros
       ..RREE     Relative inset end           Document structure macros
       ..RRII     Roman, italic alternating    Font style macros
       ..RRSS     Relative inset start         Document structure macros
       ..SSBB     Small bold                   Font style macros
       ..SSHH     Section heading              Document structure macros
       ..SSMM     Small                        Font style macros
       ..SSSS     Subsection heading           Document structure macros
       ..SSYY     Synopsis start               Command synopsis macros
       ..TTHH     Title heading                Document structure macros
       ..TTPP     Tagged paragraph             Paragraphing macros
       ..TTQQ     Supplemental paragraph tag   Paragraphing macros
       ..UUEE     URI end                      Hyperlink macros
       ..UURR     URI start                    Hyperlink macros
       ..YYSS     Synopsis end                 Command synopsis macros

       We  discuss  other macros (..AATT, ..DDTT, ..HHPP, ..OOPP, ..PPDD, and ..UUCC) 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.

   MMaaccrroo rreeffeerreennccee pprreelliimmiinnaarriieess
       A tagged paragraph describes each macro.  We present coupled pairs  to‐
       gether, as with ..EEXX and ..EEEE.

       An  empty  macro argument can be specified with a pair of double‐quotes
       (""), but the _m_a_n 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.

   DDooccuummeenntt ssttrruuccttuurree mmaaccrrooss
       Document structure macros organize a man page’s content.  All  of  them
       break  the output line.  ..TTHH (title heading) identifies the document as
       a man page and configures the page headers and footers.  Section  head‐
       ings (..SSHH), 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  (..SSSS)  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
       ..EEXX and ..EEEE.  When none of the foregoing meets a structural demand, use
       ..RRSS/..RREE to inset a region within a (sub)section.

       ..TTHH _t_o_p_i_c _s_e_c_t_i_o_n [_f_o_o_t_e_r_‐_m_i_d_d_l_e] [_f_o_o_t_e_r_‐_i_n_s_i_d_e] [_h_e_a_d_e_r_‐_m_i_d_d_l_e]
              Determine  the contents of the page header and footer.  The sub‐
              ject of the man page is _t_o_p_i_c and the section of the  manual  to
              which  it  belongs  is  _s_e_c_t_i_o_n_.  See _m_a_n(1) or _i_n_t_r_o(1) for the
              manual sectioning applicable to your system.  _t_o_p_i_c and  _s_e_c_t_i_o_n
              are  positioned  together  at  the  left and right in the header
              (with _s_e_c_t_i_o_n in parentheses  immediately  appended  to  _t_o_p_i_c).
              _f_o_o_t_e_r_‐_m_i_d_d_l_e 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  --rrDD11.   When  disabled  (the default),
              _f_o_o_t_e_r_‐_i_n_s_i_d_e is positioned  at  the  bottom  left.   Otherwise,
              _f_o_o_t_e_r_‐_i_n_s_i_d_e 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 --rrccRR==11, in which case it is
              the _t_o_p_i_c and _s_e_c_t_i_o_n_, as in the header.  _h_e_a_d_e_r_‐_m_i_d_d_l_e is  cen‐
              tered  in  the header.  If _s_e_c_t_i_o_n is an integer between 1 and 9
              (inclusive), there is no need to specify _h_e_a_d_e_r_‐_m_i_d_d_l_e_;  _a_n_._t_m_a_c
              will  supply text for it.  The macro package may also abbreviate
              _t_o_p_i_c and _f_o_o_t_e_r_‐_i_n_s_i_d_e 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  --rrCC11 option is given).  This feature is in‐
              tended only for formatting multiple _m_a_n documents in sequence.

              A valid _m_a_n document calls ..TTHH once, early in the file, prior to
              any other macro calls.

       ..SSHH [_h_e_a_d_i_n_g_‐_t_e_x_t]
              Set _h_e_a_d_i_n_g_‐_t_e_x_t as a section heading.  If no argument is given,
              a one‐line input trap is planted; text on the next line  becomes
              _h_e_a_d_i_n_g_‐_t_e_x_t_.  The left margin is reset to zero to set the head‐
              ing  text in bold (or the font specified by the string HHFF), and,
              on typesetting devices, slightly larger than the base type size.
              If the heading font \\**[[HHFF]] is bold, use of an  italic  style  in
              _h_e_a_d_i_n_g_‐_t_e_x_t  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 IINN register.  Text after _h_e_a_d_‐
              _i_n_g_‐_t_e_x_t is set as an ordinary paragraph (..PP).

              The content of _h_e_a_d_i_n_g_‐_t_e_x_t 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  ..TTHH  call,  and
              must contain only text of the form
                     _t_o_p_i_c[,, _a_n_o_t_h_e_r_‐_t_o_p_i_c]... \- _s_u_m_m_a_r_y_‐_d_e_s_c_r_i_p_t_i_o_n
              for  a  man page to be properly indexed.  See _g_r_o_f_f___m_a_n___s_t_y_l_e(7)
              for suggestions and _m_a_n(7) for  the  conventions  prevailing  on
              your system.

       ..SSSS [_s_u_b_h_e_a_d_i_n_g_‐_t_e_x_t]
              Set  _s_u_b_h_e_a_d_i_n_g_‐_t_e_x_t  as a subsection heading indented between a
              section heading and an ordinary paragraph (..PP).  If no  argument
              is  given,  a  one‐line  input trap is planted; text on the next
              line becomes _s_u_b_h_e_a_d_i_n_g_‐_t_e_x_t_.  The left margin is reset  to  the
              value of the SSNN register to set the heading text in bold (or the
              font specified by the string HHFF).  If the heading font \\**[[HHFF]] is
              bold, use of an italic style in _s_u_b_h_e_a_d_i_n_g_‐_t_e_x_t 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
              IINN register.  Text after _s_u_b_h_e_a_d_i_n_g_‐_t_e_x_t is set as  an  ordinary
              paragraph (..PP).

       ..EEXX
       ..EEEE    Begin  and  end  example.   After ..EEXX, filling is disabled and a
              constant‐width (monospaced) font is selected.  Calling  ..EEEE  en‐
              ables filling and restores the previous font.

              These macros are extensions introduced in Ninth Edition Research
              Unix.   Systems  running  that _t_r_o_f_f, or those from Documenter’s
              Workbench, Heirloom Doctools, or Plan 9 _t_r_o_f_f support them.   To
              be  certain  your  page will be portable to systems that do not,
              copy their definitions from the _a_n_-_e_x_t_._t_m_a_c file of a _g_r_o_f_f  in‐
              stallation.

       ..RRSS [_i_n_s_e_t_‐_a_m_o_u_n_t]
              Start a new relative inset level.  The position of the left mar‐
              gin  is  saved,  then moved right by _i_n_s_e_t_‐_a_m_o_u_n_t_, if specified,
              and by the amount of the IINN register otherwise.   Calls  to  ..RRSS
              can be nested; each increments by 1 the inset level used by ..RREE.
              The level prior to any ..RRSS calls is 1.

       ..RREE [_l_e_v_e_l]
              End  a  relative  inset.  The left margin corresponding to inset
              level _l_e_v_e_l is restored.  If no argument  is  given,  the  inset
              level is reduced by 1.

   PPaarraaggrraapphhiinngg mmaaccrrooss
       An  ordinary  paragraph (..PP) 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 (..TTPP) or more  (..TTQQ)  leading  tags
       followed  by  a  paragraph that has an additional indentation.  The in‐
       dented paragraph (..IIPP) macro is useful to continue the indented content
       of a narrative started with ..TTPP, 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 ..SSHH or ..SSSS, they (except for ..TTQQ)
       follow  the break with a default amount of vertical space, which can be
       changed by the deprecated ..PPDD macro;  see  subsection  “Horizontal  and
       vertical  spacing” below.  They also reset the type size and font style
       to defaults (..TTQQ again excepted); see subsection  “Font  style  macros”
       below.

       ..PP
       ..LLPP
       ..PPPP    Begin  a new paragraph; these macros are synonymous.  The inden‐
              tation is reset to the default value; the left  margin,  as  af‐
              fected by ..RRSS and ..RREE, is not.

       ..TTPP [_i_n_d_e_n_t_a_t_i_o_n]
              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 \\cc escape sequence.  Subsequent  text  is  in‐
              dented by _i_n_d_e_n_t_a_t_i_o_n_, if specified, and by the amount of the IINN
              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.

       ..TTQQ    Set an additional tag for a paragraph tagged with ..TTPP.  An input
              trap is planted as with ..TTPP.

              This  macro  is  a  GNU extension not defined on systems running
              AT&T, Plan 9, or  Solaris  _t_r_o_f_f;  see  _a_n_-_e_x_t_._t_m_a_c  in  section
              “Files” below.

       ..IIPP [_t_a_g] [_i_n_d_e_n_t_a_t_i_o_n]
              Set an indented paragraph with an optional tag.  The _t_a_g and _i_n_‐
              _d_e_n_t_a_t_i_o_n  arguments,  if present, are handled as with ..TTPP, with
              the exception that the _t_a_g argument  to  ..IIPP  cannot  include  a
              macro call.

   CCoommmmaanndd ssyynnooppssiiss mmaaccrrooss
       ..SSYY  and ..YYSS aid 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 _t_r_o_f_f; see _a_n_-_e_x_t_._t_m_a_c in section “Files” below.

       ..SSYY _c_o_m_m_a_n_d
              Begin  synopsis.   A new paragraph begins at the left margin un‐
              less ..SSYY has already been called without a corresponding ..YYSS, in
              which case only a break is performed.  Adjustment and  automatic
              hyphenation  are  disabled.  _c_o_m_m_a_n_d is set in bold.  If a break
              is required, lines after the first are indented by the width  of
              _c_o_m_m_a_n_d plus a space.

       ..YYSS    End  synopsis.  Indentation, adjustment, and hyphenation are re‐
              stored to their previous states.

   HHyyppeerrlliinnkk mmaaccrrooss
       Man page cross references are best presented with ..MMRR.  Text may be hy‐
       perlinked to email addresses with ..MMTT/..MMEE or other URIs  with  ..UURR/..UUEE.
       Hyperlinked text is supported on HTML and terminal output devices; ter‐
       minals  and  pager programs must support ECMA‐48 OSC 8 escape sequences
       (see _g_r_o_t_t_y(1)).  When device support is unavailable or  disabled  with
       the UU register (see section “Options” below), ..MMTT and ..UURR URIs are ren‐
       dered between angle brackets after the linked text.

       ..MMTT,  ..MMEE,  ..UURR, and ..UUEE are GNU extensions not defined on systems run‐
       ning AT&T, Plan 9, or Solaris _t_r_o_f_f; see _a_n_-_e_x_t_._t_m_a_c in section “Files”
       below.  Plan 9 from User Space’s _t_r_o_f_f implements ..MMRR.

       The arguments to ..MMRR, ..MMTT, and ..UURR should 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 \\:: escape sequences
       from hyperlinks when supplying device control commands to  output  dri‐
       vers.

       ..MMRR _t_o_p_i_c _m_a_n_u_a_l_‐_s_e_c_t_i_o_n [_t_r_a_i_l_i_n_g_‐_t_e_x_t]
              _(_s_i_n_c_e groff _1_._2_3_) Set a man page cross reference as “_t_o_p_i_c((_m_a_n_‐
              _u_a_l_‐_s_e_c_t_i_o_n))”.   If  _t_r_a_i_l_i_n_g_‐_t_e_x_t  (typically  punctuation)  is
              specified, it follows the closing parenthesis without  interven‐
              ing space.  Hyphenation is disabled while the cross reference is
              set.   _t_o_p_i_c is set in the font specified by the MMFF string.  The
              cross reference hyperlinks to a URI of the form  “mmaann::_t_o_p_i_c(_m_a_n_‐
              _u_a_l_‐_s_e_c_t_i_o_n)”.

       ..MMTT _a_d_d_r_e_s_s
       ..MMEE [_t_r_a_i_l_i_n_g_‐_t_e_x_t]
              Identify  _a_d_d_r_e_s_s  as  an RFC 6068 _a_d_d_r_‐_s_p_e_c for a “mailto:” URI
              with the text between the two macro calls as the link text.   An
              argument  to ..MMEE is placed after the link text without interven‐
              ing space.  _a_d_d_r_e_s_s may not be visible in the rendered  document
              if  hyperlinks  are  enabled and supported by the output driver.
              If they are not, _a_d_d_r_e_s_s is set in angle brackets after the link
              text and before _t_r_a_i_l_i_n_g_‐_t_e_x_t_.  If hyperlinking is  enabled  but
              there  is  no  link  text,  _a_d_d_r_e_s_s is formatted and hyperlinked
              _w_i_t_h_o_u_t angle brackets.

       ..UURR _u_r_i
       ..UUEE [_t_r_a_i_l_i_n_g_‐_t_e_x_t]
              Identify _u_r_i as an RFC 3986 URI hyperlink with the text  between
              the  two  macro  calls  as the link text.  An argument to ..UUEE is
              placed after the link text without intervening space.   _u_r_i  may
              not  be  visible  in the rendered document if hyperlinks are en‐
              abled and supported by the output driver.  If they are not,  _u_r_i
              is  set  in angle brackets after the link text and before _t_r_a_i_l_‐
              _i_n_g_‐_t_e_x_t_.  If hyperlinking is enabled but there is no link text,
              _u_r_i is formatted and hyperlinked _w_i_t_h_o_u_t angle brackets.

       The hyperlinking of ..TTPP paragraph tags with ..UURR/..UUEE and ..MMTT/..MMEE is  not
       yet  supported;  if attempted, the hyperlink will be typeset at the be‐
       ginning of the indented paragraph even on hyperlink‐supporting devices.

   FFoonntt ssttyyllee mmaaccrrooss
       The _m_a_n macro package is limited in its font styling options,  offering
       only bboolldd (..BB), _i_t_a_l_i_c (..II), and roman.  Italic text is usually set un‐
       derscored instead on terminal devices.  The ..SSMM and ..SSBB macros 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 ..BBII, ..BBRR, ..IIBB, ..IIRR, ..RRBB, and ..RRII,  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 XX7755--1122 and XX110000--1122 devices where the type size  is
       12 points.  The default style is roman.

       ..BB [_t_e_x_t]
              Set  _t_e_x_t  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.

       ..II [_t_e_x_t]
              Set _t_e_x_t 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.

       ..SSMM [_t_e_x_t]
              Set  _t_e_x_t  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.

       ..SSBB [_t_e_x_t]
              Set  _t_e_x_t 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.

       ..BBII _b_o_l_d_‐_t_e_x_t _i_t_a_l_i_c_‐_t_e_x_t ...
              Set each argument in bold and italics, alternately.

       ..BBRR _b_o_l_d_‐_t_e_x_t _r_o_m_a_n_‐_t_e_x_t ...
              Set each argument in bold and roman, alternately.

       ..IIBB _i_t_a_l_i_c_‐_t_e_x_t _b_o_l_d_‐_t_e_x_t ...
              Set each argument in italics and bold, alternately.

       ..IIRR _i_t_a_l_i_c_‐_t_e_x_t _r_o_m_a_n_‐_t_e_x_t ...
              Set each argument in italics and roman, alternately.

       ..RRBB _r_o_m_a_n_‐_t_e_x_t _b_o_l_d_‐_t_e_x_t ...
              Set each argument in roman and bold, alternately.

       ..RRII _r_o_m_a_n_‐_t_e_x_t _i_t_a_l_i_c_‐_t_e_x_t ...
              Set each argument in roman and italics, alternately.

   HHoorriizzoonnttaall aanndd vveerrttiiccaall ssppaacciinngg
       The _i_n_d_e_n_t_a_t_i_o_n argument accepted by ..IIPP, ..TTPP, and the  deprecated  ..HHPP
       is  a  number  plus an optional scaling unit, as is ..RRSS’s _i_n_s_e_t_‐_a_m_o_u_n_t.
       If no scaling unit is given, the _m_a_n package assumes “n”.  An  indenta‐
       tion  specified  in  a call to ..IIPP, ..TTPP, or the deprecated ..HHPP persists
       until (1) another of these macros is called with an  _i_n_d_e_n_t_a_t_i_o_n  argu‐
       ment, or (2) ..SSHH, ..SSSS, or ..PP or its synonyms is called; these clear the
       indentation entirely.

       The  left  margin used by ordinary paragraphs set with ..PP (and its syn‐
       onyms) not within an ..RRSS/..RREE relative inset is 7.2n for typesetting de‐
       vices and 7n for terminal devices (but see the --rrIINN option).   Headers,
       footers  (both set with ..TTHH), and section headings (..SSHH) are set at the
       page offset (see _g_r_o_f_f(7)) and subsection headings (..SSSS) indented  from
       it by 3n (but see the --rrSSNN option).

       Several  macros  insert vertical space: ..SSHH, ..SSSS, ..TTPP, ..PP (and its syn‐
       onyms), ..IIPP, and the deprecated ..HHPP.  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 ..PPDD can change this vertical
       spacing, but its use is discouraged.)  Between ..EEXX and ..EEEE  calls,  the
       inter‐paragraph spacing is 1v regardless of output device.

   RReeggiisstteerrss
       Registers  are  described  in section “Options” below.  They can be set
       not only on the command line but in the site _m_a_n_._l_o_c_a_l  file  as  well;
       see section “Files” below.

   SSttrriinnggss
       The  following strings are defined for use in man pages.  None of these
       is necessary in a contemporary man page; see _g_r_o_f_f___m_a_n___s_t_y_l_e(7).   Oth‐
       ers  are  supported for configuration of rendering parameters; see sec‐
       tion “Options” below.

       \\**RR    interpolates a special character escape sequence for the “regis‐
              tered sign” glyph, \\((rrgg, if available, and “(Reg.)” otherwise.

       \\**SS    interpolates an escape sequence setting the  type  size  to  the
              document default.

       \\**((llqq
       \\**((rrqq  interpolate  special  character  escape  sequences  for left and
              right double‐quotation marks, \\((llqq and \\((rrqq, respectively.

       \\**((TTmm  interpolates a special character escape sequence for the  “trade
              mark sign” glyph, \\((ttmm, if available, and “(TM)” otherwise.

   HHooookkss
       Two macros, both GNU extensions, are called internally by the _g_r_o_f_f _m_a_n
       package  to format page headers and footers and can be redefined by the
       administrator in a site’s _m_a_n_._l_o_c_a_l file (see section  “Files”  below).
       The  presentation  of ..TTHH above describes the default headers and foot‐
       ers.  Because these macros are hooks for _g_r_o_f_f _m_a_n 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; ..PPTT furthermore has
       the responsibility of emitting a PDF bookmark after writing  the  first
       page  header  in  a  document.  Consult the existing implementations in
       _a_n_._t_m_a_c when drafting replacements.

       ..BBTT    Set the page footer text (“bottom trap”).

       ..PPTT    Set the page header text (“page trap”).

       To remove a page header or  footer  entirely,  define  the  appropriate
       macro as empty rather than deleting it.

   DDeepprreeccaatteedd ffeeaattuurreess
       Use  of  the following in man pages for public distribution is discour‐
       aged.

       ..AATT [_s_y_s_t_e_m [_r_e_l_e_a_s_e]]
              Alter the footer for use with legacy AT&T man pages,  overriding
              any definition of the _f_o_o_t_e_r_‐_i_n_s_i_d_e argument to ..TTHH.  This macro
              exists only to render man pages from historical systems.

              _s_y_s_t_e_m can be any of the following.

                     3      7th edition _(_d_e_f_a_u_l_t_)

                     4      System III

                     5      System V

              The  optional  _r_e_l_e_a_s_e argument specifies the release number, as
              in “System V Release 3”.

       ..DDTT    Reset 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 _t_b_l(1) instead.

       ..HHPP [_i_n_d_e_n_t_a_t_i_o_n]
              Set  up a paragraph with a hanging left indentation.  The _i_n_d_e_n_‐
              _t_a_t_i_o_n argument, if present, is handled as with ..TTPP.

              Use of this presentation‐oriented macro is deprecated.  A  hang‐
              ing  indentation  cannot  be expressed naturally under HTML, and
              non‐_r_o_f_f‐based man page interpreters may treat ..HHPP as  an  ordi‐
              nary  paragraph.   Thus, information or distinctions you mean to
              express with indentation may be lost.

       ..OOPP _o_p_t_i_o_n_‐_n_a_m_e [_o_p_t_i_o_n_‐_a_r_g_u_m_e_n_t]
              Indicate an optional command parameter called _o_p_t_i_o_n_‐_n_a_m_e, which
              is set in bold.  If the option takes an  argument,  specify  _o_p_‐
              _t_i_o_n_‐_a_r_g_u_m_e_n_t  using  a  noun,  abbreviation, or hyphenated noun
              phrase.  If present, _o_p_t_i_o_n_‐_a_r_g_u_m_e_n_t 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  _t_r_o_f_f, 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.

       ..PPDD [_v_e_r_t_i_c_a_l_‐_s_p_a_c_e]
              Define  the  vertical space between paragraphs or (sub)sections.
              The optional argument _v_e_r_t_i_c_a_l_‐_s_p_a_c_e 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 ..PPDD to express  are  likely  to  be
              lost.

       ..UUCC [_v_e_r_s_i_o_n]
              Alter  the  footer for use with legacy BSD man pages, overriding
              any definition of the _f_o_o_t_e_r_‐_i_n_s_i_d_e argument to ..TTHH.  This macro
              exists only to render man pages from historical systems.

              _v_e_r_s_i_o_n can be any of the following.

                     3      3rd Berkeley Distribution _(_d_e_f_a_u_l_t_)

                     4      4th Berkeley Distribution

                     5      4.2 Berkeley Distribution

                     6      4.3 Berkeley Distribution

                     7      4.4 Berkeley Distribution

   HHiissttoorryy
       M. Douglas McIlroy designed, implemented, and documented the  AT&T  _m_a_n
       macros  for  Unix  Version 7 (1979) and employed them to edit the first
       volume of its _P_r_o_g_r_a_m_m_e_r_’_s _M_a_n_u_a_l, a compilation of all man pages  sup‐
       plied by the system.  That _m_a_n supported the macros listed in this page
       not  described as extensions, except ..PP and the deprecated ..AATT and ..UUCC.
       The only strings defined were RR and SS; no registers were documented.

       ..UUCC appeared in 3BSD (1980).  Unix System III (1980) introduced ..PP  and
       exposed  the  registers  IINN  and LLLL, which had been internal to Seventh
       Edition Unix _m_a_n.  PWB/UNIX 2.0  (1980)  added  the  TTmm  string.   4BSD
       (1980)  added  llqq and rrqq strings.  SunOS 2.0 (1985) recognized CC, DD, PP,
       and XX registers.  4.3BSD (1986) added ..AATT and ..PP.   Ninth  Edition  Re‐
       search Unix (1986) introduced ..EEXX and ..EEEE.  SunOS 4.0 (1988) added ..SSBB.

       The  foregoing features were what James Clark implemented in early ver‐
       sions of _g_r_o_f_f.  Later, _g_r_o_f_f  1.20  (2009)  originated  ..SSYY/..YYSS,  ..TTQQ,
       ..MMTT/..MMEE, and ..UURR/..UUEE.  Plan 9 from User Space’s _t_r_o_f_f introduced ..MMRR in
       2020.

OOppttiioonnss
       The  following  _g_r_o_f_f options set registers (with --rr) and strings (with
       --dd) recognized and used by the _m_a_n macro package.  To ensure  rendering
       consistent  with output device capabilities and reader preferences, man
       pages should never manipulate them.

       --ddAADD==_a_d_j_u_s_t_m_e_n_t_‐_m_o_d_e
              Set line adjustment to _a_d_j_u_s_t_m_e_n_t_‐_m_o_d_e_, which is  typically  “bb”
              for  adjustment  to  both margins (the default), or “ll” for left
              alignment (ragged right margin).  Any valid argument to  _g_r_o_f_f’s
              “.ad”  request  may  be  used.   See  _g_r_o_f_f(7)  for  less‐common
              choices.

       --rrccRR==11 Enable 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 --rrccRR==00 to  disable  it
              on terminal devices; on HTML devices, it cannot be disabled.

       --rrCC11   Number  output  pages  consecutively, in strictly increasing se‐
              quence, rather than resetting the page number to 1 (or the value
              of register PP) with each new _m_a_n document.

       --rrCCSS==11 Set section headings (the argument(s) to ..SSHH) in full  capitals.
              This  transformation  is off by default because it discards case
              distinction information.

       --rrCCTT==11 Set the man page topic (the first argument to ..TTHH) in full capi‐
              tals in headers and footers.  This transformation is off by  de‐
              fault because it discards case distinction information.

       --rrDD11   Enable  double‐sided layout, formatting footers for even and odd
              pages differently; see the  description  of  ..TTHH  in  subsection
              “Document structure macros” above.

       --rrFFTT==_f_o_o_t_e_r_‐_d_i_s_t_a_n_c_e
              Set distance of the footer relative to the bottom of the page to
              _f_o_o_t_e_r_‐_d_i_s_t_a_n_c_e_;  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.

       --ddHHFF==_h_e_a_d_i_n_g_‐_f_o_n_t
              Set  the  font used for section and subsection headings; the de‐
              fault is “BB” (bold style of the default family).  Any valid  ar‐
              gument to _g_r_o_f_f’s “.ft” request may be used.  See _g_r_o_f_f(7).

       --rrHHYY==00 Disable  automatic  hyphenation.   Normally,  it is enabled (1).
              The hyphenation mode is determined by the _g_r_o_f_f locale; see sec‐
              tion “Localization“ of _g_r_o_f_f(7).

       --rrIINN==_s_t_a_n_d_a_r_d_‐_i_n_d_e_n_t_a_t_i_o_n
              Set the amount of indentation used for ordinary  paragraphs  (..PP
              and  its  synonyms)  and  the default indentation amount used by
              ..IIPP, ..RRSS, ..TTPP, and the deprecated ..HHPP.  See subsection “Horizon‐
              tal and vertical spacing” above for the default.   For  terminal
              devices, _s_t_a_n_d_a_r_d_‐_i_n_d_e_n_t_a_t_i_o_n should always be an integer multi‐
              ple of unit “n” to get consistent indentation.

       --rrLLLL==_l_i_n_e_‐_l_e_n_g_t_h
              Set  line  length;  the  default is 78n for terminal devices and
              6.5i for typesetting devices.

       --rrLLTT==_t_i_t_l_e_‐_l_e_n_g_t_h
              Set the line length for titles.  By default, it is  set  to  the
              line length (see --rrLLLL above).

       --ddMMFF==_m_a_n_‐_p_a_g_e_‐_t_o_p_i_c_‐_f_o_n_t
              Set  the  font  used  for  man  page topics named in ..TTHH and ..MMRR
              calls; the default is “II” (italic style of the default  family).
              Any valid argument to _g_r_o_f_f’s “.ft” request may be used.  If the
              MMFF  string ends in “I”, it is assumed to be an oblique typeface,
              and italic corrections are applied before  and  after  man  page
              topics.

       --rrPP_n   Start enumeration of pages at _n.  The default is 1.

       --rrSS_t_y_p_e_‐_s_i_z_e
              Use  _t_y_p_e_‐_s_i_z_e  for  the document’s body text; acceptable values
              are 10, 11, or 12 points.  See subsection  “Font  style  macros”
              above for the default.

       --rrSSNN==_s_u_b_s_e_c_t_i_o_n_‐_i_n_d_e_n_t_a_t_i_o_n
              Set  indentation  of  subsection headings to _s_u_b_s_e_c_t_i_o_n_‐_i_n_d_e_n_t_a_‐
              _t_i_o_n_.  See subsection “Horizontal and  vertical  spacing”  above
              for the default.

       --rrUU11   Enable  generation  of  URI hyperlinks in the _g_r_o_h_t_m_l and _g_r_o_t_t_y
              output drivers.  _g_r_o_h_t_m_l enables them by  default;  _g_r_o_t_t_y  does
              not,  pending more widespread pager support for OSC 8 escape se‐
              quences.  Use --rrUU00 to disable hyperlinks; this will make the ar‐
              guments to MMTT and UURR calls visible in the document text produced
              by link‐capable drivers.

       --rrXX_p   Number successors of page _p as _pa, _pb, _pc, and  so  forth.   The
              register  tracking the suffixed page letter uses format “a” (see
              the “.af” request in _g_r_o_f_f(7)).

FFiilleess
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_a_n_._t_m_a_c
              Most _m_a_n macros are defined in this file.  It also loads  exten‐
              sions from _a_n_-_e_x_t_._t_m_a_c (see below).

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_a_n_d_o_c_._t_m_a_c
              This  brief  _g_r_o_f_f program detects whether the _m_a_n or _m_d_o_c 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 ..TTHH or ..DDdd, respectively, before any other macros.   A
              _m_a_n program or user typing, for example, “ggrrooffff --mmaannddoocc ppaaggee..11”,
              need  not know which package the file _p_a_g_e_._1 uses.  Multiple man
              pages, in either format, can  be  handled;  _a_n_d_o_c  reloads  each
              macro package as necessary.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_a_n_-_e_x_t_._t_m_a_c
              Except  for ..SSBB, 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 _a_n_._t_m_a_c, and are ig‐
              nored if the formatter is GNU _t_r_o_f_f.  They  are  written  to  be
              compatible  with  AT&T _t_r_o_f_f and permissively licensed—not copy‐
              lefted.  To reduce the risk of name space collisions, string and
              register names begin only with “mm”..  We encourage man  page  au‐
              thors who are concerned about portability to legacy Unix systems
              to  copy  these definitions into their pages, and maintainers of
              _t_r_o_f_f implementations or  work‐alike  systems  that  format  man
              pages to re‐use them.

              The  definitions  for  these  macros are read after a page calls
              ..TTHH, 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 ..TTHH is 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  _m_a_k_e_‐
              _w_h_a_t_i_s  or _m_a_n_d_b implementations that may give up their scan for
              indexing material early.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_m_a_n_._t_m_a_c
              This is a wrapper that loads _a_n_._t_m_a_c.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_m_a_n_d_o_c_._t_m_a_c
              This is a wrapper that loads _a_n_d_o_c_._t_m_a_c.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_s_i_t_e_-_t_m_a_c_/_m_a_n_._l_o_c_a_l
              Put site‐local changes and customizations into this file.

AAuutthhoorrss
       The initial GNU implementation of the _m_a_n macro package was written  by
       James  Clark.   Later, Werner Lemberg supplied the SS, LLTT, and ccRR regis‐
       ters, the last a 4.3BSD‐Reno _m_d_o_c(7) feature.  Larry Kollar  added  the
       FFTT,  HHYY, and SSNN registers; the HHFF string; and the PPTT and BBTT macros.  G.
       Branden Robinson implemented the AADD and MMFF strings; CCSS, CCTT, and UU  reg‐
       isters;  and  the  MMRR macro.  Except for ..SSBB, the extension macros were
       written by Lemberg, Eric S. Raymond, and Robinson.

       This document was originally written for the Debian GNU/Linux system by
       Susan G. Kleinmann.  It was corrected and updated by Lemberg and Robin‐
       son.  The extension macros were documented by Raymond and Robinson.

SSeeee aallssoo
       _t_b_l(1), _e_q_n(1), and _r_e_f_e_r(1) are preprocessors  used  with  man  pages.
       _m_a_n(1)  describes the man page librarian on your system.  _g_r_o_f_f___m_d_o_c(7)
       details the _g_r_o_f_f version of the BSD‐originated alternative macro pack‐
       age for man pages.

       _g_r_o_f_f___m_a_n___s_t_y_l_e(7), _g_r_o_f_f(7), _g_r_o_f_f___c_h_a_r(7), _m_a_n(7)

groff 1.23.0                      3 June 2025                     _g_r_o_f_f___m_a_n(7)
───────────────────────────────────────────────────────────────────────────────
_g_r_o_f_f___m_a_n___s_t_y_l_e(7)     Miscellaneous Information Manual     _g_r_o_f_f___m_a_n___s_t_y_l_e(7)

NNaammee
       groff_man_style - GNU _r_o_f_f man page tutorial and style guide

SSyynnooppssiiss
       ggrrooffff --mmaann [_o_p_t_i_o_n ...] [_f_i_l_e ...]
       ggrrooffff --mm mmaann [_o_p_t_i_o_n ...] [_f_i_l_e ...]

DDeessccrriippttiioonn
       The GNU implementation of the _m_a_n macro package is part  of  the  _g_r_o_f_f
       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
       ───────────────────────────────────────────────────────────────
       ..BB      Bold                         Font style macros
       ..BBII     Bold, italic alternating     Font style macros
       ..BBRR     Bold, roman alternating      Font style macros
       ..EEEE     Example end                  Document structure macros
       ..EEXX     Example begin                Document structure macros
       ..II      Italic                       Font style macros
       ..IIBB     Italic, bold alternating     Font style macros
       ..IIPP     Indented paragraph           Paragraphing macros
       ..IIRR     Italic, roman alternating    Font style macros
       ..LLPP     Begin paragraph              Paragraphing macros
       ..MMEE     Mail‐to end                  Hyperlink macros
       ..MMRR     Man page cross reference     Hyperlink macros
       ..MMTT     Mail‐to start                Hyperlink macros
       ..PP      Begin paragraph              Paragraphing macros
       ..PPPP     Begin paragraph              Paragraphing macros
       ..RRBB     Roman, bold alternating      Font style macros
       ..RREE     Relative inset end           Document structure macros
       ..RRII     Roman, italic alternating    Font style macros
       ..RRSS     Relative inset start         Document structure macros
       ..SSBB     Small bold                   Font style macros
       ..SSHH     Section heading              Document structure macros
       ..SSMM     Small                        Font style macros
       ..SSSS     Subsection heading           Document structure macros
       ..SSYY     Synopsis start               Command synopsis macros
       ..TTHH     Title heading                Document structure macros
       ..TTPP     Tagged paragraph             Paragraphing macros
       ..TTQQ     Supplemental paragraph tag   Paragraphing macros
       ..UUEE     URI end                      Hyperlink macros
       ..UURR     URI start                    Hyperlink macros
       ..YYSS     Synopsis end                 Command synopsis macros

       We discuss other macros (..AATT, ..DDTT, ..HHPP, ..OOPP, ..PPDD, and ..UUCC)  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).

   FFuunnddaammeennttaall ccoonncceeppttss
       _g_r_o_f_f is a programming system for typesetting: we thus  often  use  the
       verb  “to  set” in the sense “to typeset”.  The formatter _t_r_o_f_f(1) col‐
       lects words from the input and _f_i_l_l_s output lines with as many as  will
       fit.   _W_o_r_d_s  are  separated by spaces and newlines.  A transition to a
       new output line is called a _b_r_e_a_k_.  When formatted, a word may be  bro‐
       ken at hyphens, at \\%% or \\:: escape sequences (see subsection “Portabil‐
       ity”  below), or at predetermined locations if automatic hyphenation is
       enabled (see the --rrHHYY option in section “Options”  below).   An  output
       line may be supplemented with _i_n_t_e_r_‐_s_e_n_t_e_n_c_e _s_p_a_c_e_, and then optionally
       _a_d_j_u_s_t_e_d  with more space to a consistent line length (see the --ddAADD op‐
       tion).  _r_o_f_f(7) details these processes.

       An input line that starts with a dot (.) or neutral apostrophe (') is a
       _c_o_n_t_r_o_l _l_i_n_e_.  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 _a_r_g_u_m_e_n_t_s_, 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 _e_m_p_t_y _r_e_q_u_e_s_t_; it does nothing.  _T_e_x_t _l_i_n_e_s are
       input lines that are not control lines.

       We describe below several _m_a_n macros that plant one‐line  _i_n_p_u_t  _t_r_a_p_s_:
       the  next input line that directly produces formatted output is treated
       specially.  For _m_a_n 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  ..TTPP  macro  descrip‐
       tion).

   MMaaccrroo rreeffeerreennccee pprreelliimmiinnaarriieess
       A  tagged paragraph describes each macro.  We present coupled pairs to‐
       gether, as with ..EEXX and ..EEEE.

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

   DDooccuummeenntt ssttrruuccttuurree mmaaccrrooss
       Document  structure  macros organize a man page’s content.  All of them
       break the output line.  ..TTHH (title heading) identifies the document  as
       a  man page and configures the page headers and footers.  Section head‐
       ings (..SSHH), 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 (..SSSS) 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
       ..EEXX and ..EEEE.  When none of the foregoing meets a structural demand, use
       ..RRSS/..RREE to inset a region within a (sub)section.

       ..TTHH _t_o_p_i_c _s_e_c_t_i_o_n [_f_o_o_t_e_r_‐_m_i_d_d_l_e] [_f_o_o_t_e_r_‐_i_n_s_i_d_e] [_h_e_a_d_e_r_‐_m_i_d_d_l_e]
              Determine the contents of the page header and footer.  _r_o_f_f sys‐
              tems refer to these collectively as “titles”.   The  subject  of
              the  man page is _t_o_p_i_c and the section of the manual to which it
              belongs is _s_e_c_t_i_o_n_.  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  _m_a_n(1) or _i_n_t_r_o(1) for the manual sectioning ap‐
              plicable to your system.  _t_o_p_i_c and _s_e_c_t_i_o_n are  positioned  to‐
              gether  at  the  left  and  right in the header (with _s_e_c_t_i_o_n in
              parentheses immediately appended to  _t_o_p_i_c).   _f_o_o_t_e_r_‐_m_i_d_d_l_e  is
              centered  in  the  footer.   The  arrangement of the rest of the
              footer depends on whether double‐sided layout  is  enabled  with
              the  option --rrDD11.  When disabled (the default), _f_o_o_t_e_r_‐_i_n_s_i_d_e is
              positioned at the bottom left.  Otherwise, _f_o_o_t_e_r_‐_i_n_s_i_d_e 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 --rrccRR==11, in which case it is  the  _t_o_p_i_c  and
              _s_e_c_t_i_o_n_,  as  in  the  header.  _h_e_a_d_e_r_‐_m_i_d_d_l_e is centered in the
              header.  If _s_e_c_t_i_o_n is an integer between 1 and  9  (inclusive),
              there  is  no need to specify _h_e_a_d_e_r_‐_m_i_d_d_l_e_; _a_n_._t_m_a_c will supply
              text for it.  The macro package may also  abbreviate  _t_o_p_i_c  and
              _f_o_o_t_e_r_‐_i_n_s_i_d_e  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 --rrCC11 option is given).   This  feature  is  in‐
              tended only for formatting multiple _m_a_n documents in sequence.

              A valid _m_a_n document calls ..TTHH once, early in the file, prior to
              any other macro calls.

              By convention, _f_o_o_t_e_r_‐_m_i_d_d_l_e is the date of the most recent mod‐
              ification  to the man page source document, and _f_o_o_t_e_r_‐_i_n_s_i_d_e is
              the name and version or release of the project providing it.

       ..SSHH [_h_e_a_d_i_n_g_‐_t_e_x_t]
              Set _h_e_a_d_i_n_g_‐_t_e_x_t as a section heading.  If no argument is given,
              a one‐line input trap is planted; text on the next line  becomes
              _h_e_a_d_i_n_g_‐_t_e_x_t_.  The left margin is reset to zero to set the head‐
              ing  text in bold (or the font specified by the string HHFF), and,
              on typesetting devices, slightly larger than the base type size.
              If the heading font \\**[[HHFF]] is bold, use of an  italic  style  in
              _h_e_a_d_i_n_g_‐_t_e_x_t  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 IINN register.  Text after _h_e_a_d_‐
              _i_n_g_‐_t_e_x_t is set as an ordinary paragraph (..PP).

              The content of _h_e_a_d_i_n_g_‐_t_e_x_t 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  ..TTHH  call,  and
              must contain only text of the form
                     _t_o_p_i_c[,, _a_n_o_t_h_e_r_‐_t_o_p_i_c]... \- _s_u_m_m_a_r_y_‐_d_e_s_c_r_i_p_t_i_o_n
              for  a man page to be properly indexed.  See _m_a_n(7) for the con‐
              ventions prevailing on your system.

       ..SSSS [_s_u_b_h_e_a_d_i_n_g_‐_t_e_x_t]
              Set _s_u_b_h_e_a_d_i_n_g_‐_t_e_x_t as a subsection heading indented  between  a
              section  heading and an ordinary paragraph (..PP).  If no argument
              is given, a one‐line input trap is planted;  text  on  the  next
              line  becomes  _s_u_b_h_e_a_d_i_n_g_‐_t_e_x_t_.  The left margin is reset to the
              value of the SSNN register to set the heading text in bold (or the
              font specified by the string HHFF).  If the heading font \\**[[HHFF]] is
              bold, use of an italic style in _s_u_b_h_e_a_d_i_n_g_‐_t_e_x_t 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
              IINN  register.   Text after _s_u_b_h_e_a_d_i_n_g_‐_t_e_x_t is set as an ordinary
              paragraph (..PP).

       ..EEXX
       ..EEEE    Begin and end example.  After ..EEXX, filling  is  disabled  and  a
              constant‐width  (monospaced)  font is selected.  Calling ..EEEE en‐
              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 '', --, \\, ^^, ``, and ~~,  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  .. or ?? followed by multiple spaces can change.
              Use the dummy character escape sequence \\&& before the spaces.

              These macros are extensions introduced in Ninth Edition Research
              Unix.  Systems running that _t_r_o_f_f, or  those  from  Documenter’s
              Workbench,  Heirloom Doctools, or Plan 9 _t_r_o_f_f support them.  To
              be certain your page will be portable to systems  that  do  not,
              copy  their definitions from the _a_n_-_e_x_t_._t_m_a_c file of a _g_r_o_f_f in‐
              stallation.

       ..RRSS [_i_n_s_e_t_‐_a_m_o_u_n_t]
              Start a new relative inset level.  The position of the left mar‐
              gin is saved, then moved right by  _i_n_s_e_t_‐_a_m_o_u_n_t_,  if  specified,
              and  by  the  amount of the IINN register otherwise.  Calls to ..RRSS
              can be nested; each increments by 1 the inset level used by ..RREE.
              The level prior to any ..RRSS calls is 1.

       ..RREE [_l_e_v_e_l]
              End a relative inset.  The left margin  corresponding  to  inset
              level  _l_e_v_e_l  is  restored.   If no argument is given, the inset
              level is reduced by 1.

   PPaarraaggrraapphhiinngg mmaaccrrooss
       An ordinary paragraph (..PP) 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 (..TTPP) or more (..TTQQ) lead‐
       ing tags followed by a paragraph that has  an  additional  indentation.
       The  indented  paragraph (..IIPP) macro is useful to continue the indented
       content of a narrative started with ..TTPP, 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 ..SSHH or ..SSSS,  they  (ex‐
       cept for ..TTQQ) follow the break with a default amount of vertical space,
       which can be changed by the deprecated ..PPDD macro; see subsection “Hori‐
       zontal  and vertical spacing” below.  They also reset the type size and
       font style to defaults (..TTQQ again excepted); see subsection “Font style
       macros” below.

       ..PP
       ..LLPP
       ..PPPP    Begin a new paragraph; these macros are synonymous.  The  inden‐
              tation  is  reset  to the default value; the left margin, as af‐
              fected by ..RRSS and ..RREE, is not.

       ..TTPP [_i_n_d_e_n_t_a_t_i_o_n]
              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  \\cc escape sequence.  Subsequent text is in‐
              dented by _i_n_d_e_n_t_a_t_i_o_n_, if specified, and by the amount of the IINN
              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 ..BB.  ..TTPP was used to write
              the first paragraph of this description of ..TTPP, and ..IIPP the sub‐
              sequent one.

       ..TTQQ    Set an additional tag for a paragraph tagged with ..TTPP.  An input
              trap is planted as with ..TTPP.

              This macro is a GNU extension not  defined  on  systems  running
              AT&T,  Plan  9,  or  Solaris  _t_r_o_f_f;  see _a_n_-_e_x_t_._t_m_a_c in section
              “Files” below.

              The descriptions of ..PP, ..LLPP, and ..PPPP above  were  written  using
              ..TTPP and ..TTQQ.

       ..IIPP [_t_a_g] [_i_n_d_e_n_t_a_t_i_o_n]
              Set an indented paragraph with an optional tag.  The _t_a_g and _i_n_‐
              _d_e_n_t_a_t_i_o_n  arguments,  if present, are handled as with ..TTPP, with
              the exception that the _t_a_g argument  to  ..IIPP  cannot  include  a
              macro call.

              Two convenient uses for ..IIPP are

                  (1) to start a new paragraph with the same indentation as an
                      immediately preceding ..IIPP or ..TTPP paragraph, if no _i_n_d_e_n_‐
                      _t_a_t_i_o_n argument is given; and

                  (2) to set a paragraph with a short _t_a_g that is not semanti‐
                      cally  important, such as a bullet (•)—obtained with the
                      \\((bbuu special character escape sequence—or list  enumera‐
                      tor, as seen in this very paragraph.

   CCoommmmaanndd ssyynnooppssiiss mmaaccrrooss
       ..SSYY  and ..YYSS aid 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 _t_r_o_f_f; see _a_n_-_e_x_t_._t_m_a_c in section “Files” below.

       ..SSYY _c_o_m_m_a_n_d
              Begin  synopsis.   A new paragraph begins at the left margin (as
              with ..PP) unless ..SSYY has already been  called  without  a  corre‐
              sponding  ..YYSS, in which case only a break is performed.  Adjust‐
              ment and automatic hyphenation are disabled.  _c_o_m_m_a_n_d is set  in
              bold.   If  a  break  is required, lines after the first are in‐
              dented by the width of _c_o_m_m_a_n_d plus a space.

       ..YYSS    End synopsis.  Indentation, adjustment, and hyphenation are  re‐
              stored to their previous states.

       Multiple  ..SSYY/..YYSS  blocks can be specified, for instance to distinguish
       differing modes of operation of a complex  command  like  _t_a_r(1);  each
       will be vertically separated as paragraphs are.

       ..SSYY  can be repeated before ..YYSS to indicate synonymous ways of invoking
       a particular mode of operation.

       _g_r_o_f_f’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 ]
              _(_a_n_d _s_o _o_n _s_i_m_i_l_a_r_l_y_)
              .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.

              ggrrooffff [--aabbccCCeeEEggGGiijjkkllNNppRRssSSttUUVVXXzzZZ] [--dd _c_s] [--dd _n_a_m_e==_s_t_r_i_n_g]
                    [--DD _e_n_c] [--ff _f_a_m] [--FF _d_i_r] [--II _d_i_r] [--KK _e_n_c] [--LL _a_r_g]
                    [--mm _n_a_m_e] [--MM _d_i_r] [--nn _n_u_m] [--oo _l_i_s_t] [--PP _a_r_g] [--rr _c_n]
                    [--rr _r_e_g==_e_x_p_r] [--TT _d_e_v] [--ww _n_a_m_e] [--WW _n_a_m_e] [_f_i_l_e ...]

              ggrrooffff --hh
              ggrrooffff ----hheellpp

              ggrrooffff --vv [_o_p_t_i_o_n ...] [_f_i_l_e ...]
              ggrrooffff ----vveerrssiioonn [_o_p_t_i_o_n ...] [_f_i_l_e ...]

       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 bboolldd to cue the user that
         they should be input literally.

       • Option dashes are specified with the \\-- escape 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 _i_t_a_l_i_c_s (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 \\~~ is used to pre‐
         vent the output line from being broken within  the  option  brackets;
         see subsection “Portability” below.

       • The  output  line  continuation  escape sequence \\cc is 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 \\&& follows 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.

   HHyyppeerrlliinnkk mmaaccrrooss
       Man page cross references like _l_s(1) are best presented with ..MMRR.  Text
       may be hyperlinked to email addresses with ..MMTT/..MMEE or other  URIs  with
       ..UURR/..UUEE.  Hyperlinked text is supported on HTML and terminal output de‐
       vices;  terminals  and pager programs must support ECMA‐48 OSC 8 escape
       sequences (see _g_r_o_t_t_y(1)).  When device support is unavailable or  dis‐
       abled  with  the  UU register (see section “Options” below), ..MMTT and ..UURR
       URIs are rendered between angle brackets after the linked text.

       ..MMTT, ..MMEE, ..UURR, and ..UUEE are GNU extensions not defined on  systems  run‐
       ning AT&T, Plan 9, or Solaris _t_r_o_f_f; see _a_n_-_e_x_t_._t_m_a_c in section “Files”
       below.  Plan 9 from User Space’s _t_r_o_f_f implements ..MMRR.

       The  arguments  to ..MMRR, ..MMTT, and ..UURR should 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 _t_r_o_f_f warnings when a hyperlink is longer
       than an output line.  The application of non‐printing break  point  es‐
       cape sequences \\:: after each slash (or series thereof), and before each
       dot  (or series thereof) is recommended as a rule of thumb.  The former
       practice avoids forcing a trailing slash in a URI onto a separate  out‐
       put  line,  and  the latter helps the reader to avoid mistakenly inter‐
       preting 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 \\:: escape sequences from hyperlinks when supplying device control
       commands to output drivers.

       ..MMRR _t_o_p_i_c _m_a_n_u_a_l_‐_s_e_c_t_i_o_n [_t_r_a_i_l_i_n_g_‐_t_e_x_t]
              _(_s_i_n_c_e groff _1_._2_3_) Set a man page cross reference as “_t_o_p_i_c((_m_a_n_‐
              _u_a_l_‐_s_e_c_t_i_o_n))”.   If  _t_r_a_i_l_i_n_g_‐_t_e_x_t  (typically  punctuation)  is
              specified, it follows the closing parenthesis without  interven‐
              ing space.  Hyphenation is disabled while the cross reference is
              set.   _t_o_p_i_c is set in the font specified by the MMFF string.  The
              cross reference hyperlinks to a URI of the form  “mmaann::_t_o_p_i_c(_m_a_n_‐
              _u_a_l_‐_s_e_c_t_i_o_n)”.

                     The output driver
                     .MR grops 1
                     produces PostScript from
                     .I troff
                     output.
                     .
                     The Ghostscript program (\c
                     .MR gs 1 )
                     interprets PostScript and PDF.

       ..MMTT _a_d_d_r_e_s_s
       ..MMEE [_t_r_a_i_l_i_n_g_‐_t_e_x_t]
              Identify  _a_d_d_r_e_s_s  as  an RFC 6068 _a_d_d_r_‐_s_p_e_c for a “mailto:” URI
              with the text between the two macro calls as the link text.   An
              argument  to ..MMEE is placed after the link text without interven‐
              ing space.  _a_d_d_r_e_s_s may not be visible in the rendered  document
              if  hyperlinks  are  enabled and supported by the output driver.
              If they are not, _a_d_d_r_e_s_s is set in angle brackets after the link
              text and before _t_r_a_i_l_i_n_g_‐_t_e_x_t_.  If hyperlinking is  enabled  but
              there  is  no  link  text,  _a_d_d_r_e_s_s is formatted and hyperlinked
              _w_i_t_h_o_u_t angle brackets.

              When rendered by _g_r_o_f_f 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.”.

       ..UURR _u_r_i
       ..UUEE [_t_r_a_i_l_i_n_g_‐_t_e_x_t]
              Identify  _u_r_i as an RFC 3986 URI hyperlink with the text between
              the two macro calls as the link text.  An  argument  to  ..UUEE  is
              placed  after  the link text without intervening space.  _u_r_i may
              not be visible in the rendered document if  hyperlinks  are  en‐
              abled  and supported by the output driver.  If they are not, _u_r_i
              is set in angle brackets after the link text and  before  _t_r_a_i_l_‐
              _i_n_g_‐_t_e_x_t_.  If hyperlinking is enabled but there is no link text,
              _u_r_i is formatted and hyperlinked _w_i_t_h_o_u_t angle brackets.

              When rendered by _g_r_o_f_f 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  _g_r_o_f_f   home   page   ⟨https://www.gnu.org/software/
              groff/⟩.”.

       The  hyperlinking of ..TTPP paragraph tags with ..UURR/..UUEE and ..MMTT/..MMEE is not
       yet supported; if attempted, the hyperlink will be typeset at  the  be‐
       ginning of the indented paragraph even on hyperlink‐supporting devices.

   FFoonntt ssttyyllee mmaaccrrooss
       The  _m_a_n macro package is limited in its font styling options, offering
       only bboolldd (..BB), _i_t_a_l_i_c (..II), and roman.  Italic text is usually set un‐
       derscored instead on terminal devices.  The ..SSMM and ..SSBB macros 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 ..BBII, ..BBRR, ..IIBB, ..IIRR, ..RRBB, and ..RRII, 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 XX7755--1122 and XX110000--1122 devices where the type size  is
       12 points.  The default style is roman.

       ..BB [_t_e_x_t]
              Set  _t_e_x_t  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  ..EEXX/..EEEE
              example  of  interactive I/O (such as a shell session), set only
              user input in bold.

       ..II [_t_e_x_t]
              Set _t_e_x_t 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  ..IIRR
              and ..RRII below), and italics again in running roman text when re‐
              ferring to the variant material.

       ..SSMM [_t_e_x_t]
              Set  _t_e_x_t  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.

              _N_o_t_e_: terminals will render _t_e_x_t at normal size instead.  Do not
              rely  upon ..SSMM to communicate semantic information distinct from
              using roman style at normal size; it will be hidden from readers
              using such devices.

       ..SSBB [_t_e_x_t]
              Set _t_e_x_t 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.

              _N_o_t_e_:  terminals will render _t_e_x_t in bold at the normal size in‐
              stead.  Do not rely upon ..SSBB to communicate semantic information
              distinct from using bold style at normal size; it will be hidden
              from readers using such devices.

       Observe what is _n_o_t 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
       \\((llqq, \\((rrqq, \\((ooqq, and \\((ccqq escape 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 \\cc and/or \\ff escape
       sequences.  See subsection “Portability” below for approaches.

       ..BBII _b_o_l_d_‐_t_e_x_t _i_t_a_l_i_c_‐_t_e_x_t ...
              Set each argument in bold and italics, alternately.

                     .BI -r  register = numeric‐expression

       ..BBRR _b_o_l_d_‐_t_e_x_t _r_o_m_a_n_‐_t_e_x_t ...
              Set each argument in bold and roman, alternately.

                     After
                     .B .NH
                     is called,

       ..IIBB _i_t_a_l_i_c_‐_t_e_x_t _b_o_l_d_‐_t_e_x_t ...
              Set each argument in italics and bold, alternately.

                     In places where
                     .IB n th
                     is allowed,

       ..IIRR _i_t_a_l_i_c_‐_t_e_x_t _r_o_m_a_n_‐_t_e_x_t ...
              Set each argument in italics and roman, alternately.

                     Use GNU
                     .IR pic 's
                     .B figname
                     command to change the name of the vbox.

       ..RRBB _r_o_m_a_n_‐_t_e_x_t _b_o_l_d_‐_t_e_x_t ...
              Set each argument in roman and bold, alternately.

                     if
                     .I file
                     is
                     .RB \[lq] \- \[rq],
                     the standard input stream is read.

       ..RRII _r_o_m_a_n_‐_t_e_x_t _i_t_a_l_i_c_‐_t_e_x_t ...
              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

   HHoorriizzoonnttaall aanndd vveerrttiiccaall ssppaacciinngg
       The _i_n_d_e_n_t_a_t_i_o_n argument accepted by ..IIPP, ..TTPP, and the  deprecated  ..HHPP
       is  a  number  plus an optional scaling unit, as is ..RRSS’s _i_n_s_e_t_‐_a_m_o_u_n_t.
       If no scaling unit is given, the _m_a_n package assumes “n”; that is,  the
       width of a letter “n” in the font current when the macro is called (see
       section  “Measurements”  in  _g_r_o_f_f(7)).   An indentation specified in a
       call to ..IIPP, ..TTPP, or the deprecated ..HHPP persists until (1)  another  of
       these  macros  is called with an _i_n_d_e_n_t_a_t_i_o_n argument, or (2) ..SSHH, ..SSSS,
       or ..PP or its synonyms is called; these clear the indentation entirely.

       The left margin used by ordinary paragraphs set with ..PP (and  its  syn‐
       onyms) not within an ..RRSS/..RREE relative inset is 7.2n for typesetting de‐
       vices  and 7n for terminal devices (but see the --rrIINN option).  Headers,
       footers (both set with ..TTHH), and section headings (..SSHH) are set at  the
       page  offset (see _g_r_o_f_f(7)) and subsection headings (..SSSS) indented from
       it by 3n (but see the --rrSSNN option).

       It may be helpful to think of the left margin and  indentation  as  re‐
       lated  but  distinct  concepts; _g_r_o_f_f’s implementation of the _m_a_n macro
       package tracks them separately.  The left margin is manipulated by  ..RRSS
       and  ..RREE (and by ..SSHH and ..SSSS, which reset it to the default).  Indenta‐
       tion is controlled by the paragraphing macros (though, again,  ..SSHH  and
       ..SSSS  reset  it);  it  is  imposed  by  the ..TTPP, ..IIPP, and deprecated ..HHPP
       macros, and cancelled by ..PP and its  synonyms.   An  extensive  example
       follows.

       This  ordinary  (..PP)  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  ..RRSS  and started another ordinary paragraph
              with ..PP.

              ttaagg    This tagged paragraph, set with ..TTPP, is still within  the
                     ..RRSS  region,  but lines after the first have a supplemen‐
                     tary indentation that the tag lacks.

                     A paragraph like this one, set with ..IIPP, will  appear  to
                     the reader as also associated with the tag above, because
                     ..IIPP  re‐uses  the previous paragraph’s indentation unless
                     given an argument to change it.  This  paragraph  is  af‐
                     fected  both  by the moved left margin (..RRSS) and indenta‐
                     tion (..IIPP).
                     ┌──────────────────────────────────┐
                     │ 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 (..PP) 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 ..RREE, which (because
       we used only one ..RRSS/..RREE pair) has reset the left  margin  to  the  de‐
       fault.  This is an ordinary ..PP paragraph.

       Resist  the  temptation  to mock up tabular or multi‐column output with
       tab characters or the indentation arguments to ..IIPP, ..TTPP,  ..RRSS,  or  the
       deprecated  ..HHPP;  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 _t_b_l(1) can likely meet your needs.

       Several macros insert vertical space: ..SSHH, ..SSSS, ..TTPP, ..PP (and  its  syn‐
       onyms), ..IIPP, and the deprecated ..HHPP.  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 ..PPDD can change this vertical spacing, but its use
       is discouraged.)  Between ..EEXX and ..EEEE calls, the inter‐paragraph  spac‐
       ing is 1v regardless of output device.

   RReeggiisstteerrss
       Registers  are  described  in section “Options” below.  They can be set
       not only on the command line but in the site _m_a_n_._l_o_c_a_l  file  as  well;
       see section “Files” below.

   SSttrriinnggss
       The  following  strings  are  defined for use in man pages.  Others are
       supported for configuration of rendering parameters; see  section  “Op‐
       tions” below.

       \\**RR    interpolates a special character escape sequence for the “regis‐
              tered sign” glyph, \\((rrgg, if available, and “(Reg.)” otherwise.

       \\**SS    interpolates  an  escape  sequence  setting the type size to the
              document default.

       \\**((llqq
       \\**((rrqq  interpolate special character  escape  sequences  for  left  and
              right double‐quotation marks, \\((llqq and \\((rrqq, respectively.

       \\**((TTmm  interpolates  a special character escape sequence for the “trade
              mark sign” glyph, \\((ttmm, if available, and “(TM)” otherwise.

       None of the above is necessary in a contemporary man page.  \\**SS is  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 \\((rrgg, \\((llqq,  \\((rrqq,  and
       \\((ttmm  special  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 _t_r_o_f_f,  though  even  it  supports  \\((rrgg),  the  above
       strings should be avoided.

   PPoorrttaabbiilliittyy
       It is wise to quote multi‐word section and subsection headings; the ..SSHH
       and ..SSSS macros of _m_a_n(7) implementations descended from Seventh Edition
       Unix supported six arguments at most.  A similar restriction applied to
       the ..BB, ..II, ..SSMM, and font style alternation macros.

       The two major syntactical categories for formatting control in the _r_o_f_f
       language  are  requests and escape sequences.  Since the _m_a_n macros are
       implemented in terms of _g_r_o_f_f requests and escape sequences,  one  can,
       in  principle,  supplement  the  functionality of _m_a_n with these lower‐
       level elements where necessary.

       However, using raw _g_r_o_f_f requests (apart from the empty request “..”) 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 _g_r_o_f_f 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  (..EEXX/..EEEE, ..SSYY/..YYSS, ..TTQQ, ..UURR/..UUEE, ..MMTT/..MMEE, ..MMRR, and ..SSBB)
       should be used with caution, as they may not be built in to some viewer
       that is important to your audience.  See _a_n_-_e_x_t_._t_m_a_c 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 _r_o_f_f 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 '' -- \\ ^^ `` ~~ (apostrophe, dash or minus, backslash, caret, grave ac‐
       cent, tilde).

       \\""     Comment.   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 (“..”).

       \\_n_e_w_l_i_n_e
              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 _g_r_o_f_f as a single input line.  Use  this  escape  se‐
              quence  to split excessively long input lines for document main‐
              tenance.

       \\%%     Control hyphenation.   The  location  of  this  escape  sequence
              within  a  word marks a hyphenation point, supplementing _g_r_o_f_f’s
              automatic hyphenation patterns.  At the beginning of a word,  it
              suppresses  any hyphenation breaks within _e_x_c_e_p_t those specified
              with \\%%.

       \\::     Insert 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 \\:: and \\%% in 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  _g_r_o_f_f  extension  also  supported  by
              Heirloom  Doctools  _t_r_o_f_f 050915 (September 2005), _m_a_n_d_o_c 1.14.5
              (2019‐03‐10), and _n_e_a_t_r_o_f_f (commit  399a4936,  2014‐02‐17),  but
              not by Plan 9, Solaris, or Documenter’s Workbench _t_r_o_f_fs.

       \\~~     Adjustable 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  _g_r_o_f_f  extension  also  supported  by
              Heirloom  Doctools  _t_r_o_f_f  050915 (September 2005), _m_a_n_d_o_c 1.9.5
              (2009‐09‐21),  _n_e_a_t_r_o_f_f  (commit  1c6ab0f6e,  2016‐09‐13),   and
              Plan  9  from  User Space _t_r_o_f_f (commit 93f8143600, 2022‐08‐12),
              but not by Solaris or Documenter’s Workbench _t_r_o_f_fs.

       \\&&     Dummy character.  Insert at the beginning of an  input  line  to
              prevent  a dot or apostrophe from being interpreted as beginning
              a _r_o_f_f control line.  Append to an  end‐of‐sentence  punctuation
              sequence to keep it from being recognized as such.

       \\||     Thin  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 ddvvii, ppddff, and ppss.

       \\cc     End 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 _m_a_y  be  broken  there  (if
              not,  an  adjustable space is inserted); if filling is disabled,
              the line _w_i_l_l be broken there, as in ..EEXX/..EEEE examples.  The next
              line is interpreted as usual and can include a macro call  (con‐
              trast  with  \\_n_e_w_l_i_n_e).  \\cc is 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  ..EEXX/..EEEE  examples,
              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 \\ff font
              selection escape sequence can be used; see below.  Using  \\cc  to
              continue  a  ..TTPP  paragraph tag across multiple input lines will
              render incorrectly with _g_r_o_f_f 1.22.3, _m_a_n_d_o_c 1.14.1, older  ver‐
              sions of these programs, and perhaps with some other formatters.

       \\ee     Format  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  \\((rrss  (“reverse  solidus”)  special character escape se‐
              quence.

       \\ffBB, \\ffII, \\ffRR, \\ffPP
              Switch to bold, italic, roman, or back to  the  previous  style,
              respectively.   Either  \\ff  or \\cc is 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 \\cc.   As  shown
              above,  it  is  up to you to account for italic corrections with
              “\\//” and “\\,,”, which are themselves GNU extensions,  if  desired
              and if supported by your implementation.

              \\ffPP  reliably  returns to the style in use immediately preceding
              the previous \\ff escape 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 ..BB and ..BBII usually result in more readable _r_o_f_f source than
              \\ff escape sequences do.

       Several  special  characters  are also widely portable.  Except for \\--,
       \\((eemm, and \\((ggaa, AT&T _t_r_o_f_f did not consistently define  the  characters
       listed below, but its descendants, like Plan 9 or Solaris _t_r_o_f_f, can be
       made to support them by defining them in font description files, making
       them aliases of existing glyphs if necessary; see _g_r_o_f_f___f_o_n_t(5).

       \\--     Minus  sign  or  basic Latin hyphen‐minus.  This escape sequence
              produces the Unix command‐line option dash in the  output.   “--”
              is a hyphen in the _r_o_f_f language; some output devices replace it
              with U+2010 (hyphen) or similar.

       \\((aaqq   Basic  Latin neutral apostrophe.  Some output devices format “''”
              as a right single quotation mark.

       \\((ooqq
       \\((ccqq   Opening (left) and closing (right) single quotation marks.   Use
              these for paired directional single quotes, ‘like this’.

       \\((ddqq   Basic  Latin  quotation mark (double quote).  Use in macro calls
              to prevent ‘""” from being interpreted as beginning a quoted  ar‐
              gument, or simply for readability.

                     .TP
                     .BI "split \(dq" text \(dq

       \\((llqq
       \\((rrqq   Left and right double quotation marks.  Use these for paired di‐
              rectional double quotes, “like this”.

       \\((eemm   Em‐dash.   Use  for  an  interruption—such as this one—in a sen‐
              tence.

       \\((eenn   En‐dash.  Use to separate the ends of a range, particularly  be‐
              tween numbers; for example, “the digits 1–9”.

       \\((ggaa   Basic  Latin  grave accent.  Some output devices format “``” as a
              left single quotation mark.

       \\((hhaa   Basic Latin circumflex accent (“hat”).  Some output devices for‐
              mat “^^” as U+02C6 (modifier letter circumflex accent)  or  simi‐
              lar.

       \\((rrss   Reverse  solidus  (backslash).  The backslash is the default es‐
              cape character in the _r_o_f_f language, so it  does  not  represent
              itself in output.  Also see \\ee above.

       \\((ttii   Basic  Latin  tilde.   Some  output devices format “~~” as U+02DC
              (small tilde) or similar.

       For maximum portability, escape sequences and  special  characters  not
       listed above are better avoided in man pages.

   HHooookkss
       Two macros, both GNU extensions, are called internally by the _g_r_o_f_f _m_a_n
       package  to format page headers and footers and can be redefined by the
       administrator in a site’s _m_a_n_._l_o_c_a_l file (see section  “Files”  below).
       The  presentation  of ..TTHH above describes the default headers and foot‐
       ers.  Because these macros are hooks for _g_r_o_f_f _m_a_n 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; ..PPTT furthermore has
       the responsibility of emitting a PDF bookmark after writing  the  first
       page  header  in  a  document.  Consult the existing implementations in
       _a_n_._t_m_a_c when drafting replacements.

       ..BBTT    Set the page footer text (“bottom trap”).

       ..PPTT    Set the page header text (“page trap”).

       To remove a page header or  footer  entirely,  define  the  appropriate
       macro as empty rather than deleting it.

   DDeepprreeccaatteedd ffeeaattuurreess
       Use  of  the following in man pages for public distribution is discour‐
       aged.

       ..AATT [_s_y_s_t_e_m [_r_e_l_e_a_s_e]]
              Alter the footer for use with legacy AT&T man pages,  overriding
              any definition of the _f_o_o_t_e_r_‐_i_n_s_i_d_e argument to ..TTHH.  This macro
              exists only to render man pages from historical systems.

              _s_y_s_t_e_m can be any of the following.

                     3      7th edition _(_d_e_f_a_u_l_t_)

                     4      System III

                     5      System V

              The  optional  _r_e_l_e_a_s_e argument specifies the release number, as
              in “System V Release 3”.

       ..DDTT    Reset 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 _t_b_l(1) instead.

       ..HHPP [_i_n_d_e_n_t_a_t_i_o_n]
              Set  up a paragraph with a hanging left indentation.  The _i_n_d_e_n_‐
              _t_a_t_i_o_n argument, if present, is handled as with ..TTPP.

              Use of this presentation‐oriented macro is deprecated.  A  hang‐
              ing  indentation  cannot  be expressed naturally under HTML, and
              non‐_r_o_f_f‐based man page interpreters may treat ..HHPP as  an  ordi‐
              nary  paragraph.   Thus, information or distinctions you mean to
              express with indentation may be lost.

       ..OOPP _o_p_t_i_o_n_‐_n_a_m_e [_o_p_t_i_o_n_‐_a_r_g_u_m_e_n_t]
              Indicate an optional command parameter called _o_p_t_i_o_n_‐_n_a_m_e, which
              is set in bold.  If the option takes an  argument,  specify  _o_p_‐
              _t_i_o_n_‐_a_r_g_u_m_e_n_t  using  a  noun,  abbreviation, or hyphenated noun
              phrase.  If present, _o_p_t_i_o_n_‐_a_r_g_u_m_e_n_t 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  _t_r_o_f_f, 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.

       ..PPDD [_v_e_r_t_i_c_a_l_‐_s_p_a_c_e]
              Define  the  vertical space between paragraphs or (sub)sections.
              The optional argument _v_e_r_t_i_c_a_l_‐_s_p_a_c_e 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 ..PPDD to express  are  likely  to  be
              lost.

       ..UUCC [_v_e_r_s_i_o_n]
              Alter  the  footer for use with legacy BSD man pages, overriding
              any definition of the _f_o_o_t_e_r_‐_i_n_s_i_d_e argument to ..TTHH.  This macro
              exists only to render man pages from historical systems.

              _v_e_r_s_i_o_n can be any of the following.

                     3      3rd Berkeley Distribution _(_d_e_f_a_u_l_t_)

                     4      4th Berkeley Distribution

                     5      4.2 Berkeley Distribution

                     6      4.3 Berkeley Distribution

                     7      4.4 Berkeley Distribution

   HHiissttoorryy
       M. Douglas McIlroy designed, implemented, and documented the  AT&T  _m_a_n
       macros  for  Unix  Version 7 (1979) and employed them to edit the first
       volume of its _P_r_o_g_r_a_m_m_e_r_’_s _M_a_n_u_a_l, a compilation of all man pages  sup‐
       plied by the system.  That _m_a_n supported the macros listed in this page
       not  described as extensions, except ..PP and the deprecated ..AATT and ..UUCC.
       The only strings defined were RR and SS; no registers were documented.

       ..UUCC appeared in 3BSD (1980).  Unix System III (1980) introduced ..PP  and
       exposed  the  registers  IINN  and LLLL, which had been internal to Seventh
       Edition Unix _m_a_n.  PWB/UNIX 2.0  (1980)  added  the  TTmm  string.   4BSD
       (1980)  added  llqq and rrqq strings.  SunOS 2.0 (1985) recognized CC, DD, PP,
       and XX registers.  4.3BSD (1986) added ..AATT and ..PP.   Ninth  Edition  Re‐
       search Unix (1986) introduced ..EEXX and ..EEEE.  SunOS 4.0 (1988) added ..SSBB.

       The  foregoing features were what James Clark implemented in early ver‐
       sions of _g_r_o_f_f.  Later, _g_r_o_f_f  1.20  (2009)  originated  ..SSYY/..YYSS,  ..TTQQ,
       ..MMTT/..MMEE, and ..UURR/..UUEE.  Plan 9 from User Space’s _t_r_o_f_f introduced ..MMRR in
       2020.

OOppttiioonnss
       The  following  _g_r_o_f_f options set registers (with --rr) and strings (with
       --dd) recognized and used by the _m_a_n macro package.  To ensure  rendering
       consistent  with output device capabilities and reader preferences, man
       pages should never manipulate them.

       --ddAADD==_a_d_j_u_s_t_m_e_n_t_‐_m_o_d_e
              Set line adjustment to _a_d_j_u_s_t_m_e_n_t_‐_m_o_d_e_, which is  typically  “bb”
              for  adjustment  to  both margins (the default), or “ll” for left
              alignment (ragged right margin).  Any valid argument to  _g_r_o_f_f’s
              “.ad”  request  may  be  used.   See  _g_r_o_f_f(7)  for  less‐common
              choices.

       --rrccRR==11 Enable 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 --rrccRR==00 to  disable  it
              on terminal devices; on HTML devices, it cannot be disabled.

       --rrCC11   Number  output  pages  consecutively, in strictly increasing se‐
              quence, rather than resetting the page number to 1 (or the value
              of register PP) with each new _m_a_n document.

       --rrCCSS==11 Set section headings (the argument(s) to ..SSHH) in full  capitals.
              This  transformation  is off by default because it discards case
              distinction information.

       --rrCCTT==11 Set the man page topic (the first argument to ..TTHH) in full capi‐
              tals in headers and footers.  This transformation is off by  de‐
              fault because it discards case distinction information.

       --rrDD11   Enable  double‐sided layout, formatting footers for even and odd
              pages differently; see the  description  of  ..TTHH  in  subsection
              “Document structure macros” above.

       --rrFFTT==_f_o_o_t_e_r_‐_d_i_s_t_a_n_c_e
              Set distance of the footer relative to the bottom of the page to
              _f_o_o_t_e_r_‐_d_i_s_t_a_n_c_e_;  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.

       --ddHHFF==_h_e_a_d_i_n_g_‐_f_o_n_t
              Set  the  font used for section and subsection headings; the de‐
              fault is “BB” (bold style of the default family).  Any valid  ar‐
              gument to _g_r_o_f_f’s “.ft” request may be used.  See _g_r_o_f_f(7).

       --rrHHYY==00 Disable  automatic  hyphenation.   Normally,  it is enabled (1).
              The hyphenation mode is determined by the _g_r_o_f_f locale; see sec‐
              tion “Localization“ of _g_r_o_f_f(7).

       --rrIINN==_s_t_a_n_d_a_r_d_‐_i_n_d_e_n_t_a_t_i_o_n
              Set the amount of indentation used for ordinary  paragraphs  (..PP
              and  its  synonyms)  and  the default indentation amount used by
              ..IIPP, ..RRSS, ..TTPP, and the deprecated ..HHPP.  See subsection “Horizon‐
              tal and vertical spacing” above for the default.   For  terminal
              devices, _s_t_a_n_d_a_r_d_‐_i_n_d_e_n_t_a_t_i_o_n should always be an integer multi‐
              ple of unit “n” to get consistent indentation.

       --rrLLLL==_l_i_n_e_‐_l_e_n_g_t_h
              Set  line  length;  the  default is 78n for terminal devices and
              6.5i for typesetting devices.

       --rrLLTT==_t_i_t_l_e_‐_l_e_n_g_t_h
              Set the line length for titles.  (“Titles” is the _r_o_f_f term  for
              headers  and footers.)  By default, it is set to the line length
              (see --rrLLLL above).

       --ddMMFF==_m_a_n_‐_p_a_g_e_‐_t_o_p_i_c_‐_f_o_n_t
              Set the font used for man page  topics  named  in  ..TTHH  and  ..MMRR
              calls;  the default is “II” (italic style of the default family).
              Any valid argument to _g_r_o_f_f’s “.ft” request may be used.  If the
              MMFF string ends in “I”, it is assumed to be an oblique  typeface,
              and  italic  corrections  are  applied before and after man page
              topics.

       --rrPP_n   Start enumeration of pages at _n.  The default is 1.

       --rrSS_t_y_p_e_‐_s_i_z_e
              Use _t_y_p_e_‐_s_i_z_e for the document’s body  text;  acceptable  values
              are  10,  11,  or 12 points.  See subsection “Font style macros”
              above for the default.

       --rrSSNN==_s_u_b_s_e_c_t_i_o_n_‐_i_n_d_e_n_t_a_t_i_o_n
              Set indentation of subsection  headings  to  _s_u_b_s_e_c_t_i_o_n_‐_i_n_d_e_n_t_a_‐
              _t_i_o_n_.   See  subsection  “Horizontal and vertical spacing” above
              for the default.

       --rrUU11   Enable generation of URI hyperlinks in the  _g_r_o_h_t_m_l  and  _g_r_o_t_t_y
              output  drivers.   _g_r_o_h_t_m_l  enables them by default; _g_r_o_t_t_y does
              not, pending more widespread pager support for OSC 8 escape  se‐
              quences.  Use --rrUU00 to disable hyperlinks; this will make the ar‐
              guments to MMTT and UURR calls visible in the document text produced
              by link‐capable drivers.

       --rrXX_p   Number  successors  of  page _p as _pa, _pb, _pc, and so forth.  The
              register tracking the suffixed page letter uses format “a”  (see
              the  “.af”  request  in _g_r_o_f_f(7)).  For example, the option --rrXX22
              produces the following page numbers: 1, 2,  2a,  2b,  ...,  2aa,
              2ab, and so on.

FFiilleess
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_a_n_._t_m_a_c
              Most  _m_a_n macros are defined in this file.  It also loads exten‐
              sions from _a_n_-_e_x_t_._t_m_a_c (see below).

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_a_n_d_o_c_._t_m_a_c
              This brief _g_r_o_f_f program detects whether the _m_a_n or  _m_d_o_c  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 ..TTHH or ..DDdd, respectively, before any other macros.  A
              _m_a_n program or user typing, for example, “ggrrooffff --mmaannddoocc ppaaggee..11”,
              need not know which package the file _p_a_g_e_._1 uses.  Multiple  man
              pages,  in  either  format,  can  be handled; _a_n_d_o_c reloads each
              macro package as necessary.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_a_n_-_e_x_t_._t_m_a_c
              Except for ..SSBB, 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 _a_n_._t_m_a_c, and  are  ig‐
              nored  if  the  formatter  is GNU _t_r_o_f_f.  They are written to be
              compatible with AT&T _t_r_o_f_f and permissively  licensed—not  copy‐
              lefted.  To reduce the risk of name space collisions, string and
              register  names  begin only with “mm”..  We encourage man page au‐
              thors who are concerned about portability to legacy Unix systems
              to copy these definitions into their pages, and  maintainers  of
              _t_r_o_f_f  implementations  or  work‐alike  systems  that format man
              pages to re‐use them.

              The definitions for these macros are read  after  a  page  calls
              ..TTHH, 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 ..TTHH is 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 _m_a_k_e_‐
              _w_h_a_t_i_s or _m_a_n_d_b implementations that may give up their scan  for
              indexing material early.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_m_a_n_._t_m_a_c
              This is a wrapper that loads _a_n_._t_m_a_c.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_m_a_n_d_o_c_._t_m_a_c
              This is a wrapper that loads _a_n_d_o_c_._t_m_a_c.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_s_i_t_e_-_t_m_a_c_/_m_a_n_._l_o_c_a_l
              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 _m_a_n_._l_o_c_a_l 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 _m_a_n(1) program may lack permission
              to open such files.

NNootteess
       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.
              ────────────────────────────────────────────
                                  ''   \\((aaqq
                                  --   \\--
                                  \\   \\((rrss
                                  ^^   \\((hhaa
                                  ``   \\((ggaa
                                  ~~   \\((ttii
              ────────────────────────────────────────────

              Additionally, if a neutral double quote (") is needed in a macro
              argument,  you  can use \\((ddqq to get it.  You should _n_o_t use \\((aaqq
              for an ordinary apostrophe (as in “can’t”) or \\-- for 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.
              ────────────────────────────────────────────────────────────────
              ..TTPP """"                         ..TTPP
              ────────────────────────────────────────────────────────────────
              ..BBII """" _i_t_a_l_i_c_‐_t_e_x_t _b_o_l_d_‐_t_e_x_t   ..IIBB _i_t_a_l_i_c_‐_t_e_x_t _b_o_l_d_‐_t_e_x_t
              ────────────────────────────────────────────────────────────────
              ..TTHH ffoooo 11 """" ""ffoooo 11..22..33""       ..TTHH ffoooo 11 _y_y_y_y‐‐_m_m‐‐_d_d ""ffoooo 11..22..33""
              ────────────────────────────────────────────────────────────────
              ..IIPP """" 44nn                      ..IIPP
              ────────────────────────────────────────────────────────────────
              ..IIPP """" 44nn                      ..RRSS 44nn
              _p_a_r_a_g_r_a_p_h                      ..PP
              ...                            _p_a_r_a_g_r_a_p_h
              ...                            ..RREE
              ────────────────────────────────────────────────────────────────
              ..BB oonnee ttwwoo """" tthhrreeee            ..BB oonnee ttwwoo tthhrreeee

              In the title heading (..TTHH), 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.

              ..IIPP  is 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 --rrIINN option.  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 ..RRSS and ..RREE instead.

              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.

       • ..RRSS doesn’t indent relative to my indented paragraph.
              The  ..RRSS  macro  sets  the left margin; that is, the position at
              which an _o_r_d_i_n_a_r_y paragraph (..PP and its synonyms) will  be  set.
              ..IIPP,  ..TTPP,  and the deprecated ..HHPP use the same default indenta‐
              tion.  If not given an argument, ..RRSS moves the  left  margin  by
              this  same  amount.   To create an inset relative to an indented
              paragraph, call ..RRSS repeatedly until an  acceptable  indentation
              is  achieved,  or  give  ..RRSS  an indentation argument that is at
              least as much as the paragraph’s indentation amount relative  to
              an adjacent ..PP paragraph.  See subsection “Horizontal and verti‐
              cal spacing” above for the values.

              Another  approach you can use with tagged paragraphs is to place
              an ..RRSS call 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 ..PP instead of ..IIPP.  Remember to use ..RREE to end the  in‐
              dented  region before starting the next tagged paragraph (at the
              appropriate nesting level).

       • ..RREE doesn’t move the inset back to the expected level.
       • warning: scaling unit invalid in context
       • warning: register 'an-saved-margin_n' not defined
       • warning: register 'an-saved-prevailing-indent_n' not defined
              The ..RRSS macro takes an _i_n_d_e_n_t_a_t_i_o_n _a_m_o_u_n_t as  an  argument;  the
              ..RREE  macro’s  argument is a specific _i_n_s_e_t _l_e_v_e_l_.  ..RREE 11 goes to
              the level before any ..RRSS macros were called, ..RREE 22 goes  to  the
              level  of the first ..RRSS call you made, and so forth.  If you de‐
              sire symmetry in your macro calls, simply issue one ..RREE  without
              an argument for each ..RRSS that precedes it.

              After  calls  to the ..SSHH and ..SSSS sectioning macros, all relative
              insets are cleared and calls to ..RREE have no effect until ..RRSS  is
              used again.

       • Do I need to keep typing the indentation in a series of ..IIPP calls?
              Not if you don’t want to change it.  Review subsection “Horizon‐
              tal and vertical spacing” above.

                Instead of...     ...should be considered.
              ─────────────────────────────────────────────
              ..IIPP \\((bbuu 44nn         ..IIPP \\((bbuu 44nn
              _p_a_r_a_g_r_a_p_h           _p_a_r_a_g_r_a_p_h
              ..IIPP \\((bbuu 44nn         ..IIPP \\((bbuu
              _a_n_o_t_h_e_r_‐_p_a_r_a_g_r_a_p_h   _a_n_o_t_h_e_r_‐_p_a_r_a_g_r_a_p_h
              ─────────────────────────────────────────────

       • 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  _r_o_f_f  ellipsis  is  three
              dots  (periods)  with  thin space escape sequences \\|| internally
              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 \\&&.  That fact stands even if a string
              is  defined to contain the sequence; further, if the string ends
              with \\&&, 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  EELL  that  contained  an  ellipsis, but not the
              trailing dummy character \\&&, would then need to be suffixed with
              the latter when not ending a sentence.

                  Instead of...              ...do this.
              ──────────────────────────────────────────────────
              ..ddss EELL \\&&..\\||..\\||..         AArrgguummeennttss aarree
              AArrgguummeennttss aarree            ..IIRR ssrrcc‐‐ffiillee\\~~ ..\\||..\\||..\\&&
              ..IIRR ssrrcc‐‐ffiillee\\~~ \\**((EELL\\&&   ..IIRR ddeesstt‐‐ddiirr ..
              ..IIRR ddeesstt‐‐ddiirr ..
              ──────────────────────────────────────────────────

              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‐_r_o_f_f 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 \\NN escape 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.

AAuutthhoorrss
       The  initial GNU implementation of the _m_a_n macro package was written by
       James Clark.  Later, Werner Lemberg supplied the SS, LLTT, and  ccRR  regis‐
       ters,  the  last a 4.3BSD‐Reno _m_d_o_c(7) feature.  Larry Kollar added the
       FFTT, HHYY, and SSNN registers; the HHFF string; and the PPTT and BBTT macros.   G.
       Branden Robinson  implemented the AADD and MMFF strings; CCSS, CCTT, and UU reg‐
       isters; and the MMRR macro.  Except for ..SSBB, the  extension  macros  were
       written by Lemberg, Eric S. Raymond, and Robinson.

       This document was originally written for the Debian GNU/Linux system by
       Susan G. Kleinmann.  It was corrected and updated by Lemberg and Robin‐
       son.   The  extension  macros  were documented by Raymond and Robinson.
       Raymond also originated the portability section, to which Ingo Schwarze
       contributed most of the material on escape sequences.

SSeeee aallssoo
       _t_b_l(1), _e_q_n(1), and _r_e_f_e_r(1) are preprocessors  used  with  man  pages.
       _m_a_n(1)  describes the man page librarian on your system.  _g_r_o_f_f___m_d_o_c(7)
       details the _g_r_o_f_f version of the BSD‐originated alternative macro pack‐
       age for man pages.

       _g_r_o_f_f___m_a_n(7), _g_r_o_f_f(7), _g_r_o_f_f___c_h_a_r(7), _m_a_n(7)

groff 1.23.0                      3 June 2025               _g_r_o_f_f___m_a_n___s_t_y_l_e(7)
───────────────────────────────────────────────────────────────────────────────
_g_r_o_f_f___m_d_o_c(7)           Miscellaneous Information Manual         _g_r_o_f_f___m_d_o_c(7)

NNaammee
       groff_mdoc — compose BSD‐style manual (man) pages with GNU _r_o_f_f

SSyynnooppssiiss
       ggrrooffff --mmddoocc _f_i_l_e ...

DDeessccrriippttiioonn
       The GNU implementation of  the  _m_d_o_c  macro  package  is  part  of  the
       _g_r_o_f_f(1)  document  formatting system.  _m_d_o_c is a structurally‐ and se‐
       mantically‐oriented  package  for  writing  Unix  manual   pages   with
       _t_r_o_f_f(1).   Its  predecessor,  the  _m_a_n(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.

       _m_d_o_c organizes its macros into _d_o_m_a_i_n_s.  The _p_a_g_e _s_t_r_u_c_t_u_r_e _d_o_m_a_i_n lays
       out  the  page  and  comprises  titles, section headings, displays, and
       lists.  The _g_e_n_e_r_a_l _t_e_x_t _d_o_m_a_i_n supplies macros to quote or style text,
       or to interpolate common noun phrases.  The _m_a_n_u_a_l _d_o_m_a_i_n 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.

GGeettttiinngg ssttaarrtteedd
       The _m_d_o_c package attempts to simplify man page authorship  and  mainte‐
       nance  without  requiring  mastery of the _r_o_f_f language.  This document
       presents only essential facts about _r_o_f_f_. For further  background,  in‐
       cluding  a  discussion of basic typographical concepts like “breaking”,
       “filling”, and “adjustment”, see _r_o_f_f(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
       _g_r_o_f_f(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 .DDqq macro, which double‐quotes its arguments.
             ..DDqq mmaann ppaaggee  → “man page”

   UUssaaggee
       An  _m_d_o_c  _m_a_c_r_o  is  _c_a_l_l_e_d  by placing the _r_o_f_f 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 _n_o_t 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  _n_o_t  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 _e_m_p_t_y _r_e_q_u_e_s_t.  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 _r_o_f_f 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  _t_r_o_f_f accept an unlimited number of arguments, in con‐
       trast to other _t_r_o_f_fs 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 ‘\_n_e_w_l_i_n_e’ escape sequence;  see  subsection
       “Extended  arguments”  below.   Neutral  double quotes "" can be used to
       group multiple words into an argument; see  subsection  “Passing  space
       characters in an argument” below.

       Most  of _m_d_o_c’s general text and manual domain macros _p_a_r_s_e their argu‐
       ment lists for _c_a_l_l_a_b_l_e 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
       _m_d_o_c package, not a general feature of _r_o_f_f syntax.

       For  example,  the  option  macro,  .OOpp, may call the flag and argument
       macros, .FFll and .AArr, to specify an optional flag with an argument.
             ..OOpp FFll ss AArr bbyytteess      → [--ss _b_y_t_e_s]
       To prevent a word from being interpreted as a macro  name,  precede  it
       with the dummy character.
             ..OOpp \\&&FFll ss \\&&AArr bbyytteess  → [Fl s Ar bytes]

       In  this  document, macros whose argument lists are parsed for callable
       arguments are referred to as _p_a_r_s_e_d, and those that may be called  from
       an  argument list are referred to as _c_a_l_l_a_b_l_e.  This usage is a techni‐
       cal _f_a_u_x _p_a_s, since all _m_d_o_c 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 _m_d_o_c macros are
       parsed and callable.

       In the following, we term an _m_d_o_c macro that  starts  a  line  (with  a
       leading  dot)  a _c_o_m_m_a_n_d if a distinction from those appearing as argu‐
       ments of other macros is necessary.

   PPaassssiinngg ssppaaccee cchhaarraacctteerrss iinn aann aarrgguummeenntt
       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 _m_d_o_c work faster;
       macros that parse arguments do so once (at most) for each.   For  exam‐
       ple, the function command .FFnn expects 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 _a_n_d 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  “_i_n_t
       _f_o_o”.

       There  are  a few ways to embed a space in a macro argument.  One is to
       use the unadjustable  space  escape  sequence  \\_s_p_a_c_e.   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 _g_r_o_f_f extension
       is widely but not perfectly portable.  Another method is to enclose the
       string in double quotes.
             ..FFnn ffeettcchh cchhaarr\\ **ssttrr   → ffeettcchh(_c_h_a_r _*_s_t_r)
             ..FFnn ffeettcchh cchhaarr\\~~**ssttrr   → ffeettcchh(_c_h_a_r _*_s_t_r)
             ..FFnn ffeettcchh ""cchhaarr **ssttrr""  → ffeettcchh(_c_h_a_r _*_s_t_r)
       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.
             ..FFnn ffeettcchh cchhaarr **ssttrr    → ffeettcchh(_c_h_a_r, _*_s_t_r)

   TTrraaiilliinngg ssppaaccee cchhaarraacctteerrss
       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.

   FFoorrmmaattttiinngg tthhee bbaacckkssllaasshh ggllyypphh
       When you need the _r_o_f_f 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 _r_o_f_f request is used to
       change it, which should never happen in man pages.  ‘\(rs’ is  a  _g_r_o_f_f
       special  character escape sequence that explicitly formats the “reverse
       solidus” (backslash) glyph.

   OOtthheerr ppoossssiibbllee ppiittffaallllss
       _g_r_o_f_f _m_d_o_c warns when an  empty  input  line  is  found  outside  of  a
       _d_i_s_p_l_a_y, 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; _m_d_o_c 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 _r_o_f_f(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,  _m_d_o_c
       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 ‘..\\""’ at the
       start of an input line, ‘\\""’ after other input, or ‘\\##’  anywhere  (the
       last is a _g_r_o_f_f extension); the remainder of any such line is ignored.

AA mmaann ppaaggee tteemmppllaattee
       Use _m_d_o_c 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 .DDdd, .DDtt, and .OOss.
       They identify the page  and  are  discussed  below  in  section  “Title
       macros”.

       The  remaining  items  in  the  template are section headings (.SShh); 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.

CCoonnvveennttiioonnss
       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.
             zzttaarr {cc | xx} [--ww [--yy | --zz]] [--ff _a_r_c_h_i_v_e] _m_e_m_b_e_r ...
       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.
             zzttaarr cc [--ww [--yy | --zz]] [--ff _a_r_c_h_i_v_e] _m_e_m_b_e_r ...
             zzttaarr xx [--ww [--yy | --zz]] [--ff _a_r_c_h_i_v_e] _m_e_m_b_e_r ...

       Most  macros  affect subsequent arguments until another macro or a new‐
       line is encountered.  For example, ‘..LLii llss BBqq AArr ffiillee’ doesn’t  produce
       ‘llss [[ffiillee]]’, but ‘llss [_f_i_l_e]’.  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.
             ..LLii ""llss [[ffiillee]]""  → llss [[ffiillee]] _# _l_i_s_t _a_n_y _f_i_l_e_s _n_a_m_e_d _e_, _f_, _i_, _o_r _l

       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 _m_d_o_c package.  Explicit --wwiiddtthh and --ooffffsseett arguments to the .BBll and
       .BBdd macros are preferable.

TTiittllee mmaaccrrooss
       We  present  the  mmaannddaattoorryy  title 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 _r_o_f_f parlance termed “titles”.

       ..DDdd _d_a_t_e
               This  first macro of any _m_d_o_c manual records the last modifica‐
               tion date of the document source.  Arguments  are  concatenated
               and separated with space characters.

               Historically,  _d_a_t_e  was  written  in  U.S. traditional format,
               “_M_o_n_t_h _d_a_y , _y_e_a_r” where _M_o_n_t_h is the full month name  in  Eng‐
               lish, _d_a_y an integer without a leading zero, and _y_e_a_r the four‐
               digit  year.   This localism is not enforced, however.  You may
               prefer  ISO  8601  format,  _Y_Y_Y_Y_‐_M_M_‐_D_D_.  A  _d_a_t_e  of  the  form
               ‘$$MMddooccddaattee::  _M_o_n_t_h  _d_a_y _y_e_a_r $$’ is also recognized.  It is used
               in OpenBSD manuals to automatically  insert  the  current  date
               when committing.

               This macro is neither callable nor parsed.

       ..DDtt _t_o_p_i_c [_s_e_c_t_i_o_n_‐_i_d_e_n_t_i_f_i_e_r [_s_e_c_t_i_o_n_‐_k_e_y_w_o_r_d_‐_o_r_‐_t_i_t_l_e]]
               _t_o_p_i_c  is  the  subject  of the man page.  A _s_e_c_t_i_o_n_‐_i_d_e_n_t_i_f_i_e_r
               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 _s_e_c_t_i_o_n_‐_k_e_y_w_o_r_d_‐_o_r_‐_t_i_t_l_e designates  a  com‐
               puter  architecture  recognized  by  _g_r_o_f_f  _m_d_o_c,  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, _s_e_c_t_i_o_n_‐_k_e_y_w_o_r_d_‐_o_r_‐_t_i_t_l_e 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)

               _r_o_f_f  strings  define  section  titles and architecture identi‐
               fiers.  Site‐specific additions might  be  found  in  the  file
               _m_d_o_c_._l_o_c_a_l; see section “Files” below.

               This macro is neither callable nor parsed.

       ..OOss [_o_p_e_r_a_t_i_n_g_‐_s_y_s_t_e_m_‐_o_r_‐_p_a_c_k_a_g_e_‐_n_a_m_e [_v_e_r_s_i_o_n_‐_o_r_‐_r_e_l_e_a_s_e]]
               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;
               _m_d_o_c  will  supply it.  In this implementation, that default is
               “Debian”.  It may be overridden in the site configuration file,
               _m_d_o_c_._l_o_c_a_l; 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
               _v_e_r_s_i_o_n_‐_o_r_‐_r_e_l_e_a_s_e  argument  should use the standard nomencla‐
               ture for the software specified.  In the following table,  rec‐
               ognized  _v_e_r_s_i_o_n_‐_o_r_‐_r_e_l_e_a_s_e arguments for some predefined oper‐
               ating systems are listed.  As with .DDtt, site additions might be
               defined in _m_d_o_c_._l_o_c_a_l.

                     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 .DDtt was BBSSDD or  AATTTT.
               An  unrecognized  version  argument  after AATTTT is 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 “..OOss ggrrooffff 11..2233..00” whereas a  locally  produced  page
               might employ “..OOss ""UUXXYYZZ CCSS DDeeppaarrttmmeenntt""”, omitting versioning.

               This macro is neither callable nor parsed.

IInnttrroodduuccttiioonn ttoo mmaannuuaall aanndd ggeenneerraall tteexxtt ddoommaaiinnss
   WWhhaatt’’ss iinn aa NNaammee...
       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 _m_d_o_c macro command usage.  Second is the description of a
       Unix command _w_i_t_h _m_d_o_c 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, _t_r_o_f_f macros are themselves a type of  command;  the
       general syntax for a _t_r_o_f_f command is:

             ..XXxx aarrgguummeenntt11 aarrgguummeenntt22 ......

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

             ffiilltteerr [--ffllaagg] ⟨_i_n_f_i_l_e⟩ ⟨_o_u_t_f_i_l_e⟩

       Here, ffiilltteerr is the command name and the bracketed string  --ffllaagg  is  a
       _f_l_a_g  argument  designated as optional by the option brackets.  In _m_d_o_c
       terms, ⟨_i_n_f_i_l_e⟩ and ⟨_o_u_t_f_i_l_e⟩ are called _m_e_t_a _a_r_g_u_m_e_n_t_s; 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 _m_d_o_c 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  ⟨_i_n_f_i_l_e⟩
       and  ⟨_o_u_t_f_i_l_e⟩  from the example above might be referred to as _o_p_e_r_a_n_d_s
       or _f_i_l_e _a_r_g_u_m_e_n_t_s.  Some command‐line argument lists are quite long:

             mmaakkee  [--eeiikknnqqrrssttvv] [--DD _v_a_r_i_a_b_l_e] [--dd _f_l_a_g_s] [--ff _m_a_k_e_f_i_l_e] [--II
                   _d_i_r_e_c_t_o_r_y] [--jj _m_a_x___j_o_b_s] [_v_a_r_i_a_b_l_e=_v_a_l_u_e] [_t_a_r_g_e_t ...]

       Here one might talk about the command _m_a_k_e and  qualify  the  argument,
       _m_a_k_e_f_i_l_e,  as an argument to the flag, --ff, or discuss the optional file
       operand _t_a_r_g_e_t.  In the verbal context, such detail can prevent  confu‐
       sion, however the _m_d_o_c package does not have a macro for an argument _t_o
       a flag.  Instead the ‘Ar’ argument macro is used for an operand or file
       argument  like  _t_a_r_g_e_t  as well as an argument to a flag like _v_a_r_i_a_b_l_e.
       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”.

   GGeenneerraall SSyynnttaaxx
       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:

             ..AArr ssppttrr,, ppttrr)),,

       The result is:

             _s_p_t_r_, _p_t_r_)_,

       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:

             ..AArr ssppttrr ,, ppttrr )) ,,

       The result is:

             _s_p_t_r, _p_t_r),

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

                 ..         ,,         ::         ;;         ((
                 ))         [[         ]]         ??         !!

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

MMaannuuaall ddoommaaiinn
   AAddddrreesssseess
       The address macro identifies an address construct.

             UUssaaggee:: ..AAdd ⟨address⟩ ...

                      ..AAdd aaddddrr11           _a_d_d_r_1
                      ..AAdd aaddddrr11 ..         _a_d_d_r_1.
                      ..AAdd aaddddrr11 ,, ffiillee22   _a_d_d_r_1, _f_i_l_e_2
                      ..AAdd ff11 ,, ff22 ,, ff33 ::  _f_1, _f_2, _f_3:
                      ..AAdd aaddddrr )) )) ,,      _a_d_d_r)),

       The default width is 12n.

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

             UUssaaggee:: ..AAnn ⟨author name⟩ ...

                      ..AAnn ""JJooee AAuutthhoorr""        Joe Author

                      ..AAnn ""JJooee AAuutthhoorr"" ,,      Joe Author,

                      ..AAnn ""JJooee AAuutthhoorr"" AAqq nnoobbooddyy@@FFrreeeeBBSSDD..oorrgg
                                              Joe Author <nobody@FreeBSD.org>

                      ..AAnn ""JJooee AAuutthhoorr"" )) )) ,,  Joe 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

   AArrgguummeennttss
       The  ..AArr argument macro may be used whenever an argument is referenced.
       If called without arguments, ‘_f_i_l_e _._._.’ 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.

             UUssaaggee:: ..AArr [⟨argument⟩] ...

                      ..AArr              _f_i_l_e _._._.
                      ..AArr ffiillee NNoo ......  _f_i_l_e ...
                      ..AArr ffiillee11        _f_i_l_e_1
                      ..AArr ffiillee11 ..      _f_i_l_e_1.
                      ..AArr ffiillee11 ffiillee22  _f_i_l_e_1 _f_i_l_e_2
                      ..AArr ff11 ff22 ff33 ::   _f_1 _f_2 _f_3:
                      ..AArr ffiillee )) )) ,,   _f_i_l_e)),

       The default width is 12n.

   CCoonnffiigguurraattiioonn DDeeccllaarraattiioonn ((SSeeccttiioonn FFoouurr OOnnllyy))
       The  ‘.Cd’  macro  is used to demonstrate a _c_o_n_f_i_g(8) declaration for a
       device interface in a section four manual.

             UUssaaggee:: ..CCdd ⟨argument⟩ ...

                      ..CCdd ""ddeevviiccee llee00 aatt ssccooddee??""  ddeevviiccee llee00 aatt ssccooddee??

       In a section titled “Synopsis”, ‘Cd’ causes a break  before  and  after
       its arguments.

       The default width is 12n.

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

   DDeeffiinneedd VVaarriiaabblleess
       A  variable  (or constant) that is defined in an include file is speci‐
       fied by the macro ‘.Dv’.

             UUssaaggee:: ..DDvv ⟨defined‐variable⟩ ...

                      ..DDvv MMAAXXHHOOSSTTNNAAMMEELLEENN  MAXHOSTNAMELEN
                      ..DDvv TTIIOOCCGGPPGGRRPP ))     TIOCGPGRP)

       The default width is 12n.

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

             UUssaaggee:: ..EErr ⟨errno type⟩ ...

                      ..EErr EENNOOEENNTT      ENOENT
                      ..EErr EENNOOEENNTT )) ;;  ENOENT);
                      ..BBqq EErr EENNOOTTDDIIRR  [ENOTDIR]

       The default width is 17n.

   EEnnvviirroonnmmeenntt VVaarriiaabblleess
       The ‘.Ev’ macro specifies an environment variable.

             UUssaaggee:: ..EEvv ⟨argument⟩ ...

                      ..EEvv DDIISSPPLLAAYY        DISPLAY
                      ..EEvv PPAATTHH ..         PATH.
                      ..EEvv PPRRIINNTTEERR )) )) ,,  PRINTER)),

       The default width is 15n.

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

             UUssaaggee:: ..FFll ⟨argument⟩ ...

                      ..FFll          --
                      ..FFll ccffvv      --ccffvv
                      ..FFll ccffvv ..    --ccffvv.
                      ..CCmm ccffvv ..    ccffvv.
                      ..FFll ss vv tt    --ss --vv --tt
                      ..FFll -- ,,      ----,
                      ..FFll xxyyzz )) ,,  --xxyyzz),
                      ..FFll ||        -- |

       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.

   FFuunnccttiioonn DDeeccllaarraattiioonnss
       The ‘.Fd’ macro is used in the “Synopsis” section with section  two  or
       three functions.  It is neither callable nor parsed.

             UUssaaggee:: ..FFdd ⟨argument⟩ ...

                      ..FFdd ""##iinncclluuddee <<ssyyss//ttyyppeess..hh>>""  ##iinncclluuddee <<ssyyss//ttyyppeess..hh>>

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

             UUssaaggee:: ..IInn ⟨header file⟩

                      ..IInn ssttddiioo..hh  <_s_t_d_i_o_._h>
                      ..IInn ssttddiioo..hh  <_s_t_d_i_o_._h>

   FFuunnccttiioonn TTyyppeess
       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.)

             UUssaaggee:: ..FFtt ⟨type⟩ ...

                      ..FFtt ssttrruucctt ssttaatt  _s_t_r_u_c_t _s_t_a_t

   FFuunnccttiioonnss ((LLiibbrraarryy RRoouuttiinneess))
       The ‘.Fn’ macro is modeled on ANSI C conventions.

             UUssaaggee:: ..FFnn ⟨function⟩ [⟨parameter⟩] ...

                      ..FFnn ggeettcchhaarr              ggeettcchhaarr()
                      ..FFnn ssttrrlleenn )) ,,           ssttrrlleenn()),
                      ..FFnn aalliiggnn ""cchhaarr **ppttrr"" ,,  aalliiggnn(_c_h_a_r _*_p_t_r),

       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:

             _i_n_t rreess__mmkkqquueerryy(_i_n_t _o_p, _c_h_a_r _*_d_n_a_m_e, _i_n_t _c_l_a_s_s, _i_n_t _t_y_p_e,
             _c_h_a_r _*_d_a_t_a, _i_n_t _d_a_t_a_l_e_n, _s_t_r_u_c_t _r_r_e_c _*_n_e_w_r_r, _c_h_a_r _*_b_u_f,
             _i_n_t _b_u_f_l_e_n)

       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.

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

             UUssaaggee:: ..FFaa ⟨function argument⟩ ...

                      ..FFaa dd__nnaammlleenn )) )) ,,  _d___n_a_m_l_e_n)),
                      ..FFaa iioovv__lleenn         _i_o_v___l_e_n

       The default width is 12n.

   RReettuurrnn VVaalluueess
       The ‘.Rv’ macro generates text for use in the “Return values” section.

             UUssaaggee:: ..RRvv [-std] [⟨function⟩ ...]

       For example, ‘.Rv -std atexit’ produces:

             The aatteexxiitt() function returns the value 0 if successful; other‐
             wise the value -1 is returned and the global variable _e_r_r_n_o is
             set to indicate the error.

       The  --ssttdd  option is valid only for manual page sections 2 and 3.  Cur‐
       rently, this macro does nothing if used without the --ssttdd flag.

   EExxiitt SSttaattuuss
       The ‘.Ex’ macro generates text for use in the “Diagnostics” section.

             UUssaaggee:: ..EExx [-std] [⟨utility⟩ ...]

       For example, ‘.Ex -std cat’ produces:

             The ccaatt utility exits 0 on success, and >0 if an error occurs.

       The --ssttdd option is valid only for manual page  sections  1,  6  and  8.
       Currently, this macro does nothing if used without the --ssttdd flag.

   IInntteerraaccttiivvee CCoommmmaannddss
       The ‘.Ic’ macro designates an interactive or internal command.

             UUssaaggee:: ..IIcc ⟨argument⟩ ...

                      ..IIcc ::wwqq                ::wwqq
                      ..IIcc ""ddoo wwhhiillee {{......}}""   ddoo wwhhiillee {{......}}
                      ..IIcc sseetteennvv ,, uunnsseetteennvv  sseetteennvv, uunnsseetteennvv

       The default width is 12n.

   LLiibbrraarryy NNaammeess
       The ‘.Lb’ macro is used to specify the library where a particular func‐
       tion is compiled in.

             UUssaaggee:: ..LLbb ⟨argument⟩ ...

       Available arguments to ‘.Lb’ and their results are:

             lliibbaarrcchhiivvee     Reading  and  Writing  Streaming  Archives Library
                            (libarchive, -larchive)
             lliibbaarrmm         ARM Architecture Library (libarm, -larm)
             lliibbaarrmm3322       ARM32 Architecture Library (libarm32, -larm32)
             lliibbbblluueettooootthh   Bluetooth Library (libbluetooth, -lbluetooth)
             lliibbbbssmm         Basic Security Module Library (libbsm, -lbsm)
             lliibbcc           Standard C Library (libc, -lc)
             lliibbcc__rr         Reentrant C Library (libc_r, -lc_r)
             lliibbccaalleennddaarr    Calendar    Arithmetic    Library    (libcalendar,
                            -lcalendar)
             lliibbccaamm         Common Access Method User Library (libcam, -lcam)
             lliibbccddkk         Curses Development Kit Library (libcdk, -lcdk)
             lliibbcciipphheerr      FreeSec Crypt Library (libcipher, -lcipher)
             lliibbccoommppaatt      Compatibility Library (libcompat, -lcompat)
             lliibbccrryypptt       Crypt Library (libcrypt, -lcrypt)
             lliibbccuurrsseess      Curses Library (libcurses, -lcurses)
             lliibbddeevviinnffoo     Device  and  Resource  Information Utility Library
                            (libdevinfo, -ldevinfo)
             lliibbddeevvssttaatt     Device Statistics Library (libdevstat, -ldevstat)
             lliibbddiisskk        Interface to Slice and  Partition  Labels  Library
                            (libdisk, -ldisk)
             lliibbddwwaarrff       DWARF Access Library (libdwarf, -ldwarf)
             lliibbeeddiitt        Command Line Editor Library (libedit, -ledit)
             lliibbeellff         ELF Access Library (libelf, -lelf)
             lliibbeevveenntt       Event Notification Library (libevent, -levent)
             lliibbffeettcchh       File Transfer Library for URLs (libfetch, -lfetch)
             lliibbffoorrmm        Curses Form Library (libform, -lform)
             lliibbggeeoomm        Userland  API  Library  for  kernel GEOM subsystem
                            (libgeom, -lgeom)
             lliibbggppiibb        General‐Purpose  Instrument  Bus  (GPIB)   library
                            (libgpib, -lgpib)
             lliibbii338866        i386 Architecture Library (libi386, -li386)
             lliibbiinnttll        Internationalized    Message    Handling   Library
                            (libintl, -lintl)
             lliibbiippsseecc       IPsec Policy Control Library (libipsec, -lipsec)
             lliibbiippxx         IPX Address Conversion  Support  Library  (libipx,
                            -lipx)
             lliibbiissccssii       iSCSI protocol library (libiscsi, -liscsi)
             lliibbjjaaiill        Jail Library (libjail, -ljail)
             lliibbkkiiccoonnvv      Kernel side iconv library (libkiconv, -lkiconv)
             lliibbkkssee         N:M Threading Library (libkse, -lkse)
             lliibbkkvvmm         Kernel Data Access Library (libkvm, -lkvm)
             lliibbmm           Math Library (libm, -lm)
             lliibbmm6688kk        m68k Architecture Library (libm68k, -lm68k)
             lliibbmmaaggiicc       Magic   Number   Recognition   Library  (libmagic,
                            -lmagic)
             lliibbmmdd          Message Digest (MD4, MD5,  etc.)  Support  Library
                            (libmd, -lmd)
             lliibbmmeemmssttaatt     Kernel   Memory   Allocator   Statistics   Library
                            (libmemstat, -lmemstat)
             lliibbmmeennuu        Curses Menu Library (libmenu, -lmenu)
             lliibbnneettggrraapphh    Netgraph User Library (libnetgraph, -lnetgraph)
             lliibbnneettppggpp      Netpgp  signing,  verification,   encryption   and
                            decryption (libnetpgp, -lnetpgp)
             lliibboossssaauuddiioo    OSS    Audio   Emulation   Library   (libossaudio,
                            -lossaudio)
             lliibbppaamm         Pluggable Authentication Module  Library  (libpam,
                            -lpam)
             lliibbppccaapp        Packet Capture Library (libpcap, -lpcap)
             lliibbppccii         PCI Bus Access Library (libpci, -lpci)
             lliibbppmmcc         Performance Counters Library (libpmc, -lpmc)
             lliibbppoossiixx       POSIX Compatibility Library (libposix, -lposix)
             lliibbpprroopp        Property   Container   Object   Library  (libprop,
                            -lprop)
             lliibbpptthhrreeaadd     POSIX Threads Library (libpthread, -lpthread)
             lliibbppuuffffss       puffs Convenience Library (libpuffs, -lpuffs)
             lliibbrreeffuussee      File  System  in  Userspace  Convenience   Library
                            (librefuse, -lrefuse)
             lliibbrreessoollvv      DNS Resolver Library (libresolv, -lresolv)
             lliibbrrppccsseecc__ggssss  RPC GSS‐API Authentication Library (librpcsec_gss,
                            -lrpcsec_gss)
             lliibbrrppccssvvcc      RPC Service Library (librpcsvc, -lrpcsvc)
             lliibbrrtt          POSIX Real‐time Library (librt, -lrt)
             lliibbssddpp         Bluetooth  Service Discovery Protocol User Library
                            (libsdp, -lsdp)
             lliibbsssspp         Buffer Overflow Protection Library (libssp, -lssp)
             lliibbSSyysstteemm      System Library (libSystem, -lSystem)
             lliibbtteerrmmccaapp     Termcap Access Library (libtermcap, -ltermcap)
             lliibbtteerrmmiinnffoo    Terminal   Information    Library    (libterminfo,
                            -lterminfo)
             lliibbtthhrr         1:1 Threading Library (libthr, -lthr)
             lliibbuuffss         UFS File System Access Library (libufs, -lufs)
             lliibbuuggiiddffww      File System Firewall Interface Library (libugidfw,
                            -lugidfw)
             lliibbuulloogg        User Login Record Library (libulog, -lulog)
             lliibbuussbbhhiidd      USB  Human  Interface  Devices Library (libusbhid,
                            -lusbhid)
             lliibbuuttiill        System Utilities Library (libutil, -lutil)
             lliibbvvggll         Video Graphics Library (libvgl, -lvgl)
             lliibbxx8866__6644      x86_64 Architecture Library (libx86_64, -lx86_64)
             lliibbzz           Compression Library (libz, -lz)

       Site‐specific additions might be found in the file _m_d_o_c_._l_o_c_a_l; see sec‐
       tion “Files” below.

       In a section titled “Library”, ‘Lb’ causes a break before and after its
       arguments.

   LLiitteerraallss
       The ‘Li’ literal macro may be used  for  special  characters,  symbolic
       constants,  and other syntactical items that should be typed exactly as
       displayed.

             UUssaaggee:: ..LLii ⟨argument⟩ ...

                      ..LLii \\eenn          \\nn
                      ..LLii MM11 MM22 MM33 ;;   MM11 MM22 MM33;
                      ..LLii ccnnttrrll--DD )) ,,  ccnnttrrll‐‐DD),
                      ..LLii 11002244 ......     11002244 ......

       The default width is 16n.

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

                      ..NNmm ggrrooffff__mmddoocc  ggrrooffff__mmddoocc
                      ..NNmm             ggrrooffff__mmddoocc
                      ..NNmm \\--mmddoocc      --mmddoocc
                      ..NNmm ffoooo )) )) ,,   ffoooo)),
                      ..NNmm ::           ggrrooffff__mmddoocc:

       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.

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

             UUssaaggee:: ..OOpp [⟨option⟩] ...

                      ..OOpp                                []
                      ..OOpp FFll kk                           [--kk]
                      ..OOpp FFll kk )) ..                       [--kk]).
                      ..OOpp FFll kk AArr kkooookkffiillee               [--kk _k_o_o_k_f_i_l_e]
                      ..OOpp FFll kk AArr kkooookkffiillee ,,             [--kk _k_o_o_k_f_i_l_e],
                      ..OOpp AArr oobbjjffiill OOpp AArr ccoorrffiill         [_o_b_j_f_i_l [_c_o_r_f_i_l]]
                      ..OOpp FFll cc AArr oobbjjffiill OOpp AArr ccoorrffiill ,,  [--cc _o_b_j_f_i_l [_c_o_r_f_i_l]],
                      ..OOpp wwoorrdd11 wwoorrdd22                    [word1 word2]
                      ..LLii ..OOpp OOoo AAoo ooppttiioonn AAcc OOcc ......     ..OOpp [⟨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:

             [[--kk _k_i_l_o_b_y_t_e_s] [--ii _i_n_t_e_r_v_a_l] [--cc _c_o_u_n_t]]

       The  default  width  values of ‘.Op’ and ‘.Oo’ are 14n and 10n, respec‐
       tively.

   PPaatthhnnaammeess
       The ‘.Pa’ macro formats file specifications.  If called  without  argu‐
       ments,  ‘_~’  (recognized  by  many  shells) is output, representing the
       user’s home directory.

             UUssaaggee:: ..PPaa [⟨pathname⟩] ...

                      ..PPaa                    _~
                      ..PPaa //uussrr//sshhaarree         _/_u_s_r_/_s_h_a_r_e
                      ..PPaa //ttmmpp//ffooooXXXXXXXXXX )) ..  _/_t_m_p_/_f_o_o_X_X_X_X_X).

       The default width is 32n.

   SSttaannddaarrddss
       The ‘.St’ macro  replaces  standard  abbreviations  with  their  formal
       names.

             UUssaaggee:: ..SStt ⟨abbreviation⟩ ...

       Available pairs for “Abbreviation/Formal Name” are:

       ANSI/ISO C

             --aannssiiCC          ANSI X3.159‐1989 (“ANSI C89”)
             --aannssiiCC--8899       ANSI X3.159‐1989 (“ANSI C89”)
             --iissooCC           ISO/IEC 9899:1990 (“ISO C90”)
             --iissooCC--9900        ISO/IEC 9899:1990 (“ISO C90”)
             --iissooCC--9999        ISO/IEC 9899:1999 (“ISO C99”)
             --iissooCC--22001111      ISO/IEC 9899:2011 (“ISO C11”)

       POSIX Part 1: System API

             --iissoo99994455--11--9900   ISO/IEC 9945‐1:1990 (“POSIX.1”)
             --iissoo99994455--11--9966   ISO/IEC 9945‐1:1996 (“POSIX.1”)
             --pp11000033..11        IEEE Std 1003.1 (“POSIX.1”)
             --pp11000033..11--8888     IEEE Std 1003.1‐1988 (“POSIX.1”)
             --pp11000033..11--9900     ISO/IEC 9945‐1:1990 (“POSIX.1”)
             --pp11000033..11--9966     ISO/IEC 9945‐1:1996 (“POSIX.1”)
             --pp11000033..11bb--9933    IEEE Std 1003.1b‐1993 (“POSIX.1”)
             --pp11000033..11cc--9955    IEEE Std 1003.1c‐1995 (“POSIX.1”)
             --pp11000033..11gg--22000000  IEEE Std 1003.1g‐2000 (“POSIX.1”)
             --pp11000033..11ii--9955    IEEE Std 1003.1i‐1995 (“POSIX.1”)
             --pp11000033..11--22000011   IEEE Std 1003.1‐2001 (“POSIX.1”)
             --pp11000033..11--22000044   IEEE Std 1003.1‐2004 (“POSIX.1”)
             --pp11000033..11--22000088   IEEE Std 1003.1‐2008 (“POSIX.1”)

       POSIX Part 2: Shell and Utilities

             --iissoo99994455--22--9933   ISO/IEC 9945‐2:1993 (“POSIX.2”)
             --pp11000033..22        IEEE Std 1003.2 (“POSIX.2”)
             --pp11000033..22--9922     IEEE Std 1003.2‐1992 (“POSIX.2”)
             --pp11000033..22aa--9922    IEEE Std 1003.2a‐1992 (“POSIX.2”)

       X/Open

             --ssuussvv11          Version   1  of  the  Single  UNIX  Specification
                             (“SUSv1”)
             --ssuussvv22          Version  2  of  the  Single  UNIX   Specification
                             (“SUSv2”)
             --ssuussvv33          Version   3  of  the  Single  UNIX  Specification
                             (“SUSv3”)
             --ssuussvv44          Version  4  of  the  Single  UNIX   Specification
                             (“SUSv4”)
             --ssvviidd44          System  V  Interface  Definition,  Fourth Edition
                             (“SVID4”)
             --xxbbdd55           X/Open Base Definitions Issue 5 (“XBD5”)
             --xxccuu55           X/Open Commands and Utilities Issue 5 (“XCU5”)
             --xxccuurrsseess44..22     X/Open Curses Issue 4, Version 2 (“XCURSES4.2”)
             --xxnnss55           X/Open Networking Services Issue 5 (“XNS5”)
             --xxnnss55..22         X/Open Networking Services Issue 5.2 (“XNS5.2”)
             --xxppgg33           X/Open Portability Guide Issue 3 (“XPG3”)
             --xxppgg44           X/Open Portability Guide Issue 4 (“XPG4”)
             --xxppgg44..22         X/Open  Portability  Guide  Issue  4,  Version  2
                             (“XPG4.2”)
             --xxsshh55           X/Open  System  Interfaces  and  Headers  Issue 5
                             (“XSH5”)

       Miscellaneous

             --iieeeeee775544        IEEE Std 754‐1985
             --iissoo88660011        ISO 8601
             --iissoo88880022--33      ISO/IEC 8802‐3:1989

   VVaarriiaabbllee TTyyppeess
       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).

             UUssaaggee:: ..VVtt ⟨type⟩ ...

                      ..VVtt eexxtteerrnn cchhaarr **ooppttaarrgg ;;  _e_x_t_e_r_n _c_h_a_r _*_o_p_t_a_r_g;
                      ..VVtt FFIILLEE **                 _F_I_L_E _*

   VVaarriiaabblleess
       Generic variable reference.

             UUssaaggee:: ..VVaa ⟨variable⟩ ...

                      ..VVaa ccoouunntt             _c_o_u_n_t
                      ..VVaa sseettttiimmeerr ,,        _s_e_t_t_i_m_e_r,
                      ..VVaa ""iinntt **pprrtt"" )) ::    _i_n_t _*_p_r_t):
                      ..VVaa ""cchhaarr ss"" ]] )) )) ,,  _c_h_a_r _s])),

       The default width is 12n.

   MMaannuuaall PPaaggee CCrroossss RReeffeerreenncceess
       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.

             UUssaaggee:: ..XXrr ⟨man page name⟩ [⟨section⟩] ...

                      ..XXrr mmddoocc        _m_d_o_c
                      ..XXrr mmddoocc ,,      _m_d_o_c,
                      ..XXrr mmddoocc 77      _m_d_o_c(7)
                      ..XXrr xxiinniitt 11xx ;;  _x_i_n_i_t(1x);

       The default width is 10n.

GGeenneerraall tteexxtt ddoommaaiinn
   AATT&&TT MMaaccrroo
             UUssaaggee:: ..AAtt [⟨version⟩] ...

                      ..AAtt       AT&T UNIX
                      ..AAtt vv66 ..  Version 6 AT&T UNIX.

       The following values for ⟨version⟩ are possible:

             3322vv,, vv11,, vv22,, vv33,, vv44,, vv55,, vv66,, vv77,, IIIIII,, VV,, VV..11,, VV..22,, VV..33,, VV..44

   BBSSDD MMaaccrroo
             UUssaaggee:: ..BBxx {-alpha | -beta | -devel} ...
                    ..BBxx [⟨version⟩ [⟨release⟩]] ...

                      ..BBxx         BSD
                      ..BBxx 44..33 ..   4.3BSD.
                      ..BBxx --ddeevveell  BSD (currently under development)

       ⟨version⟩ will be prepended to the string ‘BSD’.  The following  values
       for ⟨release⟩ are possible:

             RReennoo,, rreennoo,, TTaahhooee,, ttaahhooee,, LLiittee,, lliittee,, LLiittee22,, lliittee22

   NNeettBBSSDD MMaaccrroo
             UUssaaggee:: ..NNxx [⟨version⟩] ...

                      ..NNxx        NetBSD
                      ..NNxx 11..44 ..  NetBSD 1.4.

       For  possible values of ⟨version⟩ see the description of the ‘.Os’ com‐
       mand above in section “Title macros”.

   FFrreeeeBBSSDD MMaaccrroo
             UUssaaggee:: ..FFxx [⟨version⟩] ...

                      ..FFxx        FreeBSD
                      ..FFxx 22..22 ..  FreeBSD 2.2.

       For possible values of ⟨version⟩ see the description of the ‘.Os’  com‐
       mand above in section “Title macros”.

   DDrraaggoonnFFllyy MMaaccrroo
             UUssaaggee:: ..DDxx [⟨version⟩] ...

                      ..DDxx        DragonFly
                      ..DDxx 11..44 ..  DragonFly 1.4.

       For  possible values of ⟨version⟩ see the description of the ‘.Os’ com‐
       mand above in section “Title macros”.

   OOppeennBBSSDD MMaaccrroo
             UUssaaggee:: ..OOxx [⟨version⟩] ...

                      ..OOxx 11..00  OpenBSD 1.0

   BBSSDD//OOSS MMaaccrroo
             UUssaaggee:: ..BBssxx [⟨version⟩] ...

                      ..BBssxx 11..00  BSD/OS 1.0

   UUnniixx MMaaccrroo
             UUssaaggee:: ..UUxx ......

                      ..UUxx  Unix

   EEmmpphhaassiiss MMaaccrroo
       Text may be stressed or emphasized with the  ‘.Em’  macro.   The  usual
       font for emphasis is italic.

             UUssaaggee:: ..EEmm ⟨argument⟩ ...

                      ..EEmm ddooeess nnoott          _d_o_e_s _n_o_t
                      ..EEmm eexxcceeeedd 11002244 ..     _e_x_c_e_e_d _1_0_2_4.
                      ..EEmm vviiddee iinnffrraa )) )) ,,  _v_i_d_e _i_n_f_r_a)),

       The default width is 10n.

   FFoonntt MMooddee
       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:

             ..BBff ⟨font mode⟩

       ⟨font mode⟩ must be one of the following three types:

             EEmm | --eemmpphhaassiiss  Same as if the ‘.Em’ macro was used for  the  en‐
                             tire block of text.
             LLii | --lliitteerraall   Same  as  if the ‘.Li’ macro was used for the en‐
                             tire block of text.
             SSyy | --ssyymmbboolliicc  Same as if the ‘.Sy’ macro was used for  the  en‐
                             tire block of text.

       Both macros are neither callable nor parsed.

   EEnncclloossuurree aanndd QQuuoottiinngg MMaaccrrooss
       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.

       QQuuoottee   OOppeenn   CClloossee   FFuunnccttiioonn                  RReessuulltt
       .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.

       ..EEoo, ..EEcc  These  macros expect the first argument to be the opening and
                 closing strings, respectively.

       ..EEss, ..EEnn  To work around the nine‐argument limit in the original  _t_r_o_f_f
                 program,  _m_d_o_c  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.

       ..EEqq       The  first and second arguments of this macro are the opening
                 and closing strings respectively, followed by  the  arguments
                 to be enclosed.

       ..QQll       The  quoted  literal  macro  behaves differently in _t_r_o_f_f and
                 _n_r_o_f_f modes.  If formatted with _n_r_o_f_f(1), a quoted literal is
                 always quoted.  If formatted with  _t_r_o_f_f,  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.

       ..PPff       The prefix macro suppresses the whitespace between its  first
                 and second argument:

                       ..PPff (( FFaa nnaammee22  (_n_a_m_e_2

                 The default width is 12n.

                 The  ‘.Ns’  macro  (see  below) performs the analogous suffix
                 function.

       ..AApp       The ‘.Ap’ macro inserts an apostrophe and exits  any  special
                 text modes, continuing in ‘.No’ mode.

       Examples of quoting:

             ..AAqq                      ⟨⟩
             ..AAqq PPaa ccttyyppee..hh )) ,,       ⟨_c_t_y_p_e_._h⟩),
             ..BBqq                      []
             ..BBqq EEmm GGrreeeekk ,, FFrreenncchh ..  [_G_r_e_e_k, _F_r_e_n_c_h].
             ..DDqq                      “”
             ..DDqq ssttrriinngg aabbcc ..         “string abc”.
             ..DDqq ''\\[[hhaa]][[AA--ZZ]]''         “’^[A‐Z]’”
             ..QQll mmaann mmddoocc             ‘man mdoc’
             ..QQqq                      ""
             ..QQqq ssttrriinngg )) ,,           "string"),
             ..QQqq ssttrriinngg NNss )),,         "string),"
             ..SSqq                      ‘’
             ..SSqq ssttrriinngg               ‘string’
             ..EEmm oorr AApp iinngg            _o_r’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.

   NNoorrmmaall tteexxtt mmaaccrroo
       ‘No’ formats subsequent argument(s) normally, ending the effect of ‘Em’
       and similar.  Parsing is _n_o_t suppressed, so you must prefix words  like
       ‘No’ with ‘\&’ to avoid their interpretation as _m_d_o_c macros.

             UUssaaggee:: ..NNoo _a_r_g_u_m_e_n_t ...

                      ..EEmm UUssee ccaauuttiioonn NNoo hheerree ..  → _U_s_e _c_a_u_t_i_o_n here.
                      ..EEmm NNoo ddooggss aalllloowweedd ..      → _N_o dogs allowed.
                      ..EEmm \\&&NNoo ddooggss aalllloowweedd ..    → _N_o _d_o_g_s _a_l_l_o_w_e_d.

       The default width is 12n.

   NNoo‐‐SSppaaccee MMaaccrroo
       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:

             UUssaaggee:: ...... ⟨argument⟩ Ns [⟨argument⟩] ...
                    ..NNss ⟨argument⟩ ...

                      ..OOpp FFll II NNss AArr ddiirreeccttoorryy  [--II_d_i_r_e_c_t_o_r_y]

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

   ((SSuubb))sseeccttiioonn ccrroossss rreeffeerreenncceess
       Use  the  ‘.Sx’  macro  to cite a (sub)section heading within the given
       document.

             UUssaaggee:: ..SSxx ⟨section‐reference⟩ ...

                      ..SSxx FFiilleess  → “Files”

       The default width is 16n.

   SSyymmbboolliiccss
       The symbolic emphasis macro is generally a boldface macro in either the
       symbolic sense or the traditional English usage.

             UUssaaggee:: ..SSyy ⟨symbol⟩ ...

                      ..SSyy IImmppoorrttaanntt NNoottiiccee  → IImmppoorrttaanntt NNoottiiccee

       The default width is 6n.

   MMaatthheemmaattiiccaall SSyymmbboollss
       Use this macro for mathematical symbols and similar things.

             UUssaaggee:: ..MMss ⟨math symbol⟩ ...

                      ..MMss ssiiggmmaa  → ssiiggmmaa

       The default width is 6n.

   RReeffeerreenncceess aanndd CCiittaattiioonnss
       The following macros make a modest attempt to  handle  references.   At
       best,  the  macros  make  it convenient to manually drop in a subset of
       _r_e_f_e_r(1) style references.

             ..RRss     Reference 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.
             ..RRee     Reference  end  (does not take arguments).  The reference
                     is printed.
             ..%%AA     Reference author name; one name per invocation.
             ..%%BB     Book title.
             ..%%CC     City/place.
             ..%%DD     Date.
             ..%%II     Issuer/publisher name.
             ..%%JJ     Journal name.
             ..%%NN     Issue number.
             ..%%OO     Optional information.
             ..%%PP     Page number.
             ..%%QQ     Corporate or foreign author.
             ..%%RR     Report name.
             ..%%TT     Title of article.
             ..%%UU     Optional hypertext reference.
             ..%%VV     Volume.

       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, _I_m_p_l_e_m_e_n_t_a_t_i_o_n _N_o_t_e_s _o_n _f_o_o_b_a_r_(_1_),
             Technical Report ABC‐DE‐12‐345, Drofnats College, Nowhere, April
             1991.

   TTrraaddee NNaammeess oorr AAccrroonnyymmss
       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.

             UUssaaggee:: ..TTnn ⟨symbol⟩ ...

                      ..TTnn DDEECC    DEC
                      ..TTnn AASSCCIIII  ASCII

       The default width is 10n.

   EExxtteennddeedd AArrgguummeennttss
       The ..XXoo and ..XXcc macros allow one to extend an argument list on a  macro
       boundary  for  the  ‘.It’ macro (see below).  Note that ..XXoo and ..XXcc are
       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

             II_o_p_e_r_a_t_i_o_n\n_c_o_u_n_t\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

             SS/_o_l_d___p_a_t_t_e_r_n/_n_e_w___p_a_t_t_e_r_n/[gg]

       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

             ..iiffnnddeeff [!]_v_a_r_i_a_b_l_e [_o_p_e_r_a_t_o_r _v_a_r_i_a_b_l_e ...]

PPaaggee ssttrruuccttuurree ddoommaaiinn
   SSeeccttiioonn hheeaaddiinnggss
       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.

       ..SShh NNaammee           The ‘.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  _N_a_m_e  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.

       ..SShh LLiibbrraarryy        This  section  is for section two and three function
                          calls.  It should consist of a  single  ‘.Lb’  macro
                          call; see “Library Names”.

       ..SShh SSyynnooppssiiss       The  “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:

                                ccaatt [--bbeennssttuuvv] [--] _f_i_l_e ...

                          The following macros were used:

                                ..NNmm ccaatt
                                ..OOpp FFll bbeennssttuuvv
                                ..OOpp FFll
                                ..AArr ffiillee NNoo ......

       ..SShh DDeessccrriippttiioonn    In 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).

       ..SShh IImmpplleemmeennttaattiioonn nnootteess
                          Implementation specific information should be placed
                          here.

       ..SShh RReettuurrnn vvaalluueess  Sections 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.

       ..SShh EEnnvviirroonnmmeenntt    The _E_n_v_i_r_o_n_m_e_n_t section should  reveal  any  related
                          environment  variables  and  clues to their behavior
                          and/or usage.

       ..SShh FFiilleess          Files which are used or created by the man page sub‐
                          ject should be listed via the  ‘.Pa’  macro  in  the
                          “Files” section.

       ..SShh EExxaammpplleess       There are several ways to create examples.  See sub‐
                          section “Examples and Displays” below for details.

       ..SShh DDiiaaggnnoossttiiccss    Diagnostic  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”.

       ..SShh CCoommppaattiibbiilliittyy  Known  compatibility issues (e.g. deprecated options
                          or parameters) should be listed here.

       ..SShh EErrrroorrss         Specific 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).

       ..SShh SSeeee aallssoo       References  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 _r_e_f_e_r(1) style references are not accommo‐
                          dated.

                          It  is  recommended  that  the  cross  references be
                          sorted by section  number,  then  alphabetically  by
                          name  within each section, then separated by commas.
                          Example:

                          _l_s(1), _p_s(1), _g_r_o_u_p(5), _p_a_s_s_w_d(5)

       ..SShh SSttaannddaarrddss      If 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 _H_i_s_t_o_r_y section.

       ..SShh HHiissttoorryy        Any  command  which  does not adhere to any specific
                          standards should be outlined  historically  in  this
                          section.

       ..SShh AAuutthhoorrss        Credits  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.

       ..SShh BBuuggss           Blatant problems with the topic go here.

       User‐specified  ‘.Sh’  sections may be added; for example, this section
       was set with:

                      .Sh "Page structure domain"

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

   PPaarraaggrraapphhss aanndd LLiinnee SSppaacciinngg
       ..PPpp  The ‘.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 --ccoommppaacctt flag is given).

            The  macro  is neither callable nor parsed and takes no arguments;
            an alternative name is ‘.Lp’.

   KKeeeeppss
       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 --wwoorrddss (also the  default);  this  pre‐
       vents  breaks  in  the middle of options.  In the example for mmaakkee com‐
       mand‐line arguments (see “What’s in a Name”), the keep  prevents  _n_r_o_f_f
       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 --lliinnee
       option should be added.

   EExxaammpplleess aanndd DDiissppllaayyss
       There are seven types of displays.

       ..DD11  (This is D‐one.)  Display one line of indented text.   This  macro
            is parsed but not callable.

                  --llddgghhffssttrruu

            The above was produced by: ..DD11 FFll llddgghhffssttrruu.

       ..DDll  (This  is D‐ell.)  Display one line of indented _l_i_t_e_r_a_l 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.

                  %% llss --llddgg //uussrr//llooccaall//bbiinn

            The above was produced by: ..DDll %% llss \\--llddgg //uussrr//llooccaall//bbiinn.

       ..BBdd  Begin display.  The ‘.Bd’ display must be  ended  with  the  ‘.Ed’
            macro.  It has the following syntax:

                  ..BBdd {-literal | -filled | -unfilled | -ragged | -centered}
                       [-offset ⟨string⟩] [-file ⟨file name⟩] [-compact]

            --rraaggggeedd            Fill,  but do not adjust the right margin (only
                               left‐justify).
            --cceenntteerreedd          Center lines between the current left and right
                               margin.  Note that each  single  line  is  cen‐
                               tered.
            --uunnffiilllleedd          Do  not  fill;  break  lines  where their input
                               lines are broken.  This  can  produce  overlong
                               lines without warning messages.
            --ffiilllleedd            Display  a  filled block.  The block of text is
                               formatted (i.e., the text is justified on  both
                               the left and right side).
            --lliitteerraall           Display block with literal font (usually fixed‐
                               width).   Useful  for  source  code  or  simple
                               tabbed or spaced text.
            --ffiillee ⟨_f_i_l_e _n_a_m_e⟩  The file whose name follows the --ffiillee  flag  is
                               read  and  displayed  before  any data enclosed
                               with ‘.Bd’ and ‘.Ed’, using the  selected  dis‐
                               play type.  Any _t_r_o_f_f_/_m_d_o_c commands in the file
                               will be processed.
            --ooffffsseett ⟨_s_t_r_i_n_g⟩   If --ooffffsseett is 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:

                               _l_e_f_t        Align  block  on  the  current left
                                           margin; this is the default mode of
                                           ‘.Bd’.
                               _c_e_n_t_e_r      Supposedly center  the  block.   At
                                           this  time unfortunately, the block
                                           merely gets left aligned  about  an
                                           imaginary center margin.
                               _i_n_d_e_n_t      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).
                               _i_n_d_e_n_t_-_t_w_o  Indent two times the default indent
                                           value.
                               _r_i_g_h_t       This  _l_e_f_t  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 _t_r_o_f_f.

                               If  ⟨string⟩  is a valid numeric expression in‐
                               stead (_w_i_t_h  _a  _s_c_a_l_i_n_g  _i_n_d_i_c_a_t_o_r  _o_t_h_e_r  _t_h_a_n
                               ‘_u’), use that value for indentation.  The most
                               useful  scaling  indicators  are  ‘m’  and ‘n’,
                               specifying the  so‐called  _E_m  and  _E_n  _s_q_u_a_r_e.
                               This  is approximately the width of the letters
                               ‘m’ and ‘n’ respectively of  the  current  font
                               (for _n_r_o_f_f output, both scaling indicators give
                               the  same values).  If ⟨string⟩ isn’t a numeric
                               expression, it is tested whether it is an  _m_d_o_c
                               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.
            --ccoommppaacctt           Suppress insertion of vertical space before be‐
                               gin of display.

       ..EEdd  End display (takes no arguments).

   LLiissttss aanndd CCoolluummnnss
       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 (--ttaagg).

       It has the following syntax forms:

             ..BBll {-hang | -ohang | -tag | -diag | -inset} [-width ⟨string⟩]
                  [-offset ⟨string⟩] [-compact]
             ..BBll -column [-offset ⟨string⟩] ⟨string1⟩ ⟨string2⟩ ...
             ..BBll {-item | -enum [-nested] | -bullet | -hyphen | -dash}
                  [-offset ⟨string⟩] [-compact]

       And now a detailed description of the list types.

       --bbuulllleett  A bullet list.

                      .Bl -bullet -offset indent -compact
                      .It
                      Bullet one goes here.
                      .It
                      Bullet two here.
                      .El

                Produces:

                      ••   Bullet one goes here.
                      ••   Bullet two here.

       --ddaasshh (or --hhyypphheenn)
                A dash list.

                      .Bl -dash -offset indent -compact
                      .It
                      Dash one goes here.
                      .It
                      Dash two here.
                      .El

                Produces:

                      --   Dash one goes here.
                      --   Dash two here.

       --eennuumm    An 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 --nneesstteedd flag
                (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.

       --iitteemm    A list of type --iitteemm without 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.

       --ttaagg     A list with tags.  Use --wwiiddtthh to 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

       --ddiiaagg    Diag lists create section four diagnostic lists and are  simi‐
                lar  to  inset  lists except callable macros are ignored.  The
                --wwiiddtthh flag is not meaningful in this context.

                Example:

                      .Bl -diag
                      .It You can’t use Sy here.
                      The message says all.
                      .El

                produces

                YYoouu ccaann’’tt uussee SSyy hheerree..  The message says all.

       --hhaanngg    A list with hanging tags.

                      _H_a_n_g_e_d  labels appear similar to tagged lists  when  the
                              label is smaller than the label width.

                      _L_o_n_g_e_r  _h_a_n_g_e_d  _l_i_s_t _l_a_b_e_l_s 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

       --oohhaanngg   Lists with overhanging tags do not  use  indentation  for  the
                items; tags are written to a separate line.

                      SSLL
                      sleep time of the process (seconds blocked)

                      PPAAGGEEIINN
                      number  of disk I/O operations resulting from references
                      by the process to pages not loaded in core.

                      UUIIDD
                      numerical user‐id of process owner

                      PPPPIIDD
                      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

       --iinnsseett   Here is an example of inset labels:

                      _T_a_g The tagged list (also called a tagged paragraph)  is
                      the  most common type of list used in the Berkeley manu‐
                      als.  Use a --wwiiddtthh attribute as described below.

                      _D_i_a_g Diag lists create section four diagnostic lists and
                      are similar to inset lists except  callable  macros  are
                      ignored.

                      _H_a_n_g Hanged labels are a matter of taste.

                      _O_h_a_n_g  Overhanging  labels  are  nice when space is con‐
                      strained.

                      _I_n_s_e_t Inset labels are useful for controlling blocks  of
                      paragraphs  and are valuable for converting _m_d_o_c 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

       --ccoolluummnn  This list type generates  multiple  columns.   The  number  of
                columns  and the width of each column is determined by the ar‐
                guments to the --ccoolluummnn list, ⟨_s_t_r_i_n_g_1⟩,  ⟨_s_t_r_i_n_g_2⟩,  etc.   If
                ⟨_s_t_r_i_n_g_N⟩  starts  with  a ‘.’ (dot) immediately followed by a
                valid _m_d_o_c macro name, interpret ⟨_s_t_r_i_n_g_N⟩ and use  the  width
                of  the  result.   Otherwise,  the width of ⟨_s_t_r_i_n_g_N⟩ (typeset
                with a fixed‐width font) is taken as the _Nth 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:

                      SSttrriinngg    NNrrooffff    TTrrooffff
                      <<==        <=       ≤
                      >>==        >=       ≥

                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 _t_b_l(1), the table pre‐
                processor.

       Other keywords:

       --wwiiddtthh ⟨_s_t_r_i_n_g⟩   If ⟨_s_t_r_i_n_g⟩ starts with a ‘.’ (dot) immediately  fol‐
                         lowed  by a valid _m_d_o_c macro name, interpret ⟨_s_t_r_i_n_g⟩
                         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:

                         --tteesstt ⟨_s_t_r_i_n_g⟩  This is a longer sentence to show how
                                         the --wwiiddtthh flag works in  combination
                                         with a tag list.

                         (Note  that the current state of _m_d_o_c is saved before
                         ⟨_s_t_r_i_n_g⟩ is interpreted;  afterwards,  all  variables
                         are  restored again.  However, boxes (used for enclo‐
                         sures) can’t be saved in GNU _t_r_o_f_f(1);  as  a  conse‐
                         quence,  arguments  must  always be _b_a_l_a_n_c_e_d 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 ⟨_s_t_r_i_n_g⟩ is a valid numeric  expression
                         (_w_i_t_h  _a  _s_c_a_l_i_n_g _i_n_d_i_c_a_t_o_r _o_t_h_e_r _t_h_a_n ‘_u’), use that
                         value for indentation.  The most useful scaling indi‐
                         cators are ‘m’ and ‘n’, specifying the  so‐called  _E_m
                         and  _E_n  _s_q_u_a_r_e.   This is approximately the width of
                         the letters ‘m’ and ‘n’ respectively of  the  current
                         font  (for _n_r_o_f_f output, both scaling indicators give
                         the same values).  If ⟨_s_t_r_i_n_g⟩ isn’t  a  numeric  ex‐
                         pression,  it  is  tested whether it is an _m_d_o_c macro
                         name, and the default  width  value  associated  with
                         this  macro is used.  Finally, if all tests fail, the
                         width of ⟨_s_t_r_i_n_g⟩ (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.

       --ooffffsseett ⟨_s_t_r_i_n_g⟩  If ⟨_s_t_r_i_n_g⟩ is _i_n_d_e_n_t, a default indent  value  (nor‐
                         mally  set  to 6n, similar to the value used in ‘.Dl’
                         or ‘.Bd’) is used.  If ⟨_s_t_r_i_n_g⟩ is  a  valid  numeric
                         expression  instead  (_w_i_t_h  _a _s_c_a_l_i_n_g _i_n_d_i_c_a_t_o_r _o_t_h_e_r
                         _t_h_a_n ‘_u’), use that value for indentation.  The  most
                         useful scaling indicators are ‘m’ and ‘n’, specifying
                         the  so‐called  _E_m  and  _E_n _s_q_u_a_r_e.  This is approxi‐
                         mately the width of the letters ‘m’ and  ‘n’  respec‐
                         tively  of  the  current font (for _n_r_o_f_f output, both
                         scaling  indicators  give  the  same   values).    If
                         ⟨_s_t_r_i_n_g⟩  isn’t  a  numeric  expression, it is tested
                         whether it is an _m_d_o_c macro  name,  and  the  default
                         offset value associated with this macro is used.  Fi‐
                         nally,  if  all  tests  fail,  the  width of ⟨_s_t_r_i_n_g⟩
                         (typeset with a fixed‐width font)  is  taken  as  the
                         offset.

       --ccoommppaacctt          Suppress  insertion of vertical space before the list
                         and between list items.

MMiisscceellllaanneeoouuss mmaaccrrooss
       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 _g_r_o_f_f_@_g_n_u_._o_r_g and include a  speci‐
       men with its provenance.

       ..BBtt  formats boilerplate text.

                  ..BBtt  → is currently in beta test.

            It is neither callable nor parsed and takes no arguments.  Its de‐
            fault width is 6n.

       ..FFrr  is an obsolete means of specifying a function return value.

                  Usage: .FFrr _r_e_t_u_r_n_‐_v_a_l_u_e ...

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

       ..HHff  Inlines the contents of a (header) file into the document.

                  Usage: .HHff _f_i_l_e

            It  first  prints ‘File:’ followed by the file name, then the con‐
            tents of _f_i_l_e.  It is neither callable nor parsed.

       ..LLkk  Embed hyperlink.

                  Usage: .LLkk _u_r_i [_l_i_n_k_‐_t_e_x_t]

            Its default width is 6n.

       ..MMee  Usage unknown.  The _m_d_o_c sources describe it as a macro for  “menu
            entries”.

            Its default width is 6n.

       ..MMtt  Embed email address.

                  Usage: .MMtt _e_m_a_i_l_‐_a_d_d_r_e_s_s

            Its default width is 6n.

       ..OOtt  Usage unknown.  The _m_d_o_c sources describe it as “old function type
            (fortran)”.

       ..SSmm  Manipulate or toggle argument‐spacing mode.

                  Usage: .SSmm [oonn | ooffff] ...

            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.

       ..UUdd  formats boilerplate text.

                  ..UUdd  → currently under development.

            It is neither callable nor parsed and takes no arguments.  Its de‐
            fault width is 8n.

PPrreeddeeffiinneedd ssttrriinnggss
       The following strings are predefined for compatibility with legacy _m_d_o_c
       documents.  Contemporary ones should use the alternatives shown in  the
       “Prefer”  column  below.   See  _g_r_o_f_f___c_h_a_r(7)  for a full discussion of
       these special character escape sequences.

       SSttrriinngg   77‐‐bbiitt     88‐‐bbiitt     UUCCSS   PPrreeffeerr   MMeeaanniinngg
       \*(<=    <=        <=        ≤     \(<=     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    _N_a_N       _N_a_N       _N_a_N   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, _m_d_o_c 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 _m_d_o_c 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.

DDiiaaggnnoossttiiccss
       The  debugging  macro ‘.Db’ offered by previous versions of _m_d_o_c is un‐
       available in GNU _t_r_o_f_f(1) since the latter provides  better  facilities
       to check parameters; additionally, _g_r_o_f_f _m_d_o_c 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.

OOppttiioonnss
       The  following  _g_r_o_f_f options set registers (with --rr) and strings (with
       --dd) recognized and used by the _m_d_o_c 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 _g_r_o_f_f’s ‘ad’ request may be used.  See _g_r_o_f_f(7) for less‐com‐
       mon choices.
             ggrrooffff --TTuuttff88 --ddAADD==ll --mmddoocc ggrrooffff__mmddoocc..77 | lleessss --RR

       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 _m_d_o_c 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 _g_r_o_f_f(1).
             ggrrooffff --TTllaattiinn11 --rrccRR==00 --mmddoocc ffoooo..mmaann >> ffoooo..ttxxtt
       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’.
             ggrrooffff --TTppss --rrDD11 --mmddoocc ffoooo..mmaann >> ffoooo..ppss

       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 _g_r_o_f_f’s ‘ft’ request may be used.

       Normally, automatic hyphenation is enabled using a mode appropriate  to
       the  _g_r_o_f_f  locale;  see section “Localization“ of _g_r_o_f_f(7).  It can be
       disabled by setting the ‘HY’ register to zero.
             ggrrooffff --TTuuttff88 --rrHHYY==00 --mmddoocc ffoooo..mmaann | lleessss --RR

       The paragraph and subsection heading indentation amounts can be changed
       by setting the registers ‘IN’ and ‘SN’.
             ggrrooffff --TTuuttff88 --rrIINN==55nn --rrSSNN==22nn --mmddoocc ffoooo..mmaann | lleessss --RR
       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:
             ggrrooffff --TTuuttff88 --rrLLLL==110000nn --rrLLTT==110000nn --mmddoocc ffoooo..mmaann | lleessss --RR
       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:
             ggrrooffff --TTddvvii --rrSS1111 --mmddoocc ffoooo..mmaann >> ffoooo..ddvvii
       Register ‘S’ is ignored when formatting for terminal devices.

       Setting the ‘X’ register to a page number _p numbers its  successors  as
       _paa, _pbb, _pcc, and so forth.  The register tracking the suffixed page let‐
       ter uses format ‘a’ (see the ‘af’ request in _g_r_o_f_f(7)).

FFiilleess
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_a_n_d_o_c_._t_m_a_c
               This  brief _g_r_o_f_f program detects whether the _m_a_n or _m_d_o_c 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 TTHH or DDdd, respectively, before any other  macros.   A
               user typing, for example,
                     ggrrooffff --mmaannddoocc ppaaggee..11
               need not know which package the file _p_a_g_e_._1 uses.  Multiple man
               pages,  in  either  format,  can be handled; _a_n_d_o_c_._t_m_a_c reloads
               each macro package as necessary.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_d_o_c_._t_m_a_c
               implements the bulk of the _g_r_o_f_f _m_d_o_c package and loads further
               components as needed from the _m_d_o_c subdirectory.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_m_d_o_c_._t_m_a_c
               is a wrapper that loads _d_o_c_._t_m_a_c.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_m_d_o_c_/_d_o_c_-_c_o_m_m_o_n
               defines macros, registers, and strings concerned with the  pro‐
               duction  of  formatted output.  It includes strings of the form
               ‘doc-volume-ds-_X’ and ‘doc-volume-as-_X’ for manual section  ti‐
               tles  and architecture identifiers, respectively, where _X is an
               argument recognized by .DDtt.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_m_d_o_c_/_d_o_c_-_n_r_o_f_f
               defines parameters appropriate for rendering  to  terminal  de‐
               vices.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_m_d_o_c_/_d_o_c_-_d_i_t_r_o_f_f
               defines  parameters appropriate for rendering to typesetter de‐
               vices.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_m_d_o_c_/_d_o_c_-_s_y_m_s
               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-_O--_V’,  ‘doc-str-St----_S--_I’  (observe  the  double
               dashes), or ‘doc-str-Lb-_L’, where _O is  one  of  the  operating
               system macros from section “General text domain” above, _V is an
               encoding  of  an  operating  system  release (sometimes omitted
               along with the ‘-’ preceding it), _S an identifier for  a  stan‐
               dards  body or committee, _I one for an issue of a standard pro‐
               mulgated by _S, and _L a keyword identifying a *BSD library.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_s_i_t_e_-_t_m_a_c_/_m_d_o_c_._l_o_c_a_l
               This file houses local  additions  and  customizations  to  the
               package.  It can be empty.

SSeeee aallssoo
       The _m_a_n_d_o_c: https://mandoc.bsd.lv/ project maintains an independent im‐
       plementation  of  the _m_d_o_c language and a renderer that directly parses
       its markup as well as that of _m_a_n.

       _g_r_o_f_f(1), _m_a_n(1), _t_r_o_f_f(1), _g_r_o_f_f___m_a_n(7), _m_d_o_c(7)

BBuuggss
       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 _g_r_o_f_f 1.23, ‘Tn’ no longer changes the type size; this  function‐
       ality may return in the next release.

groff 1.23.0                      3 June 2025                    _g_r_o_f_f___m_d_o_c(7)
───────────────────────────────────────────────────────────────────────────────
_g_r_o_f_f___m_e(7)            Miscellaneous Information Manual            _g_r_o_f_f___m_e(7)

NNaammee
       groff_me - “me” macro package for formatting _r_o_f_f documents

SSyynnooppssiiss
       ggrrooffff --mmee [_o_p_t_i_o_n ...] [_f_i_l_e ...]
       ggrrooffff --mm mmee [_o_p_t_i_o_n ...] [_f_i_l_e ...]

DDeessccrriippttiioonn
       The  GNU  implementation  of  the _m_e macro package is part of the _g_r_o_f_f
       document formatting system.  The _m_e package of  macro  definitions  for
       the  _r_o_f_f language provides a convenient facility for preparing techni‐
       cal papers in various formats.  This version is based on  the  _m_e  dis‐
       tributed  with  4.4BSD  and can be used with the GNU _t_r_o_f_f formatter as
       well as those descended from AT&T _t_r_o_f_f.

       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  llpp  or  pppp.
       Some  arguments are optional; see _g_r_o_f_f(7) for details, particularly of
       requests whose argument list is designated with an ellipsis.  An aster‐
       isk ** marks _g_r_o_f_f extensions.

       aadd _c       set text adjustment mode to _c
       aaff _r _f     assign format _f to register _r
       aamm _m _e     append to macro _m until _e called
       aass _s _t     append rest of line _t to string _s
       bbpp _n       begin new page numbered _n
       bbrr         break output line
       ccee _n       center next _n output lines
       ccpp _n       en‐/disable AT&T _t_r_o_f_f compatibility mode**
       ddee _m _e     define macro _m until _e called
       ddoo _t       interpret input _t with compatibility mode off**
       ddss _s _t     define rest of line _t as string _s
       eell _t       interpret _t if corresponding iiee false
       ffcc _c _d     set field delimiter _c and padding glyph _d
       ffii         enable filling
       hhcc _c       set hyphenation character to _c
       hhyy _m       set automatic hyphenation mode to _m
       iiee _p _t     as iiff, but enable interpretation of later eell
       iiff _p _t     if condition _p, interpret rest of line _t
       iinn _h       set indentation to distance _h
       llcc _c       set leader repetition glyph to _c
       llss _n       set line spacing to _n
       mmcc _c _h     set (right) margin glyph to _c at distance _h
       mmkk _r       mark vertical position in register _r
       nnaa         disable adjustment of text
       nnee _v       need vertical space of distance _v
       nnff         disable filling
       nnhh         disable automatic hyphenation
       nnrr _r _n _i   assign register _r value _n with auto‐increment _i
       nnss         begin no‐space mode
       ppll _v       set page length to _v
       ppnn _n       set next page number to _n
       ppoo _h       set page offset to _h
       rrjj _n       right‐align next _n output lines**
       rrmm _m       remove macro, string, or request _m
       rrnn _m _n     rename macro, string, or request _m to _n
       rrrr _r       remove register _r
       rrss         resume spacing (end no‐space mode)
       rrtt _v       return to vertical position set by mmkk, or _v
       ssoo _f       source (interpolate) input file _f
       sspp _n       insert _n lines of vertical space
       ttaa ...     set tab stops
       ttcc _c       set tab repetition glyph to _c
       ttii _h       set temporary indentation (next line only) to _h
       ttll ...     output three‐part title
       ttrr ...     translate characters
       uull _n       underline next _n output lines

       Except on title pages (produced by calling ttpp), _m_e suppresses the  out‐
       put  of  vertical  space  at the tops of pages (after the output of any
       page header); the sspp request will thus not work there.  You can instead
       call bbll or enclose the desired spacing request in a diversion, for  in‐
       stance  by  calling  ((bb and ))bb.  _m_e also intercepts the llll request; see
       the “_m_e Reference Manual” for details.

   NNaammee ssppaaccee
       Objects in _m_e 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
       _g_r_o_f_f _m_e, limit names to two characters, and avoid  the  name  [[  (left
       square  bracket).)   The  names  employed  by  any preprocessors in use
       should also not be repurposed.

   MMaaccrrooss
       $$00   post‐section heading hook
       $$11   pre‐section depth 1 hook
       $$22   pre‐section depth 2 hook
       $$33   pre‐section depth 3 hook
       $$44   pre‐section depth 4 hook
       $$55   pre‐section depth 5 hook
       $$66   pre‐section depth 6 hook
       $$CC   post‐chapter title hook
       $$HH   page/column heading hook
       $$cc   output chapter number and title
       $$ff   output footer
       $$hh   output header
       $$pp   output section heading
       $$ss   output footnote area separator
       ((bb   begin block
       ((cc   begin centered block
       ((dd   begin delayed text
       ((ff   begin footnote
       ((ll   begin list
       ((qq   begin long quotation
       ((xx   begin index entry
       ((zz   begin floating keep
       ))bb   end block
       ))cc   end centered block
       ))dd   end delayed text
       ))ff   end footnote
       ))ll   end list
       ))qq   end long quotation
       ))xx   end index entry
       ))zz   end floating keep
       ++++   set document segment type
       ++cc   begin chapter
       11cc   end multi‐column layout
       22cc   begin multi‐column layout
       EENN   end _e_q_n equation
       EEQQ   begin _e_q_n equation
       GGEE   end _g_r_n picture with drawing position at bottom
       GGFF   end _g_r_n picture with drawing position at top
       GGSS   start _g_r_n picture
       IIEE   end _i_d_e_a_l picture with drawing position at bottom
       IIFF   end _i_d_e_a_l picture with drawing position at top
       IISS   start _i_d_e_a_l picture
       PPEE   end _p_i_c picture with drawing position at bottom
       PPFF   end _p_i_c picture with drawing position at top
       PPSS   start _p_i_c picture
       TTEE   end _t_b_l table
       TTHH   end heading for multi‐page _t_b_l table
       TTSS   start _t_b_l table
       bb    embolden argument
       bbaa   set base indentation
       bbcc   begin new column
       bbii   embolden and italicize argument
       bbxx   box argument
       eeff   set even‐numbered page footer
       eehh   set even‐numbered page header
       eepp   end page
       ffoo   set footer
       hhee   set header
       hhll   draw horizontal line
       hhxx   suppress next page’s headers/footers
       ii    italicize argument
       iipp   begin indented paragraph
       lldd   reset localization and date registers and strings**
       llll   set line length
       llpp   begin fully left‐aligned paragraph
       nnpp   begin numbered paragraph
       ooff   set odd‐numbered page footer
       oohh   set odd‐numbered page header
       ppdd   output delayed text
       pppp   begin first‐line indented paragraph
       qq    quote argument
       rr    set argument in roman
       rree   reset tab stops
       sshh   begin numbered section
       ssmm   set argument at smaller type size
       ssxx   change section depth
       sszz   set type size and vertical spacing
       ttpp   begin title page
       uu    underline argument
       uuhh   begin unnumbered section
       xxll   set line length (local)
       xxpp   output index

       Some macros are provided for “old” _r_o_f_f(1) compatibility.  The “_m_e Ref‐
       erence Manual” describes alternatives for modern documents.

       aarr   use Arabic numerals for page numbers
       bbll   insert space (even at page top; cf. sspp)
       iixx   set indentation without break
       mm11   set page top to header distance
       mm22   set header to text distance
       mm33   set text to footer distance
       mm44   set footer to page bottom distance
       nn11   begin output line numbering
       nn22   end or alter output line numbering
       ppaa   begin page
       rroo   use Roman numerals for page numbers
       sskk   skip next page

   RReeggiisstteerrss
       $$00   section depth
       $$11   first section number component
       $$22   second section number component
       $$33   third section number component
       $$44   fourth section number component
       $$55   fifth section number component
       $$66   sixth section number component
       $$cc   current column number
       $$dd   delayed text number
       $$ff   footnote number
       $$ii   paragraph base indentation
       $$ll   column width
       $$mm   number of available columns
       $$pp   numbered paragraph number
       $$ss   column spacing (indentation)
       bbii   display (block) indentation
       bbmm   distance from text area to page bottom
       bbss   display (block) pre/post space
       bbtt   block threshold for keeps
       cchh   current chapter number
       ddff   display font
       ddvv   vertical spacing of displayed text (as percentage)**
       eess   equation pre/post space
       ffff   footnote font
       ffii   footnote indentation (first line only)
       ffmm   footer margin
       ffpp   footnote type size in points
       ffss   footnote prespace
       ffuu   footnote undent (right indentation)
       hhmm   header margin
       iiii   indented paragraph indentation
       nnoo   line numbering offset**
       ppff   paragraph font
       ppii   paragraph indentation
       ppoo   page offset
       pppp   paragraph type size in points
       ppss   paragraph prespace
       qqii   long quotation left/right indentation
       qqpp   long quotation type size in points
       qqss   long quotation pre/post space
       ssff   section title font
       ssii   section indentation per level of depth
       ssoo   additional section title offset
       sspp   section title type size in points
       ssss   section prespace
       ssxx   super/subscript line height increase**
       ttff   title font
       ttmm   distance from page top to text area
       ttpp   title type size in points
       ttvv   vertical spacing of text (as percentage)**
       xxss   index entry prespace
       xxuu   index undent (right indentation)
       yy22   year of the century**
       yy44   year**
       yyrr   year minus 1900
       zzss   floating keep pre/post space

   SSttrriinnggss
       ##    delayed text marker
       $$nn   concatenated section number
       **    footnote marker
       --    em dash
       <<    begin subscripting
       >>    end subscripting
       ddww   weekday name
       llqq   left double quotation mark
       mmoo   month name
       rrqq   right double quotation mark
       ttdd   date
       wwaa   term for “appendix” used by ..$$cc**
       wwcc   term for “chapter” used by ..$$cc**
       {{    begin superscripting
       }}    end superscripting

FFiilleess
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_e_._t_m_a_c
              implements the package.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_r_e_f_e_r_-_m_e_._t_m_a_c
              implements _r_e_f_e_r(1) support for _m_e.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_m_e_._t_m_a_c
              is a wrapper enabling the package to be loaded  with  “ggrrooffff  --mm
              mmee”.

NNootteess
       Early _r_o_f_f macro packages often limited their names to a single letter,
       which  followed the formatter’s mm flag letter, resulting in _m_m, _m_s, _m_v,
       _m_n, 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.

SSeeee aallssoo
       Two manuals are available in source and rendered form.  On your system,
       they may be compressed and/or available in additional formats.

       _/_u_s_r_/_s_h_a_r_e_/_d_o_c_/_g_r_o_f_f_-_b_a_s_e_/_m_e_i_n_t_r_o_._m_e
       _/_u_s_r_/_s_h_a_r_e_/_d_o_c_/_g_r_o_f_f_-_b_a_s_e_/_m_e_i_n_t_r_o_._p_s
              is “Writing Papers with _G_r_o_f_f Using -_m_e”,  by  Eric  P.  Allman,
              adapted for _g_r_o_f_f by James Clark.

       _/_u_s_r_/_s_h_a_r_e_/_d_o_c_/_g_r_o_f_f_-_b_a_s_e_/_m_e_r_e_f_._m_e
       _/_u_s_r_/_s_h_a_r_e_/_d_o_c_/_g_r_o_f_f_-_b_a_s_e_/_m_e_r_e_f_._p_s
              is  the  “_m_e  Reference  Manual”, by Eric P. Allman, adapted for
              _g_r_o_f_f by James Clark and G. Branden Robinson.

       _G_r_o_f_f_: _T_h_e _G_N_U _I_m_p_l_e_m_e_n_t_a_t_i_o_n _o_f _t_r_o_f_f, by Trent A. Fisher  and  Werner
       Lemberg,  is the primary _g_r_o_f_f manual.  You can browse it interactively
       with “info groff”.

       For  preprocessors  supported  by  _m_e,  see  _e_q_n(1),  _g_r_n(1),   _p_i_c(1),
       _r_e_f_e_r(1), and _t_b_l(1).

       _g_r_o_f_f(1), _t_r_o_f_f(1), _g_r_o_f_f(7)

groff 1.23.0                      3 June 2025                      _g_r_o_f_f___m_e(7)
───────────────────────────────────────────────────────────────────────────────
_g_r_o_f_f___m_m(7)            Miscellaneous Information Manual            _g_r_o_f_f___m_m(7)

NNaammee
       groff_mm - memorandum macros for GNU _r_o_f_f

SSyynnooppssiiss
       ggrrooffff --mmmm [_o_p_t_i_o_n ...] [_f_i_l_e ...]
       ggrrooffff --mm mmmm [_o_p_t_i_o_n ...] [_f_i_l_e ...]

DDeessccrriippttiioonn
       The  GNU  implementation  of  the _m_m macro package is part of the _g_r_o_f_f
       document formatting system.  The _m_m package is suitable for the  compo‐
       sition of letters, memoranda, reports, and books.

       Call an _m_m macro at the beginning of a document to initialize the pack‐
       age.  A simple _m_m document might use only PP for paragraphing.  Set num‐
       bered  and  unnumbered  section  headings  with HH and HHUU, respectively.
       Change the style of the typeface with BB, II, and RR;  you  can  alternate
       styles  with  BBII,  BBRR, IIBB, IIRR, RRBB, and RRII.  Several nestable list types
       are available via AALL, BBLL, BBVVLL, DDLL, MMLL, RRLL, and VVLL; each of these begins
       a list, to which LLII adds an item and LLEE ends the (nested)  list.   Cus‐
       tomized  list arrangements are supported by LLBB.  DDSS and DDFF start static
       and floating displays, respectively; either is terminated with DDEE.

       _g_r_o_f_f _m_m is intended to be compatible with the _m_m implementation  found
       in  the  AT&T  Documenter’s Workbench (DWB), with the following limita‐
       tions.

       • Omitted features include the logo and company name  strings,  }}ZZ  and
         ]]SS,  respectively; the encoded company site location addresses recog‐
         nized as the third argument to the AAUU macro; the PPvv (“private”  head‐
         ing) register; and the OOKK (other keywords), and PPMM (proprietary mark‐
         ings) macros.

       • The  CCSS (output cover sheet) macro is implemented only for memorandum
         type 4.

       • The _g_r_a_p preprocessor is not  explicitly  supported;  no  GG11  and  GG22
         macros are defined.

       • The  registers  AA,  CC,  EE,  TT, and UU, typically set from the _t_r_o_f_f or
         _n_r_o_f_f command lines with DWB _m_m, are not recognized.

       • When setting the registers LL or WW from the command line, use  an  ex‐
         plicit scaling unit to avoid surprises.

       • DWB _m_m’s nnPP macro indented the second line of a paragraph to align it
         with the start of the text of the first (after the paragraph number);
         _g_r_o_f_f _m_m’s does not.

       • Cut marks are not supported.

       DWB  _m_m supported only seven levels of heading.  As a compatible exten‐
       sion, _g_r_o_f_f _m_m supports fourteen, introducing new registers HH88  through
       HH1144, and affecting the interpretation of the HHFF and HHPP strings.

       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.  _m_m’s macro
       names are usually in full capitals; registers and strings tend to  have
       mixed‐case names.

   DDooccuummeenntt ssttyylleess
       _g_r_o_f_f  _m_m  offers three different frameworks for document organization.
       CCOOVVEERR/CCOOVVEENNDD is a flexible means of preparing any document requiring  a
       cover  page.   LLTT/LLOO  aids preparation of typical Anglophone correspon‐
       dence (business letters, for example).  The MMTT memorandum  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.

   LLooccaalliizzaattiioonn
       _g_r_o_f_f _m_m is designed to be easily localized.  For languages other  than
       English,  strings  that  can appear in output are collected in the file
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/xx_._t_m_a_c, where _x_x is an ISO 639 two‐letter
       language identifier.  Localization packages should be loaded after  _m_m;
       for  example,  you  might format a Swedish _m_m document with the command
       “ggrrooffff --mmmm --mmssvv”.

       This package can also be localized by site or territory;  for  example,
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_m_s_e_._t_m_a_c illustrates how to adapt the out‐
       put  to  a national standard using its ISO 3166 territory code.  Such a
       package can define a string that causes a macro file  _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/
       _1_._2_3_._0_/_t_m_a_c_/_m_m_/territory___l_o_c_a_l_e to be loaded at package initialization.
       If  this  mechanism is not used, _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_m_m_/_l_o_c_a_l_e
       is loaded instead.  No diagnostic is produced if these files do not ex‐
       ist.

   RReeggiisstteerrss aanndd ssttrriinnggss
       Much _m_m behavior can be configured by registers and strings.  A  regis‐
       ter is assigned with the nnrr request.

              ..nnrr _i_d_e_n_t [±±]_n [_i]

       _i_d_e_n_t  is  the name of the register, and _n is the value to be assigned.
       _n can be prefixed with a plus or minus sign if incrementation or decre‐
       mentation (respectively) of the register’s existing value by _n  is  de‐
       sired.   If  assignment of a (possibly) negative _n is required, further
       prefix it with a zero or enclose it in parentheses.  If _i is specified,
       the register is automatically modified by _i prior to interpolation if a
       plus or minus sign is included in the escape sequence as follows.

              \\nn[±±][[_i_d_e_n_t]]

       _i can be negative; it combines algebraically with the sign in  the  in‐
       terpolation escape sequence.

       Strings are defined with the ddss request.

              ..ddss _i_d_e_n_t _c_o_n_t_e_n_t_s

       _c_o_n_t_e_n_t_s  consumes  everything  up  to  the  end of the line, including
       trailing spaces.  It is a good practice to end _c_o_n_t_e_n_t_s with a  comment
       escape  sequence  (\\"")  so that extraneous spaces do not intrude during
       document maintenance.  To include leading spaces in _c_o_n_t_e_n_t_s, prefix it
       with a double quote.  Strings are interpolated with the \\**  escape  se‐
       quence.

              \\**[[_i_d_e_n_t]]

       Register  and  string  name spaces are distinct, but strings and macros
       share a name space.  Defining a string with the  same  name  as  an  _m_m
       macro  is not supported and may cause incorrect rendering, the emission
       of diagnostic messages, and an error exit status from _t_r_o_f_f.

   RReeggiisstteerr ffoorrmmaatt
       A register is interpolated using Arabic numerals if no other format has
       been assigned to it.  Assign a format to a register  with  the  aaff  re‐
       quest.

              ..aaff _R _c

       _R is the name of the register, and _c is the format.  If _c is a sequence
       of  Arabic numerals, their quantity defines a zero‐padded minimum width
       for the interpolated register value.

              FFoorrmm   SSeeqquueennccee
              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, ...

   FFoonnttss
       In _g_r_o_f_f _m_m, the fonts (or rather, font styles) RR (roman), II  (italic),
       and  BB  (bold) are mounted at font positions 11, 22, and 33, 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 _g_r_o_f_f’s ffaamm request or
       using its --ff command‐line option.  On the other hand, if  you  want  to
       replace  just,  for  example,  font  II with Zapf Chancery Medium italic
       (available on _g_r_o_f_f’s ppddff and ppss output devices), you have to  use  the
       ffpp  request,  replacing the font at position 2 with “..ffpp 22 ZZCCMMII”).  Be‐
       cause the cover sheet, memorandum type, and _r_e_f_e_r(1) integration macros
       explicitly request fonts named BB, II, and RR, you will also need to remap
       these font names with the ffttrr request, for instance with “..ffttrr II ZZCCMMII”.

MMaaccrrooss
       An explicitly empty argument may be specified with  a  pair  of  double
       quotes;  to call a macro XXXX with 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 _m_m’s published interface but are  documented
       aspects of _g_r_o_f_f _m_m_.

       ))EE _l_e_v_e_l _t_e_x_t
              Add heading text _t_e_x_t to the table of contents with _l_e_v_e_l, which
              is  either  0 or in the range 1 to 7.  See also HH.  This undocu‐
              mented DWB _m_m macro is exposed by _g_r_o_f_f _m_m to enable  customized
              tables of contents.

       11CC [11] Format  page text in one column.  The page is broken.  A 11 argu‐
              ment suppresses this break; its use may cause body  text  and  a
              pending footnote to overprint.  See 22CC, MMCC, and NNCCOOLL.

       22CC     Begin two‐column formatting.  This is a special case of MMCC.  See
              11CC and NNCCOOLL.

       AAEE     Abstract end; stop collecting abstract text.  See AASS.

       AAFF [_f_i_r_m_‐_n_a_m_e]
              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.  AAFF terminates a document title started
              with TTLL, and can be called without an argument for that purpose.
              See MMTT and CCOOVVEERR.

       AALL [_t_y_p_e [_t_e_x_t_‐_i_n_d_e_n_t [11]]]
              Begin an auto‐incrementing numbered list.  Item numbers start at
              one.  The _t_y_p_e argument assigns the register format (see  above)
              of  the list item enumerators.  The default is 11.  An explicitly
              empty _t_y_p_e also indicates the default.  A  _t_e_x_t_‐_i_n_d_e_n_t  argument
              overrides  register  LLii.   A third argument suppresses the blank
              line that normally precedes each list item.  Use LLII  to  declare
              list items, and LLEE to end the list.

       AAPPPP [_i_d [_t_i_t_l_e]]
              Begin  an  appendix.  If the identifier _i_d is omitted, it is in‐
              cremented (or initialized, if necessary).  The  register  format
              used  for  _i_d is “A”.  The page is broken.  The register AApphh de‐
              termines whether an appendix heading is  then  formatted.   This
              heading  uses  the string AApppp followed by _i_d.  Appendices appear
              in any table of contents (see TTCC).  The string AAppppttxxtt is set  to
              _t_i_t_l_e if the latter is present, and made empty otherwise.

       AAPPPPSSKK _i_d _n [_t_i_t_l_e]
              As  AAPPPP,  but increment the page number by _n.  Use this macro to
              “skip pages” when diagrams or other materials not  formatted  by
              _t_r_o_f_f are included in appendices.

       AASS [_p_l_a_c_e_m_e_n_t [_i_n_d_e_n_t_a_t_i_o_n]]
              Abstract start; begin collecting abstract.  Input up to the next
              AAEE  call  is included in the abstract.  _p_l_a_c_e_m_e_n_t influences the
              location of the abstract on the cover sheet of a memorandum (see
              MMTT).  CCOOVVEERR, by contrast, ignores _p_l_a_c_e_m_e_n_t by default, but  can
              be customized to interpret it.

              _pp_ll_aa_cc_ee_mm_ee_nn_tt   EEffffeecctt
              0           The  abstract  appears  on page 1 and cover sheet if
                          the document is a “released paper” memorandum  (“..MMTT
                          44”); otherwise, it appears on page 1 without a cover
                          sheet.
              1           The  abstract  appears only on the cover sheet (“..MMTT
                          44” only).

              An abstract does not appear at all  in  external  letters  (“..MMTT
              55”).   A  _p_l_a_c_e_m_e_n_t  of  22 was supported by DWB _m_m but is not by
              _g_r_o_f_f _m_m.

              A second argument increases the indentation by  _i_n_d_e_n_t_a_t_i_o_n  and
              reduces the line length by twice this amount.  A scaling unit of
              ens is assumed.  The default is 0.

       AASSTT [_c_a_p_t_i_o_n]
              Set  the  caption  above the abstract to _c_a_p_t_i_o_n, or clear it if
              there is no argument.  The default is “ABSTRACT”.

       AATT _t_i_t_l_e ...
              Specify author’s title(s).  If present, AATT must appear just  af‐
              ter  the corresponding author’s AAUU.  Each _t_i_t_l_e occupies an out‐
              put line beneath the author’s name in the signature  block  used
              by  LLTT letters (see SSGG) and in MMTT memoranda.  The mmss cover sheet
              style also uses it.

       AAUU [_n_a_m_e [_i_n_i_t_i_a_l_s [_l_o_c [_d_e_p_t [_e_x_t [_r_o_o_m [_a_r_g_1 [_a_r_g_2 [_a_r_g_3]]]]]]]]]
              Specify author.  AAUU terminates a document title started with TTLL,
              and can be called without arguments for  that  purpose.   Author
              information is used by cover sheets, MMTT memoranda, and SSGG.  Fur‐
              ther  arguments  comprise  initials, location, department, tele‐
              phone extension, room number or name, and up to three additional
              items.  Repeat AAUU to identify multiple authors.

              Use WWAA/WWEE instead to identify the author for documents employing
              LLTT.

       AAVV [_n_a_m_e [11]]
              Format approval lines for a handwritten signature and date.  Two
              horizontal rules are drawn, with the specified _n_a_m_e and the text
              of the string LLeettddaattee beneath them.  Above these rules, the text
              in the string LLeettaapppp is formatted; a  second  argument  replaces
              this text with a blank line.  See LLTT.

       AAVVLL [_n_a_m_e]
              As AAVV, but the date, date rule, and approval notation LLeettaapppp are
              omitted.

       BB [_b_o_l_d_‐_t_e_x_t [_p_r_e_v_i_o_u_s_‐_f_o_n_t_‐_t_e_x_t]] ...
              Join _b_o_l_d_‐_t_e_x_t in boldface with _p_r_e_v_i_o_u_s_‐_f_o_n_t_‐_t_e_x_t in the previ‐
              ous font, without space between the arguments.  If no arguments,
              switch font to bold style.

       BB11     Begin  boxed, kept display.  The text is indented one character,
              and the right margin is one character shorter.  This  is  a  GNU
              extension.

       BB22     End boxed, kept display.  This is a GNU extension.

       BBEE     End bottom block; see BBSS.

       BBII [_b_o_l_d_‐_t_e_x_t [_i_t_a_l_i_c_‐_t_e_x_t]] ...
              Join  _b_o_l_d_‐_t_e_x_t in boldface with _i_t_a_l_i_c_‐_t_e_x_t in italics, without
              space between the arguments.

       BBLL [_t_e_x_t_‐_i_n_d_e_n_t [11]]
              Begin bulleted list.  Items are prefixed with  a  bullet  and  a
              space.   A _t_e_x_t_‐_i_n_d_e_n_t argument overrides register PPii.  A second
              argument suppresses blank lines between items.  Use  LLII  to  de‐
              clare list items, and LLEE to end the list.

       BBRR [_b_o_l_d_‐_t_e_x_t [_r_o_m_a_n_‐_t_e_x_t]] ...
              Join _b_o_l_d_‐_t_e_x_t in boldface with _r_o_m_a_n_‐_t_e_x_t in roman style, with‐
              out space between the arguments.

       BBSS     Begin  bottom block.  Input is collected until BBEE is called, and
              output between the footnote area and footer of each page.

       BBVVLL [_t_e_x_t_‐_i_n_d_e_n_t [_m_a_r_k_‐_i_n_d_e_n_t [11]]]
              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 VVLL.  _t_e_x_t_‐_i_n_d_e_n_t sets the indentation of the
              text, and _m_a_r_k_‐_i_n_d_e_n_t 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 LLII to  declare  list
              items, and LLEE to end the list.

       CCOOVVEERR [_s_t_y_l_e]
              Begin  a  cover  page description.  CCOOVVEERR must appear before the
              body text (or main matter) of a document.  The argument _s_t_y_l_e is
              used to construct the file name _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_m_m_/
              style_._c_o_v and load it with the mmssoo request.  The  default  _s_t_y_l_e
              is mmss; the _m_s_._c_o_v file prepares a cover page resembling those of
              the _m_s package.  A _._c_o_v file must define a CCOOVVEENNDD macro, which a
              document  must  call  at  the end of the cover description.  Use
              cover description macros in the following order; only TTLL and  AAUU
              are required.

              .COVER
              .TL
              .AF
              .AU
              .AT
              .AS
              .AE
              .COVEND

       CCOOVVEENNDD End the cover description.

       DDEE     End static or floating display begun with DDSS or DDFF.

       DDFF [_f_o_r_m_a_t [_f_i_l_l [_r_i_g_h_t_‐_i_n_d_e_n_t_a_t_i_o_n]]]
              Begin  floating display.  A floating display is saved in a queue
              and output in the order entered.  Arguments are  handled  as  in
              DDSS.   Floating displays cannot be nested.  Placement of floating
              displays is controlled by the registers DDee and DDff.

       DDLL [_t_e_x_t_‐_i_n_d_e_n_t [11]]
              Begin dashed list.  Items are prefixed with an  em  dash  and  a
              space.   A _t_e_x_t_‐_i_n_d_e_n_t argument overrides register PPii.  A second
              argument suppresses blank lines between items.  Use  LLII  to  de‐
              clare list items, and LLEE to end the list.

       DDSS [_f_o_r_m_a_t [_f_i_l_l [_r_i_g_h_t_‐_i_n_d_e_n_t_a_t_i_o_n]]]
              Begin  static  display.   Input  until DDEE is called is collected
              into a display.  The display is output on a single  page  unless
              it  is  taller  than  the  height of the page.  DDSS can be nested
              (contrast with DDFF).

              _ff_oo_rr_mm_aa_tt   EEffffeecctt
              _n_o_n_e     Do not indent the display.
              L        Do not indent the display.
              I        Indent text by \\nn[[SSii]].
              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 _m_m_.

              _ff_ii_ll_ll   EEffffeecctt
              _n_o_n_e   Disable filling.
              N      Disable filling.
              F      Enable filling.

              “N” and “F” can also be specified as “0” and “1”,  respectively,
              for compatibility with DWB _m_m_.

              A third argument reduces the line length by _r_i_g_h_t_‐_i_n_d_e_n_t_a_t_i_o_n_.

              _m_m  normally  places  blank  lines before and after the display.
              Set register DDss to 0 to suppress these.

       EECC [_t_i_t_l_e [_o_v_e_r_r_i_d_e [_f_l_a_g [_r_e_f_n_a_m_e]]]]
              Caption an equation.  The caption consists of  the  string  LLiieecc
              followed  by an automatically incrementing counter stored in the
              register EEcc, punctuation configured by the register OOff, then _t_i_‐
              _t_l_e (if any).  Use the aaff request to configure EEcc’s number  for‐
              mat.   _o_v_e_r_r_i_d_e  and  _f_l_a_g alter the equation number as follows.
              Omitting _f_l_a_g and specifying 00 in its place are equivalent.

              _ff_ll_aa_gg   EEffffeecctt
              0      Prefix number with _o_v_e_r_r_i_d_e.
              1      Suffix number with _o_v_e_r_r_i_d_e.
              2      Replace number with _o_v_e_r_r_i_d_e.

              Equation captions are centered irrespective of the alignment  of
              any enclosing display.

              _r_e_f_n_a_m_e  stores  the  equation  number using SSEETTRR; it can be re‐
              treived with “..GGEETTSSTT _r_e_f_n_a_m_e”.  This argument is  a  GNU  exten‐
              sion.

              Captioned  equations  are listed in a table of contents (see TTCC)
              if the Boolean register LLee is true.  Such a list uses the string
              LLee as a heading.

       EEFF [""''_l_e_f_t''_c_e_n_t_e_r''_r_i_g_h_t''""]
              Define the even‐page footer, which is formatted just  above  the
              normal  page footer on even‐numbered pages.  See PPFF.  EEFF defines
              the string EEOOPPeeff.

       EEHH [""''_l_e_f_t''_c_e_n_t_e_r''_r_i_g_h_t''""]
              Define the even‐page header, which is formatted just  below  the
              normal  page header on even‐numbered pages.  See PPHH.  EEHH defines
              the string TTPPeehh.

       EENN     End equation input preprocessed by _e_q_n(1); see EEQQ.

       EEOOPP    If defined, this macro is called in lieu of normal  page  footer
              layout.   Headers  and footers are formatted in a separate envi‐
              ronment.  See TTPP.

              SSttrriinnggss aavvaaiillaabbllee ttoo EEOOPP
              ─────────────────────────
              EEOOPPff     argument to PPFF
              EEOOPPeeff    argument to EEFF
              EEOOPPooff    argument to OOFF

       EEPPIICC [--LL] _w_i_d_t_h _h_e_i_g_h_t [_n_a_m_e]
              Draw a box with the given _w_i_d_t_h and _h_e_i_g_h_t.  It also prints  the
              text _n_a_m_e or a default string if _n_a_m_e is not specified.  This is
              used  to  include  external  pictures; just give the size of the
              picture.  --LL left‐aligns the picture; the default is to  center.
              See PPIICC.

       EEQQ [_l_a_b_e_l]
              Start  equation  input  preprocessed by _e_q_n(1).  EEQQ and EENN macro
              calls bracket an equation region.  Such  regions  must  be  con‐
              tained  in displays (DDSS/DDEE), except when the region is used only
              to configure _e_q_n and not to produce output.  If  present,  _l_a_b_e_l
              appears  aligned to the right and centered vertically within the
              display; see register EEqq.  If multiple _e_q_n regions occur  within
              a display, only the last _l_a_b_e_l (if any) is used.

       EEXX [_t_i_t_l_e [_o_v_e_r_r_i_d_e [_f_l_a_g [_r_e_f_n_a_m_e]]]]
              Caption  an  exhibit.   Arguments are handled analogously to EECC.
              The register EExx is the exhibit counter.  The  string  LLiieexx  pre‐
              cedes  the  exhibit  number and any _t_i_t_l_e_.  Exhibit captions are
              centered irrespective of the alignment of any enclosing display.

              Captioned exhibits are listed in a table of contents (see TTCC) if
              the Boolean register LLxx is true.  Such a list uses the string LLxx
              as a heading.

       FFCC [_c_l_o_s_i_n_g_‐_t_e_x_t]
              Output the string LLeettffcc, or the specified _c_l_o_s_i_n_g_‐_t_e_x_t_,  as  the
              formal closing of a letter.

       FFDD [_a_r_g [11]]
              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.

              _aa_rr_gg   HHyypphheennaattee??   AAddjjuusstt??   IInnddeenntt??   LLaabbeell aalliiggnnmmeenntt
              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 _a_r_g greater than 11 is treated as 00.  _m_m’s default is 00.

              If  a second argument, conventionally 11, is given, footnote num‐
              bering is reset when a first‐level heading is encountered.   See
              FFSS.

       FFEE     End footnote; see FFSS.

       FFGG [_t_i_t_l_e [_o_v_e_r_r_i_d_e [_f_l_a_g [_r_e_f_n_a_m_e]]]]
              Caption a figure.  Arguments are handled analogously to EECC.  The
              register FFgg is the figure counter.  The string LLiiffgg precedes the
              figure number and any _t_i_t_l_e_.  Figure captions are centered irre‐
              spective of the alignment of any enclosing display.

              Captioned  figures are listed in a table of contents (see TTCC) if
              the Boolean register LLff is true.  Such a list uses the string LLff
              as a heading.

       FFSS [_l_a_b_e_l]
              Start footnote.  Input until FFEE is called is  collected  into  a
              footnote.   By  default,  footnotes  are  automatically numbered
              starting at 1; the number is available in register ::pp and,  with
              a  trailing period, in string FF.  This string precedes the foot‐
              note text at the bottom of the column or  page.   Footnotes  are
              vertically separated by the product of registers FFss and LLsspp.  In
              _g_r_o_f_f _m_m, footnotes may be used in displays.

              A  _l_a_b_e_l argument replaces the contents of the string FF; it need
              not be numeric.  In this event, the footnote marker in the  body
              text must be explicitly written.

       GGEETTHHNN _r_e_f_n_a_m_e [_v_a_r_n_a_m_e]
              Include  the  heading number where the corresponding “..SSEETTRR _r_e_f_‐
              _n_a_m_e” was placed.  This is displayed as “X.X.X.” in pass 1.  See
              IINNIITTRR.  If _v_a_r_n_a_m_e is used, GGEETTHHNN sets the string _v_a_r_n_a_m_e to the
              heading number.

       GGEETTPPNN _r_e_f_n_a_m_e [_v_a_r_n_a_m_e]
              Include the page number where the corresponding “..SSEETTRR  _r_e_f_n_a_m_e”
              was  placed.  This is displayed as “9999” in pass 1.  See IINNIITTRR.
              If _v_a_r_n_a_m_e is used, GGEETTPPNN sets the string _v_a_r_n_a_m_e  to  the  page
              number.

       GGEETTRR _r_e_f_n_a_m_e
              Combine  GGEETTHHNN  and  GGEETTPPNN with the text “chapter” and “, page”.
              The string QQrrff contains the text for the cross reference:

                     .ds Qrf See chapter \\*[Qrfh], page \\*[Qrfp].

              QQrrff may be changed to support other languages.  Strings QQrrffhh and
              QQrrffpp are set by GGEETTRR and contain the page  and  heading  number,
              respectively.

       GGEETTSSTT _r_e_f_n_a_m_e [_v_a_r_n_a_m_e]
              Include  the  string  saved  with  the second argument to ..SSEETTRR.
              This is a dummy string in pass 1.  If  _v_a_r_n_a_m_e  is  used,  GGEETTSSTT
              sets it to the saved string.  See IINNIITTRR.

       HH _l_e_v_e_l [_t_i_t_l_e [_s_u_f_f_i_x]]
              Set  a  numbered section heading at _l_e_v_e_l.  _m_m produces numbered
              _h_e_a_d_i_n_g _m_a_r_k_s of the form _a._b._c..., with up to  fourteen  levels
              of  nesting.   Each  level’s number increases automatically with
              each HH call and is reset to zero when a more  significant  _l_e_v_e_l
              is  specified.  “11” is the most significant or coarsest division
              of the document.  Text after an HH call is formatted as  a  para‐
              graph; calling PP is unnecessary.

              _t_i_t_l_e  specifies  an optional title; it must be double‐quoted if
              it contains spaces.  _m_m appends _s_u_f_f_i_x to _t_i_t_l_e in the  body  of
              the  document, but omits it from any table of contents (see TTCC).
              This facility can be used to annotate the heading title  with  a
              footnote.  _s_u_f_f_i_x should not interpolate the FF string; specify a
              footnote mark explicitly.  See FFSS.

              Heading  behavior is highly configurable.  Several registers set
              a _t_h_r_e_s_h_o_l_d_, 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 CCll  is
              included in the table of contents (see TTCC).

              _H_e_a_d_i_n_g  _l_a_y_o_u_t_.  Register EEjj sets 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 HHppss is  preceded
              by  the  amount  of  vertical space in register HHppss11, and by the
              amount in HHppss22 otherwise.  The HHbb register sets a threshold  be‐
              low which a break occurs after the heading, and register HHss sets
              a threshold below which vertical space follows it.  If the head‐
              ing  level  is  not less than both of these, a _r_u_n_‐_i_n _h_e_a_d_i_n_g is
              produced; paragraph text follows on the same output line.   Oth‐
              erwise,  register  HHii  configures  the indentation of text after
              headings.  Threshold register HHcc enables the centering of  head‐
              ings;  a heading level below both of the HHbb and HHcc thresholds is
              centered.

              _H_e_a_d_i_n_g _t_y_p_e_f_a_c_e _a_n_d _s_i_z_e_.  The fonts used for  heading  numbers
              and  titles  at each level are configured by the HHFF string.  The
              string HHPP likewise assigns a type size to  each  heading  level.
              The  vertical  spacing used by headings may be controlled by the
              user‐definable macros HHXX and/or HHZZ.

              _H_e_a_d_i_n_g _n_u_m_b_e_r _f_o_r_m_a_t_.  Registers named  HH11  through  HH1144  store
              counters for each heading level.  Their values are printed using
              Arabic  numerals  by  default;  see  HHMM.  The heading levels are
              catenated with dots for formatting; to typeset only the deepest,
              set the HHtt register.  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 HH11ddoott register.

              _C_u_s_t_o_m_i_z_i_n_g  _h_e_a_d_i_n_g  _b_e_h_a_v_i_o_r_.   _m_m calls _h_o_o_k macros to enable
              further customization of headings.  (DWB _m_m  called  these  “ex‐
              its”.)   They can be used to change the heading’s _m_a_r_k (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
              _d_e_c_l_a_r_e_d_‐_l_e_v_e_l  is  the _l_e_v_e_l argument to HH, or 00 for unnumbered
              headings (see HHUU).  _a_c_t_u_a_l_‐_l_e_v_e_l is the same  as  _d_e_c_l_a_r_e_d_‐_l_e_v_e_l
              for  numbered  headings, and the value of register HHuu for unnum‐
              bered headings.  _t_i_t_l_e is the corresponding argument to HH or HHUU.

              HHXX _d_e_c_l_a_r_e_d_‐_l_e_v_e_l _a_c_t_u_a_l_‐_l_e_v_e_l _t_i_t_l_e
                     _m_m calls HHXX before setting the heading.  Your  definition
                     may alter }}00, }}22, and ;;33.

                     }}00 (string)
                            contains  the  heading mark plus two spaces if _d_e_‐
                            _c_l_a_r_e_d_‐_l_e_v_e_l is non‐zero, and otherwise is empty.

                     ;;00 (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.

                     }}22 (string)
                            is the suffix that separates a run‐in heading from
                            the text.  It contains two spaces if  register  ;;00
                            is 0, and otherwise is empty.

                     ;;33 (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 22vv.

              HHYY _d_e_c_l_a_r_e_d_‐_l_e_v_e_l _a_c_t_u_a_l_‐_l_e_v_e_l _t_i_t_l_e
                     _m_m  calls  HHYY  after  determing  the heading typeface and
                     size.  It could be used to change indentation.

              HHZZ _d_e_c_l_a_r_e_d_‐_l_e_v_e_l _a_c_t_u_a_l_‐_l_e_v_e_l _t_i_t_l_e
                     _m_m calls HHZZ after formatting the heading, just  before  HH
                     or  HHUU  returns.   It  could  be  used to change the page
                     header to include a section heading.

       HHCC [_h_y_p_h_e_n_a_t_i_o_n_‐_c_h_a_r_a_c_t_e_r]
              Set hyphenation character.  Default value is  “\%”.   Resets  to
              the  default  if  called  without  argument.  Hyphenation can be
              turned off by setting register HHyy to 0 at the beginning  of  the
              file.

       HHMM [_a_r_g_1 [_a_r_g_2 [... [_a_r_g_1_4]]]]
              Set the heading mark style.  Each argument assigns the specified
              register  format (see above) to the corresponding heading level.
              The default is 11 for all levels.  An explicitly  empty  argument
              also indicates the default.

       HHUU _h_e_a_d_i_n_g_‐_t_e_x_t
              Set an unnumbered section heading.  Except for a heading number,
              it  is treated as a numbered heading of the level stored in reg‐
              ister HHuu; see HH.

       II [_i_t_a_l_i_c_‐_t_e_x_t [_p_r_e_v_i_o_u_s_‐_f_o_n_t_‐_t_e_x_t]] ...
              Join _i_t_a_l_i_c_‐_t_e_x_t in italics with _p_r_e_v_i_o_u_s_‐_f_o_n_t_‐_t_e_x_t in the  pre‐
              vious  font,  without  space between the arguments.  If no argu‐
              ments, switch font to italic style.

       IIAA [_r_e_c_i_p_i_e_n_t_‐_n_a_m_e [_t_i_t_l_e]]
              Specify the inside address in a letter.  Input is collected into
              the inside address until IIEE is called, and then output.  You can
              specify multiple recipients with empty  IIAA/IIEE  pairs;  only  the
              last  address is used.  The arguments give each recipient a name
              and title.  See LLTT.

       IIBB [_i_t_a_l_i_c_‐_t_e_x_t [_b_o_l_d_‐_t_e_x_t]] ...
              Join _i_t_a_l_i_c_‐_t_e_x_t in italics with _b_o_l_d_‐_t_e_x_t in boldface,  without
              space between the arguments.

       IIEE     End the inside address begun with IIAA.

       IINNDD _a_r_g_u_m_e_n_t ...
              If  the  Boolean register RReeff is true, write an index entry as a
              specially prepared _r_o_f_f comment to the  standard  error  stream,
              with each _a_r_g_u_m_e_n_t separated from its predecessor by a tab char‐
              acter.   The entry’s location information is arranged as config‐
              ured by the most recent IINNIITTII call.

       IINNDDPP   Output the index set up by IINNIITTII and populated by IINNDD calls.  By
              default, IINNDDPP calls SSKK and writes a centered caption interpolat‐
              ing the string IInnddeexx.  It then disables filling  and  calls  22CC;
              afterward, it restores filling and calls 11CC.

              Define  macros to customize this behavior.  IINNDDPP calls TTXXIINNDD be‐
              fore the caption, TTYYIINNDD _i_n_s_t_e_a_d  of  writing  the  caption,  and
              TTZZIINNDD after formatting the index.

       IINNIITTII _l_o_c_a_t_i_o_n_‐_t_y_p_e _f_i_l_e_‐_n_a_m_e [_m_a_c_r_o]
              Initialize  _g_r_o_f_f  _m_m’s indexing system.  Argument _l_o_c_a_t_i_o_n_‐_t_y_p_e
              selects how the location of each index entry is reported.  _f_i_l_e_‐
              _n_a_m_e populates an internal string used later by IINNDDPP.

              _ll_oo_cc_aa_tt_ii_oo_nn_‐‐_tt_yy_pp_ee   EEnnttrryy ffoorrmmaatt
              N               page number
              H               heading mark
              B               page number, tab character, heading mark

              If _m_a_c_r_o is specified, it is called for each  index  entry  with
              the arguments given to IINNDD.

       IINNIITTRR _i_d
              Initialize  the  cross  reference  macros.  Cross references are
              written to the standard error stream, which should be redirected
              into a file named id_._q_r_f.  _m_m_r_o_f_f(1) handles this  and  the  two
              formatting  passes it requires.  The first pass identifies cross
              references, and the second one includes them.

              See SSEETTRR, GGEETTPPNN, and GGEETTHHNN.

       IIRR [_i_t_a_l_i_c_‐_t_e_x_t [_r_o_m_a_n_‐_t_e_x_t]] ...
              Join _i_t_a_l_i_c_‐_t_e_x_t in italics  with  _r_o_m_a_n_‐_t_e_x_t  in  roman  style,
              without space between the arguments.

       IISSOODDAATTEE [00]
              Use  ISO  8601  format for the date string DDTT used by some cover
              sheet and memorandum types; that is, _Y_Y_Y_Y‐_M_M‐_D_D.  Must be called
              before NNDD to be effective.  If given an argument of 00,, the  tra‐
              ditional  date format for the _g_r_o_f_f locale is used; this is also
              the default.

       LLBB _t_e_x_t_‐_i_n_d_e_n_t _m_a_r_k_‐_i_n_d_e_n_t _p_a_d _t_y_p_e [_m_a_r_k [_p_r_e_‐_i_t_e_m_‐_s_p_a_c_e [_p_r_e_‐_l_i_s_t_‐
       _s_p_a_c_e]]]
              Begin list.  The macros AALL, BBLL, BBVVLL, DDLL, MMLL, RRLL, and VVLL call  LLBB
              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 _m_m_; the outermost level
              is  0.   The  text of each list item is indented by _t_e_x_t_‐_i_n_d_e_n_t_;
              the default is taken from the LLii register (in ens).  Each item’s
              mark is indented by _m_a_r_k_‐_i_n_d_e_n_t_; the default is 00nn.  The mark is
              normally left‐aligned.  If _p_a_d is greater than zero, _m_a_r_k_‐_i_n_d_e_n_t
              is overridden such that _p_a_d ens of space follow the mark.   _t_y_p_e
              selects one of six possible ways to display the mark.

              _tt_yy_pp_ee   OOuuttppuutt ffoorr aa mmaarrkk ““xx””
              1      x.
              2      x)
              3      (x)
              4      [x]
              5      <x>
              6      {x}

              If  _t_y_p_e  is 0 and _m_a_r_k is unspecified, the items are set with a
              hanging indent.  Otherwise, _m_a_r_k  is  interpreted  as  a  string
              defining  the mark.  If _t_y_p_e is greater than zero, items are au‐
              tomatically numbered; _m_a_r_k is interpreted as a register  format.
              The default _t_y_p_e is 00.

              The  last  two arguments manage vertical space.  Unless a list’s
              nesting level is greater than the  value  of  register  LLss,  its
              items  are preceded by _p_r_e_‐_i_t_e_m_‐_s_p_a_c_e multiplied by the register
              LLsspp; the default is 11.  LLBB precedes the list  by  _p_r_e_‐_l_i_s_t_‐_s_p_a_c_e
              multiplied by the register LLsspp; the default is 00.

       LLCC [_l_i_s_t_‐_l_e_v_e_l]
              Clear  list  state.   Active lists are terminated as if with LLEE,
              either all (the default) or only those from  the  current  level
              down to _l_i_s_t_‐_l_e_v_e_l if specified.  HH calls LLCC automatically.

       LLEE [11] End  list.   The  current  list is terminated.  An argument of 11
              causes vertical space in the amount of register  LLsspp  to  follow
              the list.

       LLII [_m_a_r_k [_i_t_e_m_‐_m_a_r_k_‐_m_o_d_e]]
              Begin  a  list  item.  Input is collected into a list item until
              the current list is terminated or LLII is called  again.   By  de‐
              fault, the item’s text is preceded by any mark configured by the
              current  list.   If only _m_a_r_k is specified, it replaces the con‐
              figured mark.  A second argument prefixes _m_a_r_k to the configured
              mark; an _i_t_e_m_‐_m_a_r_k_‐_m_o_d_e value of 1 places an  unbreakable  space
              after _m_a_r_k_, while a value of 2 does not (rendering the two adja‐
              cent).  Also see register LLiimmsspp.

       LLOO _o_p_t_i_o_n [_v_a_l_u_e]
              Specify  letter  options;  see LLTT.  Standard options are as fol‐
              lows.  See IIAA regarding the inside address and string DDTT regard‐
              ing the date.

              _oo_pp_tt_ii_oo_nn   EEffffeecctt
              AT       Attention; put contents of string LLeettAATT and _v_a_l_u_e left‐
                       aligned after the inside address.
              CN       Confidential; put _v_a_l_u_e_, or contents of  string  LLeettCCNN,
                       left‐aligned after the date.
              RN       Reference; put contents of string LLeettRRNN and _v_a_l_u_e after
                       the confidental notation (if any) and the date, aligned
                       with the latter.
              SA       Salutation;  put  _v_a_l_u_e_,  or  contents of string LLeettSSAA,
                       left‐aligned after the inside address and the confiden‐
                       tal notation (if any).
              SJ       Subject; put contents of string LLeettSSJJ and  _v_a_l_u_e  left‐
                       aligned  after the inside address and the attention and
                       salutation notations (if any).  In  letter  type  “SP”,
                       LLeettSSJJ is ignored and _v_a_l_u_e is set in full capitals.

       LLTT [_s_t_y_l_e]
              Format  a  letter in the designated _s_t_y_l_e_, defaulting to BBLL (see
              below).  A letter begins with the writer’s address (WWAA/WWEE), fol‐
              lowed by the date (NNDD), the inside address (IIAA/IIEE), the body  of
              the  letter  (PP and other general‐purpose _m_m macros), the formal
              closing (FFCC), the signature (SSGG), and notations (NNSS/NNEE).  Any of
              these may be omitted.  Letter options specified with LLOO add fur‐
              ther annotations, which are extensible; see section  “Internals”
              below.

              _ss_tt_yy_ll_ee   DDeessccrriippttiioonn
              BBLL      Blocked: the writer’s address, date, formal closing, and
                      signature  are  indented  to  the  center  of  the line.
                      Everything else is left‐aligned.
              SSBB      Semi‐blocked: as BBLL, but the first line  of  each  para‐
                      graph is indented by 55mm.
              FFBB      Fully blocked: everything begins at the left margin.
              SSPP      Simplified:  as FFBB, but a formal closing is omitted, and
                      the signature is set in full capitals.

       MMCC _c_o_l_u_m_n_‐_w_i_d_t_h [_g_u_t_t_e_r_‐_w_i_d_t_h]
              Begin multi‐column layout.  _g_r_o_f_f _m_m creates as many columns  of
              _c_o_l_u_m_n_‐_w_i_d_t_h  as  the  line length will permit.  _g_u_t_t_e_r_‐_w_i_d_t_h is
              the interior spacing between columns.  It  defaults  to  _c_o_l_u_m_n_‐
              _w_i_d_t_h/15.   11CC returns to single‐column layout.  MMCC is a GNU ex‐
              tension.  See MMUULLBB for an alternative.

       MMLL _m_a_r_k [_t_e_x_t_‐_i_n_d_e_n_t [11]]
              Start a list with the _m_a_r_k argument preceding  each  list  item.
              _t_e_x_t_‐_i_n_d_e_n_t  overrides the default indentation of the list items
              set by register LLii.  If a third argument, conventionally  11,  is
              given,  the  blank line that normally precedes each list item is
              suppressed.  Use LLII to declare list items, and  LLEE  to  end  the
              list.

       MMTT [_t_y_p_e [_a_d_d_r_e_s_s_e_e]]
              Select  memorandum  type.   These  correspond to formats used by
              AT&T Bell Laboratories, where the _m_m package was  initially  de‐
              veloped,  affecting the document layout.  Some of these included
              a cover page with a caption categorizing the document.  _g_r_o_f_f _m_m
              uses _t_y_p_e to construct the  file  name  _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/
              _t_m_a_c_/_m_m_/type_._M_T  and  load  it with the mmssoo request.  Memorandum
              types 0 to 5 are supported; any other value of _t_y_p_e is mapped to
              type 6.  If _t_y_p_e is omitted, 00 is  implied.   _a_d_d_r_e_s_s_e_e  sets  a
              string analogous to one used by AT&T cover sheet macros that are
              not implemented in _g_r_o_f_f _m_m.

              _tt_yy_pp_ee   DDeessccrriippttiioonn
              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 CCOOVVEERR for a more flexible cover sheet mechanism.

       MMOOVVEE _y_‐_p_o_s [_x_‐_p_o_s [_l_i_n_e_‐_l_e_n_g_t_h]]
              Move  to  a  position,  setting  page offset to _x_‐_p_o_s.  If _l_i_n_e_‐
              _l_e_n_g_t_h is not given, the difference between current and new page
              offset is used.  Use PPGGFFOORRMM without arguments to return to  nor‐
              mal.

       MMUULLBB _c_w_1 _s_p_a_c_e_1 [_c_w_2 _s_p_a_c_e_2] ... _c_w_n
              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 nn.  MMUULLBB uses a diversion
              and operates in a separate environment.

       MMUULLNN   Begin next column in alternative column mode.

       MMUULLEE   End alternative multi‐column mode and emit the columns.

       NNCCOOLL   Move to the start of the next column (only when using 22CC or MMCC).
              Contrast with MMUULLNN.

       NNDD [_a_r_g]
              Set the document’s date.  _m_m does not interpret _a_r_g; it can be a
              revision identifier (or empty).

       NNEE     End notation begun with NNSS; filling is enabled.

       nnPP [_t_y_p_e]
              Begin a numbered paragraph at heading level two.  See PP.

       NNSS [_c_o_d_e [11]]
              Declare notations, typically for letters or  memoranda,  of  the
              type  specified by _c_o_d_e.  The text corresponding to _c_o_d_e is out‐
              put, and filling is disabled until NNEE is called.   Typically,  a
              list  of names or attachments lies within NNSS/NNEE.  If _c_o_d_e is ab‐
              sent or does not match one of the values listed under the  LLeettnnss
              string description below, each line of notations is formatted as
              “Copy  (_l_i_n_e)  to”.   If a second argument, conventionally 11, is
              given, _c_o_d_e becomes the entire notation and NNEE is not necessary.
              In _g_r_o_f_f _m_m, you can set up further notations to  be  recognized
              by NNSS; see the strings LLeettnnss and LLeettnnssddeeff below.

       OOFF [""''_l_e_f_t''_c_e_n_t_e_r''_r_i_g_h_t''""]
              Define  the  odd‐page  footer, which is formatted just above the
              normal page footer on odd‐numbered pages.  See PPFF.   OOFF  defines
              the string EEOOPPooff.

       OOHH [""''_l_e_f_t''_c_e_n_t_e_r''_r_i_g_h_t''""]
              Define  the  odd‐page  header, which is formatted just below the
              normal page header on odd‐numbered pages.  See PPHH.   OOHH  defines
              the string TTPPoohh.

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

       PP [_t_y_p_e]
              Begin new paragraph.  If _t_y_p_e is missing or  0, PP sets the para‐
              graph  fully left-aligned.  A _t_y_p_e of 1 idents the first line by
              \\[[PPii]] ens.  Set the register PPtt to select  a  default  paragraph
              indentation  style.  The register PPss controls the vertical spac‐
              ing between paragraphs.

       PPEE     Picture end; see _p_i_c(1).

       PPFF [""''_l_e_f_t''_c_e_n_t_e_r''_r_i_g_h_t''""]
              Define the page footer.  The footer is formatted at  the  bottom
              of  each page; the argument is otherwise as described in PPHH.  PPFF
              defines the string EEOOPPff.  See EEFF, OOFF, and EEOOPP.

       PPGGFFOORRMM [_l_i_n_e_l_e_n_g_t_h [_p_a_g_e_l_e_n_g_t_h [_p_a_g_e_o_f_f_s_e_t [11]]]]
              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.   PPGGFFOORRMM
              can  be  used without arguments to reset everything after a MMOOVVEE
              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.)

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

       PPHH [""''_l_e_f_t''_c_e_n_t_e_r''_r_i_g_h_t''""]
              Define  the  page  header, formatted at the top of each page, as
              the argument, where _l_e_f_t, _c_e_n_t_e_r, and _r_i_g_h_t are aligned  to  the
              respective locations on the line.  A “%%” character in _a_r_g 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 PPXX (if de‐
              fined) after formatting the header.  PPHH defines the string  TTPPhh.
              See EEHH, OOHH, and TTPP.

       PPIICC [--BB] [--CC|--II _n|--LL|--RR] _f_i_l_e [_w_i_d_t_h [_h_e_i_g_h_t]]
              Include  PostScript  document  _f_i_l_e.   The  optional --BB argument
              draws a box around the picture.  The optional --LL,  --CC,  --RR,  and
              --II  _n  arguments align the picture or indent it by _n (assuming a
              scaling unit of mm).  By default, the  picture  is  left‐aligned.
              Optional  _w_i_d_t_h and _h_e_i_g_h_t arguments resize the picture.  Use of
              this  macro  requires  two‐pass  processing;   see   IINNIITTRR   and
              _m_m_r_o_f_f(1).

       PPSS     Picture start; see _p_i_c(1).

       PPYY     Picture  end with flyback.  Ends a _p_i_c(1) picture, returning the
              vertical position to where it was prior to the picture.  This is
              a GNU extension.

       RR [_r_o_m_a_n_‐_t_e_x_t [_p_r_e_v_i_o_u_s_‐_f_o_n_t_‐_t_e_x_t]] ...
              Join _r_o_m_a_n_‐_t_e_x_t in roman style with  _p_r_e_v_i_o_u_s_‐_f_o_n_t_‐_t_e_x_t  in  the
              previous font, without space between the arguments.  If no argu‐
              ments, switch font to roman style.

       RRBB [_r_o_m_a_n_‐_t_e_x_t [_b_o_l_d_‐_t_e_x_t]] ...
              Join _r_o_m_a_n_‐_t_e_x_t in roman style with _b_o_l_d_‐_t_e_x_t in boldface, with‐
              out space between the arguments.

       RRDD [_p_r_o_m_p_t [_d_i_v_e_r_s_i_o_n [_s_t_r_i_n_g]]]
              Read  from  standard input to diversion and/or string.  The text
              is saved in a diversion named _d_i_v_e_r_s_i_o_n.   Recall  the  text  by
              writing  the name of the diversion after a dot on an empty line.
              A string is also defined if _s_t_r_i_n_g is given.   _D_i_v_e_r_s_i_o_n  and/or
              _p_r_o_m_p_t can be empty ("").

       RRFF     Reference  end.  Ends a reference definition and returns to nor‐
              mal processing.  See RRSS.

       RRII [_r_o_m_a_n_‐_t_e_x_t [_i_t_a_l_i_c_‐_t_e_x_t]] ...
              Join _r_o_m_a_n_‐_t_e_x_t in roman  style  with  _i_t_a_l_i_c_‐_t_e_x_t  in  italics,
              without space between the arguments.

       RRLL [_t_e_x_t_‐_i_n_d_e_n_t [11]]
              Begin reference list.  Each item is preceded by an automatically
              incremented  number  between square brackets; compare AALL.  _t_e_x_t_‐
              _i_n_d_e_n_t changes the default indentation.  Use LLII to declare  list
              items,  and  LLEE to end the list.  A second argument, convention‐
              ally 11, suppresses the blank line that  normally  precedes  each
              list item.

       RRPP [_s_u_p_p_r_e_s_s_‐_c_o_u_n_t_e_r_‐_r_e_s_e_t [_p_a_g_e_‐_e_j_e_c_t_i_o_n_‐_p_o_l_i_c_y]]
              Format  a reference page, listing items accumulated within RRSS/RRFF
              pairs.  The reference counter is reset unless the first argument
              is 11.  Normally, page breaks occur before and after  the  refer‐
              ences are output; the register RRppee configures this behavior, and
              a  second  argument  overrides its value.  TTCC calls RRPP automati‐
              cally if references have accumulated.

              References are list items, and  thus  are  vertically  separated
              (see  LLBB).   Setting  register  LLss to 00 suppresses this spacing.
              The string RRpp contains the reference page caption.

       RRSS [_r_e_f_e_r_e_n_c_e_‐_s_t_r_i_n_g]
              Begin an automatically numbered reference  definition.   By  de‐
              fault,  references  are  numbered  starting  at 1; the number is
              available in register ::RR.  Interpolate the string RRff  where  the
              reference  mark  should be and write the reference between RRSS/RRFF
              on an input line after the reference mark.  If  _r_e_f_e_r_e_n_c_e_‐_s_t_r_i_n_g
              is  specified,  _g_r_o_f_f  _m_s  also  stores  the reference mark in a
              string of that name, which can be interpolated as  \\**[[_r_e_f_e_r_e_n_c_e_‐
              _s_t_r_i_n_g]] subsequently.

       SS [_t_y_p_e_‐_s_i_z_e [_v_e_r_t_i_c_a_l_‐_s_p_a_c_i_n_g]]
              Set  type  size  and vertical spacing.  Each argument is a _g_r_o_f_f
              measurement, using an appropriate scaling unit and an optional ++
              or -- prefix to increment or decrement the current value.  An ar‐
              gument of PP restores the previous value, CC indicates the current
              value, and DD requests the default.  An empty or omitted argument
              is treated as PP.

       SSAA [_m_o_d_e]
              Set or restore the default enablement of adjustment.  Specify  00
              or  11  as  _m_o_d_e to set a document’s default explicitly; 11 is as‐
              sumed by _m_m.  Adjustment can be temporarily suspended  with  the
              nnaa  request.  When the HH or HHUU macros are used to format a head‐
              ing, or when SSAA is called without a _m_o_d_e argument,  the  default
              adjustment is restored.

       SSEETTRR _r_e_f_n_a_m_e [_s_t_r_i_n_g]
              Remember the current heading and page numbers as _r_e_f_n_a_m_e.  Saves
              _s_t_r_i_n_g  if  _s_t_r_i_n_g  is defined.  _s_t_r_i_n_g is retrieved with GGEETTSSTT.
              See IINNIITTRR.

       SSGG [_a_r_g [11]]
              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 AAUU.  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 WWAA/WWEE.  See section “Internals” be‐
              low.

       SSKK [_n] Skip  _n  pages.  If _n is 0 or omitted, the page is broken unless
              the drawing position is already at the top of  a  page.   Other‐
              wise,  _n  pages,  blank  except for any headers and footers, are
              printed.

       SSMM _t_e_x_t [_p_o_s_t]
       SSMM _p_r_e _t_e_x_t _p_o_s_t
              Format _t_e_x_t at a smaller type size, joined  with  any  specified
              _p_r_e and _p_o_s_t at normal size.

       SSPP [_l_i_n_e_s]
              Space  vertically.  _l_i_n_e_s can have any scaling factor, like “3i”
              or “8v”.  Several SSPP calls in a line only produces  the  maximum
              number  of  lines,  not  the  sum.  SSPP is ignored also until the
              first text line in a page.  Add \\&& before a call to SSPP to  avoid
              this.

       TTAABB    Reset tab stops to every 5 ens.

       TTBB [_t_i_t_l_e [_o_v_e_r_r_i_d_e [_f_l_a_g [_r_e_f_n_a_m_e]]]]
              Caption  a table.  Arguments are handled analogously to EECC.  The
              register TTbb is the table counter.  The string LLiittbb precedes  the
              table  number  and any _t_i_t_l_e_.  Table captions are centered irre‐
              spective of the alignment of any enclosing display.

              Captioned tables are listed in a table of contents (see  TTCC)  if
              the Boolean register LLtt is true.  Such a list uses the string LLtt
              as a heading.

       TTCC [_s_l_e_v_e_l [_s_p_a_c_i_n_g [_t_l_e_v_e_l [_t_a_b [_h_1 [_h_2 [_h_3 [_h_4 [_h_5]]]]]]]]]
              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 RRSS), calls RRPP.  It then begins a
              new page with the contents caption, stored in the string  LLiiccoonn,
              centered  at  the  top.   The entries follow after three vees of
              space.  Each entry is a saved section (number and) heading title
              (see the CCll register), 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 CCii overrides these
              indentations.  Entries at heading levels  up  to  and  including
              _s_l_e_v_e_l  are preceded by _s_p_a_c_i_n_g vees of space.  Entries at head‐
              ing levels up to and including _t_l_e_v_e_l are followed by  a  leader
              and  a right‐aligned page number.  If the Boolean‐valued _t_a_b ar‐
              gument is true, the leader is replaced with horizontal motion in
              the same amount.  For entries above heading  level  _t_l_e_v_e_l,  the
              page  number  follows the heading text after a word space.  Each
              argument _h_1..._h_5 appears in order on  its  own  line,  centered,
              above  the  contents  caption.  Page numbering restarts at 1, in
              register format “i”.  If the OOcc register is true,  numbering  of
              these pages is suppressed.

              If  TTCC is called with at most four arguments, it calls the user‐
              defined macro TTXX (if defined) prior to formatting  the  contents
              caption,  and TTYY (if defined) _i_n_s_t_e_a_d of formatting the contents
              caption.

              Analogous handling of lists of figures, tables,  equations,  and
              exhibits  is achieved by defining TTXX_x_x and TTYY_x_x macros, where _x_x
              is “FG”, “TB”, “EC”,  or  “EX”,  respectively.   Similarly,  the
              strings  LLiiffgg, LLiittbb, LLiieexx, and LLiieecc determine captions for their
              respective lists.

       TTEE     Table end.  See TTSS.

       TTHH     End table heading.  It is repeated after page  breaks  within  a
              table.   See  TTSS.  The NN argument supported by DWB _m_m is not im‐
              plemented by _g_r_o_f_f _m_m_.

       TTLL [_c_h_a_r_g_i_n_g_‐_c_a_s_e_‐_n_u_m_b_e_r [_f_i_l_i_n_g_‐_c_a_s_e_‐_n_u_m_b_e_r]]
              Begin document title.  Input is collected into the  title  until
              AAFF  or  AAUU  is called, and output as directed by the cover page.
              _c_h_a_r_g_i_n_g_‐_c_a_s_e_‐_n_u_m_b_e_r and _f_i_l_i_n_g_‐_c_a_s_e_‐_n_u_m_b_e_r are saved for use in
              memorandum types 0 and 5.  See MMTT.

       TTMM _n_u_m_b_e_r ...
              Declare technical memorandum number(s) used by MMTT.

       TTPP     If defined, this macro is called in lieu of normal  page  header
              layout.   Headers  and footers are formatted in a separate envi‐
              ronment.  See EEOOPP.

              SSttrriinnggss aavvaaiillaabbllee ttoo TTPP
              ────────────────────────
              TTPPhh     argument to PPHH
              TTPPeehh    argument to EEHH
              TTPPoohh    argument to OOHH

       TTSS [HH] Table start.  Argument “H” tells _m_m that the table has  a  head‐
              ing.  See TTEE, TTHH, and _t_b_l(1).

       VVEERRBBOONN [_f_o_r_m_a_t [_t_y_p_e_‐_s_i_z_e [_f_o_n_t]]]
              Begin verbatim display, where characters have equal width.  _f_o_r_‐
              _m_a_t  controls  several parameters.  Add up the values of desired
              features; the default is 00.  On typesetting devices, further ar‐
              guments configure the _t_y_p_e_‐_s_i_z_e in scaled points, and  the  face
              (_f_o_n_t); the default is CCRR (Courier roman).

              VVaalluuee   EEffffeecctt
              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 nnmm request with
                      arguments in string VVeerrbbnnmm.
              16      Indent by the amount stored in register VVeerrbbiinn.

       VVEERRBBOOFFFF
              End verbatim display.

       VVLL [_t_e_x_t_‐_i_n_d_e_n_t [_m_a_r_k_‐_i_n_d_e_n_t [11]]]
              Begin variable‐item (or “tagged”) list.  Each item should supply
              its own mark, or tag.  If the mark is  wider  than  _m_a_r_k_‐_i_n_d_e_n_t_,
              one  space  separates  it  from  subsequent  text; contrast BBVVLL.
              _t_e_x_t_‐_i_n_d_e_n_t sets the indentation of the  text,  and  _m_a_r_k_‐_i_n_d_e_n_t
              the  distance  from the current list indentation to the mark.  A
              third argument suppresses the blank line that normally  precedes
              each list item.  Use LLII to declare list items, and LLEE to end the
              list.

       VVMM [--TT] [_t_o_p [_b_o_t_t_o_m]]
              Vertical  margin.  Increase the top and bottom margin by _t_o_p and
              _b_o_t_t_o_m, respectively.  If option --TT is specified, set those mar‐
              gins to _t_o_p and _b_o_t_t_o_m.  If no argument is given, reset the mar‐
              gin to zero, or to the default (“7v 5v”) if --TT is used.   It  is
              highly  recommended that macros TTPP and/or EEOOPP are defined if us‐
              ing --TT and setting top and/or bottom margin to less than the de‐
              fault.  This undocumented DWB _m_m macro is exposed by _g_r_o_f_f _m_m to
              increase user control of page layout.

       WWAA [_w_r_i_t_e_r_’_s_‐_n_a_m_e [_t_i_t_l_e]]
              Specify the writer(s) of an LLTT letter.  Input is collected  into
              the  writer’s  address until WWAA is called, and then output.  You
              can specify multiple writers with empty WWAA/WWEE  pairs;  only  the
              last address is used.  The arguments give each writer a name and
              title.

       WWCC [_f_o_r_m_a_t ...]
              Control width of footnotes and displays.

              _ff_oo_rr_mm_aa_tt   EEffffeecctt
              NN        equivalent to “--WWFF --FFFF --WWDD” (default)
              WWFF       set  footnotes  at full line length, even in two‐column
                       mode
              --WWFF      set footnotes using column line length
              FFFF       apply width of first footnote to encountered to  subse‐
                       quent ones
              --FFFF      footnote width determined by WWFF and --WWFF
              WWDD       set  displays  at  full line length, even in two‐column
                       mode
              --WWDD      set displays using column line length

       WWEE     End the writer’s address begun with WWAA.

SSttrriinnggss
       Many _m_m strings interpolate predefined, localizable  text.   These  are
       presented in quotation marks.

       AApppp    “APPENDIX”

       AAppppttxxtt stores the _t_i_t_l_e argument to the last AAPPPP call.

       BBUU     interpolates a bullet (see BBLL).

       CCii     is  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 “11ii”) and is mapped
              one‐to‐one to heading levels 1, 2, and so on.

       DDTT     The date; set by the NNDD macro (defaults to the date the document
              is formatted).  The format is the conventional one for the _g_r_o_f_f
              locale, but see the IISSOODDAATTEE macro and IIssoo register.

       EEMM     interpolates an em dash.

       FF      interpolates an automatically numbered footnote marker; the num‐
              ber is used by the next FFSS call without an argument.   In  _t_r_o_f_f
              mode,  the  marker  is  superscripted; in _n_r_o_f_f mode, it is sur‐
              rounded by square brackets.

       HH11ttxxtt  Updated by ..HH and ..HHUU to the current heading text.  Also updated
              in table of contents & friends.

       HHFF     assigns 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 “22 22 22 22 22 22 22 22 22 22 22 22 22 22”,
              which places all headings in italics.  DWB _m_m’s default was “33 33
              22 22 22 22 22”.

       HHPP     assigns 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 1100.   Omitted  values  are
              assumed  to  be 0 (and are translated accordingly).  The default
              is “00 00 00 00 00 00 00 00 00 00 00 00 00 00”.

       IInnddeexx  “INDEX”

       LLee     “LIST OF EQUATIONS”

       LLeettffcc  “Yours very truly,” (see FFCC)

       LLeettaapppp “APPROVED:” (see AAVV)

       LLeettAATT  “ATTENTION:” (see LLOO)

       LLeettCCNN  “CONFIDENTIAL” (see LLOO)

       LLeettddaattee
              “Date” (see AAVV)

       LLeettnnss  is a group of strings structuring the notations produced by  NNSS.
              If  the _c_o_d_e argument to NNSS has no corresponding string, the no‐
              tation  is   included   between   parentheses,   prefixed   with
              LLeettnnss!!ccooppyy,  and suffixed with LLeettnnss!!ttoo.  Observe the spaces af‐
              ter “Copy” and before “to”.

              NNSS ccooddee   SSttrriinngg       CCoonntteennttss
              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 _(_w_i_t_h _t_r_a_i_l_i_n_g _s_p_a_c_e_)
              —         Letns!to      to _(_n_o_t_e _l_e_a_d_i_n_g _s_p_a_c_e_)

       LLeettnnssddeeff
              Select the notation format used by NNSS when it is given no  argu‐
              ment.  The default is “00”.

       LLeettRRNN  “In reference to:” (see LLOO)

       LLeettSSAA  “To Whom It May Concern:” (see LLOO)

       LLeettSSJJ  “SUBJECT:” (see LLOO)

       LLff     “LIST OF FIGURES”

       LLiiccoonn  “CONTENTS”

       LLiieecc   “Equation”

       LLiieexx   “Exhibit”

       LLiiffgg   “Figure”

       LLiittbb   “TABLE”

       LLtt     “LIST OF TABLES”

       LLxx     “LIST OF EXHIBITS”

       MMOO11...MMOO1122
              “January” through “December”

       QQrrff    “See chapter \\*[Qrfh], page \\n[Qrfp].”

       RRff     interpolates  an automatically numbered reference mark; the num‐
              ber is used by the next RRSS call.  In _t_r_o_f_f mode, the  marker  is
              superscripted;  in _n_r_o_f_f mode, it is surrounded by square brack‐
              ets.

       RRpp     “REFERENCES”

       SSmm     interpolates ℠, the service mark sign.

       TTccsstt   interpolates an indicator of the TTCC macro’s  processing  status.
              If  TTCC  is  not  operating, it is empty.  User‐defined TTPP or EEOOPP
              macros might condition page headers or footers on its contents.

              VVaalluuee   MMeeaanniinngg
              co      Table of contents
              fg      List of figures
              tb      List of tables
              ec      List of equations
              ex      List of exhibits
              ap      Appendix

       TTmm     interpolates ™, the trade mark sign.

       VVeerrbbnnmm supplies argument(s) to the nnmm request employed  by  the  VVEERRBBOONN
              macro.  The default is “1”.

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

       ..mmggmm   indicates that _g_r_o_f_f _m_m is in use (Boolean‐valued; 11).

       ::pp     is an auto‐incrementing footnote counter; see FFSS.

       ::RR     is an auto‐incrementing reference counter; see RRSS.

       AApphh    formats an appendix heading (and title, if  supplied);  see  AAPPPP
              (Boolean‐valued; 11).

       AAuu     includes  supplemental  author information (the third and subse‐
              quent arguments to AAUU) in  memorandum  “from”  information;  see
              CCOOVVEERR and MMTT (Boolean‐valued; 11).

       CCll     sets  the threshold for inclusion of headings in a table of con‐
              tents.  Headings at levels above this value are excluded; see  HH
              and TTCC (22).  The CCll register controls whether a heading is _s_a_v_e_d
              for  output  in  the  table  of  contents at the time HH or HHUU is
              called; if you change CCll’s value immediately  prior  to  calling
              TTCC, you are unlikely to get the result you want.

       CCpp     suppresses  page breaks before lists of captioned equations, ex‐
              hibits, figures, and tables, and before an index;  see  EECC,  EEXX,
              FFGG, TTBB, and IINNDDPP (Boolean‐valued; 00).

       DD      produces  debugging  information for the _m_m 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 (00).

       DDee     causes  a  page break after a floating display is output; see DDFF
              (Boolean‐valued; 00).

       DDff     configures the behavior of DDFF.  The following values are  recog‐
              nized; 4 and 5 do not override the DDee register (55).

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

       DDss     puts  vertical  space in the amount of register DDsspp (if defined)
              or LLsspp before and after each static display;  see  DDSS  (Boolean‐
              valued; 11).

       DDsspp    configures  the amount of vertical space placed before and after
              static displays; see DDSS and register DDss (_u_n_d_e_f_i_n_e_d).

       EEcc     is an auto‐incrementing equation counter; see EECC.

       EEjj     sets 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 HH (00).

       EEqq     aligns an equation label to the left of a display instead of the
              right (Boolean‐valued; 00).

       EExx     is an auto‐incrementing exhibit counter; see EEXX.

       FFgg     is an auto‐incrementing figure counter; see FFGG.

       FFss     is  multiplied by register LLsspp to vertically separate footnotes;
              see FFSS (11).

       HH11...HH1144
              are auto‐incrementing counters  corresponding  to  each  heading
              level; see HH.

       HH11ddoott  appends  a  period  to  the number of a level one heading; see HH
              (Boolean‐valued; 11).

       HH11hh    is a copy of A copy of register register HH11, but  it  is  incre‐
              mented just before a page break.  This can be useful in user‐de‐
              fined macros; see HH and HHXX.

       HHbb     sets  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 HH (22).

       HHcc     sets the threshold for centering a heading.  Headings at  levels
              above this value use the prevailing alignment (that is, they are
              not centered); see HH (00).

       HHii     configures  the indentation of text after headings.  It does not
              affect “run‐in” headings.  The following values are  recognized;
              see HH and PP (11).

              VVaalluuee   EEffffeecctt
              0       no indentation
              1       indent per the paragraph type
              2       indent to align with heading title

       HHppss    sets  the  heading  level threshold for application of preceding
              vertical space; see HH.  Headings at levels above  the  value  in
              register HHppss use the amount of space in register HHppss11; otherwise
              that  in HHppss22.  The value of HHppss should be strictly greater than
              that of EEjj (11).

       HHppss11   configures the amount of  vertical  space  preceding  a  heading
              above  the  HHppss threshold; see HH (_t_r_o_f_f devices: 00..55vv; _n_r_o_f_f de‐
              vices: 11vv).

       HHppss22   configures the amount of vertical space preceding a  heading  at
              or  below the HHppss threshold; see HH (_t_r_o_f_f devices: 11vv; _n_r_o_f_f de‐
              vices: 22vv).

       HHss     sets the heading level threshold for application  of  succeeding
              vertical  space.   If  the heading level is greater than HHss, the
              heading is followed by vertical space in the  amount  of  regis‐
              ter HHssss; see HH (22).

       HHssss    is  multiplied  by  register LLsspp to produce vertical space after
              headings above the threshold in register HHss; see HH (11).

       HHtt     suppresses output of heading level  counters  above  the  lowest
              when the heading is formatted; see HH (Boolean‐valued; 00).

       HHuu     sets the heading level used by unnumbered headings; see HHUU (22).

       HHyy     enables automatic hyphenation of words (Boolean‐valued; 00).

       IIssoo    configures  the  use  of ISO 8601 date format if specified (with
              any value) on the command line; see IISSOODDAATTEE.  The default is de‐
              termined by localization files.

       LL      defines 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 _g_r_o_f_f output device.

       LLee
       LLff
       LLtt
       LLxx     configure the report of lists of equation,  figure,  table,  and
              exhibit  captions,  respectively, after a table of contents; see
              TTCC (Boolean‐valued; LLee: 00; LLff, LLtt, LLxx: 11).

       LLeettwwaamm sets the maximum number of input lines permitted in  a  writer’s
              address; see WWAA and WWEE (1144).

       LLii     configures  the  amount  of  indentation  in ens applied to list
              items; see LLII (66).

       LLiimmsspp  inserts a space between the prefix and the mark in automatically
              numbered lists; see AALL (Boolean‐valued; 11).

       LLss     sets 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 LLII (9999).

       LLsspp    configures the base amount of vertical space used for separation
              in  the  document.   _m_m  applies  this spacing to many contexts,
              sometimes with multipliers; see DDSS, FFSS, HH, LLII, and PP (_t_r_o_f_f  de‐
              vices: 00..55vv; _n_r_o_f_f devices: 11vv).

       NN      configures the header and footer placements used by PPHH.  The de‐
              fault footer is empty.  If “section‐page” numbering is selected,
              the  default header becomes empty and the default footer becomes
              “_x‐_y”, where _x is is the section number (the number of the  cur‐
              rent  first‐level heading) and _y the page number within the sec‐
              tion.  The following values are recognized; for  finer  control,
              see  PPHH,  PPFF, EEHH, EEFF, OOHH, and OOFF, and registers SSeeccttff and SSeeccttpp.
              Value 5 is a GNU extension (00).

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

       NNpp     causes  paragraphs  after first‐level headings (only) to be num‐
              bered in the format _s._p, where _s is is the section  number  (the
              number  of  the  current first‐level heading) and _p is the para‐
              graph number, starting at 1; see HH and PP (Boolean‐valued; 00).

       OO      defines the page offset of the document, and must  be  set  from
              the  command  line.  A scaling unit should be appended.  The de‐
              fault is ..7755ii on terminal devices.  On typesetters, it is  ..996633ii
              or set to 11ii by the _p_a_p_e_r_s_i_z_e_._t_m_a_c package; see _g_r_o_f_f___t_m_a_c(5).

       OOcc     suppresses  the  appearance of page numbers in the table of con‐
              tents; see TTCC (Boolean‐valued; 00).

       OOff     selects a separator format within equation, exhibit, figure, and
              table captions; see EECC, EEXX, FFGG, and TTBB.   The  following  values
              are recognized; the spaces shown are unpaddable (00).

              VVaalluuee   EEffffeecctt
              0       ".  "
              1       " — "

       PP      interpolates  the  current page number; it is the same as regis‐
              ter %% except when “section‐page” numbering is enabled.

       PPii     configures the amount of indentation in ens applied to the first
              line of a paragraph; see PP (55).

       PPggppss   causes the type size and vertical spacing set by SS to  apply  to
              headers  and  footers,  overriding the HHPP string.  If not set, SS
              calls affect headers and footers only when followed by  PPHH,  PPFF,
              OOHH, EEHH, OOFF, or OOEE calls (Boolean‐valued; 11).

       PPss     is multiplied by register LLsspp to vertically separate paragraphs;
              see PP (11).

       PPtt     determines  when  a first‐line indentation is applied to a para‐
              graph; see PP (00).

              VVaalluuee   EEffffeecctt
              0       never
              1       always
              2       always, except immediately after HH, DDEE, or LLEE

       RReeff    is used internally to control _m_m_r_o_f_f(1)’s two‐pass  approach  to
              index  and  reference management; see IINNIITTII and RRSS (Boolean‐val‐
              ued; 00).

       RRppee    configures the default page ejection policy for reference pages;
              see RRPP (00).

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

       SS      defines the type size for the document, and must be set from the
              command line.  A scaling unit should be appended; pp  is  typical
              (1100pp).

       SSeeccttff  selects  the “section‐figure” numbering style.  Its default is 00
              unless register NN is set to 55 at the command line  (Boolean‐val‐
              ued).

       SSeeccttpp  selects  the  “section‐page”  numbering style.  Its default is 00
              unless register NN is set to 33 or 55 at the command line (Boolean‐
              valued).

       SSii     configures the amount of display indentation in ens; see DDSS (55).

       TTbb     is an auto‐incrementing table counter; see TTBB.

       VV      defines the vertical spacing for the document, and must  be  set
              from  the command line.  A scaling unit should be appended; pp is
              typical.  The default vertical spacing is 120% of the type size.

       VVeerrbbiinn configures the amount of indentation for verbatim displays  when
              indentation is selected; see VVEERRBBOONN (55nn).

       WW      defines  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  66ii  or  assigned  by   the   _p_a_p_e_r_s_i_z_e_._t_m_a_c   package;   see
              _g_r_o_f_f___t_m_a_c(5).

IInntteerrnnaallss
       The  LLTT letter 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.  LLTT sets the registers PPtt and PPii to 0 and  5,  respec‐
       tively.   The  following macros must be defined to support a new letter
       type.

       lleett@@iinniitt___t_y_p_e
              LLTT calls this macro to initialize any registers and  other  data
              needed by the letter type.

       lleett@@hheeaadd___t_y_p_e
              formats  the  letterhead; it is called instead of the usual page
              header macro.  Its definition should remove the alias lleett@@hheeaaddeerr
              unless the letterhead is desired on subsequent pages.

       lleett@@ssgg___t_y_p_e _n_a_m_e _t_i_t_l_e _n _i_s_‐_f_i_n_a_l [_S_G_‐_a_r_g ...]
              SSGG calls this macro only for letters; MMTT  memoranda  have  their
              own  signature processing.  _n_a_m_e and _t_i_t_l_e are specified through
              WWAA/WWEE.  _n is the index of the _nth writer, and _i_s_‐_f_i_n_a_l  is  true
              for  the last writer to be listed.  Further SSGG arguments are ap‐
              pended to the signature line.

       lleett@@ffcc___t_y_p_e _c_l_o_s_i_n_g
              This macro is called by FFCC, and has the formal  closing  as  the
              argument.

       LLOO  implements letter options.  It requires that a string named LLeett_t_y_p_e
       be defined, where _t_y_p_e is the letter type.  LLOO then assigns its  second
       argument (_v_a_l_u_e) to the string lleett**lloo--_t_y_p_e.

FFiilleess
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_m_._t_m_a_c
              is the _g_r_o_f_f implementation of the memorandum macros.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_m_m_._t_m_a_c
              is wrapper to load _m_._t_m_a_c.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_r_e_f_e_r_-_m_m_._t_m_a_c
              implements _r_e_f_e_r(1) support for _m_m.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_m_m_/_m_s_._c_o_v
              implements an _m_s‐like cover sheet.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_m_m_/_0_._M_T
              implements memorandum types 0–3 and 6.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_m_m_/_4_._M_T
              implements memorandum type 4.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_m_m_/_5_._M_T
              implements memorandum type 5.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_m_m_/_l_o_c_a_l_e
              performs  any (further) desired necessary localization; empty by
              default.

AAuutthhoorrss
       The GNU version of the _m_m macro package was written by  Jörgen Hägg  of
       Lund, Sweden.

SSeeee aallssoo
       _M_M _- _A _M_a_c_r_o _P_a_c_k_a_g_e _f_o_r _G_e_n_e_r_a_t_i_n_g _D_o_c_u_m_e_n_t_s,  the  DWB 3.3 _m_m manual,
       introduces the package but does not document GNU extensions.

       _G_r_o_f_f_: _T_h_e _G_N_U _I_m_p_l_e_m_e_n_t_a_t_i_o_n _o_f _t_r_o_f_f, by Trent A. Fisher  and  Werner
       Lemberg,  is the primary _g_r_o_f_f manual.  You can browse it interactively
       with “info groff”.

       _g_r_o_f_f(1), _t_r_o_f_f(1), _t_b_l(1),  _p_i_c(1),  _e_q_n(1),  _r_e_f_e_r(1),  _g_r_o_f_f___m_m_s_e(7)
       (only in Swedish locales)

groff 1.23.0                      3 June 2025                      _g_r_o_f_f___m_m(7)
───────────────────────────────────────────────────────────────────────────────
_g_r_o_f_f___m_m_s_e(7)           Handbok för diverse information          _g_r_o_f_f___m_m_s_e(7)

NNaammnn
       groff_mmse - svenska ”memorandum” makro för GNU _r_o_f_f

SSyynnttaaxx
       ggrrooffff --mmmmssee [_f_l_a_g_g_o_r ...] [_f_i_l_e_r ...]
       ggrrooffff --mm mmmmssee [_f_l_a_g_g_o_r ...] [_f_i_l_e_r ...]

BBeesskkrriivvnniinngg
       _m_m_s_e  är  en svensk variant av _m_m. 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.

       CCOOVVEERR kan använda _s_e___m_s som argument. Detta ger ett  svenskt  försätts‐
       blad. Se _g_r_o_f_f___m_m(7) för övriga detaljer.

BBrreevv
       Tillgängliga brevtyper:

       ..LLTT SSVVVV
              Vänsterställd  löptext  med  adressat  i  position  T0 (vänster‐
              ställt).

       ..LLTT SSVVHH
              Högerställd löptext med adressat i position T4 (passar  fönster‐
              kuvert).

       Följande extra LO‐variabler används.

       ..LLOO DDNNAAMMNN _n_a_m_n
              Anger dokumentets namn.

       ..LLOO MMDDAATT _d_a_t_u_m
              Mottagarens datum, anges under EErrtt ddaattuumm:: (LLeettMMDDAATT).

       ..LLOO BBIILL _s_t_r_ä_n_g
              Anger  bilaga,  nummer eller sträng med BBiillaaggaa (LLeettBBIILL) som pre‐
              fix.

       ..LLOO KKOOMMPP _t_e_x_t
              Anger kompletteringsuppgift.

       ..LLOO DDBBEETT _b_e_t_e_c_k_n_i_n_g
              Anger dokumentbeteckning eller dokumentnummer.

       ..LLOO BBEETT _b_e_t_e_c_k_n_i_n_g
              Anger beteckning (ärendebeteckning i form av diarienummer  eller
              liknande).

       ..LLOO SSIIDDOORR _a_n_t_a_l
              Anger  totala  antalet  sidor och skrivs ut efter sidnumret inom
              parenteser.

       Om makrot ..TTPP är definierat anropas det efter utskrift av  brevhuvudet.
       Där lägger man lämpligen in postadress och annat som brevfot.

SSkkrriivveett aavv
       Jörgen Hägg, Lund, Sweden <Jorgen.Hagg@axis.se>

FFiilleerr
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_m_s_e_._t_m_a_c

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_m_m_/_s_e__*_._c_o_v

SSee oocckkssåå
       _g_r_o_f_f___m_m(7)

groff 1.23.0                      3 June 2025                    _g_r_o_f_f___m_m_s_e(7)
───────────────────────────────────────────────────────────────────────────────
_g_r_o_f_f___m_o_m(7)           Miscellaneous Information Manual           _g_r_o_f_f___m_o_m(7)

NNaammee
       groff_mom - modern macros for document composition with GNU _r_o_f_f

SSyynnooppssiiss
       ggrrooffff --mmoomm [_o_p_t_i_o_n ...] [_f_i_l_e ...]
       ggrrooffff --mm mmoomm [_o_p_t_i_o_n ...] [_f_i_l_e ...]

DDeessccrriippttiioonn
       _m_o_m  is  a macro set for _g_r_o_f_f, designed primarily to prepare documents
       for PDF and PostScript output.  _m_o_m provides macros in two  categories:
       typesetting  and  document  processing.   The  former provide access to
       _g_r_o_f_f’s typesetting capabilities in ways that  are  simpler  to  master
       than  _g_r_o_f_f’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  _p_d_f_m_o_m(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.  _g_r_o_f_f’s native PDF driver, _g_r_o_p_d_f(1), is  used  to  generate
       the output.  When _p_d_f_m_o_m is given the “--TT ppss” option, it still produces
       PDF,  but  processing is delegated to _p_d_f_r_o_f_f, which uses _g_r_o_f_f’s Post‐
       Script driver, _g_r_o_p_s(1).  Not all PDF features are available when --TT ppss
       is given; its primary use is to allow processing of files with embedded
       PostScript images.

       Files processed with ggrrooffff --mmoomm (or --mm mmoomm) format for the device spec‐
       ified with the --TT option.  (In this installation,  ppss  is  the  default
       output device.)

       _m_o_m comes with her own comprehensive documentation in HTML.  A PDF man‐
       ual,  “Producing PDFs with _g_r_o_f_f and _m_o_m”, discusses preparation of PDF
       documents with _m_o_m in detail.

FFiilleess
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_m_o_m_._t_m_a_c
              is a wrapper enabling the package to be loaded  with  “ggrrooffff  --mm
              mmoomm”.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_o_m_._t_m_a_c
              implements the package.

       _/_u_s_r_/_s_h_a_r_e_/_d_o_c_/_g_r_o_f_f_-_b_a_s_e_/_h_t_m_l_/_m_o_m_/_t_o_c_._h_t_m_l
              is the entry point to the HTML documentation.

       _/_u_s_r_/_s_h_a_r_e_/_d_o_c_/_g_r_o_f_f_-_b_a_s_e_/_p_d_f_/_m_o_m_-_p_d_f_._p_d_f
              is  “Producing PDFs with _g_r_o_f_f and _m_o_m”, by Deri James and Peter
              Schaffter.

       _/_u_s_r_/_s_h_a_r_e_/_d_o_c_/_g_r_o_f_f_-_b_a_s_e_/_e_x_a_m_p_l_e_s_/_m_o_m_/*_._m_o_m
              are examples of _m_o_m usage.

RReeffeerreennccee
   EEssccaappee sseeqquueenncceess
       \\**[[_<_c_o_l_o_r_n_a_m_e_>]]
              begin using an initialized colour inline

       \\**[[BBCCKK _n]]
              move backward in a line

       \\**[[BBOOLLDDEERR]]
              invoke pseudo bold inline (related to macro ..SSEETTBBOOLLDDEERR)

       \\**[[BBOOLLDDEERRXX]]
              off pseudo bold inline (related to macro ..SSEETTBBOOLLDDEERR)

       \\**[[BBUU _n]]
              move characters pairs closer together inline (related  to  macro
              ..KKEERRNN)

       \\**[[CCOONNDD]]
              invoke pseudo condensing inline (related to macro ..CCOONNDDEENNSSEE)

       \\**[[CCOONNDDXX]]
              off pseudo condensing inline (related to macro ..CCOONNDDEENNSSEE)

       \\**[[CCOONNDDSSUUPP]]...\\**[[CCOONNDDSSUUPPXX]]
              pseudo‐condensed superscript

       \\**[[DDOOWWNN _n]]
              temporarily move downward in a line

       \\**[[EENN--MMAARRKK]]
              mark  initial line of a range of line numbers (for use with line
              numbered endnotes)

       \\**[[EEXXTT]]
              invoke pseudo extending inline (related to macro ..EEXXTTEENNDD)

       \\**[[EEXXTTXX]]
              off pseudo condensing inline (related to macro ..EEXXTTEENNDD)

       \\**[[EEXXTTSSUUPP]]...\\**[[EEXXTTSSUUPPXX]]
              pseudo extended superscript

       \\**[[FFUU _n]]
              move characters pairs further apart  inline  (related  to  macro
              ..KKEERRNN)

       \\**[[FFWWDD _n]]
              move forward in a line

       \\**[[LLEEAADDEERR]]
              insert leaders at the end of a line

       \\**[[RRUULLEE]]
              draw a full measure rule

       \\**[[SSIIZZEE _n]]
              change the point size inline (related to macro ..PPTT__SSIIZZEE)

       \\**[[SSLLAANNTT]]
              invoke pseudo italic inline (related to macro ..SSEETTSSLLAANNTT)

       \\**[[SSLLAANNTTXX]]
              off pseudo italic inline (related to macro ..SSEETTSSLLAANNTT)

       \\**[[SSTT_<_n_>]]...\\**[[SSTT_<_n_>XX]]
              string tabs (mark tab positions inline)

       \\**[[SSUUPP]]...\\**[[SSUUPPXX]]
              superscript

       \\**[[TTBB++]]
              inline escape for ..TTNN (_T_a_b _N_e_x_t)

       \\**[[UULL]]...\\**[[UULLXX]]
              invoke underlining inline (fixed width fonts only)

       \\**[[UUPP _n]]
              temporarily move upward in a line

   MMaaccrrooss
       ..AAUUTTOOLLEEAADD
              set the linespacing relative to the point size

       ..BB__MMAARRGGIINN
              set a bottom margin

       ..BBRR    break a justified line

       ..CCEENNTTEERR
              set line‐by‐line quad centre

       ..CCOONNDDEENNSSEE
              set the amount to pseudo condense

       ..EELL    break a line without advancing on the page

       ..EEXXTTEENNDD
              set the amount to pseudo extend

       ..FFAALLLLBBAACCKK__FFOONNTT
              establish a fallback font (for missing fonts)

       ..FFAAMM   alias to ..FFAAMMIILLYY

       ..FFAAMMIILLYY _<_f_a_m_i_l_y_>
              set the _f_a_m_i_l_y _t_y_p_e

       ..FFTT    set the font style (roman, italic, etc.)

       ..HHII [[ _<_m_e_a_s_u_r_e_> ]]
              hanging indent

       ..HHYY    automatic hyphenation on/off

       ..HHYY__SSEETT
              set automatic hyphenation parameters

       ..IIBB [[ _<_l_e_f_t _m_e_a_s_u_r_e_> _<_r_i_g_h_t _m_e_a_s_u_r_e_> ]]
              indent both

       ..IIBBXX [[ CCLLEEAARR ]]
              exit indent both

       ..IILL [[ _<_m_e_a_s_u_r_e_> ]]
              indent left

       ..IILLXX [[ CCLLEEAARR ]]
              exit indent left

       ..IIQQ [[ CCLLEEAARR ]]
              quit any/all indents

       ..IIRR [[ _<_m_e_a_s_u_r_e_> ]]
              indent right

       ..IIRRXX [[ CCLLEEAARR ]]
              exit indent right

       ..JJUUSSTTIIFFYY
              justify text to both margins

       ..KKEERRNN  automatic character pair kerning on/off

       ..LL__MMAARRGGIINN
              set a left margin (page offset)

       ..LLEEFFTT  set line‐by‐line quad left

       ..LLLL    set a line length

       ..LLSS    set a linespacing (leading)

       ..PPAAGGEE  set explicit page dimensions and margins

       ..PPAAGGEEWWIIDDTTHH
              set a custom page width

       ..PPAAGGEELLEENNGGTTHH
              set a custom page length

       ..PPAAPPEERR _<_p_a_p_e_r___t_y_p_e_>
              set common paper sizes (letter, A4, etc)

       ..PPTT__SSIIZZEE
              set the point size

       ..QQUUAADD  "justify" text left, centre, or right

       ..RR__MMAARRGGIINN
              set a right margin

       ..RRIIGGHHTT set line‐by‐line quad right

       ..SSEETTBBOOLLDDEERR
              set the amount of emboldening

       ..SSEETTSSLLAANNTT
              set the degree of slant

       ..SSPPRREEAADD
              force justify a line

       ..SSSS    set the sentence space size

       ..TT__MMAARRGGIINN
              set a top margin

       ..TTII [[ _<_m_e_a_s_u_r_e_> ]]
              temporary left indent

       ..WWSS    set the minimum word space size

DDooccuummeennttaattiioonn ooff ddeettaaiillss
   DDeettaaiillss ooff iinnlliinnee eessccaappee sseeqquueenncceess iinn aallpphhaabbeettiiccaall oorrddeerr
       \\**[[_<_c_o_l_o_r_n_a_m_e_>]]
              begin using an initialized colour inline

       \\**[[BBCCKK _n]]
              move backward in a line

       \\**[[BBOOLLDDEERR]]
       \\**[[BBOOLLDDEERRXX]]
              Emboldening on/off

              \\**[[BBOOLLDDEERR]]  begins emboldening type.  \\**[[BBOOLLDDEERRXX]] turns 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 \\**[[BBOOLLDDEERR]]everything\\**[[BBOOLLDDEERRXX]] is as it seems.

              Alternatively, if you wanted  the  whole  line  emboldened,  you
              should do
                     \\**[[BBOOLLDDEERR]]Not everything is as it seems.\\**[[BBOOLLDDEERRXX]]
              Once  \\**[[BBOOLLDDEERR]]  is  invoked, it remains in effect until turned
              off.

              Note: If  you’re  using  the  document  processing  macros  with
              ..PPRRIINNTTSSTTYYLLEE TTYYPPEEWWRRIITTEE, _m_o_m ignores \\**[[BBOOLLDDEERR]] requests.

       \\**[[BBUU _n]]
              move  characters  pairs closer together inline (related to macro
              ..KKEERRNN)

       \\**[[CCOONNDD]]
       \\**[[CCOONNDDXX]]
              Pseudo‐condensing on/off

              \\**[[CCOONNDD]] begins pseudo‐condensing  type.   \\**[[CCOONNDDXX]]  turns  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:
                     \\**[[CCOONNDD]]_N_o_t _e_v_e_r_y_t_h_i_n_g _i_s _a_s _i_t _s_e_e_m_s_.\\**[[CCOONNDDXX]]
              \\**[[CCOONNDD]] remains in effect until you turn it off with \\**[[CCOONNDDXX]].

              IMPORTANT:  You must turn \\**[[CCOONNDD]] off before making any changes
              to the point size of your type, either via the ..PPTT__SSIIZZEE macro or
              with the \\ss inline escape sequence.  If you wish the  new  point
              size to be pseudo‐condensed, simply reinvoke \\**[[CCOONNDD]] afterward.
              Equally,  \\**[[CCOONNDD]]  must  be turned off before changing the con‐
              dense percentage with ..CCOONNDDEENNSSEE.

              Note: If  you’re  using  the  document  processing  macros  with
              ..PPRRIINNTTSSTTYYLLEE TTYYPPEEWWRRIITTEE, _m_o_m ignores \\**[[CCOONNDD]] requests.

       \\**[[CCOONNDDSSUUPP]]...\\**[[CCOONNDDSSUUPPXX]]
              pseudo‐condensed superscript

       \\**[[DDOOWWNN _n]]
              temporarily move downward in a line

       \\**[[EENN--MMAARRKK]]
              mark  initial line of a range of line numbers (for use with line
              numbered endnotes)

       \\**[[EEXXTT]]
       \\**[[EEXXTTXX]]
              Pseudo‐extending on/off

              \\**[[EEXXTT]] begins pseudo‐extending type.  \\**[[EEXXTTXX]] turns  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:
                     \\**[[EEXXTT]]_N_o_t _e_v_e_r_y_t_h_i_n_g _i_s _a_s _i_t _s_e_e_m_s_.\\**[[EEXXTTXX]]
              \\**[[EEXXTT]] remains in effect until you turn it off with \\**[[EEXXTTXX]].

              IMPORTANT:  You  must turn \\**[[EEXXTT]] off before making any changes
              to the point size of your type, either via the ..PPTT__SSIIZZEE macro or
              with the \\ss inline escape sequence.  If you wish the  new  point
              size  to  be _p_s_e_u_d_o_‐_e_x_t_e_n_d_e_d, simply reinvoke \\**[[EEXXTT]] afterward.
              Equally, \\**[[EEXXTT]] must be turned off before changing  the  extend
              percentage with ..EEXXTTEENNDD.

              Note:  If  you  are  using  the  document processing macros with
              ..PPRRIINNTTSSTTYYLLEE TTYYPPEEWWRRIITTEE, _m_o_m ignores \\**[[EEXXTT]] requests.

       \\**[[EEXXTTSSUUPP]]...\\**[[EEXXTTSSUUPPXX]]
              pseudo extended superscript

       \\**[[FFUU _n]]
              move characters pairs further apart  inline  (related  to  macro
              ..KKEERRNN)

       \\**[[FFWWDD _n]]
              move forward in a line

       \\**[[LLEEAADDEERR]]
              insert leaders at the end of a line

       \\**[[RRUULLEE]]
              draw a full measure rule

       \\**[[SSIIZZEE _n]]
              change the point size inline (related to macro ..PPTT__SSIIZZEE)

       \\**[[SSLLAANNTT]]
       \\**[[SSLLAANNTTXX]]
              Pseudo italic on/off

              \\**[[SSLLAANNTT]]  begins _p_s_e_u_d_o_‐_i_t_a_l_i_c_i_z_i_n_g _t_y_p_e.  \\**[[SSLLAANNTTXX]] turns 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 \\**[[SSLLAANNTT]]everything\\**[[SSLLAANNTTXX]] is as it seems.

              Alternatively, if you wanted the whole  line  _p_s_e_u_d_o_‐_i_t_a_l_i_c_i_z_e_d,
              you’d do
                     \\**[[SSLLAANNTT]]Not everything is as it seems.\\**[[SSLLAANNTTXX]]

              Once  \\**[[SSLLAANNTT]]  is  invoked,  it remains in effect until turned
              off.

              Note: If  you’re  using  the  document  processing  macros  with
              ..PPRRIINNTTSSTTYYLLEE TTYYPPEEWWRRIITTEE, _m_o_m underlines pseudo‐italics by default.
              To    change    this    behaviour,   use   the   special   macro
              ..SSLLAANNTT__MMEEAANNSS__SSLLAANNTT.

       \\**[[SSTT_<_n_u_m_b_e_r_>]]...\\**[[SSTT_<_n_u_m_b_e_r_>XX]]
              Mark positions of string tabs

              The _q_u_a_d direction must  be  LLEEFFTT  or  JJUUSSTTIIFFYY  (see  ..QQUUAADD  and
              ..JJUUSSTTIIFFYY) or the _n_o_‐_f_i_l_l _m_o_d_e set to LLEEFFTT in order for these in‐
              lines to function properly.  Please see _I_M_P_O_R_T_A_N_T, below.

              String  tabs  need to be marked off with inline escape sequences
              before being set up with the ..SSTT macro.  Any input line may con‐
              tain string tab markers.  _<_n_u_m_b_e_r_>,  above,  means  the  numeric
              identifier of the tab.

              The following shows a sample input line with string tab markers.
                     \\**[[SSTT11]]De minimus\\**[[SSTT11XX]]non curat\\**[[SSTT22]]lex\\**[[SSTT22XX]].

              String  _t_a_b _1 begins at the start of the line and ends after the
              word _t_i_m_e.  String _t_a_b _2 starts at _g_o_o_d and ends after _m_e_n.  _I_n_‐
              _l_i_n_e _e_s_c_a_p_e _s_e_q_u_e_n_c_e_s (e.g., _f_o_n_t or _p_o_i_n_t _s_i_z_e _c_h_a_n_g_e_s, or hor‐
              izontal movements, including padding)  are  taken  into  account
              when _m_o_m determines the _p_o_s_i_t_i_o_n and _l_e_n_g_t_h of _s_t_r_i_n_g _t_a_b_s.

              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 _s_e_t with ..SSTT, after which they may be called, by number, with
              ..TTAABB.

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

              _I_M_P_O_R_T_A_N_T_:  Owing  to  the  way  _g_r_o_f_f processes input lines and
              turns them into output lines, it is  not  possible  for  _m_o_m  to
              _g_u_e_s_s 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 ..SSPPRREEAADD.

              In other words, in order to use string tabs, LLEEFFTT  must  be  ac‐
              tive, or, if ..QQUUAADD LLEEFFTT or JJUUSSTTIIFFYY are active, the line on which
              the _s_t_r_i_n_g _t_a_b_s are marked must be broken _m_a_n_u_a_l_l_y with ..BBRR (but
              not ..SSPPRREEAADD).

              To  circumvent  this behaviour, I recommend using the PPAADD to set
              up string tabs in centered or flush right lines.  Say, for exam‐
              ple, you want to use a _s_t_r_i_n_g _t_a_b to _u_n_d_e_r_s_c_o_r_e the  text  of  a
              centered line with a rule.  Rather than this,
                     ..CCEENNTTEERR
                     \\**[[SSTT11]]AA lliinnee ooff tteexxtt\\**[[SSTT11XX]]\\cc
                     ..EELL
                     ..SSTT 11
                     ..TTAABB 11
                     ..PPTT__SSIIZZEE 2244
                     ..AALLDD 33pp
                     \\**[[RRUULLEE]]
                     ..RRLLDD 33pp
                     ..TTQQ
              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

       \\**[[SSUUPP]]...\\**[[SSUUPPXX]]
              superscript

       \\**[[TTBB++]]
              Inline escape for ..TTNN (_T_a_b _N_e_x_t)

       \\**[[UULL]]...\\**[[UULLXX]]
              invoke underlining inline (fixed width fonts only)

       \\**[[UUPP _n]]
              temporarily move upward in a line

   DDeettaaiillss ooff mmaaccrrooss iinn aallpphhaabbeettiiccaall oorrddeerr
       ..AAUUTTOOLLEEAADD
              set the linespacing relative to the point size

       ..BB__MMAARRGGIINN _<_b_o_t_t_o_m _m_a_r_g_i_n_>
              Bottom Margin

              Requires a unit of measure

              ..BB__MMAARRGGIINN  sets 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, _m_o_m starts a new  page.   ..BB__MMAARRGGIINN  rreeqquuiirreess  aa
              uunniitt ooff mmeeaassuurree..  Decimal fractions are allowed.  To set a nomi‐
              nal bottom margin of 3/4 inch, enter
                     ..BB__MMAARRGGIINN ..7755ii

              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  _g_r_o_f_f,  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 ..BB__MMAARRGGIINN is slightly different when you’re
              using the document processing macros.

       ..FFAALLLLBBAACCKK__FFOONNTT _<_f_a_l_l_b_a_c_k _f_o_n_t_> [[ AABBOORRTT || WWAARRNN ]]
              Fallback Font

              In  the event that you pass an invalid argument to ..FFAAMMIILLYY (i.e.
              a non‐existent _f_a_m_i_l_y), _m_o_m, by default, uses the _f_a_l_l_b_a_c_k _f_o_n_t,
              CCoouurriieerr MMeeddiiuumm RRoommaann (CCRR), in order to continue processing  your
              file.

              If  you’d  prefer another _f_a_l_l_b_a_c_k _f_o_n_t, pass ..FFAALLLLBBAACCKK__FFOONNTT the
              full _f_a_m_i_l_y_+_f_o_n_t _n_a_m_e of the _f_o_n_t you’d like.  For  example,  if
              you’d rather the _f_a_l_l_b_a_c_k _f_o_n_t were TTiimmeess RRoommaann MMeeddiiuumm RRoommaann,
                     ..FFAALLLLBBAACCKK__FFOONNTT TTRR
              would do the trick.

              MMoomm issues a warning whenever a _f_o_n_t _s_t_y_l_e _s_e_t with ..FFTT does not
              exist,  either  because  you haven’t registered the style or be‐
              cause the _f_o_n_t _s_t_y_l_e does not exist in the  current  _f_a_m_i_l_y  _s_e_t
              with  ..FFAAMMIILLYY.  By default, mmoomm then aborts, which allows you to
              correct the problem.

              If you’d prefer that mmoomm not abort on  non‐existent  _f_o_n_t_s,  but
              rather  continue  processing using a _f_a_l_l_b_a_c_k _f_o_n_t, you can pass
              ..FFAALLLLBBAACCKK__FFOONNTT the argument WWAARRNN, either by itself, or  in  con‐
              junction with your chosen _f_a_l_l_b_a_c_k _f_o_n_t..

              Some examples of invoking ..FFAALLLLBBAACCKK__FFOONNTT:

              ..FFAALLLLBBAACCKK__FFOONNTT WWAARRNN
                     _m_o_m  will  issue  a  warning whenever you try to access a
                     non‐existent _f_o_n_t but will continue processing your  file
                     with the default _f_a_l_l_b_a_c_k _f_o_n_t, CCoouurriieerr MMeeddiiuumm RRoommaann.

              ..FFAALLLLBBAACCKK__FFOONNTT TTRR WWAARRNN
                     mmoomm  will  issue  a  warning whenever you try to access a
                     non‐existent _f_o_n_t but will continue processing your  file
                     with  a  _f_a_l_l_b_a_c_k _f_o_n_t of TTiimmeess RRoommaann MMeeddiiuumm RRoommaann; addi‐
                     tionally, TTRR will be the _f_a_l_l_b_a_c_k _f_o_n_t whenever  you  try
                     to access a _f_a_m_i_l_y that does not exist.

              ..FFAALLLLBBAACCKK__FFOONNTT TTRR AABBOORRTT
                     mmoomm  will abort whenever you try to access a non‐existent
                     ffoonntt, and will use the _f_a_l_l_b_a_c_k _f_o_n_t TTRR whenever you  try
                     to  access  a  _f_a_m_i_l_y  that does not exist.  If, for some
                     reason,  you  want  to  revert  to  AABBOORRTT,   just   enter
                     ""..FFAALLLLBBAACCKK__FFOONNTT  AABBOORRTT""  and _m_o_m will once again abort on
                     _f_o_n_t _e_r_r_o_r_s.

       ..FFAAMM _<_f_a_m_i_l_y_>
              Type Family, alias of ..FFAAMMIILLYY

       ..FFAAMMIILLYY _<_f_a_m_i_l_y_>
              Type Family, alias of ..FFAAMM

              ..FFAAMMIILLYY takes one argument: the name of  the  _f_a_m_i_l_y  you  want.
              _G_r_o_f_f  comes with a small set of basic families, each identified
              by a 1‐, 2‐ or 3‐letter mnemonic.  The standard families are:
                     AA   == AAvvaanntt GGaarrddee
                     BBMM  == BBooookkmmaann
                     HH   == HHeellvveettiiccaa
                     HHNN  == HHeellvveettiiccaa NNaarrrrooww
                     NN   == NNeeww CCeennttuurryy SScchhoooollbbooookk
                     PP   == PPaallaattiinnoo
                     TT   == TTiimmeess RRoommaann
                     ZZCCMM == ZZaappff CChhaanncceerryy

              The argument you pass to ..FFAAMMIILLYY  is  the  identifier  at  left,
              above.  For example, if you want HHeellvveettiiccaa, enter
                     ..FFAAMMIILLYY HH

              Note: The font macro (..FFTT) lets you specify both the type _f_a_m_i_l_y
              and  the  desired  font with a single macro.  While this saves a
              few keystrokes, I recommend using ..FFAAMMIILLYY ffoorr  _f_a_m_i_l_y,  and  ..FFTT
              ffoorr _f_o_n_t, except where doing so is genuinely inconvenient.  ZZCCMM,
              for example, only exists in one style: IIttaalliicc (II).

              Therefore,
                     ..FFTT ZZCCMMII
              makes  more  sense  than setting the _f_a_m_i_l_y to ZZCCMM, then setting
              the _f_o_n_t to _I.

              Additional note: If you are running a  _g_r_o_f_f  version  prior  to
              1.19.2, you must follow all ..FFAAMMIILLYY requests with a ..FFTT request,
              otherwise  _m_o_m  will  set all type up to the next ..FFTT request in
              the fallback font.

              If you are running _g_r_o_f_f 1.19.2 or later, when  you  invoke  the
              ..FFAAMMIILLYY macro, _m_o_m _r_e_m_e_m_b_e_r_s the font style ((Roman,, IIttaalliicc, etc)
              currently  in  use  (if the font style exists in the new _f_a_m_i_l_y)
              and will continue to use the same font style in the new  family.
              For example:
                     ..FFAAMMIILLYY BBMM _\_" _B_o_o_k_m_a_n _f_a_m_i_l_y
                     ..FFTT II _\_" _M_e_d_i_u_m _I_t_a_l_i_c
                     _<_s_o_m_e _t_e_x_t_> _\_" _B_o_o_k_m_a_n _M_e_d_i_u_m _I_t_a_l_i_c
                     ..FFAAMMIILLYY HH _\_" _H_e_l_v_e_t_i_c_a _f_a_m_i_l_y
                     _<_m_o_r_e _t_e_x_t_> _\_" _H_e_l_v_e_t_i_c_a _M_e_d_i_u_m _I_t_a_l_i_c

              However, if the font style does not exist in the new family, _m_o_m
              will  set  all subsequent type in the fallback font (by default,
              CCoouurriieerr MMeeddiiuumm RRoommaann) until she encounters a ..FFTT request  that’s
              valid for the _f_a_m_i_l_y.

              For  example,  assuming you don’t have the font MMeeddiiuumm CCoonnddeennsseedd
              RRoommaann (_m_o_m extension _C_D) in the _H_e_l_v_e_t_i_c_a _f_a_m_i_l_y:
                     ..FFAAMMIILLYY UUNN _\_" _U_n_i_v_e_r_s _f_a_m_i_l_y
                     ..FFTT CCDD _\_" _M_e_d_i_u_m _C_o_n_d_e_n_s_e_d
                     _<_s_o_m_e _t_e_x_t_> _\_" _U_n_i_v_e_r_s _M_e_d_i_u_m _C_o_n_d_e_n_s_e_d
                     ..FFAAMMIILLYY HH _\_" _H_e_l_v_e_t_i_c_a _f_a_m_i_l_y
                     _<_m_o_r_e _t_e_x_t_> _\_" _C_o_u_r_i_e_r _M_e_d_i_u_m _R_o_m_a_n_!

              In the above example, you must follow ..FFAAMMIILLYY HH with a  ..FFTT  re‐
              quest that’s valid for HHeellvveettiiccaa.

              Please  see  the Appendices, _A_d_d_i_n_g _f_o_n_t_s _t_o _g_r_o_f_f, for informa‐
              tion on adding fonts and families to _g_r_o_f_f,_a_swell_a_sto see a list
              of the extensions _m_o_m provides to _g_r_o_f_f’s  basic  RR,  II,  BB,  BBII
              styles.

              Suggestion: When adding _f_a_m_i_l_i_e_s _t_o _g_r_o_f_f, I recommend following
              the established standard for the naming families and fonts.  For
              example, if you add the GGaarraammoonndd family, name the font files
                     GGAARRAAMMOONNDDRR
                     GGAARRAAMMOONNDDII
                     GGAARRAAMMOONNDDBB
                     GGAARRAAMMOONNDDBBII
              GGAARRAAMMOONNDD tthheenn bbeeccoommeess aa vvaalliidd _f_a_m_i_l_y _n_a_m_e you can pass to ..FFAAMMII‐‐
              LLYY.   (You could, of course, shorten GGAARRAAMMOONNDD to just GG, or GGDD.)
              RR, II, BB, and BBII after GGAARRAAMMOONNDD are the _r_o_m_a_n, _i_t_a_l_i_c,  _b_o_l_d  and
              _b_o_l_d_‐_i_t_a_l_i_c fonts respectively.

       ..FFOONNTT RR || BB || BBII || _<_a_n_y _o_t_h_e_r _v_a_l_i_d _f_o_n_t _s_t_y_l_e_>
              Alias to ..FFTT

       ..FFTT RR || BB || BBII || _<_a_n_y _o_t_h_e_r _v_a_l_i_d _f_o_n_t _s_t_y_l_e_>
              Set font

              By default, _g_r_o_f_f permits ..FFTT to take one of four possible argu‐
              ments specifying the desired font:
                     RR == ((MMeeddiiuumm)) RRoommaann
                     II == ((MMeeddiiuumm)) IIttaalliicc
                     BB == BBoolldd ((RRoommaann))
                     BBII == BBoolldd IIttaalliicc

              For example, if your _f_a_m_i_l_y is HHeellvveettiiccaa, entering
                     ..FFTT BB
              will  give  you  the  _H_e_l_v_e_t_i_c_a  _b_o_l_d _f_o_n_t.  If your _f_a_m_i_l_y were
              PPaallaattiinnoo, you’d get the _P_a_l_a_t_i_n_o _b_o_l_d _f_o_n_t.

              MMoomm considerably extends the range of arguments you can pass  to
              ..FFTT,  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  _m_o_m
              allows.   Be  aware,  though, that you must have the fonts, cor‐
              rectly installed and named, in order to use the arguments.  (See
              _A_d_d_i_n_g _f_o_n_t_s _t_o _g_r_o_f_f for instructions and information.)  Please
              also read the _A_D_D_I_T_I_O_N_A_L _N_O_T_E found in the  description  of  the
              ..FFAAMMIILLYY macro.

              How  _m_o_m  reacts  to an invalid argument to ..FFTT depends on which
              version of _g_r_o_f_f you’re using.  If your _g_r_o_f_f version is  1.19.2
              or  later, _m_o_m 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, _m_o_m will silently continue processing,  us‐
              ing either the fallback font or the font that was in effect pri‐
              or to the invalid ..FFTT call.

              ..FFTT  will  also  accept,  as an argument, a full _f_a_m_i_l_y and _f_o_n_t
              _n_a_m_e.

              For example,
                     ..FFTT HHBB
              will set subsequent type in _H_e_l_v_e_t_i_c_a _B_o_l_d.

              However, I strongly recommend keeping _f_a_m_i_l_y and  _f_o_n_t  separate
              except where doing so is genuinely inconvenient.

              For inline control of _f_o_n_t_s, see _I_n_l_i_n_e _E_s_c_a_p_e_s, font control.

       ..HHII [[ _<_m_e_a_s_u_r_e_> ]]
              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 _h_a_n_g_s outside the _l_e_f_t _m_a_r_g_i_n.

              In order to use _h_a_n_g_i_n_g _i_n_d_e_n_t_s, you must first have a _l_e_f_t  _i_n_‐
              _d_e_n_t  active  (set  with  either ..IILL or ..IIBB).  MMoomm will not hang
              text outside the _l_e_f_t _m_a_r_g_i_n _s_e_t with ..LL__MMAARRGGIINN or  outside  the
              _l_e_f_t _m_a_r_g_i_n of a _t_a_b.

              The  first  time you invoke ..HHII, you must give it a mmeeaassuurree.  If
              you want the first line of a paragraph to _h_a_n_g _b_y, say, _1  _p_i_c_a,
              do
                     ..IILL 11PP
                     ..HHII 11PP
              Subsequent  invocations  of  ..HHII  do not require you to supply a
              _m_e_a_s_u_r_e; _m_o_m keeps track of the last measure you gave it.

              Generally speaking, you should invoke ..HHII immediately  prior  to
              the  line  you  want  hung (i.e. without any intervening control
              lines).  And because  _h_a_n_g_i_n_g  _i_n_d_e_n_t_s  affect  only  one  line,
              there’s no need to turn them off.

              _I_M_P_O_R_T_A_N_T_:  Unlike  IILL, IIRR and IIBB, measures given to ..HHII are NOT
              additive.  Each time you pass a measure to ..HHII, the  measure  is
              treated  literally.   _R_e_c_i_p_e_:  A numbered list using _h_a_n_g_i_n_g _i_n_‐
              _d_e_n_t_s

              _N_o_t_e_: _m_o_m has macros for setting lists.  This recipe  exists  to
              demonstrate the use of _h_a_n_g_i_n_g _i_n_d_e_n_t_s 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 (_T_h_e _m_o_s_t _i_m_p_o_r_t_a_n_t _p_o_i_n_t_._._.) starts at exactly
              the same spot as the indented lines that follow.

              Notice that subsequent invocations of ..HHII don’t require  a  _m_e_a_‐
              _s_u_r_e to be given.

              Paste the example above into a file and preview it with
                     ppddffmmoomm ffiilleennaammee..mmoomm || ppss22ppddff -- ffiilleennaammee..ppddff
              to see hanging indents in action.

       ..IIBB [[ _<_l_e_f_t _m_e_a_s_u_r_e_> _<_r_i_g_h_t _m_e_a_s_u_r_e_> ]]
              Indent both — the optional argument requires a unit of measure

              ..IIBB allows 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 ..IILL and ..IIRR, 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.

              _A _w_o_r_d _o_f _a_d_v_i_c_e_: If you need to manipulate left and  right  in‐
              dents  separately,  use  a combination of ..IILL and ..IIRR instead of
              ..IIBB.  You’ll save yourself a lot of grief.

              A _m_i_n_u_s _s_i_g_n 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,
                     ..IIBB \\ww''mmaarrggaarriinnee'' \\ww''jjeelllloo''
              left  indents  text by the width of the word _m_a_r_g_a_r_i_n_e and right
              indents by the width of _j_e_l_l_o.

              Like ..IILL and ..IIRR, ..IIBB with no argument indents by its  last  ac‐
              tive  values.   See the brief explanation of how mom handles in‐
              dents for more details.

              _N_o_t_e_: Calling a _t_a_b (with ..TTAABB <<nn>>)  automatically  cancels  any
              active indents.

              _A_d_d_i_t_i_o_n_a_l  _n_o_t_e_:  Invoking  ..IIBB automatically turns off ..IILL and
              ..IIRR.

       ..IILL [[ _<_m_e_a_s_u_r_e_> ]]
              Indent left — the optional argument requires a unit of measure

              ..IILL indents text from the left margin of the page, or if  you’re
              in  a  _t_a_b,  from  the left edge of the _t_a_b.  Once _I_L is on, the
              _l_e_f_t _i_n_d_e_n_t is applied uniformly to  every  subsequent  line  of
              text, even if you change the line length.

              The first time you invoke ..IILL, 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 \\ww inline escape may be used to speci‐
              fy a text‐dependent measure, in which case no unit of measure is
              required.  For example,
                     ..IILL \\ww''mmaarrggaarriinnee''
              indents text by the width of the word _m_a_r_g_a_r_i_n_e.

              With no argument, ..IILL indents by its last active value.  See the
              brief explanation of how _m_o_m handles indents for more details.

              _N_o_t_e_:  Calling  a  _t_a_b (with ..TTAABB <<nn>>) automatically cancels any
              active indents.

              _A_d_d_i_t_i_o_n_a_l _n_o_t_e_: Invoking ..IILL automatically turns off IIBB.

       ..IIQQ [[ _<_m_e_a_s_u_r_e_> ]]
              IQ — quit any/all indents

              _I_M_P_O_R_T_A_N_T _N_O_T_E_: The original macro for quitting all indents  was
              ..IIXX.   This usage has been deprecated in favour of IIQQ.  ..IIXX will
              continue to behave as before, but _m_o_m will issue  a  warning  to
              _s_t_d_e_r_r indicating that you should update your documents.

              As a consequence of this change, ..IILLXX, ..IIRRXX and ..IIBBXX may now al‐
              so  be  invoked  as ..IILLQQ, ..IIRRQQ and ..IIBBQQ.  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 CCLLEEAARR, 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.

              ..IIQQ CCLLEEAARR, as you’d suspect, quits and clears the values for all
              indent styles at once.

       ..IIRR [[ _<_m_e_a_s_u_r_e_> ]]
              Indent right — the optional argument requires a unit of measure

              ..IIRR indents text from the _r_i_g_h_t _m_a_r_g_i_n of the page, or if you’re
              in a _t_a_b, from the end of the _t_a_b.

              The first time you invoke ..IIRR, you must give it a measure.  Sub‐
              sequent invocations with a measure add to  the  previous  indent
              measure.   A _m_i_n_u_s _s_i_g_n 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
              _u_n_i_t _o_f _m_e_a_s_u_r_e is required.  For example,
                     ..IIRR \\ww''jjeelllloo''
              indents text by the width of the word _j_e_l_l_o.

              With no argument, ..IIRR indents by its last active value.  See the
              brief explanation of how _m_o_m handles indents for more details.

              _N_o_t_e_:  Calling  a  _t_a_b (with ..TTAABB <<nn>>) automatically cancels any
              active indents.

              _A_d_d_i_t_i_o_n_a_l _n_o_t_e_: Invoking ..IIRR automatically turns off IIBB.

       ..LL__MMAARRGGIINN _<_l_e_f_t _m_a_r_g_i_n_>
              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
              ..LL__MMAARRGGIINN, 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
                     ..LL__MMAARRGGIINN 33PP
              or
                     ..LL__MMAARRGGIINN ..55ii

              If you use the macros ..PPAAGGEE, ..PPAAGGEEWWIIDDTTHH or ..PPAAPPEERR without invok‐
              ing  ..LL__MMAARRGGIINN  (either  before or afterward), _m_o_m automatically
              sets ..LL__MMAARRGGIINN to _1 _i_n_c_h.

              Note: ..LL__MMAARRGGIINN behaves in a special way when you’re  using  the
              document processing macros.

       ..MMCCOO   Begin multi‐column setting.

              ..MMCCOO  (_M_u_l_t_i_‐_C_o_l_u_m_n _O_n) is the _m_a_c_r_o you use to begin _m_u_l_t_i_‐_c_o_l_‐
              _u_m_n _s_e_t_t_i_n_g.  It marks the current baseline as the top  of  your
              columns,  for  use  later  with  ..MMCCRR.   See the introduction to
              columns for an explanation of _m_u_l_t_i_‐_c_o_l_u_m_n_s and some sample  in‐
              put.

              _N_o_t_e_:  Do  not confuse ..MMCCOO with the ..CCOOLLUUMMNNSS macro in the docu‐
              ment processing macros.

       ..MMCCRR   Once you’ve turned _m_u_l_t_i_‐_c_o_l_u_m_n_s on (with ..MMCCOO),  ..MMCCRR,  at  any
              time, returns you to the _t_o_p _o_f _y_o_u_r _c_o_l_u_m_n_s.

       ..MMCCXX [[ _<_d_i_s_t_a_n_c_e _t_o _a_d_v_a_n_c_e _b_e_l_o_w _l_o_n_g_e_s_t _c_o_l_u_m_n_> ]]
              Optional argument requires a unit of measure.

              Exit multi‐columns.

              ..MMCCXX  takes you out of any _t_a_b you were in (by silently invoking
              ..TTQQ) and advances to the bottom of the longest column.

              Without an argument, ..MMCCXX advances _1 _l_i_n_e_s_p_a_c_e below the longest
              column.

              Linespace, in this instance, is the leading in effect at the mo‐
              ment ..MMCCXX is invoked.

              If you pass the _<_d_i_s_t_a_n_c_e_> argument to ..MMCCXX, it advances _1 _l_i_n_e_‐
              _s_p_a_c_e below the longest column (see  above)  _P_L_U_S  the  distance
              specified by the argument.  The argument requires a unit of mea‐
              sure;  therefore,  to advance an extra 6 points below where ..MMCCXX
              would normally place you, you’d enter
                     ..MMCCXX 66pp

              _N_o_t_e_: If you wish to advance a precise distance below the  base‐
              line  of the longest column, use ..MMCCXX with an argument of 00 (ze‐
              ro; no _u_n_i_t _o_f _m_e_a_s_u_r_e required) in conjunction  with  the  ..AALLDD
              macro, like this:
                     ..MMCCXX 00
                     ..AALLDD 2244pp
              The  above advances to precisely _2_4 _p_o_i_n_t_s below the baseline of
              the longest column.

       ..NNEEWWPPAAGGEE

              Whenever you want to start a new page, use ..NNEEWWPPAAGGEE,  by  itself
              with  no  argument.   MMoomm  will finish up processing the current
              page and move you to the top of a new one (subject  to  the  top
              margin set with ..TT__MMAARRGGIINN).

       ..PPAAGGEE _<_w_i_d_t_h_> [[ _<_l_e_n_g_t_h_> [[ _<_l_m_> [[ _<_r_m_> [[ _<_t_m_> [[ _<_b_m_> ]] ]] ]] ]] ]]

              All arguments require a unit of measure

              _I_M_P_O_R_T_A_N_T_: If you’re using the document processing macros, ..PPAAGGEE
              must come after ..SSTTAARRTT.  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).

              ..PPAAGGEE  lets 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.  _<_l_m_>, _<_r_m_>, _<_t_m_> and _<_b_m_>  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
                     ..PPAAGGEE 1111ii 1177ii
              If you want to set the left margin as well, say, at 1 inch, PPAAGGEE
              would look like this:
                     ..PPAAGGEE 1111ii 1177ii 11ii

              Now suppose you also want to set the top margin, say,  at  1–1/2
              inches.   _<_t_m_>  comes  after _<_r_m_> 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 ..PPAAGGEE  macro  would
              look like this:
                     .PAGE 11i 17i 1i 1i 1.5i
                                      |   |
                     required right---+   +---top margin
                             margin

              Clearly,  ..PPAAGGEE  is  best used when you want a convenient way to
              tell _m_o_m 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
                     ..PPAAGGEE 88..55ii 1111ii 4455pp 4455pp 4455pp 4455pp
              This sets up an 8½ by 11 inch page with  margins  of  45  points
              (5/8‐inch) all around.

              Additionally,  if  you  invoke ..PPAAGGEE with a top margin argument,
              any macros you invoke after ..PPAAGGEE will almost certainly move the
              baseline of the first line of text down by  one  linespace.   To
              compensate, do
                     ..RRLLDD 11vv
              immediately before entering any text, or, if it’s feasible, make
              ..PPAAGGEE the last macro you invoke prior to entering text.

              Please  read the _I_m_p_o_r_t_a_n_t _n_o_t_e on page dimensions and papersize
              for information on ensuring _g_r_o_f_f respects your ..PPAAGGEE dimensions
              and margins.

       ..PPAAGGEELLEENNGGTTHH _<_l_e_n_g_t_h _o_f _p_r_i_n_t_e_r _s_h_e_e_t_>
              tells _m_o_m how long your printer sheet is.  It  works  just  like
              ..PPAAGGEEWWIIDDTTHH.

              Therefore, to tell _m_o_m your printer sheet is 11 inches long, you
              enter
                     ..PPAAGGEELLEENNGGTTHH 1111ii
              Please  read the important note on page dimensions and papersize
              for information on ensuring _g_r_o_f_f respects your _P_A_G_E_L_E_N_G_T_H.

       ..PPAAGGEEWWIIDDTTHH _<_w_i_d_t_h _o_f _p_r_i_n_t_e_r _s_h_e_e_t_>

              The argument to ..PPAAGGEEWWIIDDTTHH is the width of your printer sheet.

              ..PPAAGGEEWWIIDDTTHH requires a unit of measure.   Decimal  fractions  are
              allowed.   Hence,  to  tell  _m_o_m  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 _g_r_o_f_f respects your _P_A_G_E_W_I_D_T_H.

       ..PPAAPPEERR _<_p_a_p_e_r _t_y_p_e_>
              provides  a  convenient  way to set the page dimensions for some
              common printer sheet sizes.  The argument _<_p_a_p_e_r  _t_y_p_e_>  can  be
              one  of: LLEETTTTEERR, LLEEGGAALL, SSTTAATTEEMMEENNTT, TTAABBLLOOIIDD, LLEEDDGGEERR, FFOOLLIIOO, QQUUAARR‐‐
              TTOO, EEXXEECCUUTTIIVVEE, 1100xx1144, AA33, AA44, AA55, BB44, BB55.

       ..PPRRIINNTTSSTTYYLLEE

       ..PPTT__SSIIZZEE _<_s_i_z_e _o_f _t_y_p_e _i_n _p_o_i_n_t_s_>
              Point size of type, does not require a _u_n_i_t _o_f _m_e_a_s_u_r_e.

              ..PPTT__SSIIZZEE (_P_o_i_n_t _S_i_z_e) takes one argument: the _s_i_z_e  _o_f  _t_y_p_e  in
              _p_o_i_n_t_s.   Unlike  most  other  macros that establish the _s_i_z_e or
              _m_e_a_s_u_r_e of something, ..PPTT__SSIIZZEE does not require that you  supply
              a  _u_n_i_t  _o_f  _m_e_a_s_u_r_e since it’s a near universal convention that
              _t_y_p_e _s_i_z_e is measured in _p_o_i_n_t_s.  Therefore, to change the  _t_y_p_e
              _s_i_z_e to, say, _1_1 _p_o_i_n_t_s, enter
                     ..PPTT__SSIIZZEE 1111
              _P_o_i_n_t _s_i_z_e_s may be _f_r_a_c_t_i_o_n_a_l (e.g., _1_0_._2_5 or _1_2_._5).

              You  can  prepend  a  _p_l_u_s  or  a  _m_i_n_u_s _s_i_g_n to the argument to
              ..PPTT__SSIIZZEE, in which case the _p_o_i_n_t _s_i_z_e will be changed by _+ or _-
              the original value.  For example, if the _p_o_i_n_t _s_i_z_e is  _1_2,  and
              you want _1_4, you can do
                     ..PPTT__SSIIZZEE ++22
              then later reset it to _1_2 with
                     ..PPTT__SSIIZZEE --22
              The _s_i_z_e _o_f _t_y_p_e can also be changed inline.

              _N_o_t_e_:  It  is  unfortunate that the ppiicc preprocessor has already
              taken the name, PS, and thus _m_o_m’s macro for setting _p_o_i_n_t _s_i_z_e_s
              can’t use it.  However, if you aren’t using ppiicc, you might  want
              to alias ..PPTT__SSIIZZEE as ..PPSS, since there’d be no conflict.  For ex‐
              ample
                     ..AALLIIAASS PPSS PPTT__SSIIZZEE
              would allow you to set _p_o_i_n_t _s_i_z_e_s with ..PPSS.

       ..RR__MMAARRGGIINN _<_r_i_g_h_t _m_a_r_g_i_n_>
              Right Margin

              Requires a unit of measure.

              IMPORTANT:   ..RR__MMAARRGGIINN,   if   used,  must  come  after  ..PPAAPPEERR,
              ..PPAAGGEEWWIIDDTTHH, ..LL__MMAARRGGIINN, and/or ..PPAAGGEE (if  a  right  margin  isn’t
              given  to  PAGE).   The reason is that ..RR__MMAARRGGIINN calculates 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.

              ..RR__MMAARRGGIINN  establishes  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.  ..RR__MMAARRGGIINN re‐
              quires a unit of measure.  Decimal fractions are allowed.

              The line length macro (LL) can be used in  place  of  ..RR__MMAARRGGIINN.
              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:
                     ..LL__MMAARRGGIINN 66PP
                     ..RR__MMAARRGGIINN 66PP

              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.,
                     ..LLLL 1177PP++33pp

              If  you use the macros ..PPAAGGEE, ..PPAAGGEEWWIIDDTTHH or PPAAPPEERR without invok‐
              ing ..RR__MMAARRGGIINN afterward, _m_o_m automatically sets ..RR__MMAARRGGIINN  to  _1
              _i_n_c_h.   If  you set a line length after these macros (with ..LLLL),
              the line length calculated by ..RR__MMAARRGGIINN is, of course,  overrid‐
              den.

              Note:  ..RR__MMAARRGGIINN  behaves in a special way when you’re using the
              document processing macros.

       ..SSTT _<_t_a_b _n_u_m_b_e_r_> LL || RR || CC || JJ [[ QQUUAADD ]]

              After _s_t_r_i_n_g _t_a_b_s have been marked off on  an  input  line  (see
              \\**[[SSTT]]......\\**[[SSTTXX]]),  you need to _s_e_t them by giving them a direc‐
              tion and, optionally, the QQUUAADD argument.

              In this respect, ..SSTT is like ..TTAABB__SSEETT except that you don’t have
              to give ..SSTT an indent or a line  length  (that’s  already  taken
              care of, inline, by \\**[[SSTT]]......\\**[[SSTTXX]]).

              If you want string _t_a_b _1 to be lleefftt, enter
                     ..SSTT 11 LL
              If you want it to be _l_e_f_t and _f_i_l_l_e_d, enter
                     ..SSTT 11 LL QQUUAADD
              If you want it to be justified, enter
                     ..SSTT 11 JJ

       ..TTAABB _<_t_a_b _n_u_m_b_e_r_>
              After _t_a_b_s have been defined (either with ..TTAABB__SSEETT or ..SSTT), ..TTAABB
              moves to whatever _t_a_b _n_u_m_b_e_r you pass it as an argument.

              For example,
                     ..TTAABB 33
              moves you to _t_a_b _3.

              Note:  ..TTAABB  breaks  the  line preceding it and advances 1 line‐
              space.  Hence,
                     ..TTAABB 11
                     AA lliinnee ooff tteexxtt iinn ttaabb 11..
                     ..TTAABB 22
                     AA lliinnee ooff tteexxtt iinn ttaabb 22..
              produces, on output
                     AA lliinnee ooff tteexxtt iinn ttaabb 11..
                                                  AA lliinnee ooff tteexxtt iinn ttaabb 22..

              If you want the tabs to line up, use ..TTNN (“Tab Next”)  or,  more
              conveniently, the inline escape sequence \\**[[TTBB++]]:
                     ..TTAABB 1
                     A line of text in tab 1.\*[TB+]
                     A line of text in tab 2.
              which produces
                     AA lliinnee ooff tteexxtt iinn ttaabb 11..   AA lliinnee ooff tteexxtt iinn ttaabb 22..

              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.

              _A_d_d_i_t_i_o_n_a_l _n_o_t_e_: Any indents in effect prior to  calling  a  tab
              are  automatically  turned off by TTAABB.  If you were happily zip‐
              ping down the page with a left indent of _2 _p_i_c_a_s turned on,  and
              you  call  a  _t_a_b  whose indent from the left margin is _6 _p_i_c_a_s,
              your new distance from the _l_e_f_t _m_a_r_g_i_n will be _6 _p_i_c_a_s, not I  6
              picas plus the 2 pica indent.

              _T_a_b_s  are  not  by  nature columnar, which is to say that if the
              text inside a _t_a_b runs to several  lines,  calling  another  _t_a_b
              does not automatically move to the baseline of the first line in
              the _p_r_e_v_i_o_u_s _t_a_b.  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

       ..TTBB _<_t_a_b _n_u_m_b_e_r_>
              Alias to ..TTAABB

       ..TTII [[ _<_m_e_a_s_u_r_e_> ]]
              Temporary left indent — the optional argument requires a _u_n_i_t _o_f
              _m_e_a_s_u_r_e

              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.  (MMoomm’’ss ..PPPP macro, for example, uses a  _t_e_m_‐
              _p_o_r_a_r_y _i_n_d_e_n_t.)

              The  first  time you invoke ..TTII, you must give it a measure.  If
              you want to _i_n_d_e_n_t the first line of a paragraph by, say, 2 ems,
              do
                     ..TTII 22mm

              Subsequent invocations of ..TTII do not require  you  to  supply  a
              measure; _m_o_m keeps track of the last measure you gave it.

              Because _t_e_m_p_o_r_a_r_y _i_n_d_e_n_t_s are temporary, there’s no need to turn
              them off.

              _I_M_P_O_R_T_A_N_T_: Unlike ..IILL, ..IIRR and IIBB, measures given to ..TTII are NOT
              additive.   In the following example, the second ""..TTII 22PP"" is ex‐
              actly _2 _p_i_c_a_s.
                     ..TTII 11PP
                     TThhee bbeeggiinnnniinngg ooff aa ppaarraaggrraapphh......
                     ..TTII 22PP
                     TThhee bbeeggiinnnniinngg ooff aannootthheerr ppaarraaggrraapphh......

       ..TTNN    Tab Next

              Inline escape \\**[[TTBB++]]

              TTNN moves over to the _n_e_x_t _t_a_b  in  numeric  sequence  (_t_a_b  _n_+_1)
              without  advancing on the page.  See the _N_O_T_E in the description
              of the ..TTAABB macro for an example of how TTNN works.

              In _t_a_b_s that aren’t given the QQUUAADD argument when they’re set  up
              with  ..TTAABB__SSEETT  or SSTT, you must terminate the line preceding ..TTNN
              with the \\cc inline escape sequence.  Conversely, if you did give
              a QQUUAADD argument to ..TTAABB__SSEETT or SSTT, the \\cc mmuusstt nnoott bbee uusseedd..

              If you find remembering whether to put in the \\cc bothersome, you
              may prefer to use the inline escape alternative to ..TTNN, \\**[[TTBB++]],
              which works consistently regardless of the fill mode.

              _N_o_t_e_: You must put text in the input line immediately after ..TTNN.
              Stacking of ..TTNN’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 _t_a_b_s numbered from _1 to _4, 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 _g_r_o_f_f recognizes
              as valid input, hence meets the requirement for input text  fol‐
              lowing ..TTNN.

       ..TTQQ    TTQQ  takes  you out of whatever _t_a_b you were in, advances _1 _l_i_n_e_‐
              _s_p_a_c_e, and restores the _l_e_f_t _m_a_r_g_i_n, _l_i_n_e _l_e_n_g_t_h, _q_u_a_d _d_i_r_e_c_t_i_o_n
              and _f_i_l_l _m_o_d_e that were in effect prior to invoking any _t_a_b_s.

       ..TT__MMAARRGGIINN _<_t_o_p _m_a_r_g_i_n_>
              Top margin

              Requires a unit of measure

              ..TT__MMAARRGGIINN establishes 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
                     ..TT__MMAARRGGIINN 22..55cc
              ..TT__MMAARRGGIINN  calculates 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,
                     ..TT__MMAARRGGIINN 11..55ii
              puts  the  baseline  of the first line of type 1½ inches beneath
              the top of the page.

              Note: ..TT__MMAARRGGIINN means something slightly different  when  you’re
              using  the  document processing macros.  See Top and bottom mar‐
              gins in document processing for an explanation.

              IMPORTANT: ..TT__MMAARRGGIINN does 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, ..TT__MMAARRGGIINN should  only  be
              used at the top of a file (prior to entering text) or after NEW‐
              PAGE, like this:
                     ..NNEEWWPPAAGGEE
                     ..TT__MMAARRGGIINN 66PP
                     _<_t_e_x_t_>

AAuutthhoorrss
       _m_o_m  was  written by Peter Schaffter.  PDF support was provided by Deri
       James.  This manual page was written by Bernd Warken.

SSeeee aallssoo
       _/_u_s_r_/_s_h_a_r_e_/_d_o_c_/_g_r_o_f_f_-_b_a_s_e_/_h_t_m_l_/_m_o_m_/_t_o_c_._h_t_m_l
              entry point to the HTML documentation

       ⟨http://www.schaffter.ca/mom/momdoc/toc.html⟩
              HTML documentation online

       ⟨http://www.schaffter.ca/mom/⟩
              the _m_o_m macros homepage

       _G_r_o_f_f_: _T_h_e _G_N_U _I_m_p_l_e_m_e_n_t_a_t_i_o_n _o_f _t_r_o_f_f, by Trent A. Fisher  and  Werner
       Lemberg,  is the primary _g_r_o_f_f manual.  You can browse it interactively
       with “info groff”.

       _p_d_f_m_o_m(1), _g_r_o_f_f(1), _t_r_o_f_f(1)

groff 1.23.0                      3 June 2025                     _g_r_o_f_f___m_o_m(7)
───────────────────────────────────────────────────────────────────────────────
_g_r_o_f_f___m_s(7)            Miscellaneous Information Manual            _g_r_o_f_f___m_s(7)

NNaammee
       groff_ms - GNU _r_o_f_f manuscript macro package for formatting documents

SSyynnooppssiiss
       ggrrooffff --mmss [_o_p_t_i_o_n ...] [_f_i_l_e ...]
       ggrrooffff --mm mmss [_o_p_t_i_o_n ...] [_f_i_l_e ...]

DDeessccrriippttiioonn
       The GNU implementation of the _m_s macro package is  part  of  the  _g_r_o_f_f
       document  formatting system.  The _m_s package is suitable for the compo‐
       sition of letters, memoranda, reports, and books.

       These _g_r_o_f_f 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.   _m_s
       supports the _t_b_l(1), _e_q_n(1), _p_i_c(1), and _r_e_f_e_r(1) preprocessors for in‐
       clusion  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 _m_s.  Many extensions from 4.2BSD
       (Berkeley) and Tenth Edition Research Unix have been recreated.

UUssaaggee
       The _m_s 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
       ..LLPP or ..PPPP.  Longer documents have a structure as follows.

       DDooccuummeenntt ttyyppee
              Calling  the RRPP macro at the beginning of your document puts the
              document description (see below) on a cover page.  Otherwise, _m_s
              places this information on the first page, followed  immediately
              by  the body text.  Some document types found in other _m_s imple‐
              mentations are specific to AT&T or Berkeley, and  are  not  sup‐
              ported in _g_r_o_f_f _m_s.

       FFoorrmmaatt aanndd llaayyoouutt
              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.

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

       BBooddyy tteexxtt
              The  main  matter  of  your document follows its description (if
              any).  _m_s 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.

       TTaabbllee ooff ccoonntteennttss
              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 _t_r_o_f_f 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 _m_s 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.

   DDooccuummeenntt ccoonnttrrooll sseettttiinnggss
       The  following tables list the document control registers, strings, and
       special characters.  For any parameter whose default is unsatisfactory,
       define it before calling any _m_s macro other than RRPP.

                                   MMaarrggiinn sseettttiinnggss
       PPaarraammeetteerr            DDeeffiinniittiioonn               EEffffeeccttiivvee       DDeeffaauulltt
       ────────────────────────────────────────────────────────────────────────
       \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
       ────────────────────────────────────────────────────────────────────────

                              TTiittlleess ((hheeaaddeerrss,, ffooootteerrss))
       PPaarraammeetteerr               DDeeffiinniittiioonn                 EEffffeeccttiivvee    DDeeffaauulltt
       ────────────────────────────────────────────────────────────────────────
       \*[LH]      Left header text                      next header   _e_m_p_t_y
       \*[CH]      Center header text                    next header   -\n[%]-
       \*[RH]      Right header text                     next header   _e_m_p_t_y
       \*[LF]      Left footer text                      next footer   _e_m_p_t_y
       \*[CF]      Center footer text                    next footer   _e_m_p_t_y
       \*[RF]      Right footer text                     next footer   _e_m_p_t_y
       ────────────────────────────────────────────────────────────────────────

                                    TTeexxtt sseettttiinnggss
       PPaarraammeetteerr              DDeeffiinniittiioonn                EEffffeeccttiivvee      DDeeffaauulltt
       ────────────────────────────────────────────────────────────────────────
       \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
       ────────────────────────────────────────────────────────────────────────

                                 PPaarraaggrraapphh sseettttiinnggss
        PPaarraammeetteerr             DDeeffiinniittiioonn              EEffffeeccttiivvee       DDeeffaauulltt
       ────────────────────────────────────────────────────────────────────────
       \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
       ────────────────────────────────────────────────────────────────────────

                                  HHeeaaddiinngg sseettttiinnggss
        PPaarraammeetteerr              DDeeffiinniittiioonn             EEffffeeccttiivvee      DDeeffaauulltt
       ────────────────────────────────────────────────────────────────────────
       \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]
       ────────────────────────────────────────────────────────────────────────

       \\**[[SSNN--SSTTYYLLEE]] can alternatively be made an alias of  \\**[[SSNN--NNOO--DDOOTT]]  with
       the aallss request.

                                  FFoooottnnoottee sseettttiinnggss
       PPaarraammeetteerr             DDeeffiinniittiioonn               EEffffeeccttiivvee      DDeeffaauulltt
       ────────────────────────────────────────────────────────────────────────
       \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                _s_p_e_c_i_a_l         11/12
       ────────────────────────────────────────────────────────────────────────

                                  DDiissppllaayy sseettttiinnggss
       PPaarraammeetteerr               DDeeffiinniittiioonn                EEffffeeccttiivvee    DDeeffaauulltt
       ────────────────────────────────────────────────────────────────────────
       \n[DD]      Display distance (spacing)            _s_p_e_c_i_a_l     0.5v (1v)
       \n[DI]      Display indentation                   _s_p_e_c_i_a_l     0.5i
       ────────────────────────────────────────────────────────────────────────

                                   OOtthheerr sseettttiinnggss
         PPaarraammeetteerr               DDeeffiinniittiioonn              EEffffeeccttiivvee     DDeeffaauulltt
       ────────────────────────────────────────────────────────────────────────
       \n[MINGW]       Minimum gutter width             next page      2n
       \n[TC-MARGIN]   TOC page number margin width     next PPXX call   \w'000'
       \[TC-LEADER]    TOC leader character             next PPXX call   .\h'1m'
       ────────────────────────────────────────────────────────────────────────

       For entries marked “_s_p_e_c_i_a_l” in the “Effective” column, see the discus‐
       sion  in the applicable section below.  The PPOO, LLLL, and LLTT register 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  _g_r_o_f_f(1).   The PPDD and DDDD registers 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 \\nn[[MMIINNGGWW]] is
       the gap between columns  in  multiple‐column  page  arrangements.   The
       TTCC--MMAARRGGIINN  register  and TTCC--LLEEAADDEERR special character affect the format‐
       ting of tables of contents assembled by the XXSS, XXAA, and XXEE macros.

   DDooccuummeenntt ddeessccrriippttiioonn mmaaccrrooss
       Define information describing the document by calling the macros  below
       in  the  order shown; ..DDAA or ..NNDD can 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 ..TTLL is mandatory if any of ..RRPP, ..AAUU,
       ..AAII, or ..AABB is called, and ..AAEE is mandatory if ..AABB is called.

       ..RRPP [nnoo--rreeppeeaatt--iinnffoo] [nnoo--rreennuummbbeerr]
              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 nnoo--rreeppeeaatt--iinnffoo  argument
              is  given,  _m_s  produces a cover page but does not repeat any of
              its information on subsequently (but see the DDAA macro below  re‐
              garding the date).  Normally, ..RRPP sets the page number following
              the  cover page to 1.  Specifying the optional nnoo--rreennuummbbeerr argu‐
              ment suppresses this alteration.  Optional arguments  can  occur
              in any order.  “nnoo” is recognized as a synonym of nnoo--rreeppeeaatt--iinnffoo
              for AT&T compatibility.

       ..TTLL    Specify  the  document  title.   _m_s collects text on input lines
              following this call into the title until reaching ..AAUU, ..AABB, or a
              heading or paragraphing macro call.

       ..AAUU    Specify an author’s name.  _m_s collects text on input lines  fol‐
              lowing this call into the author’s name until reaching ..AAII, ..AABB,
              another  ..AAUU,  or a heading or paragraphing macro call.  Call it
              repeatedly to specify multiple authors.

       ..AAII    Specify the preceding author’s institution.  An ..AAUU call is use‐
              fully followed by at most one ..AAII call; if there are  more,  the
              last ..AAII call controls.  _m_s collects text on input lines follow‐
              ing  this call into the author’s institution until reaching ..AAUU,
              ..AABB, or a heading or paragraphing macro call.

       ..DDAA [_x ...]
              Typeset the current date, or any  arguments  _x,  in  the  center
              footer,  and,  if ..RRPP is also called, left‐aligned at the end of
              the document description on the cover page.

       ..NNDD [_x ...]
              Typeset the current date, or any arguments _x,  if  ..RRPP  is  also
              called,  left‐aligned  at the end of the document description on
              the cover page.  This is _g_r_o_f_f _m_s’s default.

       ..AABB [nnoo]
              Begin the abstract.  _m_s collects text on input  lines  following
              this  call into the abstract until reaching an ..AAEE call.  By de‐
              fault, _m_s places the word “ABSTRACT”  centered  and  in  italics
              above the text of the abstract.  The optional argument “nnoo” sup‐
              presses this heading.

       ..AAEE    End the abstract.

   TTeexxtt sseettttiinnggss
       The  FFAAMM  string,  a GNU extension, sets the font family for body text;
       the default is “TT”.  The PPSS and VVSS registers 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 FFAAMM) footnotes.

       The HHYY register defines the automatic hyphenation mode used with the hhyy
       request.  Setting \\nn[[HHYY]] to 00 is equivalent to using  the  nnhh  request.
       This is a Tenth Edition Research Unix extension.

   TTyyppooggrraapphhiiccaall ssyymmbboollss
       _m_s  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 _g_r_o_f_f___c_h_a_r(7).

       \\**[[--]]  Interpolate an em dash.

       \\**[[QQ]]
       \\**[[UU]]  Interpolate typographer’s quotation marks where  available,  and
              neutral  double  quotes  otherwise.  \\**[[QQ]] is the left quote and
              \\**[[UU]] the right.

   PPaarraaggrraapphhss
       Paragraphing macros _b_r_e_a_k, 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 PPDD register, except at
       page or column breaks, or adjacent to displays.

       The PPOORRPPHHAANNSS register 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 \\nn[[PPOORRPPHHAANNSS]]
       lines before an automatic page break, then a page break is  forced  be‐
       fore the start of the paragraph.  This is a GNU extension.

       ..LLPP    Set a paragraph without any (additional) indentation.

       ..PPPP    Set a paragraph with a first‐line left indentation in the amount
              stored in the PPII register.

       ..IIPP [_m_a_r_k_e_r [_w_i_d_t_h]]
              Set a paragraph with a left indentation.  The optional _m_a_r_k_e_r is
              not  indented  and is empty by default.  _w_i_d_t_h overrides the in‐
              dentation amount in \\nn[[PPII]]; its default unit is “nn”.  Once spec‐
              ified, _w_i_d_t_h applies to further ..IIPP calls until specified  again
              or a heading or different paragraphing macro is called.

       ..QQPP    Set  a  paragraph  indented  from both left and right margins by
              \\nn[[QQII]].

       ..QQSS
       ..QQEE    Begin (QQSS) and end (QQEE) a region where  each  paragraph  is  in‐
              dented  from  both  margins by \\nn[[QQII]].  The text between ..QQSS and
              ..QQEE can be structured  further  by  use  of  other  paragraphing
              macros.

       ..XXPP    Set  an  “exdented”  paragraph—one  with  a  left indentation of
              \\nn[[PPII]] on every line _e_x_c_e_p_t the first (also known as  a  hanging
              indent).  This is a Berkeley extension.

   HHeeaaddiinnggss
       Use headings to create a hierarchical structure for your document.  The
       _m_s macros print headings in bboolldd using 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.

       ..NNHH [_d_e_p_t_h]
              Set  an  automatically numbered heading.  _m_s produces a numbered
              heading in the form _a._b._c..., to any  level  desired,  with  the
              numbering of each depth increasing automatically and being reset
              to  zero when a more significant depth is increased.  “11” is the
              most significant or coarsest division  of  the  document.   Only
              non‐zero values are output.  If _d_e_p_t_h is omitted, it is taken to
              be  11.   If  you specify _d_e_p_t_h such that an ascending gap occurs
              relative to the previous NNHH call—that is, you “skip a depth”, as
              by “..NNHH 11” and then “..NNHH 33”, _g_r_o_f_f _m_s emits  a  warning  on  the
              standard error stream.

       ..NNHH SS _h_e_a_d_i_n_g_‐_d_e_p_t_h_‐_i_n_d_e_x ...
              Alternatively, you can give NNHH a first argument of “SS”, 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 ..NNHH is called, the assigned  number  is  made  available  in  the
       strings SSNN--DDOOTT (as it appears in a printed heading with default format‐
       ting,  followed by a terminating period) and SSNN--NNOO--DDOOTT (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 SSNN--SSTTYYLLEE.  By default, \\**[[SSNN--SSTTYYLLEE]]
       is aliased to \\**[[SSNN--DDOOTT]].  If you prefer to omit the terminating period
       from  numbers  appearing  in  numbered  headings,  you  may alias it to
       \\**[[SSNN--NNOO--DDOOTT]].  Any such change in numbering  style  becomes  effective
       from  the  next  use  of  ..NNHH  following  redefinition of the alias for
       \\**[[SSNN--SSTTYYLLEE]].  The formatted number of the current heading is available
       in \\**[[SSNN]] (a feature first documented by Berkeley); this string facili‐
       tates its inclusion in, for example, table captions,  equation  labels,
       and ..XXSS/..XXAA/..XXEE table of contents entries.

       ..SSHH [_d_e_p_t_h]
              Set an unnumbered heading.  The optional _d_e_p_t_h argument is a GNU
              extension  indicating  the  heading  depth  corresponding to the
              _d_e_p_t_h argument of ..NNHH.  It matches the type size  at  which  the
              heading  is  set to that of a numbered heading at the same depth
              when the \\nn[[GGRROOWWPPSS]] and \\nn[[PPSSIINNCCRR]] heading size adjustment mech‐
              anism is in effect.

       The PPSSIINNCCRR register defines an increment in type size to be applied  to
       a  heading  at  a  lesser depth than that specified in \\nn[[GGRROOWWPPSS]].  The
       value of \\nn[[PPSSIINNCCRR]] should be specified in points with the “pp”  scaling
       unit and may include a fractional component.

       The GGRROOWWPPSS register defines the heading depth above which the type size
       increment  set by \\nn[[PPSSIINNCCRR]] becomes effective.  For each heading depth
       less than the value of  \\nn[[GGRROOWWPPSS]],  the  type  size  is  increased  by
       \\nn[[PPSSIINNCCRR]].  Setting \\nn[[GGRROOWWPPSS]] to a value less than 2 disables the in‐
       cremental heading size feature.

       In  other  words,  if  the value of GGRROOWWPPSS register is greater than the
       _d_e_p_t_h argument to a ..NNHH or ..SSHH call, the type size of  a  heading  pro‐
       duced  by these macros increases by \\nn[[PPSSIINNCCRR]] units over \\nn[[PPSS]] multi‐
       plied by the difference of \\nn[[GGRROOWWPPSS]] and _d_e_p_t_h.

       The \\nn[[HHOORRPPHHAANNSS]] register operates in conjunction with the  NNHH  and  SSHH
       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 _t_b_l, _p_i_c, or _e_q_n re‐
       gion between the heading and the subsequent paragraph  suppresses  this
       grouping.

   TTyyppeeffaaccee aanndd ddeeccoorraattiioonn
       The  _m_s macros provide a variety of ways to style text.  Attend closely
       to the ordering of arguments labeled _p_r_e and _p_o_s_t_, which is  not  intu‐
       itive.  Support for _p_r_e arguments is a GNU extension.

       ..BB [_t_e_x_t [_p_o_s_t [_p_r_e]]]
              Style  _t_e_x_t in bold, followed by _p_o_s_t in the previous font style
              without intervening space, and preceded by _p_r_e similarly.  With‐
              out arguments, _m_s styles subsequent text in bold until the  next
              paragraphing, heading, or no‐argument typeface macro call.

       ..RR [_t_e_x_t [_p_o_s_t [_p_r_e]]]
              As  ..BB,  but use the roman style (upright text of normal weight)
              instead of bold.  Argument recognition is a GNU extension.

       ..II [_t_e_x_t [_p_o_s_t [_p_r_e]]]
              As ..BB, but use an italic or oblique style instead of bold.

       ..BBII [_t_e_x_t [_p_o_s_t [_p_r_e]]]
              As ..BB, but use a bold italic or bold oblique  style  instead  of
              upright bold.  This is a Tenth Edition Research Unix extension.

       ..CCWW [_t_e_x_t [_p_o_s_t [_p_r_e]]]
              As  ..BB, but use a constant‐width (monospaced) roman typeface in‐
              stead of bold.  This is a Tenth Edition Research Unix extension.

       ..BBXX [_t_e_x_t]
              Typeset _t_e_x_t and draw a box around it.  On terminal devices, re‐
              verse video is used instead.  If you want _t_e_x_t to contain space,
              use unbreakable space or horizontal motion escape sequences (\\~~,
              \\_s_p_a_c_e, \\^^, \\||, \\00, or \\hh).

       ..UULL [_t_e_x_t [_p_o_s_t]]
              Typeset _t_e_x_t with an underline.  _p_o_s_t_, if present, is set  after
              _t_e_x_t with no intervening space.

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

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

       ..NNLL    Set subsequent text at the normal type size (\\nn[[PPSS]]).

       When _p_r_e is used, a hyphenation control escape sequence \\%%  that  would
       ordinarily start _t_e_x_t must start _p_r_e instead.

       _g_r_o_f_f  _m_s also offers strings to begin and end super‐ and subscripting.
       These are GNU extensions.

       \\**{{
       \\**}}    Begin and end superscripting, respectively.

       \\**<<
       \\**>>    Begin and end subscripting, respectively.

   IInnddeenntteedd rreeggiioonnss
       You may need to indent a region of text while otherwise  formatting  it
       normally.  Indented regions can be nested.

       ..RRSS    Begin  a region where headings, paragraphs, and displays are in‐
              dented (further) by \\nn[[PPII]].

       ..RREE    End the (next) most recent indented region.

   KKeeeeppss,, bbooxxeedd kkeeeeppss,, aanndd ddiissppllaayyss
       On occasion, you may want to _k_e_e_p 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 _f_l_o_a_t_i_n_g _k_e_e_p_: if a keep cannot fit  on
       the  current  page, _m_s 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 bbpp request,
       _m_s puts the floating keep at the beginning of the next page.

       ..KKSS    Begin a keep.

       ..KKFF    Begin a floating keep.

       ..KKEE    End (floating) keep.

       As  an  alternative to the keep mechanism, the nnee request forces a page
       break if there is not at least the amount of vertical  space  specified
       in its argument remaining on the page.

       A _b_o_x_e_d _k_e_e_p has a frame drawn around it.

       ..BB11    Begin a keep with a box drawn around it.

       ..BB22    End boxed keep.

       Boxed  keep  macros  cause  breaks; if you need to box a word or phrase
       within a line, see the BBXX macro 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
       ..BB11 after the first paragraphing macro, and by adding a small amount of
       vertical space before calling ..BB22.

       If you want a boxed keep to float, you will need to enclose the ..BB11 and
       ..BB22 calls within a pair of ..KKFF and ..KKEE calls.

       _D_i_s_p_l_a_y_s  turn  off  filling;  lines of verse or program code are shown
       with their lines broken as in the source document without requiring  bbrr
       requests  between  lines.  Displays can be kept on a single page or al‐
       lowed to break across pages.  The DDSS macro begins a kept display of the
       layout specified in its first argument;  non‐kept  displays  are  begun
       with dedicated macros corresponding to their layout.

       ..DDSS LL
       ..LLDD    Begin (DDSS: kept) left‐aligned display.

       ..DDSS [II [_i_n_d_e_n_t]]
       ..IIDD [_i_n_d_e_n_t]
              Begin (DDSS: kept) display indented by _i_n_d_e_n_t if specified, \\nn[[DDII]]
              otherwise.

       ..DDSS BB
       ..BBDD    Begin  (DDSS:  kept)  block  display:  the entire display is left‐
              aligned, but indented such that the longest line in the  display
              is centered on the page.

       ..DDSS CC
       ..CCDD    Begin  (DDSS:  kept) centered display: each line in the display is
              centered.

       ..DDSS RR
       ..RRDD    Begin (DDSS: kept) right‐aligned display.  This is  a  GNU  exten‐
              sion.

       ..DDEE    End any display.

       The distance stored in \\nn[[DDDD]] is inserted before and after each pair of
       display  macros;  this is a Berkeley extension.  In _g_r_o_f_f _m_s, this dis‐
       tance replaces any  adjacent  inter‐paragraph  distance  or  subsequent
       spacing  prior  to  a section heading.  The DDII register is a GNU exten‐
       sion; its value is an indentation applied to displays created with  ..DDSS
       and  ..IIDD without arguments, to “..DDSS II” without an indentation argument,
       and to equations set with “..EEQQ II”.  Changes to either register take ef‐
       fect at the next display boundary.

   TTaabblleess,, ffiigguurreess,, eeqquuaattiioonnss,, aanndd rreeffeerreenncceess
       The _m_s package is often used with the _t_b_l, _p_i_c,  _e_q_n,  and  _r_e_f_e_r  pre‐
       processors.  The \\nn[[DDDD]] distance is also applied to regions of the doc‐
       ument  preprocessed  with  _e_q_n, _p_i_c, and _t_b_l.  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.

       ..TTSS [HH]
       ..TTEE    Demarcate a table to be processed by the _t_b_l preprocessor.   The
              optional  HH  argument  instructs  _m_s to repeat table rows (often
              column headings) at the top of each new page the table spans, if
              applicable; calling the TTHH macro marks the  end  of  such  rows.
              _t_b_l(1)  provides  a  comprehensive reference to the preprocessor
              and offers examples of its use.

       ..PPSS
       ..PPEE
       ..PPFF    ..PPSS begins a picture to be processed by  the  _p_i_c  preprocessor;
              either  of  ..PPEE or ..PPFF ends it, the latter with “flyback” to the
              vertical position at its top.

       ..EEQQ [_a_l_i_g_n [_l_a_b_e_l]]
       ..EENN    Demarcate an equation to be processed by the  _e_q_n  preprocessor.
              The  equation is centered by default; _a_l_i_g_n can be CC, LL, or II to
              (explicitly) center, left‐align, or indent it by \\nn[[DDII]], respec‐
              tively.  If specified, _l_a_b_e_l is set right‐aligned.

       ..[[
       ..]]     Demarcate a bibliographic citation to be processed by the  _r_e_f_e_r
              preprocessor.   _r_e_f_e_r(1)  provides  a comprehensive reference to
              the preprocessor and the format of its bibliographic database.

       When _r_e_f_e_r emits collected references (as might be  done  on  a  “Works
       Cited”  page),  it  interpolates the string \\**[[RREEFFEERREENNCCEESS]] as an unnum‐
       bered heading (..SSHH).

       Attempting to place a multi‐page table inside a keep can  lead  to  un‐
       pleasant results, particularly if the _t_b_l “aallllbbooxx” option is used.

   FFoooottnnootteess
       A  footnote is typically anchored to a place in the text with a _m_a_r_k_e_r_,
       which is a small integer, a symbol, or arbitrary user‐specified text.

       \\****    Place an _a_u_t_o_m_a_t_i_c _n_u_m_b_e_r_, 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 FFSS and FFEE macro calls to set it at the
       nearest available “foot”, or bottom, of a text column or page.

       ..FFSS [_m_a_r_k_e_r]
              Begin a footnote.  The ..FFSS--MMAARRKK hook (see below) is called  with
              any  supplied  _m_a_r_k_e_r argument, which is then also placed at the
              beginning of the footnote text.  If _m_a_r_k_e_r is omitted, the  next
              pending  automatic  number  enqueued  by  interpolation of the **
              string is used, and if none exists, nothing is prefixed.

       ..FFEE    End footnote text.

       _g_r_o_f_f _m_s provides a hook macro, FFSS--MMAARRKK, for user‐determined operations
       to be performed when the FFSS macro is called.  It is passed the same ar‐
       guments as ..FFSS itself.  By default, this macro has an empty definition.
       ..FFSS--MMAARRKK is a GNU extension.

       Footnote text is formatted as paragraphs are, using  analogous  parame‐
       ters.   The  registers  FFII, FFPPDD, FFPPSS, and FFVVSS correspond to PPII, PPDD, PPSS,
       and VVSS, respectively; FFPPDD, FFPPSS, and FFVVSS are GNU extensions.

       The FFFF register controls the formatting of automatically numbered foot‐
       note paragraphs, and those for which ..FFSS is given a _m_a_r_k_e_r argument, at
       the bottom of a column or page as follows.

              0      Set an automatic number, or a specified FFSS  _m_a_r_k_e_r  argu‐
                     ment,  as  a  superscript (on typesetter devices) or sur‐
                     rounded by square brackets (on terminals).  The  footnote
                     paragraph  is indented as with ..PPPP if there is an ..FFSS ar‐
                     gument or an automatic number, and as with ..LLPP otherwise.
                     This is the default.

              1      As 00, but set the marker as regular text, and  follow  an
                     automatic number with a period.

              2      As 11, but without indentation (like ..LLPP).

              3      As  11,  but  set  the  footnote paragraph with the marker
                     hanging (like ..IIPP).

   LLaanngguuaaggee aanndd llooccaalliizzaattiioonn
       _g_r_o_f_f _m_s 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
       _m_s; see _g_r_o_f_f___t_m_a_c(5).

                  SSttrriinngg            DDeeffaauulltt
              ───────────────────────────────────
              \*[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  AABBSSTTRRAACCTT includes font selection escape sequences to
       set the word in italics.

   HHeeaaddeerrss aanndd ffooootteerrss
       There are multiple ways to produce headers and footers.  One is to  de‐
       fine  the  strings  LLHH,  CCHH,  and RRHH to set the left, center, and right
       headers, respectively; and LLFF, CCFF, and RRFF to 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.

       ..OOHH '_l_e_f_t'_c_e_n_t_e_r'_r_i_g_h_t'
       ..OOFF '_l_e_f_t'_c_e_n_t_e_r'_r_i_g_h_t'
       ..EEHH '_l_e_f_t'_c_e_n_t_e_r'_r_i_g_h_t'
       ..EEFF '_l_e_f_t'_c_e_n_t_e_r'_r_i_g_h_t'
              The  OOHH  and EEHH macros define headers for odd‐ (recto) and even‐
              numbered (verso) pages, respectively; the OOFF and EEFF  macros  de‐
              fine footers for them.

       With  either  method,  a percent sign %% in header or footer text is re‐
       placed by the current page number.  By default, _m_s places no header  on
       a page numbered “1” (regardless of its number format).

       ..PP11    Typeset  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, _m_s permits  redefinition  of  the  macros
       called  when  the  page  header and footer traps are sprung.  PPTT (“page
       trap”) is called by _m_s when the header is to be written, and BBTT  (“bot‐
       tom trap”) when the footer is to be.  The _g_r_o_f_f page location trap that
       _m_s  sets up to format the header also calls the (normally undefined) HHDD
       macro after ..PPTT; you can define ..HHDD if you need  additional  processing
       after  setting  the  header.  The HHDD hook is a Berkeley extension.  Any
       such macros you (re)define must implement  any  desired  specialization
       for odd‐, even‐, or first numbered pages.

   TTaabb ssttooppss
       Use the ttaa request to set tab stops as needed.

       ..TTAA    Reset  the  tab stops to the _m_s default (every 5 ens).  Redefine
              this macro to create a different set of default tab stops.

   MMaarrggiinnss
       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 \\nn[[PPOO]] and
       line length \\nn[[LLLL]] determines it.

   MMuullttiippllee ccoolluummnnss
       _m_s 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.  \\nn[[MMIINNGGWW]] is the default minimum  gutter  width;
       it is a GNU extension.  When multiple columns are in use, keeps and the
       HHOORRPPHHAANNSS  and PPOORRPPHHAANNSS registers work with respect to column breaks in‐
       stead of page breaks.

       ..11CC    Arrange page text in a single column (the default).

       ..22CC    Arrange page text in two columns.

       ..MMCC [_c_o_l_u_m_n_‐_w_i_d_t_h [_g_u_t_t_e_r_‐_w_i_d_t_h]]
              Arrange page text in multiple columns.  If you specify no  argu‐
              ments,  it  is  equivalent  to the 22CC macro.  Otherwise, _c_o_l_u_m_n_‐
              _w_i_d_t_h is the width of each column and _g_u_t_t_e_r_‐_w_i_d_t_h is the  mini‐
              mum distance between columns.

   CCrreeaattiinngg aa ttaabbllee ooff ccoonntteennttss
       Define  an  entry  to appear in the table of contents by bracketing its
       text between calls to the XXSS and XXEE macros.  A typical  application  is
       to  call  them  immediately  after NNHH or SSHH and repeat the heading text
       within them.  The XXAA macro, used within ..XXSS/..XXEE pairs,  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 XXAA macro.  ..XXSS and ..XXAA automatically
       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 TTCC or PPXX to emit the table of contents;  ..TTCC  re‐
       sets  the page number to ii (Roman numeral one), and then calls PPXX.  All
       of these macros are Berkeley extensions.

       ..XXSS [_p_a_g_e_‐_n_u_m_b_e_r]
       ..XXAA [_p_a_g_e_‐_n_u_m_b_e_r [_i_n_d_e_n_t_a_t_i_o_n]]
       ..XXEE    Begin, supplement, and end a table of contents entry.  Each  en‐
              try  is  associated with _p_a_g_e_‐_n_u_m_b_e_r (otherwise the current page
              number); a _p_a_g_e_‐_n_u_m_b_e_r of “nnoo” prevents a leader and page number
              from being emitted for that entry.  Use of ..XXAA within ..XXSS/..XXEE is
              optional; it can be repeated.  If _i_n_d_e_n_t_a_t_i_o_n is present, a sup‐
              plemental entry is indented by that amount; ens are  assumed  if
              no  unit  is indicated.  Text on input lines between ..XXSS and ..XXEE
              is stored for later recall by ..PPXX.

       ..PPXX [nnoo]
              Switch to single‐column layout.  Unless “nnoo” is specified,  cen‐
              ter  and  interpolate \\**[[TTOOCC]] in bold and two points larger than
              the body text.  Emit the table of contents entries.

       ..TTCC [nnoo]
              Set the page number to 1, the page number  format  to  lowercase
              Roman numerals, and call PPXX (with a “nnoo” argument, if present).

       The remaining features in this subsection are GNU extensions.  _g_r_o_f_f _m_s
       obviates the need to repeat heading text after ..XXSS calls.  Call ..XXNN and
       ..XXHH  after  ..NNHH and ..SSHH, 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.

       ..XXNN _h_e_a_d_i_n_g_‐_t_e_x_t
              Format _h_e_a_d_i_n_g_‐_t_e_x_t and create a corresponding table of contents
              entry;  the  indentation  is computed from the _d_e_p_t_h argument of
              the preceding NNHH call.

       ..XXHH _d_e_p_t_h _h_e_a_d_i_n_g_‐_t_e_x_t
              As ..XXNN, but use _d_e_p_t_h to determine the indentation.

       _g_r_o_f_f _m_s encourages customization of table of  contents  entry  produc‐
       tion.  (Re‐)define any of the following macros as desired.

       ..XXNN--RREEPPLLAACCEEMMEENNTT _h_e_a_d_i_n_g_‐_t_e_x_t
       ..XXHH--RREEPPLLAACCEEMMEENNTT _d_e_p_t_h _h_e_a_d_i_n_g_‐_t_e_x_t
              These  hook  macros  implement ..XXNN and ..XXHH, and call XXNN--IINNIITT and
              XXHH--IINNIITT, respectively, then call XXHH--UUPPDDAATTEE--TTOOCC  with  the  argu‐
              ments given them.

       ..XXHH--IINNIITT
       ..XXNN--IINNIITT
              These hook macros do nothing by default.

       ..XXHH--UUPPDDAATTEE--TTOOCC _d_e_p_t_h _h_e_a_d_i_n_g_‐_t_e_x_t
              Bracket _h_e_a_d_i_n_g_‐_t_e_x_t with XXSS and XXEE calls, indenting it by 2 ens
              per level of _d_e_p_t_h beyond the first.

       You  can  customize  the style of the leader that bridges each table of
       contents entry with its page number; define the TTCC--LLEEAADDEERR special char‐
       acter by using the cchhaarr request.  A typical  leader  combines  the  dot
       glyph  “..” with a horizontal motion escape sequence to spread the dots.
       The width of the page number field is stored in the TTCC--MMAARRGGIINN register.

DDiiffffeerreenncceess ffrroomm AATT&&TT _mm_ss
       The _g_r_o_f_f _m_s macros are an independent reimplementation, using no  AT&T
       code.   Since  they  take  advantage of the extended features of _g_r_o_f_f,
       they cannot be used with AT&T _t_r_o_f_f.  _g_r_o_f_f _m_s  supports  features  de‐
       scribed  above  as Berkeley and Tenth Edition Research Unix extensions,
       and adds several of its own.

       •  The internals of _g_r_o_f_f _m_s differ from  the  internals  of  AT&T  _m_s.
          Documents that depend upon implementation details of AT&T _m_s may not
          format  properly  with  _g_r_o_f_f _m_s.  Such details include macros whose
          function was not documented in the AT&T _m_s 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 _g_r_o_f_f _m_s is to detect and report er‐
          rors, rather than to ignore them silently.

       •  Tenth Edition Research Unix supported PP11/PP22 macros to  bracket  code
          examples; _g_r_o_f_f _m_s does not.

       •  _g_r_o_f_f  _m_s  does not work in GNU _t_r_o_f_f’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.

       •  _g_r_o_f_f  _m_s uses the same header and footer defaults in both _n_r_o_f_f and
          _t_r_o_f_f modes as AT&T _m_s does in _t_r_o_f_f mode; AT&T’s default  in  _n_r_o_f_f
          mode  is to put the date, in U.S. traditional format (e.g., “January
          1, 2021”), in the center footer (the CCFF string).

       •  Many _g_r_o_f_f _m_s 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 ..RRSS and ..RREE instead of the iinn request.

       •  AT&T _m_s interpreted the values of the registers PPSS and VVSS in points,
          and  did  not  support the use of scaling units with them.  _g_r_o_f_f _m_s
          interprets values of the registers PPSS, VVSS, FFPPSS, and FFVVSS, 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  _g_r_o_f_f  Texinfo  manual  or  in
          _g_r_o_f_f(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, “ggrrooffff --rrPPSS==1100..55pp” at the shell prompt  is
          equivalent  to  placing “..nnrr PPSS 1100..55pp” at the beginning of the docu‐
          ment.

       •  AT&T _m_s’s AAUU macro  supported  arguments  used  with  some  document
          types; _g_r_o_f_f _m_s does not.

       •  Right‐aligned  displays  are available.  The AT&T _m_s manual observes
          that “it is tempting to assume that “..DDSS RR” will right adjust lines,
          but it doesn’t work”.  In _g_r_o_f_f _m_s, it does.

       •  To make _g_r_o_f_f _m_s use the default page offset (which  also  specifies
          the  left  margin),  the  PPOO  register must stay undefined until the
          first _m_s macro is called.  This implies that \\nn[[PPOO]]  should  not  be
          used  early in the document, unless it is changed also: accessing an
          undefined register automatically defines it.

       •  _g_r_o_f_f _m_s supports the PPNN register, but it is not necessary; you  can
          access  the  page  number via the usual %% register and invoke the aaff
          request to assign a different format to it if desired.  (If you  re‐
          define  the _m_s PPTT macro and desire special treatment of certain page
          numbers—like “11”—you may need to handle  a  non‐Arabic  page  number
          format, as _g_r_o_f_f _m_s’s ..PPTT does; see the macro package source.  _g_r_o_f_f
          _m_s aliases the PPNN register to %%.)

       •  The  AT&T _m_s manual documents registers CCWW and GGWW as setting the de‐
          fault column width and “intercolumn gap”,  respectively,  and  which
          applied when ..MMCC was called with fewer than two arguments.  _g_r_o_f_f _m_s
          instead  treats  ..MMCC without arguments as synonymous with ..22CC; there
          is thus no occasion for a default column width  register.   Further,
          the  MMIINNGGWW register and the second argument to ..MMCC specify a _m_i_n_i_m_u_m
          space between columns, not the fixed gutter width of AT&T _m_s.

       •  The AT&T _m_s manual did not document the QQII  register;  Berkeley  and
          _g_r_o_f_f _m_s do.

       •  The  register GGSS is set to 1 by the _g_r_o_f_f _m_s macros, but is not used
          by the AT&T _m_s package.  Documents that need  to  determine  whether
          they  are  being  formatted  with _g_r_o_f_f _m_s or another implementation
          should test this register.

   UUnniixx VVeerrssiioonn 77 mmaaccrrooss nnoott iimmpplleemmeenntteedd bbyy _gg_rr_oo_ff_ff _mm_ss
       Several macros described in the Unix Version  7  _m_s  documentation  are
       unimplemented by _g_r_o_f_f _m_s 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 _g_r_o_f_f does not  sup‐
       port.   These macros implemented several document type formats (EEGG, IIMM,
       MMFF, MMRR, TTMM, TTRR), were meaningful only in conjunction with  the  use  of
       certain  document  types  (AATT,  CCSS,  CCTT, OOKK, SSGG), stored the postal ad‐
       dresses of Bell Labs sites (HHOO, IIHH, MMHH, PPYY, WWHH), or lacked a stable de‐
       finition over time (UUXX).

LLeeggaaccyy ffeeaattuurreess
       _g_r_o_f_f _m_s retains some legacy features solely to support  formatting  of
       historical  documents;  contemporary  ones  should not use them because
       they can render poorly.  See _g_r_o_f_f___c_h_a_r(7) instead.

   AATT&&TT _mm_ss aacccceenntt mmaarrkk ssttrriinnggss
       AT&T _m_s defined accent mark strings as follows.

       SSttrriinngg   DDeessccrriippttiioonn
       ──────────────────────────────────────────────────────
       \*[']    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.

   BBeerrkkeelleeyy _mm_ss aacccceenntt mmaarrkk aanndd ggllyypphh ssttrriinnggss
       Berkeley _m_s offered an AAMM macro; calling it redefined the  AT&T  accent
       mark strings (except for \\**CC), applied them to the _p_r_e_c_e_d_i_n_g glyph, and
       defined additional strings, some for spacing glyphs.

       ..AAMM    Enable alternative accent mark and glyph‐producing strings.

       SSttrriinngg   DDeessccrriippttiioonn
       ───────────────────────────────────────────────────────────────
       \*[']    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.

NNaammiinngg ccoonnvveennttiioonnss
       The  following  conventions  are used for names of macros, strings, and
       registers.  External names available to documents that use the _g_r_o_f_f _m_s
       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 _m_o_d_u_l_e**_n_a_m_e.

       •  Names used outside the module in which they are defined are  of  the
          form _m_o_d_u_l_e@@_n_a_m_e.

       •  Names  associated  with  a  particular  environment  are of the form
          _e_n_v_i_r_o_n_m_e_n_t::_n_a_m_e; these are used only within the ppaarr module.

       •  _n_a_m_e does not have a module prefix.

       •  Constructed  names  used  to  implement  arrays  are  of  the   form
          _a_r_r_a_y!!_i_n_d_e_x.

       Thus the _g_r_o_f_f _m_s macros reserve the following names:

       •  Names containing the characters **, @@, and ::.

       •  Names containing only uppercase letters and digits.

FFiilleess
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_s_._t_m_a_c
              implements the package.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_r_e_f_e_r_-_m_s_._t_m_a_c
              implements _r_e_f_e_r(1) support for _m_s.

       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_m_s_._t_m_a_c
              is  a  wrapper  enabling the package to be loaded with “ggrrooffff --mm
              mmss”.

AAuutthhoorrss
       The GNU version of the _m_s macro package was written by James Clark  and
       contributors.  This document was written by Clark, Larry Kollar, and G.
       Branden Robinson.

SSeeee aallssoo
       A  manual is available in source and rendered form.  On your system, it
       may be compressed and/or available in additional formats.

       _/_u_s_r_/_s_h_a_r_e_/_d_o_c_/_g_r_o_f_f_-_b_a_s_e_/_m_s_._m_s
       _/_u_s_r_/_s_h_a_r_e_/_d_o_c_/_g_r_o_f_f_-_b_a_s_e_/_m_s_._p_s
              “Using _g_r_o_f_f with  the  _m_s  Macro  Package”;  Larry  Kollar  and
              G. Branden Robinson.

       _/_u_s_r_/_s_h_a_r_e_/_d_o_c_/_g_r_o_f_f_-_b_a_s_e_/_m_s_b_o_x_e_s_._m_s
       _/_u_s_r_/_s_h_a_r_e_/_d_o_c_/_g_r_o_f_f_-_b_a_s_e_/_m_s_b_o_x_e_s_._p_d_f
              “Using  PDF  boxes  with  _g_r_o_f_f  and the _m_s macros”; Deri James.
              BBOOXXSSTTAARRTT and BBOOXXSSTTOOPP macros are available via the _s_b_o_x_e_s  exten‐
              sion package, enabling colored, bordered boxes when the ppddff out‐
              put device is used.

       _G_r_o_f_f_:  _T_h_e  _G_N_U _I_m_p_l_e_m_e_n_t_a_t_i_o_n _o_f _t_r_o_f_f, by Trent A. Fisher and Werner
       Lemberg, is the primary _g_r_o_f_f manual.  You can browse it  interactively
       with “info groff”.

       _g_r_o_f_f(1), _t_r_o_f_f(1), _t_b_l(1), _p_i_c(1), _e_q_n(1), _r_e_f_e_r(1)

groff 1.23.0                      3 June 2025                      _g_r_o_f_f___m_s(7)
───────────────────────────────────────────────────────────────────────────────
_g_r_o_f_f___r_f_c_1_3_4_5(7)       Miscellaneous Information Manual       _g_r_o_f_f___r_f_c_1_3_4_5(7)

NNaammee
       groff_rfc1345 - special character names from RFC 1345 and Vim digraphs

DDeessccrriippttiioonn
       The  file  _r_f_c_1_3_4_5_._t_m_a_c  defines special character escape sequences for
       _g_r_o_f_f(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, “\\[[RRxx]]” is the “recipe” or “prescription take” symbol, and
       maps  to the code point U+211E.  _g_r_o_f_f lets you write it as “\\[[uu221111EE]]”,
       but “\\[[RRxx]]” is more mnemonic.

       For  a  list  of  the  glyph  names  provided,  please  see  the   file
       _r_f_c_1_3_4_5_._t_m_a_c, which contains definitions of the form
              .char \[Rx] \[u211E]    \" PRESCRIPTION TAKE
       where  ..cchhaarr’s  first argument defines a _g_r_o_f_f 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 _r_f_c_1_3_4_5_._t_m_a_c.

       _r_f_c_1_3_4_5_._t_m_a_c contains a total of 1,696 glyph names.  It is not an error
       to load _r_f_c_1_3_4_5_._t_m_a_c 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 _g_r_o_f_f; for exam‐
       ple, “\\[[<<<<]]” means the “much less than” sign (U+226A) when _r_f_c_1_3_4_5_._t_m_a_c
       is not loaded and this special character is not otherwise defined by  a
       document  or  macro  package.   _r_f_c_1_3_4_5_._t_m_a_c  redefines  “\\[[<<<<]]” to the
       “left‐pointing   double   angle   quotation   mark”   (U+00AB).     See
       _g_r_o_f_f___c_h_a_r(7)  for the full list of predefined special character escape
       sequences.

   UUssaaggee
       Load the _r_f_c_1_3_4_5_._t_m_a_c file.  This can be done by  either  adding  “..mmssoo
       rrffcc11334455..ttmmaacc” to your document before the first use of any of the glyph
       names  the  macro  file  defines,  or  by using the _t_r_o_f_f(1) option “--mm
       rrffcc11334455” from the shell.

   BBuuggss
       As the _g_r_o_f_f Texinfo manual notes, “[o]nly the current font is  checked
       for  ligatures  and  kerns;  neither special fonts nor entities defined
       with the cchhaarr request (and its siblings) are taken into account.”  Many
       of the characters defined in _r_f_c_1_3_4_5_._t_m_a_c are accented  Latin  letters,
       and will be affected by this deficiency, producing subpar typography.

FFiilleess
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_r_f_c_1_3_4_5_._t_m_a_c
              implements the character mappings.

AAuutthhoorrss
       _r_f_c_1_3_4_5_._t_m_a_c was contributed by Dorai Sitaram.

SSeeee aallssoo
       RFC 1345, by Keld Simonsen, June 1992.

       The  Vim  digraph  table  can be listed using the _v_i_m(1) command “::hheellpp
       ddiiggrraapphh--ttaabbllee”.

       _g_r_o_f_f___c_h_a_r(7)

groff 1.23.0                      3 June 2025                 _g_r_o_f_f___r_f_c_1_3_4_5(7)
───────────────────────────────────────────────────────────────────────────────
_g_r_o_f_f___t_r_a_c_e(7)         Miscellaneous Information Manual         _g_r_o_f_f___t_r_a_c_e(7)

NNaammee
       groff_trace - macros for debugging GNU _r_o_f_f documents

SSyynnooppssiiss
       ggrrooffff --mm ttrraaccee [_o_p_t_i_o_n ...] [_f_i_l_e ...]

DDeessccrriippttiioonn
       _t_r_a_c_e is a macro package for the _g_r_o_f_f(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  “--mm  ttrraaccee”
       to  the formatter program (often _g_r_o_f_f(1)).  You can achieve finer con‐
       trol by including the macro file within the document;  invoke  the  mmssoo
       request,  as  in “..mmssoo ttrraaccee..ttmmaacc”.  Only macros that are defined after
       this invocation are traced.  If the ttrraaccee--ffuullll register  is  set  to  a
       true value, as with the command‐line option “--rr ttrraaccee--ffuullll==11”, register
       and  string  assignments,  along  with  some other requests, are traced
       also.  If another macro package should be traced as  well,  specify  it
       after “--mm ttrraaccee” on the command line.

       The  macro  file  _t_r_a_c_e_._t_m_a_c is unusual because it does not contain any
       macros to be called by a user.  Instead, _g_r_o_f_f’s macro  definition  and
       alteration  facilities  are  wrapped  such that they display diagnostic
       messages.

   LLiimmiittaattiioonnss
       Because _t_r_a_c_e_._t_m_a_c wraps the ddee request (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  ddee  redefined,  it
       passes “\n[bar]” instead.

       The  solution  to this problem is to use _g_r_o_f_f’s \\EE escape sequence, an
       escape character that is not interpreted in copy mode.
              .foo \En[bar]

EExxaammpplleess
       We will illustrate _t_r_a_c_e_._t_m_a_c using the shell’s “here document” feature
       to supply _g_r_o_f_f 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 _/_d_e_v_/_n_u_l_l.

   OObbsseerrvviinngg nneesstteedd mmaaccrroo ccaallllss
       Macro calls can be nested,  even  with  themselves.   Tracing  recurses
       along with them; this feature can help to detangle complex call stacks.

              $ ccaatt <<<<EEOOFF || ggrrooffff --mm ttrraaccee >> //ddeevv//nnuullll
              ..ddee ccoouunnttddoowwnn
              .. nnoopp \\\\$$11
              .. nnrr ccoouunntt ((\\\\$$11 ‐‐ 11))
              .. iiff \\\\nn[[ccoouunntt]] ..ccoouunnttddoowwnn \\\\nn[[ccoouunntt]]
              ....
              ..ccoouunnttddoowwnn 33
              bbllaassttooffff
              EEOOFF
               *** .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"

   TTrraacciinngg wwiitthh tthhee mmssoo rreeqquueesstt
       Now  let  us  activate tracing within the document, not with a command‐
       line option.  We might do this when using a macro package  like  _m_s  or
       _m_o_m,  where  we  may  not  want to be distracted by traces of macros we
       didn’t write.

              $ ccaatt <<<<EEOOFF || ggrrooffff ‐‐mmss >> //ddeevv//nnuullll
              ..LLPP
              TThhiiss iiss mmyy iinnttrroodduuccttoorryy ppaarraaggrraapphh..
              ..mmssoo ttrraaccee..ttmmaacc
              ..ddee MMyymmaacc
              ....
              ..MMyymmaacc
              ..PPPP
              LLeett uuss rreevviieeww tthhee eexxiissttiinngg lliitteerraattuurree..
              EEOOFF
               *** .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 _s_._t_m_a_c), their calls were not traced; contrast with the macro
       “Mymac”.

FFiilleess
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_t_r_a_c_e_._t_m_a_c
              implements the package.

AAuutthhoorrss
       _t_r_a_c_e_._t_m_a_c  was  written  by James Clark.  This document was written by
       Bernd Warken and G. Branden Robinson.

SSeeee aallssoo
       _G_r_o_f_f_: _T_h_e _G_N_U _I_m_p_l_e_m_e_n_t_a_t_i_o_n _o_f _t_r_o_f_f, by Trent A. Fisher  and  Werner
       Lemberg,  is the primary _g_r_o_f_f manual.  You can browse it interactively
       with “info groff”.

       _g_r_o_f_f(1)
              gives an overview of the _g_r_o_f_f document formatting system.

       _t_r_o_f_f(1)
              supplies details of the --mm command‐line option.

       _g_r_o_f_f___t_m_a_c(5)
              offers a survey of _g_r_o_f_f macro packages.

       _g_r_o_f_f(7)
              is a reference manual for the _g_r_o_f_f language.

groff 1.23.0                      3 June 2025                   _g_r_o_f_f___t_r_a_c_e(7)
───────────────────────────────────────────────────────────────────────────────
_g_r_o_f_f___w_w_w(7)           Miscellaneous Information Manual           _g_r_o_f_f___w_w_w(7)

NNaammee
       groff_www - GNU _r_o_f_f macros for authoring web pages

SSyynnooppssiiss
       ggrrooffff --mm wwwwww [_o_p_t_i_o_n ...] [_f_i_l_e ...]

DDeessccrriippttiioonn
       This manual page describes the GNU _w_w_w macro package, which is part  of
       the  _g_r_o_f_f(7) document formatting system.  This macro file is automati‐
       cally loaded by the default _t_r_o_f_f_r_c file when  the  formatter  (usually
       _g_r_o_f_f(1))  is  called with either of the options --TThhttmmll or --TTxxhhttmmll.  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 (_g_r_o_h_t_m_l) 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.

MMaaccrrooss
       ..JJOOBBNNAAMMEE ffiilleennaammee
              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
              _g_r_o_h_t_m_l’s --jj option.

       ..HHXX nn  Specify the cut off depth when  generating  links  from  section
              headings.   For example, a parameter of 2 would cause _g_r_o_h_t_m_l to
              generate a list of links for ..NNHH 11 and ..NNHH 22 but not for  ..NNHH 33.
              Whereas

                     .HX 0

              tells  _g_r_o_h_t_m_l  that  no heading links should be created at all.
              Another method for turning automatic headings off is by  issuing
              the command‐line switch --PP--ll to _g_r_o_f_f.

       ..BBCCLL _f_o_r_e_g_r_o_u_n_d _b_a_c_k_g_r_o_u_n_d _a_c_t_i_v_e _n_o_t_‐_v_i_s_i_t_e_d _v_i_s_i_t_e_d
              This macro takes five parameters: foreground, background, active
              hypertext  link, hypertext link not yet visited, and visited hy‐
              pertext link colour.

       ..BBGGIIMMGG iimmaaggeeffiillee
              the only parameter to this macro is the background image file.

       ..UURRLL uurrll [[ddeessccrriippttiioonn]] [[aafftteerr]]
              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 ddeessccrriippttiioonn and aafftteerr are absent  then  the  UURRLL
              becomes the anchor text.  Hyphenation is disabled while printing
              the actual URL; explicit breakpoints should be inserted with the
              \\:: escape sequence.  Here is how to encode foo:

                     ..UURRLL hhttttpp::////\\::ffoooo\\::..oorrgg// ffoooo ::

              If this is processed by a device other than --TThhttmmll or --TTxxhhttmmll it
              appears as:

                     foo ⟨http://foo.org⟩:

              The  URL macro can be of any type; for example, we can reference
              Eric Raymond’s _p_i_c guide by:

                     ..UURRLL ppiicc\\::..hhttmmll ""EErriicc RRaayymmoonndd''ss ppiicc gguuiiddee""

       ..MMTTOO aaddddrreessss [[ddeessccrriippttiioonn]] [[aafftteerr]]
              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,
              aaddddrreessss  is  used  instead.  An optional third argument is stuff
              printed immediately afterwards.  Hyphenation is  disabled  while
              printing the actual email address.  For example, Joe User can be
              achieved by the following macro:

                     ..MMTTOO jjooee@@uusseerr..oorrgg ""JJooee UUsseerr""

              All  URLs currently are treated as consuming no textual space in
              _g_r_o_f_f.  This could be considered as a bug since it  causes  some
              problems.   To  circumvent  this,  wwwwww..ttmmaacc inserts a zero‐width
              character which expands to a harmless space (only  if  run  with
              --TThhttmmll or --TTxxhhttmmll).

       ..FFTTPP uurrll [[ddeessccrriippttiioonn]] [[aafftteerr]]
              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.
              The macro example above can be specified as:

                     ..FFTTPP ffttpp::////\\::ffttpp\\::..ggnnuu\\::..oorrgg// ""GGNNUU FFTTPP sseerrvveerr"" ..

       ..TTAAGG nnaammee
              Generates an HTML name tag from its argument.  This can then  be
              referenced  using  the URL macro.  As you can see, you must pre‐
              cede the tag name with ## since 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.
                     ...

       ..IIMMGG [[--RR||--LL||--CC]] ffiilleennaammee [[wwiiddtthh]] [[hheeiigghhtt]]
              Include a picture into the document.  The first argument is  the
              horizontal  location:  right,  left,  or center (--RR, --LL, or --CC).
              Alignment is centered by default (--CC).  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 PPIIMMGG macro.

       ..PPIIMMGG [[--RR||--LL||--CC]] ffiilleennaammee [[wwiiddtthh [[hheeiigghhtt]]]]
              Include an image in PNG format.  This macro  takes  exactly  the
              same  parameters as the IIMMGG macro; 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 nneettppbbmm package: ppnnggttooppnnmm, ppnnmmccrroopp, and  ppnnmmttooppss.
              If  the  document  isn’t  processed with --TThhttmmll or --TTxxhhttmmll it is
              necessary to use the --UU option of _g_r_o_f_f.

       ..MMPPIIMMGG [[--RR||--LL]] [[--GG ggaapp]] ffiilleennaammee [[wwiiddtthh [[hheeiigghhtt]]]]
              Place a PNG image on the margin and wrap text  around  it.   The
              first parameters are optional.  The alignment: left or right (--LL
              or --RR) specifies the margin where the picture is placed at.  The
              default  alignment is left (--LL).  Optionally, --GG _g_a_p 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 ..ll register and
              the height from the ..pp register.  For example:

                     .MPIMG -L -G 2c foo.png 15%

       ..HHnnSS nn Begin heading.  The numeric heading level _n 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 --PP--ll from the command line.

       ..HHnnEE   End heading.

       ..LLKK    Force _g_r_o_h_t_m_l to place the automatically generated links at this
              position.

       ..HHRR    Generate  a  full‐width  horizontal rule for --TThhttmmll and --TTxxhhttmmll.
              No effect for all other devices.

       ..NNHHRR   Suppress generation of the top and bottom  rules  which  _g_r_o_h_t_m_l
              emits by default.

       ..HHTTLL   Generate  an HTML title only.  This differs from the TTLL macro of
              the mmss macro 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).

       ..HHEEAADD  Add  arbitrary  HTML  data  to the <head> block.  Ignored if not
              processed with --TThhttmmll or --TTxxhhttmmll.  Example:

                     .HEAD "<link \
                       rel=""icon"" \
                       type=""image/png"" \
                       href=""http://foo.org//bar.png""/>"

       ..HHTTMMLL  All text after this macro is treated as raw HTML.  If the  docu‐
              ment  is  processed  without --TThhttmmll or --TTxxhhttmmll then the macro is
              ignored.  Internally, this macro is used as a building block for
              other higher‐level macros.

              For example, the BBGGIIMMGG macro is defined as

                     .de BGIMG
                     .   HTML <body background=\\$1>
                     ..

       ..DDCC ll tteexxtt [[ccoolloorr]]
              Produce a drop capital.  The first parameter is the letter to be
              dropped and enlarged, the second parameter tteexxtt is 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.

       ..CCDDSS   Start displaying a code section in constant width font.

       ..CCDDEE   End code display

       ..AALLNN [[ccoolloorr]] [[ppeerrcceennttaaggee]]
              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.

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

       ..LLNNEE   End a two‐column table.  This should be called at the end of the
              document if .ALN was used.

       ..LLIINNKKSSTTYYLLEE ccoolloorr [[ ffoonnttssttyyllee [[ ooppeennggllyypphh cclloosseeggllyypphh ]] ]]
              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.

SSeeccttiioonn hheeaaddiinngg lliinnkkss
       By  default  _g_r_o_h_t_m_l generates links to all section headings and places
       these at the top of the HTML document.  (See LINKS for details  of  how
       to switch this off or alter the position).

LLiimmiittaattiioonnss ooff _gg_rr_oo_hh_tt_mm_ll
       _t_b_l(1)  tables are rendered as PNG images.  Paul DuBois’s approach with
       _t_b_l_c_v_t(1), part of the _t_r_o_f_f_c_v_t distribution, should be explored.

FFiilleess
       _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_3_._0_/_t_m_a_c_/_w_w_w_._t_m_a_c

AAuutthhoorrss
       The _w_w_w macro package was written by Gaius Mulley,  with  additions  by
       Werner Lemberg and Bernd Warken.

SSeeee aallssoo
       _g_r_o_f_f(1), _t_r_o_f_f(1), _g_r_o_h_t_m_l(1), _n_e_t_p_b_m(1)

groff 1.23.0                      3 June 2025                     _g_r_o_f_f___w_w_w(7)
───────────────────────────────────────────────────────────────────────────────
_r_o_f_f(7)                Miscellaneous Information Manual                _r_o_f_f(7)

NNaammee
       roff - concepts and history of _r_o_f_f typesetting

DDeessccrriippttiioonn
       The  term _r_o_f_f denotes a family of document formatting systems known by
       names like _t_r_o_f_f, _n_r_o_f_f, and _d_i_t_r_o_f_f.  A _r_o_f_f 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 _r_o_f_f system.  The manual
       pages on Unix systems (“man pages”) and bestselling books  on  software
       engineering,  including Brian Kernighan and Dennis Ritchie’s _T_h_e _C _P_r_o_‐
       _g_r_a_m_m_i_n_g _L_a_n_g_u_a_g_e and W. Richard Stevens’s _A_d_v_a_n_c_e_d _P_r_o_g_r_a_m_m_i_n_g _i_n  _t_h_e
       _U_n_i_x _E_n_v_i_r_o_n_m_e_n_t have been written using _r_o_f_f systems.  GNU _r_o_f_f—_g_r_o_f_f—
       is arguably the most widespread _r_o_f_f implementation.

       Below we present typographical concepts that form the background of all
       _r_o_f_f implementations, narrate the development history of some _r_o_f_f sys‐
       tems,  detail the command pipeline managed by _g_r_o_f_f(1), survey the for‐
       matting language, suggest tips for editing _r_o_f_f  input,  and  recommend
       further reading materials.

CCoonncceeppttss
       _r_o_f_f input files contain text interspersed with instructions to control
       the  formatter.   Even in the absence of such instructions, a _r_o_f_f 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 _r_o_f_f formatter starts up, it obtains informa‐
       tion  about  the  device for which it is preparing output from the lat‐
       ter’s description file (see _g_r_o_f_f___f_o_n_t(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 _f_i_l_l_i_n_g_.  To a _r_o_f_f system, a _w_o_r_d is any sequence
       of  one  or more characters that aren’t spaces or newlines.  The excep‐
       tions separate words.

       A _r_o_f_f formatter attempts to detect boundaries between  sentences,  and
       supplies  additional  inter‐sentence space between them.  It flags cer‐
       tain characters (normally “!!”, “??”, and “..”) as  potentially  ending  a
       sentence.   When  the formatter encounters one of these _e_n_d_‐_o_f_‐_s_e_n_t_e_n_c_e
       _c_h_a_r_a_c_t_e_r_s 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 \\&& can 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 _t_r_a_n_s_p_a_r_e_n_t_l_y after the occurrence of an end‐of‐sen‐
       tence  character.   That is, a _r_o_f_f 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 "", '', )),  ]],  **,  \\[[ddgg]],  \\[[dddd]],  \\[[rrqq]],  and
       \\[[ccqq]].   The  last  four are examples of _s_p_e_c_i_a_l _c_h_a_r_a_c_t_e_r_s_, 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 \\).

       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 _h_y_p_h_e_n_a_t_i_o_n_.  Hyphenation points can be manually specified;
       _g_r_o_f_f  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 _b_r_e_a_k_.
       In  this  document  and in _r_o_f_f 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  _r_o_f_f formatter _a_d_j_u_s_t_s 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.  _g_r_o_f_f 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 \\::.

       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  _a_d_j_u_s_t_e_d  (see  below).   Again,  macro
       packages  may  provide  other methods of producing indented paragraphs.
       Trailing spaces on _t_e_x_t _l_i_n_e_s (see below) are discarded.   The  end  of
       input causes a break.

       After the formatter performs an automatic break, it may then _a_d_j_u_s_t 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 _r_e_q_u_e_s_t_s_.

       A _r_o_f_f 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 _t_b_l(1) preproces‐
       sor to lay out tables.

   RReeqquueessttss aanndd mmaaccrrooss
       A  _r_e_q_u_e_s_t  is an instruction to the formatter that occurs after a _c_o_n_‐
       _t_r_o_l _c_h_a_r_a_c_t_e_r_, which is recognized at the beginning of an input  line.
       The  regular  control character is a dot “..”.  Its counterpart, the _n_o_‐
       _b_r_e_a_k _c_o_n_t_r_o_l _c_h_a_r_a_c_t_e_r_, a neutral apostrophe “''”, 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,
       “\\&&”.

       An input line beginning with a control character is  called  a  _c_o_n_t_r_o_l
       _l_i_n_e_.  Every line of input that is not a control line is a _t_e_x_t _l_i_n_e_.

       Requests  often  take _a_r_g_u_m_e_n_t_s_, 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 _m_a_c_r_o can be thought of as an abbreviation you can define for a  col‐
       lection  of control and text lines.  When the macro is _c_a_l_l_e_d by giving
       its name after a control character, it is replaced with what it  stands
       for.   The  process  of  textual replacement is known as _i_n_t_e_r_p_o_l_a_t_i_o_n_.
       Interpolations are handled as soon as they  are  recognized,  and  once
       performed, a _r_o_f_f formatter scans the replacement for further requests,
       macro calls, and escape sequences.

       In _r_o_f_f systems, the “ddee” request defines a macro.

   PPaaggee ggeeoommeettrryy
       _r_o_f_f  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 _r_e_s_o_l_u_t_i_o_n converts practical units like inches or
       centimeters to _b_a_s_i_c _u_n_i_t_s_, 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 _g_r_o_f_f___f_o_n_t(5)).

       A _p_a_g_e is a two‐dimensional structure upon which a _r_o_f_f 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 _d_r_a_w_i_n_g _p_o_s_i_t_i_o_n_, 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.
       (_g_r_o_f_f  does not yet support right‐to‐left scripts.)  The _t_e_x_t _b_a_s_e_l_i_n_e
       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 _r_o_f_f 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 _p_a_g_e _o_f_f_s_e_t_.  (_g_r_o_f_f’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.  _V_e_r_t_i_c_a_l _s_p_a_c_i_n_g 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 _v_e_e_.

       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,  _r_o_f_f  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 _p_a_g_e _b_r_e_a_k_.

       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.

   OOtthheerr llaanngguuaaggee eelleemmeennttss
       _E_s_c_a_p_e  _s_e_q_u_e_n_c_e_s  start  with the _e_s_c_a_p_e _c_h_a_r_a_c_t_e_r_, a backslash \\, 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.

       _S_t_r_i_n_g_s store character sequences.  In _g_r_o_f_f, they can be parameterized
       as macros can.

       _R_e_g_i_s_t_e_r_s store numerical values, including measurements.   The  latter
       are  generally in basic units; _s_c_a_l_i_n_g _u_n_i_t_s can be appended to numeric
       expressions to clarify their meaning when stored or interpolated.  Some
       read‐only predefined registers interpolate text.

       _F_o_n_t_s are identified either by a name or by a mounting position (a non‐
       negative number).  Four styles are available on all devices.  RR is “ro‐
       man”: normal, upright text.  BB is bboolldd,  an  upright  typeface  with  a
       heavier weight.  II is _i_t_a_l_i_c, a face that is oblique on typesetter out‐
       put  devices and usually underlined instead on terminal devices.  BBII is
       _bb_oo_ll_dd_‐‐_ii_tt_aa_ll_ii_cc, combining both of the foregoing style  variations.   Type‐
       setting  devices  group  these four styles into _f_a_m_i_l_i_e_s of text fonts;
       they also typically offer one or more _s_p_e_c_i_a_l fonts  that  provide  un‐
       styled glyphs; see _g_r_o_f_f___c_h_a_r(7).

       _g_r_o_f_f  supports named _c_o_l_o_r_s for glyph rendering and drawing of geomet‐
       ric objects.  Stroke and fill colors are distinct; the stroke color  is
       used for glyphs.

       _G_l_y_p_h_s  are  visual  representation forms of _c_h_a_r_a_c_t_e_r_s_.  In _g_r_o_f_f_, 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 _r_o_f_f language and may not look correct in output if used
       unthinkingly; they are the (double) quotation  mark  (""),  the  neutral
       apostrophe  (''),  the  minus  sign (--), the backslash (\\), the caret or
       circumflex accent (^^), the grave accent (``), and the tilde (~~).  All of
       these and more can be produced with _s_p_e_c_i_a_l _c_h_a_r_a_c_t_e_r escape sequences;
       see _g_r_o_f_f___c_h_a_r(7).

       _g_r_o_f_f offers _s_t_r_e_a_m_s, 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.  _E_n_v_i_r_o_n_m_e_n_t_s collect formatting  parameters
       like line length and typeface.  A _d_i_v_e_r_s_i_o_n stores formatted output for
       later  use.  A _t_r_a_p 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.

HHiissttoorryy
       Computer‐driven document formatting dates back to the 1960s.  The  _r_o_f_f
       system  is intimately connected with Unix, but its origins lie with the
       earlier operating systems CTSS, GECOS, and Multics.

   TThhee pprreeddeecceessssoorr——_RR_UU_NN_OO_FF_FF
       _r_o_f_f’s ancestor _R_U_N_O_F_F 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.
       _R_U_N_O_F_F 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 _n” 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 _R_U_N_O_F_F manual of December 1966 was documented as  follows  (with
       the  parameter  notation  slightly altered).  The abbreviations will be
       familiar to _r_o_f_f veterans.

                           Abbreviation   Control word
                                    ..aadd   .adjust
                                    ..bbpp   .begin page
                                    ..bbrr   .break
                                    ..ccee   .center
                                    ..iinn   .indent _n
                                    ..llll   .line length _n
                                    ..nnff   .nofill
                                    ..ppll   .paper length _n
                                    ..sspp   .space [_n]

       In 1965, MIT’s Project MAC teamed with Bell Telephone Laboratories  and
       General  Electric  (GE) to inaugurate the Multics project.  After a few
       years, Bell Labs discontinued its participation  in  Multics,  famously
       prompting  the development of Unix.  Meanwhile, Saltzer’s _R_U_N_O_F_F proved
       influential, seeing many ports and derivations 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 ..cccc request.  Other
       familiar requests emerged at this time; no‐adjust  (..nnaa),  need  (..nnee),
       page  offset  (..ppoo),  tab  configuration (..ttaa, though it worked differ‐
       ently), temporary indent (..ttii), character translation (..ttrr), and  auto‐
       matic  underlining  (..uull; on _R_U_N_O_F_F you had to backspace and underscore
       in the input yourself).  ..ffii to 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 _r_o_f_f, a name McIlroy attributes to Bob Morris, to
       distinguish it from CTSS _R_U_N_O_F_F.

   UUnniixx aanndd _rr_oo_ff_ff
       McIlroy’s  _r_o_f_f 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  ..hhcc  and  ..hhyy requests, line spacing control was generalized with
       the ..llss request, and what later _r_o_f_fs would call diversions were avail‐
       able via “footnote” requests.  This _r_o_f_f  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; _r_o_f_f 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.

   NNeeww _rr_oo_ff_ff aanndd TTyyppeesseetttteerr _rr_oo_ff_ff
       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 _r_o_f_f extensi‐
       ble.  Joe Ossanna’s _n_r_o_f_f, 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 _r_o_f_f systems: definition of macros  (..ddee),  diversion
       of  text  thither (..ddii), and removal thereof (..rrmm); trap planting (..wwhh;
       “when”) and relocation (..cchh; “change”); conditional  processing  (..iiff);
       and  environments  (..eevv).  Incremental improvements included assignment
       of the next page number (..ppnn); no‐space mode (..nnss) and  restoration  of
       vertical  spacing  (..rrss); the saving (..ssvv) and output (..ooss) of vertical
       space; specification of replacement characters for tabs (..ttcc) and lead‐
       ers (..llcc); configuration  of  the  no‐break  control  character  (..cc22);
       shorthand  to  disable  automatic  hyphenation (..nnhh); a condensation of
       what were formerly six different requests  for  configuration  of  page
       “titles”  (headers and footers) into one (..ttll) with a length controlled
       separately from the line length (..lltt); automatic line numbering  (..nnmm);
       interactive  input (..rrdd), which necessitated buffer‐flushing (..ffll), and
       was made convenient with early program cessation (..eexx); source file in‐
       clusion in its modern form (..ssoo; though _R_U_N_O_F_F had an “.append” control
       word for a similar purpose) and early advance to the next file argument
       (..nnxx); ignorable content (..iigg); and programmable abort (..aabb).

       Third Edition Unix also brought the _p_i_p_e(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  _r_o_f_f
       system  to  cope  with  a variety of proportionally spaced typefaces at
       multiple sizes.  Ossanna wrote a parallel implementation of  _n_r_o_f_f  for
       the  C/A/T,  dubbing  it _t_r_o_f_f (for “typesetter roff”).  Unfortunately,
       surviving documentation does not illustrate what requests  were  imple‐
       mented  at this time for C/A/T support; the _t_r_o_f_f(1) man page in Fourth
       Edition Unix (November 1973) does not feature a  request  list,  unlike
       _n_r_o_f_f(1).   Apart from typesetter‐driven features, Unix Version 4 _r_o_f_fs
       added string definitions (..ddss); made the escape character  configurable
       (..eecc);  and enabled the user to write diagnostics to the standard error
       stream (..ttmm).  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 _e_q_n for typesetting
       mathematics.  In the same year, for Fifth Edition  Unix,  Ossanna  com‐
       bined  and reimplemented the two _r_o_f_fs 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  _n_r_o_f_f  and
       _t_r_o_f_f  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 _r_o_f_f practitioners have tended to refer to it by  its  AT&T
       document  identifier, “CSTR #54”.)  Its final revision serves as the _d_e
       _f_a_c_t_o specification of AT&T _t_r_o_f_f, and all subsequent  implementors  of
       _r_o_f_f systems have done so in its shadow.

       A  small  and  simple  set of _r_o_f_f 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  _m_s  by
       Michael  Lesk  in Version 6.  He also wrote a manual, “Typing Documents
       on the Unix System”, describing _m_s and basic _n_r_o_f_f/_t_r_o_f_f usage,  updat‐
       ing it as the package accrued features.  Sixth Edition additionally saw
       the debut of the _t_b_l preprocessor for formatting tables, also by Lesk.

       For  Unix  Version 7 (January 1979), McIlroy designed, implemented, and
       documented the _m_a_n macro package, introducing most of  the  macros  de‐
       scribed  in  _g_r_o_f_f___m_a_n(7)  today,  and edited volume 1 of the Version 7
       manual using it.  Documents composed using _m_s  featured  in  volume  2,
       edited by Kernighan.

       Meanwhile,  _t_r_o_f_f 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
       _v_t_r_o_f_f, which translated _t_r_o_f_f’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 _t_r_o_f_f 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 _t_r_o_f_f manual itself,
       it is widely known by a shorthand, “CSTR #97”.

       Kernighan’s innovations prepared _t_r_o_f_f 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, _d_p_o_s_t, was swiftly developed.  However, AT&T’s software licens‐
       ing  practices  kept  Ossanna’s  _t_r_o_f_f,  with its tight coupling to the
       C/A/T’s capabilities, in parallel distribution with  device‐independent
       _t_r_o_f_f  throughout  the  1980s.  Today, however, all actively maintained
       _t_r_o_f_fs follow Kernighan’s device‐independent design.

   _gg_rr_oo_ff_ff——aa ffrreeee _rr_oo_ff_ff ffrroomm GGNNUU
       The most important free _r_o_f_f project historically has been  _g_r_o_f_f,  the
       GNU  implementation of _t_r_o_f_f, developed by James Clark starting in 1989
       and distributed under copyleft licenses, ensuring to all the availabil‐
       ity of source code and the freedom to modify and redistribute it, prop‐
       erties unprecedented in _r_o_f_f systems to that point.  _g_r_o_f_f rapidly  at‐
       tracted  contributors,  and  has served as a replacement for almost all
       applications of AT&T _t_r_o_f_f (exceptions include _m_v, a macro package  for
       preparation of viewgraphs and slides, and the _i_d_e_a_l preprocessor, which
       produces  diagrams from mathematical constraints).  Beyond that, it has
       added numerous features; see _g_r_o_f_f___d_i_f_f(7).  Since  its  inception  and
       for  at  least the following three decades, it has been used by practi‐
       cally all GNU/Linux and BSD operating systems.

       _g_r_o_f_f 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 _g_r_o_f_f the _d_e _f_a_c_t_o _r_o_f_f standard today.

   OOtthheerr ffrreeee _rr_oo_ff_ffss
       In 2007, Caldera/SCO and Sun Microsystems, having  acquired  rights  to
       AT&T  Documenter’s Workbench (DWB) _t_r_o_f_f (a descendant of the Bell Labs
       code), released it under a free but GPL‐incompatible license.  This im‐
       plementation was made portable to modern POSIX systems, and adopted and
       enhanced first by Gunnar Ritter and then Carsten Kunze to produce Heir‐
       loom Doctools _t_r_o_f_f.

       In July 2013, Ali Gholami Rudi announced _n_e_a_t_r_o_f_f, a  permissively  li‐
       censed new implementation.

       Another  descendant  of  DWB  _t_r_o_f_f  is part of Plan 9 from User Space.
       Since 2021, this _t_r_o_f_f has been available under permissive terms.

UUssiinngg _rr_oo_ff_ff
       When you read a man page, often a _r_o_f_f is  the  program  rendering  it.
       Some _r_o_f_f implementations provide wrapper programs that make it easy to
       use  the  _r_o_f_f system from the shell’s command line.  These can be spe‐
       cific to a macro package, like _m_m_r_o_f_f(1), or  more  general.   _g_r_o_f_f(1)
       provides  command‐line  options  sparing the user from constructing the
       long, order‐dependent pipelines familiar to AT&T _t_r_o_f_f users.  Further,
       a heuristic program, _g_r_o_g(1), is available to infer from  a  document’s
       contents which _g_r_o_f_f arguments should be used to process it.

   TThhee _rr_oo_ff_ff ppiippeelliinnee
       A  typical  _r_o_f_f 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.)

              $ _p_r_e_p_r_o_c_1 << _i_n_p_u_t_‐_f_i_l_e || _p_r_e_p_r_o_c_2 || ... || ttrrooffff [_o_p_t_i_o_n] ... \\
                  || _o_u_t_p_u_t_‐_d_r_i_v_e_r

       Once  all preprocessors have run, they deliver pure _r_o_f_f 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 _t_b_l(1)  and  _r_o_f_f  output,
       and  some  permit the definition of macros, as with _e_q_n(1) and _r_o_f_f in‐
       put.  Most _r_o_f_f 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 _r_o_f_f language.
       Some documents are simpler still, since their formatting packages  dis‐
       courage direct use of _r_o_f_f requests; man pages are a prominent example.
       Many features of the _r_o_f_f language are seldom needed by users; only au‐
       thors of macro packages require a substantial command of them.

   PPrreepprroocceessssoorrss
       A  _r_o_f_f  preprocessor is a program that, directly or ultimately, gener‐
       ates output in the _r_o_f_f language.  Typically, each preprocessor defines
       a language of its own that transforms its input into that for  _r_o_f_f  or
       another  preprocessor.   As an example of the latter, _c_h_e_m produces _p_i_c
       input.  Preprocessors must consequently be run in an appropriate order;
       _g_r_o_f_f(1) handles this automatically for all preprocessors  supplied  by
       the GNU _r_o_f_f system.

       Portions  of the document written in preprocessor languages are usually
       bracketed by tokens that look like _r_o_f_f macro calls.  _r_o_f_f 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  _r_o_f_f provides several preprocessors, including _e_q_n, _g_r_n, _p_i_c, _t_b_l,
       _r_e_f_e_r, and _s_o_e_l_i_m.  See _g_r_o_f_f(1) for a complete list.  Other preproces‐
       sors for _r_o_f_f systems are known.

              _d_f_o_r_m_a_t   depicts data structures;
              _g_r_a_p      constructs statistical charts; and
              _i_d_e_a_l     draws diagrams using a constraint‐based language.

   FFoorrmmaatttteerr pprrooggrraammss
       A _r_o_f_f formatter transforms _r_o_f_f language input into a single file in a
       page description language, described in _g_r_o_f_f___o_u_t(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‐_i_n_d_e_p_e_n_d_e_n_t, but not  device‐_a_g_n_o_s_t_i_c.   The
       parameters the formatter uses to arrange the document are stored in _d_e_‐
       _v_i_c_e and _f_o_n_t _d_e_s_c_r_i_p_t_i_o_n _f_i_l_e_s; see _g_r_o_f_f___f_o_n_t(5).

       AT&T  Unix  had two formatters—_n_r_o_f_f for terminals, and _t_r_o_f_f for type‐
       setters.  Often, the name _t_r_o_f_f is used loosely to refer to both.  When
       generalizing thus, _g_r_o_f_f documentation prefers the term “_r_o_f_f”.  In GNU
       _r_o_f_f, the formatter program is always _t_r_o_f_f(1).

   DDeevviicceess aanndd oouuttppuutt ddrriivveerrss
       To a _r_o_f_f system, a _d_e_v_i_c_e is a hardware interface like  a  printer,  a
       text  or  graphical  terminal, or a standardized file format that unre‐
       lated software can interpret.  An  _o_u_t_p_u_t  _d_r_i_v_e_r  is  a  program  that
       parses  the  output  of _t_r_o_f_f 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 _t_r_o_f_f 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 _t_r_o_f_f’s page description language placed low lim‐
       its on the magnitudes of some quantities it could represent.  Its Post‐
       Script output driver, _d_p_o_s_t(1), had a resolution of 720 units per inch;
       _g_r_o_f_f’s _g_r_o_p_s(1) uses 72,000.

_rr_oo_ff_ff pprrooggrraammmmiinngg
       Documents  using  _r_o_f_f are normal text files interleaved with _r_o_f_f for‐
       matting elements.  The _r_o_f_f 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.

   MMaaccrroo ppaacckkaaggeess
       Macro  packages  can  have  a much smaller vocabulary than _r_o_f_f 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  _n_a_m_e..ttmmaacc  (historically,  ttmmaacc.._n_a_m_e).
       Find  details  on  the  naming  and  placement  of  macro  packages  in
       _g_r_o_f_f___t_m_a_c(5).

       A macro package anticipated for use in a document can  be  declared  to
       the  formatter by the command‐line option --mm; see _t_r_o_f_f(1).  It can al‐
       ternatively be specified within a document using the mmssoo request of the
       _g_r_o_f_f language; see _g_r_o_f_f(7).

       Well‐known macro packages include _m_a_n for  traditional  man  pages  and
       _m_d_o_c for BSD‐style manual pages.  Macro packages for typesetting books,
       articles,  and letters include _m_s (from “manuscript macros”), _m_e (named
       by a system administrator from the first name of its creator, Eric All‐
       man), _m_m (from “memorandum macros”), and _m_o_m, a punningly named package
       exercising many _g_r_o_f_f extensions.  See _g_r_o_f_f___t_m_a_c(5) for more.

   TThhee _rr_oo_ff_ff ffoorrmmaattttiinngg llaanngguuaaggee
       The _r_o_f_f 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 _r_o_f_f is not a mere markup language, but Turing‐complete.
       It has storage (registers), it can perform tests (as in conditional ex‐
       pressions like “((\\nn[[ii]] >>== 11))”), its “iiff” and related requests alter the
       flow of control, and macro definition permits unbounded recursion.

       _R_e_q_u_e_s_t_s and _e_s_c_a_p_e _s_e_q_u_e_n_c_e_s 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 _a_d _l_i_b_i_t_u_m_.  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 _i_t is needed literally in a macro ar‐
       gument.  AT&T _t_r_o_f_f had complex rules involving the placement and repe‐
       tition  of the double quote to achieve both aims.  _g_r_o_f_f cuts this knot
       by supporting a special character escape sequence for the neutral  dou‐
       ble  quote,  “\\[[ddqq]]”,  which  never performs quoting in the typesetting
       language, but is simply a glyph, ‘""’.

       _E_s_c_a_p_e _s_e_q_u_e_n_c_e_s start with a backslash, “\\”.  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 “\\((_xx_xx”  or
       “\\[[_xx_xx_xx]]”,  break  suppression  at  input  line  endings with “\\cc”, font
       changes with “\\ff”, type size changes with “\\ss”, in‐line  comments  with
       “\\""”, and many others.

       _S_t_r_i_n_g_s  store text.  They are populated with the ddss request and inter‐
       polated using the \\** escape sequence.

       _R_e_g_i_s_t_e_r_s store numbers and measurements.  A register can be  set  with
       the  request  nnrr  and its value can be retrieved by the escape sequence
       \\nn.

FFiillee nnaammiinngg ccoonnvveennttiioonnss
       The structure or content of a file name, beyond  its  location  in  the
       file  system, is not significant to _r_o_f_f tools.  _r_o_f_f documents employ‐
       ing “full‐service” macro packages (see _g_r_o_f_f___t_m_a_c(5)) tend to be  named
       with a suffix identifying the package; we thus see file names ending in
       _._m_a_n, _._m_s, _._m_e, _._m_m, and _._m_o_m, 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 _r_o_f_f_._7.  Practice for “raw”
       _r_o_f_f documents is less consistent; they are sometimes seen  with  a  _._t
       suffix.

IInnppuutt ccoonnvveennttiioonnss
       Since _t_r_o_f_f fills text automatically, it is common practice in the _r_o_f_f
       language  to  avoid  visual composition of text in input files: the es‐
       thetic appeal of the formatted output is what matters.  Therefore, _r_o_f_f
       input should be arranged such that it is easy for authors and maintain‐
       ers to compose and develop the document, understand the syntax of  _r_o_f_f
       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 \\&& after “!!”, “??”, and “..” if they are followed by space, tab, or
         newline characters and don’t end a sentence.

       • In filled text lines, use \\&& before “..” and “''” 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 \\"" escape sequence causes _t_r_o_f_f 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 _g_r_o_f_f 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

   EEddiittiinngg wwiitthh EEmmaaccss
       Official GNU doctrine holds that the best program for  editing  a  _r_o_f_f
       document  is Emacs; see _e_m_a_c_s(1).  It provides an _n_r_o_f_f major mode that
       is suitable for all kinds of _r_o_f_f dialects.  This mode can be activated
       by the following methods.

       When editing a file within Emacs the mode can be changed by typing “_M_‐_x
       nnrrooffff--mmooddee”, where _M_‐_x 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 _r_o_f_f
       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 _n_r_o_f_f mode.

       • Technically, having the sequence

                .\" -*- nroff -*-

         in the first line of a file will cause Emacs to enter the _n_r_o_f_f major
         mode when it is loaded into the buffer.  Unfortunately,  some  imple‐
         mentations of the _m_a_n(1) program are confused by this practice, so we
         discourage it.

   EEddiittiinngg wwiitthh VViimm
       Other editors provide support for _r_o_f_f‐style files too, such as _v_i_m(1),
       an  extension  of the _v_i(1) program.  Vim’s highlighting can be made to
       recognize _r_o_f_f files by setting the ffiilleettyyppee option in a Vim  _m_o_d_e_l_i_n_e.
       For  this  feature to work, your copy of _v_i_m 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 _r_o_f_f 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 _n_o_t recognize many of the GNU extensions to _r_o_f_f, such as request,
       register, and string names longer than two characters.

AAuutthhoorrss
       This document was written by Bernd Warken and G. Branden Robinson.

SSeeee aallssoo
       Much _r_o_f_f documentation is available.  The Bell Labs papers  describing
       AT&T _t_r_o_f_f remain available, and _g_r_o_f_f is documented comprehensively.

   IInntteerrnneett ssiitteess
       _U_n_i_x _T_e_x_t _P_r_o_c_e_s_s_i_n_g,  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 _g_r_o_f_f contributors and
       enthusiasts.

       “History of Unix Manpages”, an online article maintained by the  mdocml
       project, provides an overview of _r_o_f_f development from Saltzer’s _R_U_N_O_F_F
       to  2008, with links to original documentation and recollections of the
       authors and their contemporaries.

       troff.org, Ralph Corderoy’s _t_r_o_f_f site, provides an overview and point‐
       ers to much historical _r_o_f_f information.

       Multicians, a site by Multics enthusiasts, contains a lot  of  informa‐
       tion  on the MIT projects CTSS and Multics, including _R_U_N_O_F_F; it is es‐
       pecially useful for its glossary and the many links to historical docu‐
       ments.

       The Unix Archive, curated by the Unix Heritage  Society,  provides  the
       source  code  and  some  binaries  of  historical Unices (including the
       source code of some versions  of  _t_r_o_f_f  and  its  documentation)  con‐
       tributed by their copyright holders.

       Jerry Saltzer’s home page  stores  some  documents  using  the original
       _R_U_N_O_F_F formatting language.

       _g_r_o_f_f, GNU _r_o_f_f’s web  site,  provides  convenient  access  to  _g_r_o_f_f’s
       source  code  repository,  bug  tracker,  and  mailing lists (including
       archives and the subscription interface).

   HHiissttoorriiccaall _rr_oo_ff_ff ddooccuummeennttaattiioonn
       Many AT&T _t_r_o_f_f 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.

   MMaannuuaall ppaaggeess
       As a system of multiple components, a _r_o_f_f 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 _r_o_f_f im‐
       plementations.

       For GNU _r_o_f_f, the _g_r_o_f_f(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 _g_r_o_f_f on a variety of
       topics.

       With other _r_o_f_fs, you are on your own, but _t_r_o_f_f(1)  might  be  a  good
       starting point.

groff 1.23.0                      3 June 2025                          _r_o_f_f(7)
