_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 further font
     metric information required by GNU _t_r_o_f_f(1), and writes the combined result
     to  the  standard output stream.  The information added is derived from the
     font’s existing parameters and assumptions about  traditional  _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  corre‐
     sponding  parameters  in  the  _D_E_S_C file.  _f_o_n_t is the name of the file de‐
     scribing 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 infor‐
     mation; all exit afterward.

     All other options change parameters that are used to derive the heights and
     depths.  Like the existing quantities in the font  description  file,  each
     value  _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 unspec‐
     ified parameters.  If a parameter is not specified,  the  default  will  be
     used.   The  defaults  are  chosen to produce reasonable values for a Times
     font.

EExxiitt ssttaattuuss
     _a_d_d_f_t_i_n_f_o exits with status 00 on successful operation, and status 22 if  the
     program cannot interpret its command‐line arguments.

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.24.1                       2026‐04‐22                       _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 out‐
     put

SSyynnooppssiiss
     aaffmmttooddiitt [--cckkmmnnqqssxx] [--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  generates  a font description file for use with _g_r_o_f_f(1)’s ppss and
     ppddff output devices from an Adobe Font Metric file, _a_f_m_‐_f_i_l_e.  _m_a_p_‐_f_i_l_e  as‐
     sociates a _g_r_o_f_f ordinary 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 ordi‐
     nary (if of unit length) or special (if longer) character identifier.   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 directory.

     If a PostScript glyph is not mentioned in _m_a_p_‐_f_i_l_e, and a  _g_r_o_f_f  character
     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  de‐
     scription  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 containing 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 constructed.

     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 access  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_4_._1_/_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_4_._1_/_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  pro‐
     duced 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 cor‐
     rection, 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  parameters  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.  To en‐
     able this search, _f_o_n_t_‐_d_e_s_c_r_i_p_t_i_o_n_‐_f_i_l_e can be listed as an argument to the
     ffoonnttss directive in the output device’s _D_E_S_C file; alternatively, a document
     can designate it with the ssppeecciiaall request.  If the  font  is  not  special,
     there  is  no need to do either, since _t_r_o_f_f(1) will automatically mount it
     when it is first used.

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

     --aa _s_l_a_n_t
            Use _s_l_a_n_t as the slant (“angle”) parameter in the  font  description
            file;  this  is used by _g_r_o_f_f in the positioning of accents.  By de‐
            fault _a_f_m_t_o_d_i_t uses the negative of the IIttaalliiccAAnnggllee specified in the
            AFM file; with true italic fonts it is sometimes desirable to use  a
            slant  that  is  less  than  this.   If you find that an italic font
            places accents over base glyphs too far to the right, use --aa to give
            it a smaller slant.

     --cc     Include comments in the font description file identifying the  Post‐
            Script 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 subdirectory
            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  subdi‐
            rectory 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  thou‐
            sandths  of  an  em  plus  the amount by which the right edge of the
            glyph’s bounding box is to the right of its origin.  If  this  would
            result in a negative italic correction, use a zero italic correction
            instead.

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

            Also  generate  a  left  italic  correction  for each glyph equal to
            _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  unless  op‐
            tion --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  monospaced
            (constant‐width) fonts.

     --mm     Prevent  negative  left  italic correction values.  Font description
            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.

     --qq     Quieten duplicate mapping warnings; see section “Diagnostics” below.

     --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 width of inter‐word spaces.

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

EExxiitt ssttaattuuss
     _a_f_m_t_o_d_i_t exits with status 00 on successful operation, status 22 if the  pro‐
     gram  cannot  interpret  its command‐line arguments, and status 11 if it en‐
     counters an error during operation.

FFiilleess
     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_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_4_._1_/_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_4_._1_/_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  document
            (or download to the device).

     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_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_4_._1_/_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_4_._1_/_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_4_._1_/_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_4_._1_/_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 identi‐
            fiers  for Zapf Dingbats (ZZDD), reversed Zapf Dingbats (ZZDDRR), slanted
            symbol (SSSS), symbol (SS), and text fonts, respectively.   These  _m_a_p_‐
            _f_i_l_es produce the font description 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 ig‐
            nored AGL name contains four hexadecimal  digits  _X_X_X_X.   The  Adobe
            Glyph  List  (AGL) has its own names for glyphs; they are often dif‐
            ferent from _g_r_o_f_f’s special character names.  _a_f_m_t_o_d_i_t is construct‐
            ing 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 mappings.  For example, if _x
            is DDeellttaa, _y is **DD, and _X_X_X_X is 00339944, _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 mapping 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.

            When the --qq option is used, these messages are suppressed  in  favor
            of  a  count of how many would have been emitted were the option not
            present.

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  Lem‐
     berg,  is the primary _g_r_o_f_f manual.  Section “Using Symbols” may be of par‐
     ticular 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.24.1                       2026‐04‐22                        _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  pre‐
     processor  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 language.

     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 in‐
     put 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 modi‐
     fication;  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 ...

     _c_h_e_m requires the _M_a_t_h_:_:_T_r_i_g Perl module, available via CPAN.

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

     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;  de‐
            fault is 10 point.

   BBoonnddss
     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]

     The  bboonndd  command  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 direction
     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 dot‐
     ted or dashed bonds or to specify a ttoo place.

   RRiinnggss
     There  are  lots of rings, but only five‐ and six‐sided rings get much sup‐
     port.  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 direc‐
     tion.  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 writ‐
     ten 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  appear  to  be
     fractional  values,  as in N2.5H).  The name of a moiety is determined from
     the moiety after special characters have been stripped out: e.g., N(C2H5)2)
     has the name NC2H52.

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

            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 specifying 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 command.
     It  represents  a string that should be printed (without the quotes).  Text
     within quotes ""..."" is treated more or less like a moiety  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 letters  and
     numbers is valid.

            First: bond
                   "bond 30 from First"

   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 sig‐
     nals 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 la‐
     bel.

     Since  _c_h_e_m is a _p_i_c preprocessor, it is possible to include _p_i_c statements
     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  shorthand
     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  $$...$$  construct
     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_4_._1_/_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_4_._1_/_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  dia‐
            grams.

     _/_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 Program
            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  Labora‐
     tories Computing Science Technical Report No. 122

     _g_r_o_f_f(1), _p_i_c(1)

groff 1.24.1                       2026‐04‐22                            _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 _g_l_o_b_a_l_‐_i_t_a_l_i_c_‐_f_o_n_t] [--mm _m_i_n_i_m_u_m_‐_t_y_p_e_‐_s_i_z_e]
         [--MM _e_q_n_r_c_‐_d_i_r_e_c_t_o_r_y] [--pp _s_u_p_e_r_/_s_u_b_s_c_r_i_p_t_‐_s_i_z_e_‐_r_e_d_u_c_t_i_o_n] [--ss _g_l_o_b_a_l_‐
         _t_y_p_e_‐_s_i_z_e] [--TT _d_e_v_i_c_e] [_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 formatting
     system.  _e_q_n is a _t_r_o_f_f(1) preprocessor that translates expressions in  its
     own language, embedded in _r_o_f_f(7) input, into mathematical 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 delimiters.  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  im‐
     plementing  relevant GNU extensions) must be used.  If no _f_i_l_e operands are
     present, 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 direc‐
     tories 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_4_._1_/_t_m_a_c.
     If it exists and is readable, _e_q_n processes it before any input.

     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.  Four points are
     worth 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 baseline,
        not the three centered dots of AT&T _e_q_n.  Set an ellipsis  on  the  math
        axis with the GNU extension macro ccddoottss.

     •  GNU  _e_q_n’s  ddeelliimm primitive does not treat an “oonn” argument as a pair of
        equation delimiters.

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

            .EQ
            F =
            m a
            .EN

     becomes  _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.

     Beyond their primary functions, the following input characters separate to‐
     kens 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 input.  When they
     occur, they must appear at the outermost lexical scope.  This roughly means
     that they can’t appear within braces that are necessary to disambiguate the
     input; _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 forego‐
     ing, 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  config‐
     ure  an aspect of the preprocessor’s state, as when setting a “global” font
     selection or type size (ggiiffoonntt 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 around them (as with ffaatt,  oovveerr,  ssqqrrtt,
     or uupp).

     Equation _c_o_m_p_o_n_e_n_t_s include mathematical variables, constants, numeric lit‐
     erals,  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 en‐
     sure 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
     used  together  as  a  single token.  Predefined macros make convenient the
     preparation of _e_q_n input in a form resembling its  spoken  expression;  for
     example, consider ccooss, hhaatt, iinnff, and lliimm.

   SSppaacciinngg aanndd ttyyppeeffaaccee
     GNU  _e_q_n  imputes  a  type  to each equation component, adjusting the space
     around it accordingly.  Recognized types follow; 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 nu‐
     merals 0–9, the “oorrddiinnaarryy” type.  (The “ddiiggiitt” type is  not  used,  but  is
     available for customization.)  In keeping with common practice in mathemat‐
     ical  typesetting, lowercase, but not uppercase, Greek letters are assigned
     the “lleetttteerr” type to style them in italics.  The macros for  producing  el‐
     lipses, “......”, 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
     We describe the GNU extension primitives “ttyyppee” and cchhaarrttyyppee in  subsection
     “Spacing  and  typeface” above; “sseett” and “rreesseett” in subsection “Customiza‐
     tion” below; and ggbbffoonntt, ggiiffoonntt, and ggrrffoonntt in  subsection  “Fonts”  below.
     In  the following synopses, _X can be any character not appearing in the pa‐
     rameter thus bracketed.

     _e_1 aacccceenntt _e_2
            Set _e_2 as an accent over _e_1.  _e_q_n assumes that _e_2 is at  the  appro‐
            priate height for a lowercase letter without an ascender, and shifts
            it vertically based on _e_1’s height.  For example, _e_q_n defines hhaatt as
            follows.

                   accent { roman "^" }

            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.  _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 ex‐
            pansion; 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 in‐
            put “AA oopppprriimmee ssuubb 11”, the “1” is tucked under the prime as  a  sub‐
            script  to the “A” (as is conventional in mathematical typesetting),
            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 primitives 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 reduce the type size of _e_1 and _e_2, and put less verti‐
            cal space between _e_1 and _e_2 and the fraction bar.  The  oovveerr  primi‐
            tive  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 de‐
            fault values, where _n is an integer in hundredths of an em.  If pos‐
            itive, _n increases vertical spacing before the  equation;  if  nega‐
            tive, it does so after the equation.  This primitive provides an in‐
            terface  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  ob‐
            ject  an accent over it should be placed.)  The macro must modify 00ss
            so that it outputs the desired result, returns the drawing  position
            to  the text baseline at the beginning of _e, and updates the forego‐
            ing registers to correspond to the new dimensions of the result.

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

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

            We use the \\[[mmii]] and \\[[ppll]] special characters instead of + and - be‐
            cause 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  expression;  the
            bottom  of  the  box  rests on the text baseline.  We define 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 expan‐
            sion; it is split up and the spacing between characters adjusted 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  appropri‐
            ate  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 undefined.

     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 de‐
     liberate incompatibility.

     ddeelliimm oonn
            GNU  _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 ef‐
            fect.  Few _e_q_n documents are expected to use “o” and “n” as left and
            right delimiters, respectively.  If yours does, swap 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, uses the formatter’s \\xx
            escape  sequence  to increase the vertical spacing between rows; _e_q_n
            ignores it when producing MathML.  Negative values are accepted  but
            have  no effect.  If more than one _n occurs in a matrix or pile, the
            largest is used.

   CCuussttoommiizzaattiioonn
     When _e_q_n generates _t_r_o_f_f input, the appearance of equations  is  controlled
     by  a  large  number  of  parameters.   They have no effect when generating
     MathML, which delegates typesetting to a MathML rendering engine.   Config‐
     ure these parameters with the “sseett” and “rreesseett” primitives.

     sseett _p _n  assigns parameter _p the integer value _n; _n is interpreted in units
              of hundredths of an em unless otherwise stated.  For example,
                     set x_height 45
              says that _e_q_n should assume that the font’s x‐height is 0.45 ems.

     rreesseett _p  restores the default value of parameter _p_.

     Available  parameters  _p 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 over‐
                             printing two copies of  the  equation  horizontally
                             offset  by  this amount (44).  When producing MathML
                             output, components to which ffaatt__ooffffsseett applies  in‐
                             stead 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  de‐
                             nominator; in other words, it overhangs the numera‐
                             tor and denominator by at least this amount (00).

     aacccceenntt__wwiiddtthh            When bbaarr or uunnddeerr is applied to a single character,
                             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 max‐
                             imum  amount by which the sub‐equation that the de‐
                             limiters 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 delim‐
                             iters 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  af‐
                             ter punctuation characters (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 (2288).

     hhaallff__ssppaaccee              configures the width of the space produced by the ^^
                             token (1177).

     ffuullll__ssppaaccee              configures the width of the space produced by the ~~
                             token (2288).

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

     aaxxiiss__hheeiigghhtt             The height above the  baseline  of  the  center  of
                             characters  such as “+” and “−” (2266).  It is impor‐
                             tant 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 denominator
                             by at least this amount (3366).

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

     ssuupp22                    Superscripts within superscripts or upper limits or
                             numerators of ssmmaalllloovveerr fractions are shifted up by
                             at least this amount (3377).  Conventionally, 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).   Conventionally,  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  superscript,
                             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 su‐
                             perscript is set (3388).

     ssuubb__ddrroopp                The baseline of a subscript is at least  this  much
                             below  the  bottom  of the object on which the sub‐
                             script 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  be‐
                             low  the bottom of the object on which the limit is
                             set (6600).

     bbiigg__oopp__ssppaacciinngg55         This much vertical space is added above  and  below
                             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 bot‐
                             tom 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 ma‐
                             trix (110000).

     mmaattrriixx__ssiiddee__sseepp         This much space is added at each side of  a  matrix
                             (1177).

     ddrraaww__lliinneess              If non‐zero, _e_q_n draws lines using the _t_r_o_f_f \\DD es‐
                             cape  sequence,  rather than the \\ll escape sequence
                             and the \\[[rruu]] special character.   The  _e_q_n_r_c  file
                             sets  the  default:  11 on ppss, hhttmmll, and the X11 de‐
                             vices, 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  escape  se‐
                             quence (8855).

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

     nnrrooffff                   If  non‐zero,  then nnddeeffiinnee behaves like ddeeffiinnee and
                             ttddeeffiinnee is ignored, otherwise ttddeeffiinnee behaves  like
                             ddeeffiinnee and nnddeeffiinnee is ignored.  The _e_q_n_r_c file sets
                             the  default: 11 on aasscciiii, llaattiinn11, and uuttff88 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 arguments.
     In this context only, commas and parentheses also serve  as  token  separa‐
     tors.   A  macro  argument  is not terminated by a comma inside parentheses
     nested within it.  In a macro definition, $$_n, where _n is between  1  and  9
     inclusive, is replaced by the _nth argument; if there are fewer than _n argu‐
     ments, 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 classical 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 initial capital letter (AAllpphhaa) or in full capi‐
     tals (AALLPPHHAA) to obtain uppercase forms.

     GNU _e_q_n further defines the macros ccddoott, ccddoottss, and uuttiillddee  (all  discussed
     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 (heavy).  Assign each a _g_r_o_f_f typeface with the GNU ex‐
     tension primitives ggrrffoonntt, ggiiffoonntt, and ggbbffoonntt..  The defaults are the styles
     RR, II, 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.

     ggiiffoonntt _f
            Select _f as the italic font.  GNU _e_q_n recognizes ggffoonntt as a  synonym
            for AT&T compatibility.

     ggrrffoonntt _f
            Select _f as the roman font.

   _rr_oo_ff_ff iinntteerrffaaccee
     The string 1100 stores the most recently formatted equation.  The register MMKK
     stores  the horizontal drawing position of the most recently assigned mark.
     Avoid using these names for any other purpose.

     GNU _e_q_n internally employs register, string, macro, and diversion names be‐
     ginning with the numeral 00.  (AT&T _e_q_n used identifiers starting  with  the
     numeral  11.)  A document to be preprocessed with GNU _e_q_n should not use any
     such identifiers.

OOppttiioonnss
     ----hheellpp displays a usage message, while --vv and ----vveerrssiioonn show version infor‐
     mation; 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 “ggiiffoonntt _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  “Description”
             above.

     --NN      Prohibit newlines within delimiters, allowing _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  su‐
             perscripts at 70% of the type size of the surrounding text.

     --rr      Reduce the type size of super‐ and subscripts at most once relative
             to the base type size.

     --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.  This option defines a macro _d_e_v
             with the value 11; _e_q_n_r_c thereby provides definitions appropriate to
             the  device.   However,  if _d_e_v is “MMaatthhMMLL”, _e_q_n produces output in
             that language rather than _r_o_f_f, and does not load _e_q_n_r_c.   The  de‐
             fault device is ppss.

EExxiitt ssttaattuuss
     _e_q_n  exits  with  status 00 on successful operation, status 22 if the program
     cannot interpret its command‐line arguments, and status 11 if it  encounters
     an error during operation.

FFiilleess
     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_t_m_a_c_/_e_q_n_r_c
            initializes  the preprocessor for _t_r_o_f_f output.  Any valid _e_q_n input
            is accepted.

MMaatthhMMLL oouuttppuutt lliimmiittaattiioonnss
     MathML’s design assumes that it cannot know the exact physical characteris‐
     tics of the media and devices on which it will be rendered.   It  does  not
     support control of motions and sizes to the same degree _t_r_o_f_f does.

     •  GNU  _e_q_n’s rendering parameters (see section “Customization” above) have
        no effect on generated MathML.

     •  The ssppeecciiaall, uupp, ddoowwnn, ffwwdd, and bbaacckk primitives cannot  be  implemented,
        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 output——notably the inte‐
        gral sign——may appear too small and need to have their “<mstyle>”  wrap‐
        pers adjusted by hand.

     As  when  producing  _t_r_o_f_f output, _e_q_n generates MathML that leaves the ..EEQQ
     and ..EENN tokens in place, but emits nothing corresponding  to  ddeelliimm  delim‐
     iters.   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  recognized
     as  names  of  macros  or  primitives,  or if they are to be interpreted 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 “ggiiffoonntt PPII” does not se‐
     lect the _g_r_o_p_d_f(1) or _g_r_o_p_s(1) device’s Palatino italic font as the  global
     italic face; you must use “ggiiffoonntt ""PPII""” instead.

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

     Unlike  TeX, _e_q_n does not inherently distinguish displayed and inline equa‐
     tion styles; see the ssmmaalllloovveerr primitive above.   However,  macro  packages
     frequently  define  EEQQ  and EENN macros such that the equation within is dis‐
     played.  These macros may accept arguments permitting the  equation  to  be
     labeled or captioned; see the package’s documentation.

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

     When producing terminal output, GNU _e_q_n renders lowercase Greek letters  in
     roman instead of italic style.

     When  producing  MathML  output,  the  mmaarrkk and lliinneeuupp features don’t work.
     These could, in theory, be implemented with “<maligngroup>” elements.

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

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  ap‐
     pear frequently in running text.

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

     The  quadratic  formula  affords an opportunity to use fractions, radicals,
     and the full space token ~~.

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

     Alternatively, we could define the plus‐minus sign as  a  binary  operator.
     Automatic  spacing puts 0.06 em less space on either side of the plus‐minus
     than  ~  does,  this  being  the  difference  between  the  widths  of  the
     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.  Appen‐
     dix  G  discusses many of the parameters from section “Customization” above
     in greater detail.

     _g_r_o_f_f___c_h_a_r(7) documents a variety of  special  character  escape  sequences
     useful  in  mathematical  typesetting.   See subsections “Logical symbols”,
     “Mathematical symbols”, and “Greek glyphs” in particular.

     _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.24.1                       2026‐04‐22                             _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 normally
     precedes it within _g_r_o_f_f(1) macros; nor do you need to have dollar‐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  smallest
     possible bounding box that contains all the black pixels.

OOppttiioonnss
     ----hheellpp displays a usage message, while --vv and ----vveerrssiioonn show version infor‐
     mation; 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 order shown  to  de‐
            termine  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.24.1                       2026‐04‐22                       _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_‐_f_i_l_e]

     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 writes an‐
     other, derived from both, to the standard output stream  (or  _o_u_t_p_u_t_‐_f_i_l_e),
     adding margin character (mmcc) requests at places in the output where the in‐
     put  documents differ.  _g_d_i_f_f_m_k does not interpret the source documents; it
     treats _r_o_f_f comments and nilpotent changes  to  formatting  as  meaningful.
     For  example,  it does not know that \\hh''33mm'', \\hh''((11 ** 33mm))'', and \\hh''33mm++00'' all
     mean the same thing.  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 ab‐
     sent, _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 information;
     both exit afterward.

     --aa _a_d_d_‐_m_a_r_k
            Annotate material absent from _f_i_l_e_1 but present in _f_i_l_e_2  with  _a_d_d_‐
            _m_a_r_k (default: “++”).

     --BB     Suppress  bbrr requests normally inserted by --DD option.  Use with cau‐
            tion; such requests are the only way to guarantee that deletions and
            small changes are marked.

     --cc _c_h_a_n_g_e_‐_m_a_r_k
            Annotate material differing between _f_i_l_e_1 and _f_i_l_e_2 with _c_h_a_n_g_e_‐_m_a_r_k
            (default: “||”).

     --dd _d_e_l_e_t_e_‐_m_a_r_k
            Annotate material present  in  _f_i_l_e_1  but  absent  from  _f_i_l_e_2  with
            _d_e_l_e_t_e_‐_m_a_r_k (default: “**”).

     --DD     Mark changed and deleted material with surrounding delimiters.

     --MM _m_a_r_k_1 _m_a_r_k_2
            Use  _m_a_r_k_1  (default:  “[[[[”) and _m_a_r_k_2 (default: “]]]]”) as delimiters
            when using the --DD option.

     --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 program to perform the comparison of _f_i_l_e_1  and
            _f_i_l_e_2.   _d_i_f_f_‐_c_o_m_m_a_n_d  (default:  ddiiffff) must accept GNU _d_i_f_f(1)’s --DD
            extension option.

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

EExxiitt ssttaattuuss
     _g_d_i_f_f_m_k exits with status 00 if the input files are the same; 11 if they dif‐
     fer;  22  upon a usage error; 33 if the system’s _d_i_f_f(1) or _s_h(1) commands do
     not support features _g_d_i_f_f_m_k requires; and 44 if the _o_u_t_p_u_t  argument  is  a
     duplicate of _f_i_l_e_1 or _f_i_l_e_2.

CCaavveeaattss
     The  output  is  not necessarily compatible with all macro packages or pre‐
     processors.  A reliable workaround is to run _g_d_i_f_f_m_k on the output  of  the
     final preprocessor instead 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” out‐
     put 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), _t_r_o_f_f(1), _r_o_f_f(7), _d_i_f_f(1)

groff 1.24.1                       2026‐04‐22                         _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.

     _g_l_i_l_y_p_o_n_d requires the _F_i_l_e_:_:_H_o_m_e_D_i_r Perl module, available via CPAN.

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  de‐
     vice 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 use‐
            ful _E_P_S files are send.  So at last, the temporary directory 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 tem‐
            porary directory.  This directory name is used as is without any ex‐
            tensions.   If  this directory does not exist it is be created.  The
            temporary directory is created by  Perl’s  security  operations  di‐
            rectly  under this directory.  In this temporary directory, the tem‐
            porary files are stored.

   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 argu‐
     ment can consist of arbitrary many options without  option  argument,  com‐
     posed as a collection of option characters following the single dash.

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

     This is the standard for _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  argu‐
            ment,  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 pos‐
     sible.

     The _l_o_n_g _o_p_t_i_o_n ----kkeeeepp__aallll can be abbreviated from ----kkeeeepp__aall up to ----kk  be‐
     cause  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 abbrevi‐
     ated 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 ..lliillyyppoonndd
     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  ..lliillyy‐‐
     ppoonndd 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  temporary
     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 automatically 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  pro‐
     gram.

     The  beginning  of  the names of the temporary files can be set by the com‐
     mand‐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  can‐
     not  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
     In this mode, the  current  default,  ..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 extension
     ..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  com‐
     mand
            ..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 exten‐
     sion, 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 collection
     of the corresponding _E_P_S page files.  This is done by _g_r_o_f_f commands
     ..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 fur‐
            ther 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.24.1                       2026‐04‐22                       _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 arguments 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  ver‐
     sion 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 different
     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 request
     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  run‐
     ning  _P_e_r_l  _p_a_r_t.   Of  course,  it would be reasonable to add the argument
     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 several
     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 be‐
     fore 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 restrictive.

     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 ar‐
     gument 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  command.   de‐
            fault.

     ..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.24.1                       2026‐04‐22                           _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 hun‐
     dred  base syllables, each spoken with one of five different tones.  Chang‐
     ing the tone applied to the syllable generally alters the  meaning  of  the
     word  it forms.  In Pinyin, a syllable is written in the Latin alphabet and
     a numeric tone indicator can be appended to each syllable.

     Each _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 char‐
     acter  set,  plus  the  letter “U” with dieresis (umlaut) in both cases——in
     other words, the members of the set “[a–zA–ZüÜ]”.

     In _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 upper‐
     case.  Within ..ppiinnyyiinn sections, _g_p_i_n_y_i_n supports the form “ue”  for  lower‐
     case 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 explic‐
     itly  written  at  all, but each of the first through fourth tones is indi‐
     cated with a diacritic above a specific vowel within the syllable.

     In a _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 trans‐
     formed into accents above vowels in the output.  The tone numbers 0  and  5
     are synonymous.

     The tones are written as follows.

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

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

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  lan‐
     guage  elements  of  GNU  _t_r_o_f_f and the available glyph repertoire, respec‐
     tively.

groff 1.24.1                       2026‐04‐22                         _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  smallest
     possible bounding box that contains all the black pixels.

OOppttiioonnss
     ----hheellpp displays a usage message, while --vv and ----vveerrssiioonn show version infor‐
     mation; 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 ar‐
            bitrary 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 order shown  to  de‐
            termine  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.24.1                       2026‐04‐22                      _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‐align 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 exten‐
     sion (\\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 whitespace, the first string be‐
     ing the command and the second its operand.  Commands may be upper‐ or low‐
     ercase and abbreviated down to one character.

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

     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 de‐
            fault 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, respec‐
            tively).

     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 stipples (unless
            one is set by the “ddeeffaauulltt” command), and it is invalid to include a
            _g_r_e_m_l_i_n picture with polygons without specifying 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 com‐
            pile time).  The default is 1.0 (3.0 and 5.0,  respectively),  which
            corresponds  to  0.15pt (0.45pt and 0.75pt, respectively).  A thick‐
            ness value of zero selects the smallest  available  line  thickness.
            Negative  values  cause the line thickness to be proportional to the
            current point size.

     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 lim‐
            itations, of course).  An operand of anything but ooffff will turn text
            scaling on.

     ddeeffaauulltt
            Reset  the  picture environment defaults to the settings in the cur‐
            rent picture.  This is meant to be used as a global  parameter  set‐
            ting  mechanism at the beginning of the _t_r_o_f_f input, 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  scaling
            factors present in the same picture.  “wwiiddtthh 00” is ignored.

     hheeiigghhtt _N
            Force the picture to be _N inches high, overriding other scaling fac‐
            tors.   If  both  wwiiddtthh  and  hheeiigghhtt are specified, the tighter con‐
            straint will determine the scale of the picture.  hheeiigghhtt  and  wwiiddtthh
            commands  are  not  saved with a “ddeeffaauulltt” command.  They will, how‐
            ever, 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  multiple
            ffiillee commands are given, the last one controls.  If _n_a_m_e doesn’t ex‐
            ist,  an error message is reported and processing continues 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 any‐
     thing  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 beginning  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 enclosed by previously defined delim‐
     iters (e.g., “$$”).

     When using _g_r_n along with  other  preprocessors,  run  _t_b_l(1)  before  _g_r_n,
     _p_i_c(1),  and/or  _i_d_e_a_l.  If _e_q_n(1) is needed, run it as the last preproces‐
     sor.  _g_r_o_f_f(1) automatically runs preprocessors 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 be‐
     tween “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 enter‐
     ing 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 coordinates is  _n_o_t
     compatible  with  the AED version.  As long as a _g_r_e_m_l_i_n file does not con‐
     tain 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
        “ggrreemmlliinnffiillee” (AED) or “ssuunnggrreemmlliinnffiillee” (Sun/X11).

     •  The  second  line of the file contains an orientation and _x and _y values
        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 dis‐
        play 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 position‐
        ing  point  to  be  used  when this file is read into another file.  The
        stuff on this line really isn’t all that important; a value of  “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 giving
        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        text aligned to bottom left
                    11       BBOOTTRRIIGGHHTT       text aligned to bottom right
                    22       CCEENNTTCCEENNTT       center object
                    33       VVEECCTTOORR         vector
                    44       AARRCC            arc
                    55       CCUURRVVEE          curve
                    66       PPOOLLYYGGOONN        polygon
                    77       BBSSPPLLIINNEE        b‐spline
                    88       BBEEZZIIEERR         Bézier
                   1100       TTOOPPLLEEFFTT        text aligned to top left
                   1111       TTOOPPCCEENNTT        text aligned to top center
                   1122       TTOOPPRRIIGGHHTT       text aligned to top right
                   1133       CCEENNTTLLEEFFTT       text aligned to center left
                   1144       CCEENNTTRRIIGGHHTT      text aligned to center right
                   1155       BBOOTTCCEENNTT        text aligned to bottom center

     •  Each line after the object type specifies a point used  to  display  the
        element.   It contains an _x and a _y coordinate in floating‐point format,
        separated by spaces.  The list of points is terminated by  a  line  con‐
        taining  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, 0 is also valid: it specifies an  invisible  border.   For
        text, the brush selects a font as follows.

                             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 re‐
        ally just a starting font.  The text string can contain  formatting  se‐
        quences like “\fI” or “\d” which may change the font (as well as do many
        other  things).   For  text, the size field is a decimal value between 1
        and 4.  It selects the size of the font in which the text will be drawn.
        For polygons, this size field is interpreted as a stipple number to fill
        the polygon with.  The number is used to index into a  stipple  font  at
        print time.

     •  The  last line of each element contains a decimal number and a string of
        characters, separated by a single space.  The number is a count  of  the
        number  of  characters in the string.  This information is used only for
        text elements, and contains the text string.  There can be spaces inside
        the text.  For arcs, curves, and vectors, the character  count  is  zero
        (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  vicin‐
     ity.   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  objects
     in  the  Sun/X11  version of _g_r_e_m_l_i_n.  However, files with negative coordi‐
     nates _w_i_l_l cause problems if displayed on the AED.

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

     --CC      Recognize  ..GGSS  and ..GGEE (and ..GGFF) even when followed by a character
             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 out‐
             put driver) for the _D_E_S_C file before the default  font  directories
             _/_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_4_._1_/_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_4_._1_/_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.

EExxiitt ssttaattuuss
     _g_r_n  exits  with  status 00 on successful operation, status 22 if the program
     cannot interpret its command‐line arguments, and status 11 if it  encounters
     an error during operation.

FFiilleess
     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_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.24.1                       2026‐04‐22                             _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 latter is
     given the “--TT ddvvii” 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_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 stan‐
     dard input stream.  It writes to the standard output stream.

     The DVI file generated by _g_r_o_d_v_i can be interpreted by any correctly  writ‐
     ten  DVI  driver.  _t_r_o_f_f drawing primitives are implemented using _t_p_i_c ver‐
     sion 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.  Cur‐
     rently, 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 access
     any glyph in the current font by its  position  in  the  corresponding  TFM
     file.

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

   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  mem‐
     bers 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 (cmtex10,
     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  avail‐
     able as special fonts SSAA (msam10) and SSBB (msbm10).  They are not mounted by
     default.

     You  can  load the _e_c_._t_m_a_c macro file to employ the EC and TC fonts instead
     of CM, which they resemble.  They also provide Euro  \\[[EEuu]]  and  per  mille
     \\[[%%00]]  glyphs.   Do  so  before  loading  localization macro files, because
     _e_c_._t_m_a_c does not set up automatic hyphenation codes.

   DDeevviiccee eexxtteennssiioonn ccoommmmaannddss
     _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 ac‐
     cordingly.  If either  the  page  width  or  length  is  not  positive,  no
     ppaappeerrssiizzee special is output.

     _g_r_o_d_v_i  supports  one  device  extension,  accessed  with the _g_r_o_f_f request
     ddeevviiccee or _r_o_f_f \\XX escape sequence.

     \\XX''ppaappeerrssiizzee==_w_i_d_t_h,,_l_e_n_g_t_h''
            Set the page dimensions in centimeters to _w_i_d_t_h by _l_e_n_g_t_h_.   If  the
            --ll  option  was specified, these dimensions are swapped.  Changes to
            the paper dimensions should occur prior to the first page, or during
            page ejection before starting a subsequent one.

            _C_a_u_t_i_o_n_: the ordering of dimensions differs from that used by _p_a_p_e_r_‐
            _s_i_z_e_._t_m_a_c and _t_r_o_f_f(1)’s “--dd ppaappeerr” option.

     The parameter(s) to ddeevviiccee and \\XX are translated to the same DVI  file  in‐
     structions as would be produced by \\ssppeecciiaall{{_a_n_y_t_h_i_n_g}} in TeX; _a_n_y_t_h_i_n_g can‐
     not contain a newline.

   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 following ad‐
     ditional 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  drawing
            position, and the diagonally opposite corner at the drawing position
            +(_d_h,_d_v),  which  becomes  the new drawing position afterward.  This
            command produces a rule in the DVI file and so can be  printed  even
            with  a driver that does not support _t_p_i_c specials, unlike the other
            \\DD commands.

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

     --dd      Do not use _t_p_i_c specials to implement drawing commands.  Horizontal
             and vertical lines are implemented by rules.   Other  drawing  com‐
             mands are ignored.

     --FF _d_i_r  Prepend  directory  dir_/_d_e_vname to the search path for font and de‐
             vice description files; _n_a_m_e is the name  of  the  device,  usually
             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).

EExxiitt ssttaattuuss
     _g_r_o_d_v_i exits with status 00 on successful operation, status 22 if the program
     cannot interpret its command‐line arguments, and status 11 if it  encounters
     an error during operation.

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 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_4_._1_/_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_4_._1_/_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_4_._1_/_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_4_._1_/_t_m_a_c_/_e_c_._t_m_a_c
            configures  the ddvvii output device to use the EC and TC font families
            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 resolution 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.24.1                       2026‐04‐22                          _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 system.
     GNU _r_o_f_f is a typesetting system that reads plain text input that  includes
     formatting  commands  to  produce output in PostScript, PDF, HTML, or other
     formats, or for display to a terminal.  Formatting  commands  can  be  low‐
     level  typesetting  primitives, macros from a supplied package, or user‐de‐
     fined macros.  All three approaches can be combined.  If no  _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  _t_r_o_f_f and other programs from AT&T
     Unix, _g_r_o_f_f is widely available on POSIX and other  systems  owing  to  its
     long association with Unix manuals, including man pages.  It and its prede‐
     cessor  have  produced  several  best‐selling  software  engineering texts.
     _g_r_o_f_f can create typographically sophisticated  documents  while  consuming
     minimal system resources.

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

     The _g_r_o_f_f command orchestrates the execution of preprocessors,  the  trans‐
     formation  of  input  documents  into a device‐independent page description
     language, and the production of output from that language.

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.  However,
     _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  interpreted
     differently by _g_r_o_f_f.

     --DD _e_n_c   Use _e_n_c as _p_r_e_c_o_n_v(1)’s fallback input encoding; 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.
              _g_r_o_f_f  passes  --II  options  and  their  arguments  to   _s_o_e_l_i_m(1),
              _t_r_o_f_f(1),  and  output  drivers; with the option letter changed to
              --MM, it passes the same arguments to _g_r_n(1).

     --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 behav‐
              ior 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 op‐
              tions --LL and --XX.

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

     --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 op‐
              tion 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 it; most _r_e_f_e_r options have equivalent language  ele‐
              ments that can be specified within the document.

     --ss       Run _s_o_e_l_i_m(1) preprocessor.

     --SS       Enable  safer  mode  and  ignore  any subsequent --UU option.  _g_r_o_f_f
              passes the --SS option to _p_i_c(1) and _t_r_o_f_f(1).

     --tt       Run _t_b_l(1) preprocessor.

     --TT _d_e_v   Prepare output for device _d_e_v_.  _g_r_o_f_f passes the --TT option and its
              argument to _t_r_o_f_f, then (unless the --ZZ option  is  used)  runs  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.  _g_r_o_f_f passes the --UU option to _p_i_c(1)  and
              _t_r_o_f_f(1).

     ----vveerrssiioonn
     --vv       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  and  exit.  If given more than once, _g_r_o_f_f both writes the
              pipeline to the standard error stream and runs it.

     --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  “--TT  ppss”
              uses  the  font  metrics of the PostScript device, whereas the “--TT
              XX7755”, “--TT XX7755--1122” “--TT XX110000”, and “--TT XX110000--1122” options use the met‐
              rics of X11 fonts.

     --ZZ       Disable postprocessing.  _t_r_o_f_f output appears on the standard out‐
              put stream (unless suppressed with --zz); see _g_r_o_f_f___o_u_t(5) for a de‐
              scription 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_t_e_x_t
     --dd _s_t_r_i_n_g==_t_e_x_t
              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 directory
              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 _m_a_c   Read macro package _m_a_c before input.  _g_r_o_f_f passes --mm options  and
              their arguments to _e_q_n(1), _g_r_a_p(1), and _g_r_n(1).

     --MM _d_i_r   Search directory _d_i_r for macro files.  _g_r_o_f_f passes --MM options and
              their arguments to _e_q_n(1), _g_r_a_p(1), and _g_r_n(1).

     --nn _n_u_m   Begin numbering pages at _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.

     --SS       Enable safer mode and ignore any subsequent --UU option.

     --UU       Operate in unsafe mode.

     --ww _c_a_t
     --WW _c_a_t   Enable and inhibit, respectively, warnings in category _c_a_t_.

     --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‐inde‐
     pendent _r_o_f_f implementations,  comprising  preprocessors,  macro  packages,
     output  drivers  (or  “postprocessors”), and a suite of utilities, with the
     formatter program _t_r_o_f_f(1) 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 summarizes 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  infor‐
     mation.

   GGeettttiinngg ssttaarrtteedd
     Those  who  prefer to learn by experimenting or are desirous of rapid feed‐
     back from the system may wish to start with a “Hello, world!” document.

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

     We used a _s_e_d(1) 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..ddvvii

   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  ver‐
     ify  one’s  understanding  of the formatter’s behavior and/or the syntax 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
     The formatter reads the device description file _D_E_S_C for the selected  out‐
     put  device  when  it  starts;  page  dimensions declared there are used if
     present.  _g_r_o_f_f’s build process configures a default page format and writes
     it to typesetters’ _D_E_S_C files.  This installation defaults to “AA44”.  If the
     _D_E_S_C file lacks this information, the formatter and  output  driver  use  a
     page  length  of  ““11i””  (eleven inches) for compatibility with AT&T _t_r_o_f_f.
     See _g_r_o_f_f___f_o_n_t(5).

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

     Output drivers for typesetters also recognize command‐line  options  --pp  to
     override  the  default page dimensions and --ll to use landscape orientation.
     The output driver’s man page, such as _g_r_o_p_s(1), may be helpful.

     _g_r_o_f_f’s “--dd ppaappeerr” command‐line option is a convenient means of setting the
     paper format; see _g_r_o_f_f___t_m_a_c(5).  Combine it with  appropriate  --PP  options
     for the output driver, overriding its defaults.  The following command for‐
     mats for PostScript on A4 paper in landscape orientation.

            $ ggrrooffff --TT ppss --dd ppaappeerr==aa44ll --PP --ppaa44 --PP --ll --mmss mmyy..mmss >>mmyy..ppss

   FFrroonntt eenndd
     The _g_r_o_f_f program wraps _t_r_o_f_f(1), allowing one to specify preprocessors via
     command‐line  options and running the appropriate output driver for the se‐
     lected output device.  This convenience avoids the manual  construction  of
     pipelines or management of temporary files required of users of traditional
     _r_o_f_f(7) systems.  Use _g_r_o_g(1) 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  fam‐
     ily  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 language, a  com‐
     mon 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 regions
     of _r_o_f_f input (bracketed with macro calls specific to  each  preprocessor),
     which  it  replaces.   Preprocessors  therefore often interpret a subset of
     _r_o_f_f syntax along with their own language.  GNU _r_o_f_f provides reimplementa‐
     tions of most preprocessors familiar to users of  AT&T  _t_r_o_f_f;  these  rou‐
     tinely have extended features and/or require GNU _t_r_o_f_f to format their out‐
     put.

            _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 in‐
     put  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 tokens.
     Such a token must occur at the beginning of an input line and use  the  dot
     control  character.   Spaces and tabs must not follow the control character
     or precede the end of the input line.  Deviating from these rules defeats a
     token’s recognition by the preprocessor.  Tokens are generally preserved in
     preprocessor output and interpreted as macro calls subsequently  by  _t_r_o_f_f.
     The _i_d_e_a_l preprocessor is not yet available in _g_r_o_f_f.

                ┌──────────────┬─────────────────┬────────────────┐
                │ preprocessor │ starting token  │  ending token  │
                ├──────────────┼─────────────────┼────────────────┤
                │     _c_h_e_m     │     .cstart     │     .cend      │
                │     _e_q_n      │       .EQ       │      .EN       │
                │     _g_r_a_p     │       .G1       │      .G2       │
                │     _g_r_n      │       .GS       │      .GE       │
                │    _i_d_e_a_l     │       .IS       │      .IE       │
                │              │                 │      .IF       │
                │     _p_i_c      │       .PS       │      .PE       │
                │              │                 │      .PF       │
                │              │                 │      .PY       │
                │    _r_e_f_e_r     │       .R1       │      .R2       │
                │     _t_b_l      │       .TS       │      .TE       │
                ├──────────────┼─────────────────┼────────────────┤
                │  _g_l_i_l_y_p_o_n_d   │ .lilypond start │ .lilypond stop │
                │    _g_p_e_r_l     │   .Perl start   │   .Perl stop   │
                │   _g_p_i_n_y_i_n    │  .pinyin start  │  .pinyin stop  │
                └──────────────┴─────────────────┴────────────────┘

   MMaaccrroo ppaacckkaaggeess
     Macro  files  are _r_o_f_f input files designed to produce no output themselves
     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.

     The --mm option loads a macro package prior to any _r_o_f_f input documents,  and
     after  performing any string and register assignments directed by --dd and --rr
     options.  The GNU _r_o_f_f system implements most well‐known macro packages 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 economy in early Unix
     culture,  a laconic approach that led to many of the packages being identi‐
     fied in general usage with the _n_r_o_f_f and _t_r_o_f_f option letter used to invoke
     them, sometimes to punning effect, as with “man” (short for “manual”),  and
     even  with  the  option  dash, as in the case of the _s package, much better
     known as _m_s or even _-_m_s.

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

     _a_n     is  used to compose man pages in the format originating in Version 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 alter‐
            native 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  manual
            for  extensive  documentation.   She——for  _m_o_m takes the female pro‐
            noun——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 specific
     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 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 described, 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 programs 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 sys‐
     tem.

     A shell script, _n_r_o_f_f(1), emulates the behavior of AT&T _n_r_o_f_f.  It attempts
     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 sub‐
     section.

     GNU _t_r_o_f_f generates output in a device‐independent, but  not  device‐agnos‐
     tic, 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 speci‐
     fied by the --TT option to the formatter or a front end.  If neither this op‐
     tion 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 following.

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

     ddvvii       for TeX DVI format.

     hhttmmll
     xxhhttmmll     for HTML and XHTML output, respectively.

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

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

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

     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 prepare a
     document for viewing or printing.  Postprocessors for other purposes,  such
     as page resequencing or statistical measurement of a document, are conceiv‐
     able.

     An output driver supports one or more output devices, each with its own de‐
     vice  description  file.   A  device  determines its postprocessor with the
     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 out‐
     put 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, llaattiinn11, and uuttff88.

     _g_x_d_i_t_v_i_e_w(1)
            provides XX7755, XX7755--1122, XX110000, and XX110000--1122, and additionally  can  pre‐
            view 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 interpreted 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 lan‐
     guages 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 successfully (with status 00) if either of  the  options  --hh  or
     ----hheellpp  is specified, status 22 if the program cannot interpret its command‐
     line arguments, and status 11 if it encounters an  error  during  operation.
     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  likewise.   If  not,
     _g_r_o_f_f’s  exit  status  encodes  a  summary of problems encountered, setting
     bit 2 if a command exited with a failure status, bit 3  if  a  command  was
     terminated  with  a  signal,  and bit 4 if a command could not be executed.
     (Thus, if all three misfortunes befall one’s  pipeline,  _g_r_o_f_f  exits  with
     status  2^2 + 2^3 + 2^4 = 4+8+16 = 28.)  To troubleshoot pipeline problems,
     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
     Environment  variables  in  the host system affect the behavior of programs
     supplied by _g_r_o_f_f as follows.  Normally, the path separator in  environment
     variables ending with _P_A_T_H is the colon; this may vary depending on the op‐
     erating system.  For example, Windows uses a semicolon instead.

     _G_R_O_F_F___B_I_N___P_A_T_H
            Locate  _g_r_o_f_f  commands  in  these directories, followed by those in
            _P_A_T_H.  If not set, the installation directory of GNU  _r_o_f_f  executa‐
            bles, _/_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
            Apply  a  prefix to certain GNU _r_o_f_f commands.  _g_r_o_f_f can be config‐
            ured at compile time to apply a prefix to the names of  programs  it
            provides  that  had  counterparts in AT&T _t_r_o_f_f, so that name colli‐
            sions are avoided at run time.  The default prefix is empty.

            When used, this prefix is conventionally the letter “g”.  For  exam‐
            ple,  GNU  _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  wrapper  _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
            Specify  the  assumed character encoding of the input.  _g_r_o_f_f passes
            its value as an argument to  _p_r_e_c_o_n_v(1)  preprocessor’s  --ee  option.
            This  variable’s  existence implies the _g_r_o_f_f option --kk.  If set but
            empty, _g_r_o_f_f runs _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 de‐
            scription 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  packages 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  _T_M_P_D_I_R
            is,  the  latter is used 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 cre‐
            ated 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
            temporary 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
            Declare a time stamp (expressed as seconds since the Unix epoch)  to
            use  as the output creation time stamp in place of the current time.
            The time is converted to human‐readable  form  using  _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 us‐
            able by documents and macro packages.

     _T_Z     Declare the time zone to use when converting the current time to hu‐
            man‐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.  A _m_a_n(1) librarian
     program, having located a page, might render it with a _g_r_o_f_f command.
            groff -t -man -Tutf8 /usr/share/man/man1/groff.1
     The librarian will also pipe the output through a pager,  which  might  not
     interpret  terminal escape sequences _g_r_o_f_f emits for boldface, underlining,
     italics, or hyperlinking; 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  accustomed,  one
     would type (or script) a pipeline.

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

     Shorten this pipeline to an equivalent command using _g_r_o_f_f.

            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 preprocessor
     and macro options and execute the result by using the command  substitution
     feature of the shell.

            $(grog -Tutf8 foo.me)

     Each  command‐line option to a postprocessor must be specified with any re‐
     quired leading dashes “--” because _g_r_o_f_f passes the arguments as‐is  to  the
     postprocessor; this permits arbitrary arguments to be transmitted.  For ex‐
     ample, 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, 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).

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_4_._1_/_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_4_._1
            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_4_._1_/_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_4_._1_/_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_4_._1_/_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_4_._1_/_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_4_._1_/_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, discus‐
     sion mailing lists, a support ticket tracker, and further information  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 Lem‐
     berg, is the primary _g_r_o_f_f manual.  You can browse  it  interactively  with
     “info groff”.

     A  list of all _g_r_o_f_f man pages follows.  A few (_g_r_o_h_t_m_l, _g_r_o_p_d_f, _g_x_d_i_t_v_i_e_w,
     and _x_t_o_t_r_o_f_f) will be unavailable if their corresponding programs were dis‐
     abled during compilation.

     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:
            _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  locales),
            _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),
            _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)

     Device‐independent page description 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), _m_m_r_o_f_f(1), _p_d_f_m_o_m(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.24.1                       2026‐04‐22                           _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 [_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  ren‐
     der  it.  If no operands are given, or if _f_i_l_e is “--”, _g_r_o_g reads the stan‐
     dard input stream.  The corresponding _g_r_o_f_f command is normally written  to
     the standard output stream.

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

     All other specified short options (that is, arguments beginning with a  mi‐
     nus  sign “--” followed by a letter) are interpreted as _g_r_o_f_f options or op‐
     tion clusters with or without an option argument.   Such  options  are  in‐
     cluded 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 statisti‐
     cally 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 inferred _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
     ISO 646:1991 IRV (US‐ASCII) or ISO Latin‐1 (8859‐1), we advise specifying a
     _g_r_o_f_f option to run _p_r_e_c_o_n_v(1); 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 infers 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 continuation
     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
     conceals the use of the _m_s macros NNHH and SSHH from _g_r_o_g.  Such  constructions
     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 ex‐
     ample, requires PPSS, PPEE, and PPFF calls to immediately follow the default con‐
     trol character at the beginning of a line.

     Detection of the --ss option (the _s_o_e_l_i_m(1) preprocessor) is tricky; to  cor‐
     rectly infer its necessity would require _g_r_o_g to recursively open all files
     given as arguments to the ..ssoo request under the same conditions 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  com‐
     pare  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  preprocessor  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 option 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 status 11 if a macro package appears to be in use by the in‐
     put 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.
     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 recog‐
     nizes 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 in‐
     clude 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 er‐
     rors 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 current
     implementation in Perl was written by Bernd Warken and heavily  revised  by
     G. Branden Robinson.

SSeeee aallssoo
     _g_r_o_f_f(1)

groff 1.24.1                       2026‐04‐22                            _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]
                  [--kk _e_n_c_o_d_i_n_g] [--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 translate _r_o_f_f(7) docu‐
     ments to HTML.  Because a preprocessor is (uniquely) required for this out‐
     put 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 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_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 in‐
     put stream.  It writes 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 PostScript
     format using the ppss output device.  In the second pass, the  output  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  UTF‐8‐encoded  output (but see the --kk option) and produces
     HTML character references for most non‐composite, non‐basic  Latin  Unicode
     characters.   In spite of this, _g_r_o_f_f may issue warnings about unknown spe‐
     cial characters if they can’t be found during the first pass.  You can  ig‐
     nore  these warnings unless the special characters appear inside a table or
     equation.

   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  mem‐
     bers 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 ex‐
     pect it to always be available.

     _g_r_o_h_t_m_l furthermore supports a  naming  scheme  for  East  Asian  typefaces
     shared with _g_r_o_p_d_f(1), _g_r_o_p_s(1), and _g_r_o_t_t_y(1).

            CCSSHH    Simplified Chinese, Hei style
            CCSSSS    Simplified Chinese, Song style
            CCTTHH    Traditional Chinese, Hei style
            CCTTSS    Traditional Chinese, Song style
            JJPPGG    Japanese, Gothic style
            JJPPMM    Japanese, Mincho style
            KKOOGG    Korean, Gothic style
            KKOOMM    Korean, Mincho style

   FFoonntt ddeessccrriippttiioonn ffiilleess
     The  font  description files used with _g_r_o_h_t_m_l expose the same glyph reper‐
     toire 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_a_m_c_u_t,
     _p_n_m_c_r_o_p, and _p_n_m_t_o_p_n_g, as well as Ghostscript’s _g_s and _p_s_2_p_s.

OOppttiioonnss
     ----hheellpp displays a usage message, while --vv and ----vveerrssiioonn show version infor‐
     mation; 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 op‐
            tion.

     --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  device,  usu‐
            ally 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 graphics
            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  increasing
            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  appended
            to the stem to separate it from the following image number.

     --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.  Out‐
            put 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.

     --kk _e_n_c_o_d_i_n_g
            Select  the  character  encoding used in the generated document, af‐
            fecting the declared encoding in the preamble and the form of  char‐
            acter entity references.  Valid values are “ASCII” and “UTF-8”.  The
            default is “UTF‐8”.

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

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

     --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 in‐
            crease 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 de‐
            fault 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 gen‐
            erate 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 op‐
            tion.

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

EExxiitt ssttaattuuss
     _p_r_e_-_g_r_o_h_t_m_l  and  _p_o_s_t_-_g_r_o_h_t_m_l each exit with status 00 on successful opera‐
     tion, status 22 if the program cannot interpret its command‐line  arguments,
     and status 11 if it encounters an error during operation.

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

     _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‐read‐
            able 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_4_._1_/_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_4_._1_/_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_4_._1_/_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 selected.

     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_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 de‐
            vices 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 hy‐
     phenating long input lines, which can appear in HTML output with a  hyphen‐
     ated 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.24.1                       2026‐04‐22                         _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.   Normally,
     _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 device.)  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.   It
     writes to the standard output stream.

   TTyyppeeffaacceess
     The  driver supports the Dutch, Swiss, and Swiss‐Narrow scalable typefaces,
     each in the regular, bold, italic, and bold‐italic  styles.   Additionally,
     the bitmapped, monospaced Courier and Elite typefaces are available in reg‐
     ular,  bold,  and italic styles; Courier at 8 and 12 points, Elite at 8 and
     10 points.  The following chart summarizes the _g_r_o_f_f font names used to ac‐
     cess 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 overrides
     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 di‐
     rective accepting one mandatory argument, ppoorrttrraaiitt or llaannddssccaappee.  The first
     valid orientation directive encountered controls.  The --ll, --oo, and ----oorriieenn‐‐
     ttaattiioonn 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 encoded
     as follows.

     For bitmapped fonts, _p_r_i_n_t_e_r_‐_f_o_n_t___n_a_m_e has the form NN⟨_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  ro‐
     man, italic, and bold styles, respectively.  For instance, if the printer’s
     “font  listing A” shows “Nelite12I.ISO_USA”, the corresponding entry in the
     _g_r_o_f_f font description file is “llbbppnnaammee NNeelliitteeII”.  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 listing as
     “Swiss-BoldOblique”, “llbbppnnaammee SSwwiissss--BBoollddOObblliiqquuee” 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  avail‐
     able.

     \\DD''RR _d_h _d_v''
            Draw  a  rule (solid black rectangle) with one corner at the drawing
            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  version
     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 device, usu‐
            ally 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 paper
            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).

EExxiitt ssttaattuuss
     _g_r_o_l_b_p exits with status 00 on successful operation, status 22 if the program
     cannot  interpret its command‐line arguments, and status 11 if it encounters
     an error during operation.

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

FFiilleess
     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_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_4_._1_/_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_4_._1_/_t_m_a_c_/_l_b_p_._t_m_a_c
            defines macros for use with the llbbpp output device.  It is  automati‐
            cally loaded by _t_r_o_f_f_r_c when the llbbpp output device is selected.

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.24.1                       2026‐04‐22                          _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 a Hewlett‐Packard 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.  It writes 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.  For the convenience of  a  consis‐
     tent  font  repertoire  in _g_r_o_f_f, _l_j_4_._t_m_a_c (see section “Files” below) uses
     ffttrr requests to remap HH (“Helvetica”) font names to the UU names  shown  be‐
     low.

            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  description  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 default
            is 0.

     ppccllpprrooppoorrttiioonnaall _n
            Set the proportional spacing Boolean flag to _n, which can be  either
            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  docu‐
     mented in _g_r_o_f_f(7).

     \\DD''RR _d_h _d_v''
            Draw  a  rule (solid black rectangle) with one corner at the drawing
            position, and the diagonally opposite corner at the drawing position
            +(_d_h,_d_v), at which the drawing position  will  be  afterward.   This
            generates a PCL fill rectangle command, and so will work on printers
            that do not support HP‐GL/2, unlike the other \\DD commands.

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

     The  LaserJet font files included with _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 scalable fonts; the re‐
     maining  10   scalable   fonts   were   TrueType.    Beginning   with   the
     LaserJet  4000‐series  printers  introduced  in 1997, all scalable internal
     fonts have been TrueType.  The number of printable glyphs differs  slightly
     between  Intellifont  and TrueType fonts (generally, the TrueType fonts in‐
     clude more glyphs), and there are some minor differences in glyph  metrics.
     Differences  among  printer  models  are  described in the _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 print‐
     ing 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 description of the font  file  format;  symbol
     sets  are described in greater detail 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 speci‐
     fied.

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

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

     Because  the  Intellifont  TFM files contain considerably more information,
     they generally are preferable to the TrueType TFM files even for  use  with
     the  TrueType  fonts  in  the newer printers.  The metrics for the TrueType
     fonts are very close, though not identical, to those for the earlier Intel‐
     lifont fonts of the same names.  Although most output using the Intellifont
     metrics with the newer printers is quite acceptable, a few glyphs may  fail
     to print as expected.  The differences in glyph metrics may be particularly
     noticeable with composite parentheses, brackets, and braces used by _e_q_n(1).
     A  script,  located in _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_f_o_n_t_/_d_e_v_l_j_4_/_g_e_n_e_r_a_t_e, can be
     used to adjust the metrics for these glyphs in the special font “S” for use
     with printers that have all TrueType fonts.

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

OOppttiioonnss
     ----hheellpp displays a usage message, while --vv and ----vveerrssiioonn show version infor‐
     mation; 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 device,
             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  paper
             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).

EExxiitt ssttaattuuss
     _g_r_o_l_j_4 exits with status 00 on successful operation, status 22 if the program
     cannot interpret its command‐line arguments, and status 11 if it  encounters
     an error during operation.

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

FFiilleess
     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_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_4_._1_/_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_4_._1_/_t_m_a_c_/_l_j_4_._t_m_a_c
            defines  macros for use with the lljj44 output device.  It is automati‐
            cally loaded by _t_r_o_f_f_r_c when the lljj44 output device is selected.

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.24.1                       2026‐04‐22                          _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 [--ddeellssWW] [{--ff|----ffoorrmmaatt‐‐ooppttiioonnss} _b_i_t_‐_v_e_c_t_o_r] [--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] [----ppddffvveerr {11..44|11..77}]
            [--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 de‐
     fault 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.  It writes 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 infor‐
     mation; 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).

     ----ffoorrmmaatt--ooppttiioonnss _b_i_t_‐_v_e_c_t_o_r
     --ff _b_i_t_‐_v_e_c_t_o_r
             Specify   advanced   options  for  _g_r_o_p_d_f_.   Familiarity  with  the
             ISO 32000 PDF standard is helpful.  The _b_i_t_‐_v_e_c_t_o_r argument  is  an
             integer  that configures characteristics of the generated PDF.  Add
             the following values to combine them.

                    Value   Meaning
                    ────────────────────────────────────────────────────────────
                    11       Subset included Type 1 fonts.
                    22       Use more compact format for text by including space
                            as a character.  Fonts that do not include space as
                            a glyph may conflict with this feature.
                    44       Compress all data streams.
                    88       Don’t embed font files.  (A font  required  by  the
                            document is not embedded; usually not useful.)

             The  default  feature  combination is 7.  To mimic what _g_r_o_p_d_f from
             _g_r_o_f_f 1.23 produced, specify “6” to turn off subsetting.

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

     --II _d_i_r  Search the directory _d_i_r for files named in \\XX''ppddff:: ppddffppiicc''  device
             extension  commands.   --II may be specified more than once; each _d_i_r
             is searched in the given order.  To search the current working  di‐
             rectory  before others, add “--II ..” at the desired place; it is oth‐
             erwise 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  overrides
             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.

     ----ppddffvveerr {11..44|11..77}
             PDF  version  1.7  introduced a more compact object format; this is
             now the default.  If you require the original format  (as  produced
             by _g_r_o_p_d_f 1.23) set the version to 11..44.

     --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 us‐
             ing _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.

     --WW      Exit with failure status if any warnings are issued.

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

UUssaaggee
     _g_r_o_p_d_f’s  input must be in the format produced by _t_r_o_f_f(1) and described in
     _g_r_o_f_f___o_u_t(5).  Further, its device and font  description  files  must  meet
     certain  requirements.   The  device rreessoolluuttiioonn must be an integer multiple
     of 72 times ssiizzeessccaallee.  By default, _g_r_o_p_d_f uses a rreessoolluuttiioonn of 72000 and a
     ssiizzeessccaallee of 1000.  A valid paper format is mandatory;  see  _g_r_o_f_f___f_o_n_t(5).
     While the PDF standard allows several font file formats (like TrueType), at
     present  _g_r_o_p_d_f  accepts  only  the  same Type 1 Adobe PostScript format as
     _g_r_o_p_s(1).  Fewer Type 1 fonts are supported natively in PDF documents  than
     the  standard  35 fonts supported by _g_r_o_p_s and PostScript printers, but all
     are available since _g_r_o_p_d_f automatically embeds any that  aren’t  specified
     by the PDF standard.

     _g_r_o_p_d_f supports _f_o_u_n_d_r_i_e_s that permit multiple providers to supply the same
     _g_r_o_f_f  font  names.   _g_r_o_f_f’s compilation process attempts to locate Type 1
     fonts on the system, populates a _F_o_u_n_d_r_y file  with  their  locations,  and
     generates  font  description files corresponding to them.  Font description
     files can also be added after installation.  Each such file must contain  a
     directive
            iinntteerrnnaallnnaammee _p_s_n_a_m_e
     that  maps the _g_r_o_f_f font name (such as “TR”) to a PostScript name (such as
     “Times-Roman”).  Lines starting with ## and blank lines  are  ignored.   The
     code  for each character given in the font file must correspond to the code
     in the default encoding for the font.  This code can be used  with  the  \\NN
     escape sequence in _t_r_o_f_f to select the character even if it lacks a special
     character  name.  Every character in the font description must exist in the
     font file, and the widths given in the description must match those used in
     the font file.  See _g_r_o_f_f___f_o_n_t(5).

     _g_r_o_p_d_f can automatically _e_m_b_e_d any downloadable fonts  necessary  to  print
     the  document.   Any  fonts  thus required must be listed in the file _/_u_s_r_/
     _s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_f_o_n_t_/_d_e_v_p_d_f_/_d_o_w_n_l_o_a_d, which should comprise 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 PFA or
     PFB  font file, and can be a pathname (can contain slashes).  Any lines be‐
     ginning with ## and blank lines are ignored; fields  must  be  separated  by
     tabs (spaces are nnoott allowed); if _f_i_l_e_‐_n_a_m_e is not a pathname, it is sought
     using  the same mechanism as that used for 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  de‐
     fault  foundry.   This default 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.

     The default stroke and fill colors are black.

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

     Another text font is not a member of a family.

            ZZCCMMII    ZapfChancery‐MediumItalic

     Special fonts include SS, the PostScript Symbol font; SSSS, a subset of SS with
     slanted lowercase Greek letters; EEUURROO, which offers a Euro glyph in several
     styles for use with old devices lacking it; and ZZDD, Zapf Dingbats.  In con‐
     trast to _g_r_o_p_s, _g_r_o_p_d_f does not require a reversed variant of it (ZZDDRR); the
     “hand  pointing  left”  glyph  (\\[[llhh]])  is  available  nevertheless,  since
     _p_d_f_._t_m_a_c  defines  it using the \\XX''ppddff:: xxrreevv'' device extension command (see
     below).  Some glyphs in these fonts are unnamed and must be accessed as in‐
     dexed characters, using the \\NN escape sequence.

     The fonts corresponding to EEUURROO and SSSS are unknown  to  the  PDF  standard;
     _g_r_o_f_f  therefore  provides  their  AFM  files (font metrics) and PFA or PFB
     files so that they can be used with other software and embedded in PDF out‐
     put.

   FFeeaattuurree sseerrvviiccee lleevveellss aanndd UURRWW ffoonntt ssuuppppoorrtt
     The traditional PostScript Type 1 fonts are limited in their  glyph  reper‐
     toire,  and the original versions from the Adobe foundry are not free soft‐
     ware.  Historically, because their presence was mandated by the  PostScript
     standard,  one  could expect to find support for them in any conforming de‐
     vice or software PostScript renderer.   PostScript  (“Level  1”)  initially
     standardized  14  typefaces:  Times,  Helvetica,  and  Courier each in four
     styles (which _g_r_o_f_f groups into “families”); a symbol font; and a  dingbats
     font.   PostScript  Level 2 increased the number to 35, adding the families
     Avant  Garde,  Bookman,  Helvetica  Narrow,  New  Century  Schoolbook,  and
     Palatino;  and  a  text  font in one style, Zapf Chancery medium italic.  A
     document could be small because it did not need to embed font resources un‐
     less it had unusual (for the time) glyph or  typeface  requirements.   This
     situation  carried over into the early years of PostScript’s successor page
     description language, PDF.  Nowadays, it is common to embed fonts in  PDFs,
     and  authorities widely recommend this practice, which increases the relia‐
     bility of document rendering, and many free software  fonts  are  available
     with much greater glyph coverage than Adobe’s Type 1 fonts for PostScript.

     _g_r_o_p_d_f  attempts  to  work in variety of scenarios, and delivers better re‐
     sults when configured with supporting digital font  files  (for  embedding)
     and font metrics files describing those fonts to the formatter.

     •  _F_u_l_l  _s_e_r_v_i_c_e  is  available  when _g_r_o_p_d_f can locate all 35 fonts of the
        PostScript Level 2 standard on the file system along with  their  corre‐
        sponding  font  metrics  (AFM) files.  The Adobe‐compatible unnamed (de‐
        fault) foundry supports up to 256 glyphs in each typeface.   Fonts  from
        the  URW foundry (“U”) are compatible extensions of the Adobe fonts with
        extended glyph coverage, including support for Cyrillic script.  _g_r_o_f_f’s
        build process uses _a_f_m_t_o_d_i_t(1) to generate font description  files  from
        the URW foundry’s AFM files; see section “Files” below.

     •  _I_n_t_e_r_m_e_d_i_a_t_e _s_e_r_v_i_c_e is available when _g_r_o_p_d_f can locate all 35 fonts of
        the PostScript Level 2 standard but not their corresponding font metrics
        (AFM)  files.   _g_r_o_f_f’s  build process copies the font description files
        from those for the _g_r_o_p_s(1) driver, reusing them for  _g_r_o_p_d_f;  this  re‐
        duces  glyph  coverage to 256 glyphs maximum from each face, and the “U”
        foundry is unavailable.

     •  _B_a_s_i_c _s_e_r_v_i_c_e results when _g_r_o_p_d_f cannot locate  all  35  fonts  of  the
        PostScript Level 2 standard.  Only the base 14 fonts of the PDF standard
        are  available,  and  only in the sense that the formatter can use their
        metrics (copied from _g_r_o_p_s font descriptions as described  above).   Use
        of  the  --ee option to embed fonts in the generated PDF results in an er‐
        ror.

   DDeevviiccee eexxtteennssiioonn ccoommmmaannddss
     _g_r_o_p_d_f supports many device extensions, accessed  with  the  _g_r_o_f_f  request
     ddeevviiccee  or  _r_o_f_f \\XX escape sequence.  First, it understands many of the de‐
     vice extensions 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 com‐
            mand 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

     _g_r_o_p_d_f also supports a subset of  the  commands  introduced  in  _g_p_r_e_s_e_n_t’s
     _p_r_e_s_e_n_t_._t_m_a_c.

            PPAAUUSSEE
            BBLLOOCCKKSS
            BBLLOOCCKKEE

     These  allow  you  to create presentation 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  us‐
            ing  the current BBLLOOCCKK transition setting (see “\\XX''ppddff:: ttrraannssiittiioonn''”
            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‐presen‐
            tation 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.

     _g_r_o_p_d_f also recognizes a device extension used by the DVI driver.

     \\XX''ppaappeerrssiizzee==_w_i_d_t_h,,_l_e_n_g_t_h''
            Set the page dimensions in centimeters to _w_i_d_t_h by _l_e_n_g_t_h_.   If  the
            --ll  option  was specified, these dimensions are swapped.  Changes to
            the paper dimensions should occur prior to the first page, or during
            page ejection before starting a subsequent one.

            _C_a_u_t_i_o_n_: the ordering of dimensions differs from that used by _p_a_p_e_r_‐
            _s_i_z_e_._t_m_a_c and _t_r_o_f_f(1)’s “--dd ppaappeerr” option.

     \\XX''ppddff:: mmaarrkkssttaarrtt _/_A_N_N_‐_d_e_f_i_n_i_t_i_o_n''
     \\XX''ppddff:: mmaarrkkeenndd''
            Macros that support PDF features use these extension commands inter‐
            nally to bracket _h_o_t_s_p_o_t text (a hyperlink).  User documents  should
            call  the  ..ppddffhhrreeff  macro  instead.   Their application is found in
            other macro packages (like _g_r_o_f_f___m_a_n(7) or _g_r_o_f_f___m_d_o_c(7)) that  call
            ..ppddffhhrreeff  with  a --SS argument, then indicate the end of hotspot text
            with \\XX''ppddff:: mmaarrkkeenndd''\\mm[[\\**[[ppddff::ccuurrccooll]]]].

     \\XX''ppddff:: xxrreevv''
            Toggle the reversal of glyph direction.  This feature works  by  re‐
            versing  all following text.  Each separate letter is also mirrored.
            One application is the reversal of glyphs in the Zapf Dingbats font.
            To restore the normal glyph orientation, repeat the command.

     _g_r_o_p_d_f supports several more device extensions using  the  ppddff::  tag.   The
     following  have counterpart _c_o_n_v_e_n_i_e_n_c_e _m_a_c_r_o_s that take the same arguments
     and behave equivalently.

     ..ppddffbbaacckkggrroouunndd _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
     ..ppddffbbaacckkggrroouunndd ooffff
     ..ppddffbbaacckkggrroouunndd ffoooottnnoottee _b_o_t_t_o_m
     \\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''
            Produce a background rectangle on the page.

            _c_m_d     is the command, which can be any of “ppaaggee|ffiillll|bbooxx” in  com‐
                    bination.   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).  “bbooxxffiillll”,  on  the
                    other  hand, requires the given dimensions to place the box.
                    Including “ffiillll” in the command paints  the  rectangle  with
                    the  current  fill colour (as with \\MM[[]]) and including “bbooxx”
                    gives the rectangle a border in the  current  stroke  colour
                    (as with \\mm[[]]).

                    _c_m_d  may  also be “ooffff” on its own, which terminates 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 replaces 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” com‐
                    mand 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  is  used  for  all open boxes on the current
                    page.  This is to allow room for footnote  areas  that  grow
                    while  a  page  is  processed (to accommodate multiple foot‐
                    notes, for instance).  (If the value is negative, it is used
                    as an offset from the bottom of the page.)

            _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  coordi‐
                    nates are the minimum and maximum for the box, since the ac‐
                    tual  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 bottom coordi‐
                    nates are used only if the box drawing extends onto the next
                    page; ordinarily, they would be set to the header and footer
                    margins.

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

            An _s_b_o_x_e_s macro file is also available; see _g_r_o_f_f___t_m_a_c(5).

     ..ppddffmmaarrkkssuussppeenndd
     ..ppddffmmaarrkkrreessttaarrtt
     \\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  com‐
            mands  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 hotspot.   To  pre‐
            vent  this  error,  place these device extension escape sequences or
            their   corresponding   convenience   macros   ..ppddffmmaarrkkssuussppeenndd   and
            ..ppddffmmaarrkkrreessttaarrtt  at  the  start  and  end of the trap macro, respec‐
            tively.

     ..ppddffppaaggeennaammee _n_a_m_e
     \\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’.

     ..ppddffppaaggeennuummbbeerriinngg _t_y_p_e _p_r_e_f_i_x _s_t_a_r_t
     \\XX''ppddff:: ppaaggeennuummbbeerriinngg _t_y_p_e _p_r_e_f_i_x _s_t_a_r_t''
            Control  the  page  numbering shown in a PDF reader’s outline (which
            also contains bookmarks).  Normally, the page number associated with
            each bookmark is its sequence number in the file, but this might not
            match the desired numbering scheme.  A document  may  bear  a  cover
            sheet (which has no page number); front matter (possibly including a
            table of contents) that uses lowercase roman numerals; the main mat‐
            ter,  which uses arabic numerals; and back matter, which may include
            appendices that are each prefixed with a  letter  and  independently
            numbered.   Place  this  command prior to breaking the page to which
            the new numbering scheme  is  to  apply.   It  then  persists  until
            changed again.

            _t_y_p_e    specifies  the  numbering system to use. It should be one of
                    “DDeecciimmaall”, “RRoommaann”, “rroommaann”, “AAllpphhaa”, or “aallpphhaa”.  This  pa‐
                    rameter  may  be abbreviated to the first letter, whose let‐
                    tercase determines that used for the numbers where  applica‐
                    ble.   The ordering used by the alphabetic numbering systems
                    is A‐Z ... AA‐AZ ... ZA‐ZZ.  _t_y_p_e can also be “..”, which se‐
                    lects no numbering system; you may still provide a _p_r_e_f_i_x_.

            _p_r_e_f_i_x  specifies text to precede the page number.  For example,  to
                    number  the pages of an appendix “A‐1”, “A‐2”, and so forth,
                    use a _p_r_e_f_i_x of “AA‐‐” and a _t_y_p_e of “DDeecciimmaall”.

            _s_t_a_r_t   determines the page number.  It defaults to 1.

     ..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
     \\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 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 proportion  to  the
            height.   If  both _w_i_d_t_h and _h_e_i_g_h_t are non‐zero the image is scaled
            to ‘best fit’.

            The availability of other software on the system, such  as  _P_e_r_l_M_a_g_‐
            _i_c_k,  influences  the  types  of image files _g_r_o_p_d_f can embed in its
            output.

               ┌───────┬──────┬─────────┬─────────────┬────────────────────┐
               │       │ none │ _f_i_l_e(1) │ _i_d_e_n_t_i_f_y(1) │ _I_m_a_g_e_:_:_M_a_g_i_c_k(3pm) │
               ├───────┼──────┼─────────┼─────────────┼────────────────────┤
               │ _._p_d_f  │  ✓   │    ✓    │      ✓      │         ✓          │
               ├───────┼──────┼─────────┼─────────────┼────────────────────┤
               │ _._j_p_g  │  ✗   │    ✓    │      ✓      │         ✓          │
               ├───────┼──────┼─────────┼─────────────┼────────────────────┤
               │ _._j_p_2  │  ✗   │    ✗    │      ✓      │         ✓          │
               ├───────┼──────┼─────────┼─────────────┼────────────────────┤
               │ other │  ✗   │    ✗    │      ✗      │         ✓          │
               └───────┴──────┴─────────┴─────────────┴────────────────────┘

            See _g_r_o_f_f___t_m_a_c(5) for a description of the PPDDFFPPIICC macro, which  pro‐
            vides  a  convenient  high‐level  interface for inclusion of various
            graphic file formats.

     ..ppddffsswwiittcchhttooppaaggee _w_h_e_n _n_a_m_e
     \\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 ei‐
            ther ‘_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 esoteric uses are possible.

     ..ppddffttrraannssiittiioonn _s_c_o_p_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
     \\XX''ppddff:: ttrraannssiittiioonn _s_c_o_p_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''
            Configure  the  style  of  page transitions, as used in “slides” (or
            “foils”).  _s_c_o_p_e can be either SSLLIIDDEE or BBLLOOCCKK.   SSLLIIDDEE  applies  the
            transition  when  a new slide is introduced to the screen; BBLLOOCCKK ap‐
            plies it to the individual blocks making 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, re‐
                   spectively.
                   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  vertical,  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 en‐
                   try, revealing the new page.
                   DDiissssoollvvee ‐ The old page dissolves gradually to reveal the new
                   one.
                   GGlliitttteerr ‐ As Dissolve, except that the effect  sweeps  across
                   the page in a wide band moving from one side of the screen to
                   the other in the direction specified by the _d_i_r_e_c_t_i_o_n entry.
                   RR  ‐ The new page simply replaces the old one with no special
                   transition effect; the _d_i_r_e_c_t_i_o_n entry shall be ignored.
                   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 occur: HH
            Horizontal, or VV Vertical.

            _m_o_t_i_o_n (Optional; SSpplliitt, BBooxx and FFllyy transition styles only) The di‐
            rection of motion for the specified transition effect: II Inward 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 transi‐
            tion  effect  shall  moves,  expressed  in  degrees counterclockwise
            starting from a left‐to‐right direction.  If the value is a  number,
            it  shall  be  one  of:  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 starting or
            ending scale at which the changes shall be drawn.  If _m_o_t_i_o_n  speci‐
            fies  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  tran‐
            sition

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

            Any of the parameters may be replaced with a "." which signifies the
            parameter retains its previous value, also any trailing missing  pa‐
            rameters are ignored.

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

   MMaaccrrooss
     _g_r_o_p_d_f’s support macros in _p_d_f_._t_m_a_c define the convenience macros described
     above.  Some features have no direct device extension escape sequence coun‐
     terpart.

     ..ppddffbbooookkmmaarrkk [--TT _t_a_g_‐_n_a_m_e] _l_e_v_e_l _t_e_x_t
            Mark the nearest page location as a bookmark, and optionally a named
            destination  as  well.   _B_o_o_k_m_a_r_k_s  populate the outline pane of the
            reader.  They are organized into a hierarchical tree; each level  of
            the  tree  is numbered, starting at 1, and named as _t_e_x_t in the out‐
            line.  _N_a_m_e_d _d_e_s_t_i_n_a_t_i_o_n_s permit hyperlink‐style  navigation  within
            the  document.   Specifying  --TT followed by _t_a_g_‐_n_a_m_e creates a named
            destination making the page location eligible as a target  named  by
            “..ppddffhhrreeff LL ...”.

     ..ppddffhhrreeff LL --DD _d_e_s_t [--SS] [--PP _p_r_e_f_i_x_‐_t_e_x_t] [--AA _s_u_f_f_i_x_‐_t_e_x_t] [_l_i_n_k_‐_t_e_x_t]
            Create  a  hotspot  link  to _d_e_s_t_, (the _t_a_g_‐_n_a_m_e) which a “..ppddffbbooookk‐‐
            mmaarrkk ...” or “..ppddffhhrreeff MM ...” call elsewhere in the document  should
            define.   (If  the  document  employs forward references, it must be
            processed twice; see _p_d_f_m_o_m(1).)  If _l_i_n_k_‐_t_e_x_t is omitted  the  text
            associated  with _d_e_s_t, when it was created, is formatted as the link
            text.  The --PP and --AA arguments format their successors as  text  be‐
            fore  and  after  the  link  text, respectively, without intervening
            space.  Specifying --SS prevents ppddffhhrreeff from “closing”  the  hotspot,
            requiring  the document (or macro package wrapping ppddffhhrreeff) to do so
            itself with “\\XX''ppddff:: mmaarrkkeenndd''\\mm[[\\**[[ppddff::ccuurrccooll]]]]”.

     ..ppddffhhrreeff MM [--EE] [--NN _t_a_g_‐_n_a_m_e] _d_e_s_t
            Mark the nearest page location as a  destination  named  (the  first
            word of) _d_e_s_t_, which should be unique within a document.  Specifying
            --TT  followed by _t_a_g_‐_n_a_m_e overrides this default.  Specifying --EE for‐
            mats _d_e_s_t as text in the document as well.

     ..ppddffhhrreeff WW --DD _u_r_i [--SS] [--PP _p_r_e_f_i_x_‐_t_e_x_t] [--AA _s_u_f_f_i_x_‐_t_e_x_t] _l_i_n_k_‐_t_e_x_t
            Create a hotspot link to _u_r_i_, a World Wide  Web  Universal  Resource
            Identifier  (URI).   The --PP and --AA arguments format their successors
            as text before and after the link text, respectively, without inter‐
            vening space.  Specifying --SS prevents  ppddffhhrreeff  from  “closing”  the
            hotspot,  requiring the document (or macro package wrapping ppddffhhrreeff)
            to do so itself with “\\XX''ppddff:: mmaarrkkeenndd''\\mm[[\\**[[ppddff::ccuurrccooll]]]]”.

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

     ..ppddffnnoottee [--TT _t_i_t_l_e] _t_e_x_t
            Create an annotation in the document.  Reader support for this  fea‐
            ture  varies.   Some  place  an  icon at the current position on the
            page; hovering over the icon reveals any _t_i_t_l_e,  while  clicking  on
            the icon pops up a window containing _t_e_x_t.

   PPaarraammeetteerrss
     The following parameters, shown as _r_o_f_f control lines, affect the operation
     of _g_r_o_p_d_f.

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

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

   IImmppoorrttiinngg PPDDFF ggrraapphhiiccss
     If  you  are importing an image as a PDF file, it must be a single page and
     the drawing must just fit inside the  media  size  of  the  PDF  file.   In
     _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
     For  your  convenience, _g_r_o_f_f offers _i_n_s_t_a_l_l_-_f_o_n_t_._b_a_s_h, a shell script that
     interactively assists the configuration of fonts for use with the GNU _t_r_o_f_f
     formatter and the _g_r_o_p_d_f output driver.  See section “Files” below.

     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  PostScript
        Type 1 font in PFA or PFB format, together with an AFM file.  A PFA file
        begins as follows.
               %!PS-AdobeFont-1.0:
        A  PFB  file contains this string as well, preceded by some non‐printing
        bytes.  In the following steps, we  will  consider  the  use  of  CTAN’s
        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,  respectively,  as  suf‐
        fixes  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  descriptions.
        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  de‐
        scription 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 de‐
        fault _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 necessarily 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

EExxiitt ssttaattuuss
     0      _g_r_o_p_d_f successfully produced a PDF document.

     1      _g_r_o_p_d_f  experienced  a  critical error, or warnings were emitted and
            the --WW option was specified.

     2      _g_r_o_p_d_f could not interpret its command‐line arguments.

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  device’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 directo‐
            ries 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 com‐
            mands specific to presentation PDFs, producing a normal PDF instead.

     _G_R_O_P_D_F___O_P_T_I_O_N_S
            _g_r_o_p_d_f interprets the contents of this  environment  variable  as  a
            space‐separated list of command‐line options.  Explicit command‐line
            options override any settings from this environment variable.

     _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_(_) func‐
            tion and recorded in a PDF comment.

     _T_Z     The time zone to use when converting the current time to human‐read‐
            able 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_4_._1_/_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_4_._1_/_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_4_._1_/_f_o_n_t_/_d_e_v_p_d_f_/_U_-F
            describes  the  font from the URW foundry (versus the Adobe default)
            known as _F on device ppddff.

     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_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_4_._1_/_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 PostScript
            Type 1 fonts.

     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_f_o_n_t_/_d_e_v_p_d_f_/_s_y_m_b_o_l_s_l_._a_f_m
            provides metrics for the slanted symbol font known to _g_r_o_f_f  as  SSSS.
            These data facilitate use of the font with non‐_g_r_o_f_f software.

     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_f_o_n_t_/_d_e_v_p_d_f_/_s_y_m_b_o_l_s_l_._p_f_b
            supplies the slanted symbol font known to _g_r_o_f_f as SSSS.

     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_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_4_._1_/_f_o_n_t_/_d_e_v_p_d_f_/_g_e_n_e_r_a_t_e_/_s_y_m_b_o_l_s_l_._s_f_d
            is the source form of the _s_y_m_b_o_l_s_l_._p_f_b font, in spline font database
            (SFD) format.

     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_t_m_a_c_/_p_d_f_._t_m_a_c
            defines  macros for use with the ppddff output device.  It is automati‐
            cally loaded by _t_r_o_f_f_r_c when the ppddff output device is selected.

     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_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_.

     _/_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_/_i_n_s_t_a_l_l_-_f_o_n_t_._b_a_s_h
            This script, contributed by _m_o_m macro package author Peter Schaffter
            and  long  available  at  his web site, assists with making TrueType
            (_._t_t_f), OpenType (_._o_t_f), and PostScript Type 1  (_._p_f_a,  _._p_f_b)  fonts
            available to _g_r_o_f_f.

            Change  to  its  directory and run “bbaasshh iinnssttaallll--ffoonntt..bbaasshh --HH” for a
            man page‐like description of its features and operation.

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.24.1                       2026‐04‐22                          _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 latter is
     given the “--TT ppss” 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_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  stan‐
     dard input stream.  It writes to the standard 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 catenated output, it is necessary to deactivate DSC
     handling in the printing program or previewer.

     See section “Font installation” below for a guide to installing  fonts  for
     _g_r_o_p_s.

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

     --bb _n    Work around problems with spoolers, previewers, and older printers.
             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  Tran‐
             Script  that  get confused by anything between the %%%%EEnnddPPrroolloogg com‐
             ment and the first %%%%PPaaggee comment.

             Add 2 to omit lines in included files beginning with %%!!, which con‐
             fuse 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 command).
             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 de‐
             vice 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  desired  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   directive;   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 resolution 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 descrip‐
     tion 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  encoding
     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 posi‐
     tion 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  corre‐
     spond to the code for the character in encoding file, or to the code in the
     default  encoding  for  the  font if the PostScript font is not to be reen‐
     coded.  This code can be used with the \\NN escape sequence in _t_r_o_f_f  to  se‐
     lect  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 description file must match the widths
     used in the PostScript font.  _g_r_o_p_s assumes 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 encoding  file  is
     specified)  just  defines the order of glyphs for the first 256 characters;
     all other glyphs are accessed with additional encoding vectors which  _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.  Blank lines and those beginning  with  ##  are  ig‐
     nored;  fields are separated by tabs.  _f_i_l_e is sought using the same mecha‐
     nism as for _g_r_o_f_f font description files.  The _d_o_w_n_l_o_a_d file itself  is  as
     well;  currently,  the first matching file found in the device and font de‐
     scription search path is used.

     If the file containing a downloadable font or imported document conforms to
     the Adobe Document Structuring Conventions, then _g_r_o_p_s interprets any  com‐
     ments  in  the files sufficiently to ensure that its own output is conform‐
     ing.  It also supplies any needed font resources that  are  listed  in  the
     _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 before 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 %%%%DDooccuummeennttNNeeeeddeedd‐‐
     RReessoouurrcceess, %%%%DDooccuummeennttSSuupppplliieeddRReessoouurrcceess, %%%%IInncclluuddeeRReessoouurrccee, %%%%BBeeggiinnRReessoouurrccee,
     and %%%%EEnnddRReessoouurrccee comments  (or  possibly  the  old  %%%%DDooccuummeennttNNeeeeddeeddFFoonnttss,
     %%%%DDooccuummeennttSSuupppplliieeddFFoonnttss,  %%%%IInncclluuddeeFFoonntt,  %%%%BBeeggiinnFFoonntt,  and  %%%%EEnnddFFoonntt com‐
     ments) should be used.

     The default stroke and fill colors are black.  For colors  defined  in  the
     “rgb” color space, sseettrrggbbccoolloorr is used; for “cmy” and “cmyk”, sseettccmmyykkccoolloorr;
     and for “gray”, sseettggrraayy.  sseettccmmyykkccoolloorr is a PostScript LanguageLevel 2 com‐
     mand 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 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

     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 de‐
     vices lacking it; and ZZDDRR, a reversed version of Zapf Dingbats  (with  sym‐
     bols  flipped about the vertical axis).  Most glyphs in these fonts are un‐
     named and must be accessed using \\NN.  The last three are not standard Post‐
     Script fonts, but supplied by _g_r_o_f_f and therefore included in  the  default
     _d_o_w_n_l_o_a_d file.

     _g_r_o_p_s  furthermore supports a naming scheme for East Asian typefaces shared
     with _g_r_o_h_t_m_l(1), _g_r_o_p_d_f(1), and _g_r_o_t_t_y(1).

            CCSSHH    Simplified Chinese, Hei style
            CCSSSS    Simplified Chinese, Song style
            CCTTHH    Traditional Chinese, Hei style
            CCTTSS    Traditional Chinese, Song style
            JJPPGG    Japanese, Gothic style
            JJPPMM    Japanese, Mincho style
            KKOOGG    Korean, Gothic style
            KKOOMM    Korean, Mincho style

   DDeevviiccee eexxtteennssiioonn ccoommmmaannddss
     _g_r_o_p_s recognizes device extension commands produced by  the  _g_r_o_f_f  request
     ddeevviiccee  or  _r_o_f_f  \\XX  escape sequence, 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 origin is at the
            top  left  corner  of the page; _x coordinates increase to the right,
            and _y coordinates down the page.  A procedure uu is defined that con‐
            verts _g_r_o_f_f basic units to the coordinate system in effect (provided
            the user doesn’t change the scale).  For example,
                   .nr x 1i
                   \X'ps: exec \nx u 0 rlineto stroke'
            draws a horizontal line one inch long.  _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 allocate space  for  them
            using  “\\XX''ppss:: mmddeeff _n''”.  Any definitions persist only until the end
            of the page.  If you use the \\YY escape  sequence  with  an  argument
            that  names a macro, _c_o_d_e can extend over multiple lines.  For exam‐
            ple,
                   .nr x 1i
                   .de y
                   ps: exec
                   \nx u 0 rlineto
                   stroke
                   ..
                   \Yy
            is another way to draw a horizontal line one inch long.  The  single
            backslash  before  “nnxx”——the  only  reason  to  use a register while
            defining the macro “yy”——is to  convert  a  user‐specified  dimension
            “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,  noth‐
            ing more.  In particular, it doesn’t start and end the inserted 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 defini‐
            tions  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 dic‐
            tionary  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 cre‐
            ate 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 Post‐
            Script 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 upper 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 located
            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 ver‐
            tical  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 Structuring
            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  pro‐
            vides  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 brack‐
            eted 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 certain  characters  or
            other constructs, then other substitute characters 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]] charac‐
            ter  because  the standard X11 fonts do not provide it; this problem
            can be overcome with the following request.

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

            In this case, _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 extension command, it is executed  at  the  beginning  of
     every page (before anything is drawn or written by _g_r_o_f_f).  For example, to
     underlay  the  page contents with the word “DRAFT” in light gray, you might
     use the following.
            .de XX
            ps: def
            /BPhook
            { gsave .9 setgray clippath pathbbox exch 2 copy
              .5 mul exch .5 mul translate atan rotate pop pop
              /NewCenturySchlbk‐Roman findfont 200 scalefont setfont
              (DRAFT) dup stringwidth pop -.5 mul -70 moveto show
              grestore }
            def
            ..
            .devicem XX

     Or, to cause lines and polygons  to  be  drawn  with  square  linecaps  and
     mitered linejoins instead of the round linecaps and linejoins normally used
     by _g_r_o_p_s, use the following.
            .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 unconnected.)

   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
     To  use  TrueType fonts with _g_r_o_p_s, convert them 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 Ghostscript——see _g_s(1).

     FontForge converts most outline font formats.  Here’s how we’d set  up  Ro‐
     boto Slab Serif for use with _g_r_o_f_f.

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

     _f_o_n_t_f_o_r_g_e  and _a_f_m_t_o_d_i_t may produce warnings depending on font file attrib‐
     utes.  Test the font as follows.

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

     Once you’re satisfied that the font works, you may  want  to  generate  any
     available  related  styles  (for  instance,  Roboto  Slab  also has “Bold”,
     “Light”, and “Thin” styles) and set up _G_R_O_F_F___F_O_N_T___P_A_T_H in your  environment
     to  include the directory you keep the generated fonts in so that you don’t
     have to use the --FF option.

FFoonntt iinnssttaallllaattiioonn
     For your convenience, _g_r_o_f_f offers _i_n_s_t_a_l_l_-_f_o_n_t_._b_a_s_h, a shell  script  that
     interactively assists the configuration of fonts for use with the GNU _t_r_o_f_f
     formatter and the _g_r_o_p_s output driver.  See section “Files” below.

     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 PostScript
        Type 1 font in PFA format or a PostScript Type 42 font, together with an
        AFM file.  A PFA file begins as follows.
               %!PS-AdobeFont-1.0:
        A PFB file contains this string as well, preceded by  some  non‐printing
        bytes.  If your font is in PFB format, use _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 TrueType
        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,  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_s subdirectory in
        the search path that _g_r_o_f_f uses for device and font  file  descriptions.
        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  de‐
        scription 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 em‐
        bedding  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 necessarily 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 >hello.ps
               see hello.pdf

OOlldd ffoonnttss
     _g_r_o_f_f versions 1.19.2 and earlier contained descriptions of a slightly dif‐
     ferent set of the base 35 PostScript level 2 fonts defined by  Adobe.   The
     older  set  has 314 glyphs and a larger set of kerning pairs; the newer one
     has only 229 glyphs, but includes the Euro sign.  For backward  compatibil‐
     ity,  these  old  font  descriptions  are also installed in the _/_u_s_r_/_s_h_a_r_e_/
     _g_r_o_f_f_/_1_._2_4_._1_/_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..2244..11//oollddffoonntt ...
     or add the directory to _g_r_o_f_f’s font and device description search path en‐
     vironment variable,
            $ GGRROOFFFF__FFOONNTT__PPAATTHH==//uussrr//sshhaarree//ggrrooffff//11..2244..11//oollddffoonntt \\
                   ggrrooffff --TTppss ...
     when the command runs.

EExxiitt ssttaattuuss
     _g_r_o_p_s exits with status 00 on successful operation, status 22 if the  program
     cannot  interpret its command‐line arguments, and status 11 if it encounters
     an error during operation.

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

     _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‐read‐
            able 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_4_._1_/_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_4_._1_/_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_4_._1_/_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 document
            (or download to the device).

     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_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_4_._1_/_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_4_._1_/_t_m_a_c_/_p_s_._t_m_a_c
            defines macros for use with the ppss output device.  It  is  automati‐
            cally loaded by _t_r_o_f_f_r_c when the ppss output device is selected.

     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_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_4_._1_/_t_m_a_c_/_p_s_o_l_d_._t_m_a_c
            provides replacement glyphs for text fonts that lack complete cover‐
            age 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.

     _/_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_/_i_n_s_t_a_l_l_-_f_o_n_t_._b_a_s_h
            This script, contributed by _m_o_m macro package author Peter Schaffter
            and long available at his web site,  assists  with  making  TrueType
            (_._t_t_f),  OpenType  (_._o_t_f),  and PostScript Type 1 (_._p_f_a, _._p_f_b) fonts
            available to _g_r_o_f_f.

            Change to its directory and run “bbaasshh iinnssttaallll--ffoonntt..bbaasshh  --HH”  for  a
            man page‐like description of its features and operation.

     _g_r_o_p_s  creates  temporary  files  using  the  template  “_g_r_o_p_sXXXXXX”;  see
     _g_r_o_f_f(1).

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.24.1                       2026‐04‐22                           _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 [--ddffhhoott] [--ii|--rr] [--FF _f_o_n_t_‐_d_i_r_e_c_t_o_r_y] [_f_i_l_e ...]

     ggrroottttyy --cc [--bbBBddffhhoouuUU] [--FF _f_o_n_t_‐_d_i_r_e_c_t_o_r_y] [_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  video
     terminal  emulators.  Normally, _g_r_o_t_t_y is invoked by _g_r_o_f_f(1) when the lat‐
     ter is given one of the “--TT aasscciiii”, “--TT llaattiinn11”, or “--TT uuttff88” options.  (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_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.   It  writes  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,  underline,
     reverse video [“negative image”] and colors).  Devices supporting SGR 30–37
     and  40–47  sequences  can  view _r_o_f_f documents using eight different back‐
     ground and foreground colors.  _g_r_o_t_t_y’s _t_t_y_._t_m_a_c  file  defines  the  eight
     color  names  of ISO 6429: black, white, red, green, blue, yellow, magenta,
     and cyan.  Unrecognized colors map to the default color, the value of which
     depends on the settings of the terminal.  Also see the --tt option below.

     By default, _g_r_o_t_t_y produces OSC 8 hyperlinks on devices employing  SGR  es‐
     cape sequences.

     In  accord  with long‐standing practice and terminals (emulators) that lack
     support for slanted (oblique or  italic)  faces,  _g_r_o_t_t_y  marks  italicized
     character  cells  with underlines instead 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  in‐
     structed 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 required 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 paper
     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 sequences are
     not emitted; bold, italic, and underlining character  attributes  are  thus
     not  manipulated.  Instead, _g_r_o_t_t_y overstrikes, representing a bold charac‐
     ter _c with the sequence “_c BACKSPACE _c”, an italic character _c with the se‐
     quence “__ 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  emulator)
     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) also are  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 requiring  options.   In  con‐
     trast  to  the  terminal output drivers of some other _r_o_f_f implementations,
     _g_r_o_t_t_y never outputs reverse line feeds.  You need not  filter  its  output
     through _c_o_l(1) to remove them.

   DDeevviiccee eexxtteennssiioonn ccoommmmaannddss
     _g_r_o_t_t_y  recognizes a device extension command produced by the _g_r_o_f_f request
     ddeevviiccee or _r_o_f_f \\XX escape sequence.

     \\XX''ttttyy:: lliinnkk [_u_r_i [_k_e_y==_v_a_l_u_e] ...]''
            Embed a hyperlink using the OSC 8 terminal escape sequence.   Speci‐
            fying  _u_r_i  starts hyperlinked text, and omitting it ends the hyper‐
            link.  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”  direc‐
     tive,  _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, _g_r_o_t_t_y treats the font as
     slanted; if the 02 bit is set, _g_r_o_t_t_y treats the font as bold.

   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.

     _g_r_o_t_t_y shares a naming scheme for East  Asian  typefaces  with  _g_r_o_h_t_m_l(1),
     _g_r_o_p_d_f(1), and _g_r_o_p_s(1).

            CCSSHH    Simplified Chinese, Hei style
            CCSSSS    Simplified Chinese, Song style
            CCTTHH    Traditional Chinese, Hei style
            CCTTSS    Traditional Chinese, Song style
            JJPPGG    Japanese, Gothic style
            JJPPMM    Japanese, Mincho style
            KKOOGG    Korean, Gothic style
            KKOOMM    Korean, Mincho style

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

     --bb      Suppress the use of overstriking for bold characters in legacy out‐
             put format.

     --BB      Use  only  overstriking for bold‐italic characters in legacy output
             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 drawing commands in the input.  By default, _g_r_o_t_t_y ren‐
             ders “DD ll” commands that have at least one zero  argument  (and  so
             are  either horizontal or vertical) using Unicode box drawing char‐
             acters (for the uuttff88 device) or the --, ||, and ++ characters (for all
             other devices).  _g_r_o_t_t_y handles “DD pp”  commands  that  consist  en‐
             tirely   of   horizontal   and   vertical   lines  similarly.   See
             _g_r_o_f_f___o_u_t(5).

     --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 de‐
             vice description files; _n_a_m_e describes the output device’s  charac‐
             ter encoding, one of aasscciiii, llaattiinn11, or uuttff88.

     --hh      Use  literal horizontal tab characters in the output.  Tabs are as‐
             sumed to be set every 8 columns.

     --ii      Render fonts marked as slanted 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 char‐
             acters when the legacy output format is in use; see options --bb  and
             --uu).

     --rr      Render  fonts  marked as slanted with the SGR attribute for reverse
             video text rather than underlined text.  Ignored if  --cc  or  --ii  is
             also specified.

     --tt      Assume  that  the  output  device supports SGR 38 and 48 escape se‐
             quences, which permit specification of  character  cell  foreground
             and  background colors in the RGB color space with 8 bits per chan‐
             nel.

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

EExxiitt ssttaattuuss
     _g_r_o_t_t_y exits with status 00 on successful operation, status 22 if the program
     cannot interpret its command‐line arguments, and status 11 if it  encounters
     an error during operation.

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

     _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 op‐
            tion were specified; see subsection “Legacy output format” above.

FFiilleess
     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_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_4_._1_/_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_4_._1_/_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_4_._1_/_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_4_._1_/_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_4_._1_/_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_4_._1_/_t_m_a_c_/_t_t_y_._t_m_a_c
            defines macros for use with the aasscciiii, llaattiinn11, and uuttff88  output  de‐
            vices.  It is automatically loaded by _t_r_o_f_f_r_c when any of those out‐
            put devices is selected.

     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_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 horizontal or vertical motions smaller than a
        character cell.

     •  Drawing commands producing anything other than horizontal  and  vertical
        lines are not supported.

     •  Color  handling differs from other output drivers.  The GNU _t_r_o_f_f output
        commands produced by requests and escape sequences that set  the  stroke
        and fill colors instead set the foreground and background character cell
        colors, respectively.

     The  commands  generated by the \\ll and \\LL escape sequences on one hand, and
     the \\DD''ll'' line‐drawing escape sequence on the other, make different compro‐
     mises due to the first two factors.  Specifically, (1) \\ll draws  horizontal
     lines  with  underscore  characters; \\DD''ll'' uses ACS or Unicode line‐drawing
     characters if possible, and hyphen‐minus signs if  not.   (2)  \\DD''ll''  draws
     vertical  lines an extra character cell high, and horizontal lines an extra
     cell to the right.  _g_r_o_t_t_y does this to detect intersecting lines  so  that
     it  can replace them with glyphs of appropriate appearance (like “+”).  Ob‐
     serve the difference below.

     The input

            Hello,\L'1v'
            world.\l'1n'
            .sp 2v
            Hello,\D'l 0 1v'
            world.\D'l 1n 0'
            .pl \n(nlu \" truncate page for convenience

     rendered with “nnrrooffff --TT aasscciiii” produces the following output.

            Hello,
                  | world._

            Hello,|
                  |world.--

EExxaammpplleess
     The following _g_r_o_f_f document exercises several features  for  which  output
     device  support  varies:  (1)  bold  style;  (2)  italic (underline) style;
     (3) bold‐italic style; (4) character composition by overstriking  (“coöper‐
     ate”);  (5)  foreground color; (6) background color; and (7) horizontal and
     vertical line drawing.

            You might see \f[B]bold\f[] and \f[I]italic\f[].
            Some people see \f[BI]both at once\f[].
            If the output device does (not) co\z\[ad]operate,
            you might see \m[red]red\m[].
            Black on cyan can have a \M[cyan]\m[black]prominent\m[]\M[]
            \D'l 1i 0'\D'l 0 2i'\D'l 1i 0' look.
            .\" If in nroff mode, end page now.
            .if n .pl \n[nl]u

     Given the foregoing input, compare and contrast the output of  the  follow‐
     ing.

            $ 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 document in‐
     cludes a normative description of SGR escape sequences.

     “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.24.1                       2026‐04‐22                          _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 _t_r_o_f_f output 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 --vv
     ggxxddiittvviieeww --vveerrssiioonn
     ggxxddiittvviieeww ----vveerrssiioonn

DDeessccrriippttiioonn
     _g_x_d_i_t_v_i_e_w  renders  the output of GNU _t_r_o_f_f to an X11 display.  It uses the
     standard X11 fonts, which are rendered by the X server.

     The output of _t_r_o_f_f(1) is in a  page  description  language  documented  in
     _g_r_o_f_f___o_u_t(5).   Normally,  users  do  not  observe  this output because the
     _g_r_o_f_f(1) wrapper automatically runs  an  output  driver  to  interpret  it;
     _g_r_o_f_f’s  --ZZ option leaves it on the standard output stream instead.  It can
     be viewed by explicitly 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.
     GNU _t_r_o_f_f’s page description language 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 qual‐
     ity 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 _t_r_o_f_f’s --TT option, 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, _t_r_o_f_f generates output for this device and calls _g_x_d_i_t_v_i_e_w automati‐
     cally 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    Collect a page number from a dialog box and render it.

     PPrriinntt          Collect a command from a dialog box  and  use  it  to  print
                    _t_r_o_f_f  output.   The  default command initially displayed is
                    controlled by the pprriinnttCCoommmmaanndd application resource, and  by
                    the --pprriinnttCCoommmmaanndd option.

     OOppeenn           Collect  a  file  name from a dialog box and render it.  The
                    named file should contain _t_r_o_f_f output.  If  the  file  name
                    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  PPrreevviioouuss‐‐
     PPaaggee action.  The _p key with any modifier (Shift, Control, Alt, or Meta) is
     bound  to  the  PPrriinntt 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 cur‐
     rent file, and redisplays the current page; if the current file is  a  com‐
     mand, the command will be re‐executed.  Vertical scrolling can be done with
     the  _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 basic 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: the _g_r_o_f_f font name is first, and
            the XLFD (X Logical Font Description) second.  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 indented
     below.

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

OOppttiioonnss
     --hheellpp and ----hheellpp display a usage message, while --vv, --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 rendered  _t_r_o_f_f  output  can  take  a  per‐
            ceiptible  amount of time, this option causes the server to save the
            window contents so that when it is scrolled around the viewport, the
            window is painted from contents saved in  backing  store.   _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
            _t_r_o_f_f output file will be displayed at a resolution of _r_e_s dots  per
            inch, unless the _D_E_S_C file contains the XX1111 directive, 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 file name displayed in the dialog box for the OOppeenn  menu
            entry  will be _s_t_r_i_n_g.  This can be either a file name, 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  surrounding
            the window.

     --ffgg _c_o_l_o_r
            This option specifies the color to use for displaying text.  The de‐
            fault 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.

EExxiitt ssttaattuuss
     _g_x_d_i_t_v_i_e_w  exits with status 00 on successful operation, and status 22 if the
     program cannot interpret its command‐line arguments.

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  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
     _/_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_4_._1_/_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_4_._1_/_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_4_._1_/_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_4_._1_/_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_4_._1_/_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_4_._1_/_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_4_._1_/_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_4_._1_/_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_4_._1_/_t_m_a_c_/_X_._t_m_a_c
            defines macros for use with the XX110000, XX110000--1122, XX7755, and XX7755--1122  out‐
            put  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_4_._1_/_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‐independent
            output targeting the ppss output device.  It is  automatically  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 dis‐
     play 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  (Berkeley),  Mal‐
     colm  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.24.1                       2026‐04‐22                       _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 and 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 included, 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.

     _h_p_f_t_o_d_i_t writes output 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 “--”, _h_p_f_t_o_d_i_t writes to the standard
     output stream.  The --ii option directs _h_p_f_t_o_d_i_t to automatically generate an
     italic correction, a left italic correction, and a subscript correction for
     each glyph.  See _g_r_o_f_f___f_o_n_t(5).

OOppttiioonnss
     ----hheellpp displays a usage message, while --vv and ----vveerrssiioonn show version infor‐
     mation; 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 Private Use Area (0xE000–0xF8FF)
            is also included as an unnamed glyph.

            This  option provides a simple means of adding Unicode‐named and un‐
            named glyphs to a font without including them in the map  file,  but
            it  affords little control over which glyphs are placed in a regular
            font and which are placed in a special font.  The  presence  or  ab‐
            sence of the --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 selec‐
            tive——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 includes the values
            of important TFM tags and a listing (by MSL number  for  Intellifont
            TFM  files or by Unicode value for TrueType TFM files) of the glyphs
            included in the TFM file.  The unit of measure “DU”  for  some  tags
            indicates  design  units; there are 8782 design units per em for In‐
            tellifont fonts, and 2048 design units per em  for  TrueType  fonts.
            Note that the accessibility of a glyph depends on its inclusion in a
            symbol  set;  some  TFM files list many glyphs but only a few symbol
            sets.

            The glyph listing includes the glyph index within the TFM file,  the
            MSL  or  Unicode  value,  and the symbol set and character code that
            will be used to print the glyph.  If _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 appear 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 ignored
            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.  The minimum value _h_p_f_t_o_d_i_t will  write  is
            zero.

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

            Also generate a left italic correction for each  glyph  equal  to  _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,  affecting
            the  order  in  which  HP  symbol  sets are searched for each glyph.
            Without this option, the “text” sets are searched before the “mathe‐
            matical” symbol sets.  With it, the search order is reversed.

EExxiitt ssttaattuuss
     _h_p_f_t_o_d_i_t exits with status 00 on successful operation, status 22 if the  pro‐
     gram  cannot  interpret  its command‐line arguments, and status 11 if it en‐
     counters an error during operation.

FFiilleess
     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_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_4_._1_/_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_4_._1_/_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; it can be used to regener‐
            ate them in the event the TFM files are updated.

     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_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 met‐
            rics 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_4_._1_/_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_4_._1_/_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_4_._1_/_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_4_._1_/_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.24.1                       2026‐04‐22                        _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 of 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 of the bibliographic databases in each _f_i_l_e
     to speed their access by _r_e_f_e_r(1), _l_o_o_k_b_i_b(1), and _l_k_b_i_b(1).   The  program
     writes  to  a  temporary  file that it later renames to file_._i.  If no _f_i_l_e
     operands are present and no --oo option is given,  _i_n_d_x_b_i_b  names  the  index
     _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.

     _i_n_d_x_b_i_b  stores the values set by the --cc, --ll, --nn, and --tt options in the in‐
     dex: programs that search the index interpret them, discarding and truncat‐
     ing keys appropriately, and using the original  keys  to  verify  that  any
     record found using the index actually contains the keys.  This means that a
     user  of an index need not know whether these options were used in the cre‐
     ation of the index, provided that not all the keys to be searched for would
     have been discarded during indexing and that the user supplies at least the
     part of each key that would have remained after being truncated during  in‐
     dexing.   _i_n_d_x_b_i_b  also  stores the value set by the --ii option in the index
     for use in verifying records found using it.

OOppttiioonnss
     ----hheellpp displays a usage message, while --vv and ----vveerrssiioonn show version infor‐
     mation; 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_4_._1_/_e_i_g_n.

     --dd _d_i_r  Use _d_i_r as the name of the directory to store in the index, instead
             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 option
             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  argument.
             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  minimum
             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 dis‐
             carded.

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

EExxiitt ssttaattuuss
     _i_n_d_x_b_i_b  exits  with status 00 on successful operation, status 22 if the pro‐
     gram cannot interpret its command‐line arguments, and status 11  if  it  en‐
     counters an error during operation.

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_4_._1_/_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.24.1                       2026‐04‐22                         _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 matching all keywords
     _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 vari‐
     able 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 infor‐
     mation; all exit afterward.

     --ii _s_t_r_i_n_g
            When  searching files for which no index exists, ignore the contents
            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  de‐
            fault is 6.

EExxiitt ssttaattuuss
     _l_k_b_i_b  exits with status 00 on successful operation, status 22 if the program
     cannot interpret its command‐line arguments, and status 11 if it  encounters
     an error during operation.

EEnnvviirroonnmmeenntt
     _R_E_F_E_R  Assign this variable a file name to override the 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.24.1                       2026‐04‐22                           _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 interactively

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  standard
     input  stream is not a terminal), reads from the standard input a line con‐
     taining 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 infor‐
     mation; all exit afterward.

     --ii _s_t_r_i_n_g
            When  searching files for which no index exists, ignore the contents
            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  de‐
            fault is 6.

EExxiitt ssttaattuuss
     _l_o_o_k_b_i_b  exits  with status 00 on successful operation, status 22 if the pro‐
     gram cannot interpret its command‐line arguments, and status 11  if  it  en‐
     counters an error during operation.

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.24.1                       2026‐04‐22                         _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 - reference‐ and PostScript inclusion‐handling  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 internal references in
     _m_m  documents;  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 reference and index files with  their
     corresponding  entries,  and then without to produce the document.  It also
     handles the inclusion of PostScript images with the 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 information;
     both exit afterward.

     --xx     Create or update the reference list file and exit.

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 example,
     Windows uses a semicolon instead.

     _G_R_O_F_F___B_I_N___P_A_T_H
            Locate _g_r_o_f_f commands in these directories,  followed  by  those  in
            _P_A_T_H.   If  not set, the installation directory of GNU _r_o_f_f executa‐
            bles, _/_u_s_r_/_b_i_n, is searched before _P_A_T_H.

EExxiitt ssttaattuuss
     _m_m_r_o_f_f exits with status 00 if the ----hheellpp or ----vveerrssiioonn options  were  speci‐
     fied,  or  if  --xx was specified and the program successfully created or up‐
     dated the reference list file.  It exits with status 11 if it was unable  to
     create necessary files.  Otherwise, it exits with the status of _g_r_o_f_f.

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.24.1                       2026‐04‐22                          _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.

     GNU _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.24.1                       2026‐04‐22                            _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 terminal (“TTY”) devices

SSyynnooppssiiss
     nnrrooffff [--aabbccCCEEhhiikkppRRSSttUUVVzzZZ] [--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_‐_i_n_p_u_t_‐
           _e_n_c_o_d_i_n_g] [--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] [--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 [_o_t_h_e_r_‐_n_r_o_f_f_‐_o_p_t_i_o_n ...]
     nnrrooffff ----vveerrssiioonn [_o_t_h_e_r_‐_n_r_o_f_f_‐_o_p_t_i_o_n ...]

DDeessccrriippttiioonn
     _n_r_o_f_f  formats  documents  written in the _g_r_o_f_f(7) language for typewriter‐
     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 ter‐
     minal output driver, which needs to know the character encoding scheme used
     by the device.  Consequently, acceptable arguments to  the  --TT  option  are
     aasscciiii,   llaattiinn11,  and  uuttff88;  any  others  are  ignored.   If  neither  the
     _G_R_O_F_F___T_Y_P_E_S_E_T_T_E_R environment variable nor the --TT command‐line option (which
     overrides the environment variable) specifies a (valid) device, _n_r_o_f_f  con‐
     sults  the  locale  to select an appropriate output device.  It first tries
     the _l_o_c_a_l_e(1) program, then checks several locale‐related environment vari‐
     ables; see section “Environment” below.  If  all  of  the  foregoing  fail,
     _n_r_o_f_f assumes “--TT aasscciiii”.

     The  --aa, --bb, --cc, --CC, --dd, --EE, --ii, --II, --mm, --MM, --nn, --oo, --rr, --UU, --ww, --WW, and --zz
     options have the effects described in _t_r_o_f_f(1).  --cc and --hh  imply  “--PP  --cc”
     and “--PP --hh”, respectively; --cc is also meaningful to _t_r_o_f_f itself.  Further,
     GNU  _n_r_o_f_f  ignores  the AT&T _n_r_o_f_f options --ee, --qq, and --ss.  _g_r_o_f_f(1) docu‐
     ments options --DD, --kk, --KK, --pp, --PP, --RR, --tt, --SS, and --ZZ.  --VV causes  _n_r_o_f_f  to
     display  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  status  22 if there was a problem parsing its arguments,
     with status 00 if any of the options --VV, --vv, ----vveerrssiioonn, or ----hheellpp were spec‐
     ified, 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 example,
     Windows uses a semicolon instead.

     _G_R_O_F_F___B_I_N___P_A_T_H
            Locate _g_r_o_f_f commands in these directories,  followed  by  those  in
            _P_A_T_H.   If  not set, the installation directory of GNU _r_o_f_f executa‐
            bles, _/_u_s_r_/_b_i_n, is searched before _P_A_T_H.

     _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 in‐
            valid.

FFiilleess
     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_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 def‐
            initions more poorly optically approximate typeset output than those
            of _t_t_y_._t_m_a_c in favor of communicating semantic  information.   _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 options 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.24.1                       2026‐04‐22                           _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 [----rrooffff] [--TTppddff] [_g_r_o_f_f_‐_o_p_t_i_o_n_s] [_f_i_l_e ...]

     ppddffmmoomm [----rrooffff] --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.

     If the ----rrooffff option is used, the wrapper can be used with  macro  packages
     other  than  _g_r_o_f_f___m_o_m(7).   This is also true if the wrapper is renamed or
     linked as a pseudonym; for example, creating a _p_d_f_m_s link pointing  to  the
     _p_d_f_m_o_m executable makes a wrapper for producing PDFs with the _m_s package.

     _p_d_f_m_o_m  prints to the standard output, so output must usually be redirected
     to a destination file.  The size of the final PDF can be reduced by  piping
     the output through _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,  pro‐
     cessing  is  passed  over to _p_d_f_r_o_f_f, which uses _g_r_o_f_f’s PostScript 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 op‐
     tions 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 implied 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 in‐
     formation and exits.  Using the ----hheellpp option displays a usage message  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.24.1                       2026‐04‐22                          _p_d_f_m_o_m(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 sup‐
     plied 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.24.1                       2026‐04‐22                         _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 formatting
     system.  _p_i_c is a _t_r_o_f_f(1) preprocessor that translates descriptions of di‐
     agrammatic pictures embedded in _r_o_f_f(7) or TeX input into the language  un‐
     derstood  by  TeX or _t_r_o_f_f.  It copies each _f_i_l_e’s contents to the standard
     output stream, translating each _p_i_c_t_u_r_e between lines starting with ..PPSS and
     any of ..PPEE, ..PPFF, or ..PPYY.  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 present,
     or if _f_i_l_e is “--”, _p_i_c reads the standard input stream.

     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 horizontally center each picture.

     GNU _p_i_c supports PPYY as a synonym of PPFF to work around a name  space  colli‐
     sion  with  the _m_m macro package, which defines PPFF as a page footer manage‐
     ment macro.  Use PPFF preferentially unless a similar problem faces your doc‐
     ument.

OOppttiioonnss
     ----hheellpp displays a usage message, while --vv and ----vveerrssiioonn show version infor‐
     mation; 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 \\.   GNU  _p_i_c  gives  a
            line  beginning with ..ppss special treatment: it takes an optional in‐
            teger argument specifying the line thickness (pen  size)  in  milli‐
            inches, a missing argument restores the previous line thickness, and
            the  default  line  thickness  is 8 milliinches.  The line thickness
            thus specified takes effect only when a non‐negative line  thickness
            has  not been specified by use of the tthhiicckknneessss attribute or by set‐
            ting the lliinneetthhiicckk variable.

     --CC     Recognize ..PPSS, ..PPEE, ..PPFF, and ..PPYY even when followed by  a  character
            other than space or newline.

     --nn     Don’t  use  _g_r_o_f_f extensions to the _t_r_o_f_f drawing commands.  Specify
            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     Enable safer mode and ignore any subsequent  --UU  option.   In  _s_a_f_e_r
            _m_o_d_e_, _p_i_c ignores sshh commands, which can be useful when operating on
            untrustworthy input.  _p_i_c operates in safer mode by default.

     --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 option is  unneces‐
             sary  in  GNU _p_i_c because the _t_r_o_f_f it generates is device‐indepen‐
             dent.

UUssaaggee
     This section primarily discusses the differences between GNU  _p_i_c  and  the
     Eighth  Edition 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 today for
     lending its name to a group of \\ssppeecciiaall commands it produced for TeX.)

     Lines beginning with \\ are passed through unaltered except for a  %%  suffix
     to avoid unwanted spaces.  Use this feature to change fonts or the value of
     \\bbaasseelliinneesskkiipp.   Other applications may produce undesirable results; use at
     your own risk.  By default, lines beginning with a dot are not treated spe‐
     cially——but see the --cc option.

     In TeX mode, _p_i_c defines 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  produces  slightly  more vertical space above the picture than
     below it;
            \centerline{\raise 1em\box\graph}
     would avoid this.  To give the vbox a positive height and a depth  of  zero
     (as  used by LaTeX’s _g_r_a_p_h_i_c_s_._s_t_y, for example), define the following 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  synopses
     as  braces {{ }}.  Nesting of braces is supported.  Any other characters (ex‐
     cept a space, tab, or newline) may be used as  alternative  delimiters,  in
     which  case  the members of a given pair must be identical.  GNU _p_i_c recog‐
     nizes double‐quoted strings within delimiters of either kind; such  strings
     may contain 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.  _e_x_p_r_3 can be negative, in which
            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.  A ** prefix on _v_a_r_i_a_b_l_e multiplies it by _e_x_p_r_3 (which must be
            greater than zero) at each iteration rather  than  incrementing  it.
            If  the  range constraint on _e_x_p_r_3 isn’t met, the loop does not exe‐
            cute.  _X can be any character not 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 in _i_f_‐_t_r_u_e.  _Y can be any charac‐
            ter not in _i_f_‐_f_a_l_s_e.

     pprriinntt _a_r_g ...
            Catenate  and  write arguments to the standard error stream followed
            by a newline.  Each _a_r_g must be an expression, a position, or  text.
            This feature is useful for debugging.

     ccoommmmaanndd _a_r_g ...
            Catenate  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 formatter.  Thus,
                   .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 via _s_y_s_t_e_m(3).  Ignored if --UU option not
            specified.

     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, GNU _p_i_c reads lines only  un‐
            til encountering one beginning with _w_o_r_d; which it then discards.  _X
            can be any character not 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 character is inter‐
            preted 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 variables  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 val‐
            ues times the new value of ssccaallee.

     pplloott _e_x_p_r ["_t_e_x_t"]
            Create a text object by using _t_e_x_t as a format string for _s_p_r_i_n_t_f(3)
            with an argument of _e_x_p_r.  If _t_e_x_t is omitted, ""%%gg"" is implied.  At‐
            tributes can be specified in the same way as for a normal  text  ob‐
            ject.  _C_a_u_t_i_o_n_: be very careful that you specify an appropriate for‐
            mat string in _t_e_x_t_; _p_i_c’s validation of it is limited.  pplloott is dep‐
            recated in favour of sspprriinnttff.

     _v_a_r ::== _e_x_p_r
            Update  an existing variable.  _v_a_r must already be defined, and _e_x_p_r
            is assigned to _v_a_r without creating a variable local to the  current
            block.   (By  contrast,  == 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 equivalent to
     “_d_i_r  _e_x_p_r”,  where  _d_i_r  is the current direction.  For example, “lliinnee 22ii”
     draws a line 2 inches long in the current  direction.   The  ‘i’  (or  ‘I’)
     character  is ignored; to use another measurement unit, set the ssccaallee vari‐
     able to an appropriate value.

     The maximum width and height of the picture are taken  from  the  variables
     mmaaxxppsswwiidd  and  mmaaxxppsshhtt.   Initially,  these have values 8.5 and 11, respec‐
     tively.

     Scientific notation is allowed for numbers, as with “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 nested.  For example,
            [A: [B: [C: box ]]] with .A.B.C.sw at 1,2
            circle at last [].A.B.C
     is acceptable.

     Arcs  have  compass  points  determined by the circle of which the arc is a
     part.

     Circles, ellipses, and arcs can be dotted or dashed.  In TeX mode,  splines
     can be dotted or dashed as well.

     Boxes  can have rounded corners.  The 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, generalizing them from rectangles  to  paral‐
     lelograms.   The  xxssllaanntteedd and yyssllaanntteedd attributes specify the _x and _y off‐
     sets of the box’s upper right corner from its default position.

     The ..PPSS line accepts a second argument specifying a maximum height for  the
     picture.  If a width of zero is specified, it is ignored when computing the
     scaling  factor  for  the  picture.  GNU _p_i_c always scales a picture by the
     same amount vertically and horizontally.  This differs from  DWB  2.0  _p_i_c,
     which may change the picture’s aspect ratio if a height is specified.

     Each  text  object has an associated invisible box that determines its com‐
     pass points and implicit motion.  The dimensions of the box are taken  from
     its  width  and height attributes.  If the width attribute is not supplied,
     the value of tteexxttwwiidd is assumed.  If the height attribute is not  supplied,
     the  height  defaults to the number of text strings associated with the ob‐
     ject times tteexxtthhtt.  Initially, tteexxttwwiidd and tteexxtthhtt have values of 0.

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

            sspprriinnttff((""_f_o_r_m_a_t"",, _a_r_g,, ...))

     can  be  used instead; it transforms its arguments per _f_o_r_m_a_t, which should
     be a string as described in _p_r_i_n_t_f(3), and appropriate to the  quantity  of
     arguments  supplied.  GNU _p_i_c supports only the conversion specifiers ee, EE,
     ff, gg, GG, and %%, modifiers “##”, “--”, “++”, and “ ” [space]), a minimum  field
     width, and an optional precision.

     The  thickness  of  the  lines  used  to  draw objects is controlled by the
     lliinneetthhiicckk variable, which is measured in points.  A  negative  value  indi‐
     cates  the default thickness.  In TeX output mode when the --cc option is not
     given, this means 8 milliinches.  In _t_r_o_f_f and TeX --cc output modes, the de‐
     fault thickness corresponds to the type size.  (Thus, if the type  size  is
     10 points, a line is 10 points thick.)  A lliinneetthhiicckk value of zero draws the
     thinnest   possible  line  supported  by  the  output  device.   Initially,
     lliinneetthhiicckk has a value of -1.  A tthhiicckk[nneessss] attribute  is  also  available.
     For example, “cciirrccllee tthhiicckknneessss 11..55” draws a circle with a line 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], which takes
     an optional expression argument with a value between 0 and 1;  0  fills  it
     with  white, 1 with black, and values in between with a proportionally gray
     shade.  A value greater than 1 is interpreted as the shade of gray that  is
     being  used for text and lines.  Normally this is black, but output devices
     may provide a mechanism for changing this.  Without an argument, the  value
     of  the  variable  ffiillllvvaall is used.  Initially, ffiillllvvaall has a value of 0.5.
     The iinnvviissiibbllee attribute does not affect the filling of objects.  Text asso‐
     ciated with a filled object is added after the object is  filled,  so  that
     the text is not obscured by the filling.

     Additional modifiers are available to draw colored objects: 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 re‐
     quest (see _g_r_o_f_f(7)).  _p_i_c assumes at the beginning of  each  picture  that
     the stroke and fill colors are set to the device defaults.

     To change the name of the vbox in TeX mode, set the pseudo‐variable ffiiggnnaammee
     (which is actually a specially parsed command) within a picture.  For exam‐
     ple,
            .PS
            figname = foobar;
            circle "dig here";
            .PE
     makes the picture available in the box \\ffoooobbaarr.

     Arrow  heads are drawn as solid triangles if the variable aarrrroowwhheeaadd is non‐
     zero and either TeX mode is enabled or the --nn option  is  not  used.   Ini‐
     tially,  aarrrroowwhheeaadd  has  a value of 1.  Solid arrow heads are always filled
     with the current outline (stroke) color.

     The _t_r_o_f_f output of _p_i_c is device‐independent.  The --TT option is  therefore
     redundant.   Except where noted, all measurements and dimensions use inches
     implicitly; they are never interpreted as _t_r_o_f_f basic units.

     Objects can have an aalliiggnneedd attribute, but it  is  supported  only  by  the
     _g_r_o_p_s(1) and _g_r_o_p_d_f(1) output drivers.  Any text associated with an aalliiggnneedd
     object  is rotated about the object’s center such that it is oriented along
     a line connecting the start and end points of the object.  aalliiggnneedd  has  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 sin‐
     gle token: no space is allowed between the apostrophe and the  “tthh”.   Con‐
     sider the following example.

            for i = 1 to 4 do {
               box
               move right 0.5
            }
            for i = 1 to 3 do {
               arrow from `i'th box.ne to `i+1'th box.sw
            }

     Arbitrary polygons can be drawn using the ppoollyyggoonn keyword followed by a se‐
     ries  of  _n-1 line segments, where _n is the number of edges of the polygon.
     This allows GNU _t_r_o_f_f to interpret the line segments as a  complete  object
     such  that  the  ffiilllleedd  and sshhaaddeedd attributes may be used.  The last user‐
     specified line segment determines the polygon’s final drawing position  and
     direction.  For example, draw and fill a triangle with the following.

            polygon up 1 then right 1 down 0.5 fill 0.5

     Two  reference  point  suffixes  permit the positioning of drawing elements
     relative to a polygon.  “..vveerrtteexx _e_x_p_r” locates the vertices, and “..mmiiddppooiinntt
     _e_x_p_r” for locating the midpoints of edges.  GNU ppiicc  numbers  vertices  and
     midpoints in drawing order starting from 11 ..  You can abbreviate ..vveerrtteexx as
     ..vv or ..vveerr, and ..mmiiddppooiinntt as ..mmiidd.

     For example,

            arrow down
            polygon up 0.5 right 1 \
            then down 0.5 right 1 \
            then down 0.5 left 1 \
            with .v2 at last line.end
            arrow down from last polygon.v4

     creates and correctly places a flowchart decision diamond.

     ..cceenntteerr  (..cc) is also available, but compass points do not work as expected
     and should not be used with polygons.

   CCoonnvveerrttiinngg _pp_ii_cc ttoo ootthheerr iimmaaggee ffoorrmmaattss
     To create a stand‐alone graphics file from a _p_i_c file,  first  compose  the
     picture.   Bracket  your  _p_i_c code with ..PPSS and ..PPEE tokens.  _g_r_o_f_f requests
     that don’t produce formatted output may precede ..PPSS, but  format  no  text,
     not  even  any injected by a macro package, which may include a page number
     even on the first page, as _m_m does by default.  Consider  writing  a  “raw”
     _r_o_f_f document that uses no macro package.

     Next,  convert  the _r_o_f_f/_p_i_c input into the desired format.  _g_r_o_f_f distrib‐
     utes a simple utility, _p_i_c_2_g_r_a_p_h(1), for this purpose.  Other possibilities
     exist, particularly if you first transform  your  picture  into  PostScript
     format  with “ggrrooffff --TT ppss”.  However, such a PostScript file lacks bounding
     box information; _r_o_f_f formatters produce page‐sized output.  Several  tools
     with  names beginning “psto” or “ps2” exist that can infer the bounding box
     and perform a format conversion.  One of these  is  the  PostScript  inter‐
     preter  Ghostscript  (_g_s(1)),  which  exposes  format  converters  via  its
     --ssDDEEVVIICCEE== option.  “ggss ----hheellpp” lists available devices.

     Alternatively, produce a PDF with “ggrrooffff --TT  ppddff”;  _g_r_o_p_d_f(1)’s  --pp  option
     sets the MediaBox of the file.

     The Encapsulated PostScript File (EPS) format is still sometimes seen.  The
     aforementioned  Ghostscript offers _p_s_2_e_p_s_i(1), and a standalone package and
     command _p_s_2_e_p_s(1) is also available.

     For raster image formats, use _p_s_t_o_p_n_m(1); the resulting _p_n_m(5) file can  be
     then converted to virtually any image format using the _n_e_t_p_b_m tools.

     GNU  _p_l_o_t_u_t_i_l_s  offers  a _p_i_c_2_p_l_o_t(1) utility for converting _p_i_c input to a
     wide variety of other image formats, including SVG.

EExxiitt ssttaattuuss
     _p_i_c exits with status 00 on successful operation, status 22  if  the  program
     cannot  interpret its command‐line arguments, and status 11 if it encounters
     an error during operation.

FFiilleess
     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_t_m_a_c_/_p_i_c_._t_m_a_c
            offers simple definitions of the PPSS, PPEE, PPFF, and PPYY macros.  Load it
            with the mmssoo request when eschewing a full‐service macro package, or
            using one that doesn’t supply its own definitions for them.

CCaavveeaattss
     The spacing of dots and dashes in broken lines scales with other  graphics,
     and is configurable.  For example,

            line from 0,0 to 100,0 dotted 5

     spaces  the dots in a dotted line 5 units apart.  The spacing of dashes can
     be set the same way.  The ddaasshhwwiidd variable sets the length of dashes.

BBuuggss
     Characters that are invalid as input to GNU _t_r_o_f_f (see  the  _g_r_o_f_f  Texinfo
     manual or _g_r_o_f_f___c_h_a_r(7) for a list) are rejected even in TeX mode.

     Research  Tenth  Edition  Unix _p_i_c’s ffiillllvvaall interprets 0 as black and 1 as
     white, incompatibly with GNU _p_i_c.

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,  to‐
            gether with its source, _p_i_c_._m_s, is part of the _g_r_o_f_f distribution.

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

     _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.24.1                       2026‐04‐22                             _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 im‐
     age 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 to generate images of mathematical formulae.

     The  input  PIC  code  should  _n_o_t  be wrapped with the ..PPSS and ..PPEE/..PPFF/..PPYY
     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 smallest
     possible bounding box that contains all the black pixels.

OOppttiioonnss
     ----hheellpp displays a usage message, while --vv and ----vveerrssiioonn show version infor‐
     mation; 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  delimit
            _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 ac‐
            cepted 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 ar‐
            bitrary 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 order shown to de‐
            termine 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.24.1                       2026‐04‐22                       _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.   Cur‐
     rently,  this means that code points in the range 0–127 in ISO 646:1991 IRV
     (US‐ASCII), ISO 8859, or Unicode remain as‐is and the  remainder  are  con‐
     verted  to  the  _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 begin‐
     ning of each _f_i_l_e, identifying it for the benefit of later processing  (in‐
     cluding 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 present, or if _f_i_l_e is “--”, _p_r_e_c_o_n_v reads the standard input stream.

     _p_r_e_c_o_n_v selects an 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, select UTF‐8,
         UTF‐16, or UTF‐32 accordingly.

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

     4.  If the input stream is seekable, and if the _u_c_h_a_r_d_e_t library is  avail‐
         able 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 ISO Latin‐1
         (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 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 lo‐
     cale appropriately.  _g_r_o_f_f also supports a _G_R_O_F_F___E_N_C_O_D_I_N_G environment vari‐
     able, which can be overridden by its --KK option.  Valid values for (or para‐
     meters to) all of these are enumerated in the lists  of  recognized  coding
     tags  in  the  next subsection, and are further influenced by _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  produce
     good  results  for  a preponderance of natural language texts, they are not
     absolutely reliable.  Heuristics can fail on inputs that are too  short  or
     don’t represent a natural language.

     Consequently,  _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  re‐
     gions 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.  Both “\"” and  “\#”  comment  forms
     are recognized, but the control (or no‐break control) character must be the
     default  and  must begin the line.  Similarly, the escape character must be
     the default.
            --**-- [...;;] 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

     Any “-dos”, “-unix”, or “-mac” suffix on a coding tag (which indicates  the
     end‐of‐line  convention used in the file) is ignored during comparison with
     the above tags.

   _ii_cc_oo_nn_vv ssuuppppoorrtt
     While _p_r_e_c_o_n_v recognizes all of the coding tags listed above, it is capable
     on its own of interpreting only two encodings: ISO Latin‐1 and  and  UTF‐8.
     ISO 646:1991 IRV (US‐ASCII) is a proper subset of both these encodings.  If
     _i_c_o_n_v(3)  support  is configured at compile time and available at run time,
     all others are passed to _i_c_o_n_v library functions, which may recognize  many
     additional  encoding  strings.   The command “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  follow‐
     ing  examples  using  the input “café” (note the “e” with an acute accent),
     which due to its short length challenges inference of the encoding used.
            printf 'caf\351\n' | LC_ALL=en_US.UTF-8 preconv
            printf 'caf\351\n' | preconv -e us-ascii
            printf 'caf\351\n' | preconv -e latin-1
     The fate of the accented “e” differs in each case.  In the first,  _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 representable character in the de‐
     clared 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.  Ex‐
     amples include files that are interpolated by preprocessors that run subse‐
     quently,  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  back‐
     slash \\, and writes special character escape sequences accordingly.

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

     --dd        Emit debugging messages to the standard error stream.

     --DD _f_b_e_n_c  Select the fallback encoding _f_b_e_n_c if all detection methods fail.

     --ee _e_n_c    Skip detection and select encoding _e_n_c; see _g_r_o_f_f’s --KK option.

     --rr        Write files “raw”; do not add ..llff requests.

EExxiitt ssttaattuuss
     _p_r_e_c_o_n_v exits with status 00 on successful operation, status 22 if  the  pro‐
     gram  cannot  interpret  its command‐line arguments, and status 11 if it en‐
     counters an error during operation.

SSeeee aallssoo
     _g_r_o_f_f(1), _i_c_o_n_v(3), _l_o_c_a_l_e(7)

groff 1.24.1                       2026‐04‐22                         _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 formatting
     system.  _r_e_f_e_r is a _t_r_o_f_f(1) preprocessor that prepares bibliographic cita‐
     tions by looking up keywords specified in a _r_o_f_f(7) input document, obviat‐
     ing the need to type such annotations, and permitting the citation style in
     formatted output to be altered independently and systematically.  It copies
     the contents of each _f_i_l_e to the standard output stream,  looking  up  each
     _c_i_t_a_t_i_o_n between lines starting with ..[[ and ..]] and replacing it with a bib‐
     liographic reference.  GNU _r_e_f_e_r furthermore interprets lines between those
     starting with ..RR11 and ..RR22 as instructions directing how citations are to be
     processed.   _r_e_f_e_r  interprets  and generates _r_o_f_f llff requests so that file
     names and line numbers in messages produced by commands that read its  out‐
     put  correctly  describe  the source document.  Normally, _r_e_f_e_r is not exe‐
     cuted directly by the user, but invoked by  specifying  the  --RR  option  to
     _g_r_o_f_f(1).   If no _f_i_l_e operands are present, or if _f_i_l_e is “--”, _r_e_f_e_r reads
     the standard input stream.

     A citation identifies a work by reference to a _b_i_b_l_i_o_g_r_a_p_h_i_c _r_e_c_o_r_d detail‐
     ing it.  Select a work from a database of records by listing keywords  that
     uniquely  identify  its  entry.   Alternatively,  a  document can specify a
     record for the work at the point its citation occurs.  A document  can  use
     either or both strategies as desired.

     For  each citation, _r_e_f_e_r produces a _m_a_r_k in the text, like a superscripted
     footnote number or “[Lesk1978a]”.  A  mark  consists  of  a  _l_a_b_e_l  between
     _b_r_a_c_k_e_t_s_.   The  mark can be separated from surrounding text and from other
     labels in various ways.  _r_e_f_e_r produces _r_o_f_f language requests usable by  a
     document or a macro package such as _m_e, _m_m, _m_o_m, or _m_s to produce a format‐
     ted  reference for each citation.  A citation’s reference can be output im‐
     mediately after it occurs (as with footnotes), or  references  may  _a_c_c_u_m_u_‐
     _l_a_t_e,  with  corresponding  output appearing later in the document (as with
     endnotes).  When references accumulate, multiple citations of the same ref‐
     erence produce a single formatted entry.

     Interpretation of lines between ..RR11 and ..RR22 tokens as preprocessor commands
     is a GNU _r_e_f_e_r extension.  Documents employing this feature  can  still  be
     processed by AT&T _r_e_f_e_r by adding the lines
            .de R1
            .ig R2
            ..
     to  the beginning of the document.  The foregoing input causes _t_r_o_f_f to ig‐
     nore everything between ..RR11 and ..RR22.  The effects of  some  _r_e_f_e_r  commands
     can  be  achieved by command‐line options; these are supported for compati‐
     bility with AT&T _r_e_f_e_r.  It is usually more convenient to use commands.

   BBiibblliiooggrraapphhiicc rreeccoorrddss
     A bibliographic record describes a referenced  work  in  sufficient  detail
     that  it  may  be cited to accepted standards of scholarly and professional
     clarity.  The record format permits annotation and extension that  a  docu‐
     ment  may  use or ignore.  A record is a plain text sequence of _f_i_e_l_d_s_, one
     per line, each consisting of a percent sign %%,  an  alphanumeric  character
     classifying  it,  one  space,  and its contents.  If a field’s contents are
     empty, the field is ignored.

     Frequently, such records are organized into a _b_i_b_l_i_o_g_r_a_p_h_i_c _d_a_t_a_b_a_s_e_,  with
     each  entry separated by blank lines or file boundaries.  This practice re‐
     lieves documents of the need to  maintain  bibliographic  data  themselves.
     The  programs _l_o_o_k_b_i_b(1) and _l_k_b_i_b(1) consult a bibliographic database, and
     _i_n_d_x_b_i_b(1) indexes one to speed retrieval from it, reducing  document  pro‐
     cessing time.  Use of these tools is optional.

     The  conventional  uses  of the bibliographic field entries are as follows.
     Within a record, fields other than %%AA and %%EE replace  previous  occurrences
     thereof.  The ordering of multiple %%AA and %%EE fields is significant.

     %%AA     names  an  author.   If  the name contains a suffix such as “Jr.” or
            “III”, it should be separated from the surname by a comma.  We  rec‐
            ommend always supplying an %%AA field or a %%QQ field.

     %%BB     records  the  title of the book within which a cited article is col‐
            lected.  See %%JJ and %%TT.

     %%CC     names the city or other place of publication.

     %%DD     indicates the date of publication.  Specify the year  in  full.   If
            the  month  is  specified, use its name rather than its number; only
            the first three letters are required.  We recommend always supplying
            a %%DD field; if the date is unknown, use “iinn pprreessss” or  “uunnkknnoowwnn”  as
            its contents.

     %%EE     names  an  editor  of  the book within which a cited article is col‐
            lected.  Where a work has editors but no authors, name  the  editors
            in  %%AA  fields  and  append  “,,  ((eedd..))” or “,, ((eeddss..))” to the last of
            these.

     %%GG     records the U.S. government ordering number,  ISBN,  DOI,  or  other
            unique identifier.

     %%II     names the publisher (issuer).

     %%JJ     records the name of the journal within which a cited article is col‐
            lected.  See %%BB and %%TT.

     %%KK     lists keywords intended to aid searches.

     %%LL     is  a  label;  typically unused in database entries, it can override
            the label format otherwise determined.

     %%NN     records the issue number of the journal within which a cited article
            is collected.

     %%OO     presents additional (“other”) information, typically placed  at  the
            end of the reference.

     %%PP     lists the page numbers of a cited work that is part of a larger col‐
            lection.  Specify a range with _m--_n.

     %%QQ     names  an  institutional author when no %%AA fields are present.  Only
            one %%QQ field is permitted.

     %%RR     is an identifier for a report, thesis, memorandum, or  other  unpub‐
            lished work.

     %%SS     records the title of a series to which the cited work belongs.

     %%TT     is the work’s title.  See %%BB and %%JJ.

     %%VV     is  the  volume  number  of the journal or book containing the cited
            work.

     %%XX     is an annotation.  By convention, it is not formatted in the  citing
            document.

     If  the obsolescent “accent strings” feature of the _m_s or _m_e macro packages
     is used, such strings should follow the character to  be  accented;  an  _m_s
     document  must  call  the  AAMM macro before using them.  Do not quote accent
     strings: use one \\ rather than two.  See _g_r_o_f_f___c_h_a_r(7)  for  a  modern  ap‐
     proach to the problem of diacritics.

   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 ...
            _f_i_e_l_d
            ...
            ..]]_c_l_o_s_i_n_g_‐_t_e_x_t

     _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 are optional, and only one _k_e_y_w_o_r_d or
     _f_i_e_l_d  need be specified.  If keywords are present, _r_e_f_e_r searches the bib‐
     liographic database(s) for a  unique  reference  matching  them.   Multiple
     matches  are an error; add more keywords to disambiguate the reference.  In
     the absence of keywords, _f_i_e_l_d_s constitute the bibliographic record.   Oth‐
     erwise,  _f_i_e_l_d_s  specify  additional data to replace or supplement those in
     the reference.  When references are accumulating and keywords are  present,
     specify  additional  _f_i_e_l_d_s  at  most on the first citation of a particular
     reference; they apply to all further citations thereof.

     _o_p_e_n_i_n_g_‐_t_e_x_t and _c_l_o_s_i_n_g_‐_t_e_x_t are _r_o_f_f input used  to  bracket  the  label,
     overriding the bbrraacckkeett--llaabbeell command.  Leading and trailing spaces are sig‐
     nificant.   If  either of these is non‐empty, the corresponding argument to
     the bbrraacckkeett--llaabbeell command is not used; alter this behavior with the [[ and ]]
     _f_l_a_g_s_.

     _f_l_a_g_s is a list of non‐alphanumeric characters each of which  modifies  the
     treatment  of  the particular citation.  AT&T _r_e_f_e_r ignores them since they
     are non‐alphanumeric.  They direct GNU _r_e_f_e_r as follows.

     ##      Use the label specified by the sshhoorrtt--llaabbeell command, if  any.   _r_e_f_e_r
            otherwise  uses  the  normal label.  Typically, a short label imple‐
            ments author‐date citation styles consisting of a name, a year,  and
            a  disambiguating letter if necessary.  “##” is meant to suggest such
            a (quasi‐)numeric label.

     [[      Precede  _o_p_e_n_i_n_g_‐_t_e_x_t  with  the  first  argument   given   to   the
            bbrraacckkeett--llaabbeell command.

     ]]      Follow   _c_l_o_s_i_n_g_‐_t_e_x_t   with   the  second  argument  given  to  the
            bbrraacckkeett--llaabbeell command.

     An advantage of the [[ and ]] flags over use of _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 update the document’s bracketing style in one  place  using
     the  bbrraacckkeett--llaabbeell  command.   Another is that sorting and merging of cita‐
     tions is not necessarily inhibited if the flags are used.

     _r_e_f_e_r appends any label resulting from a citation to the  _r_o_f_f  input  line
     preceding  the  ..[[ token.  If there is no such line, _r_e_f_e_r issues a warning
     diagnostic.

     There is no special notation for citing multiple references in series.  Use
     a sequence of citations, one for each reference, with nothing between them.
     _r_e_f_e_r attaches all of their labels to the line preceding the first.   These
     labels  may  be  sorted or merged.  See the description of the <<>> label ex‐
     pression, and of the ssoorrtt--aaddjjaacceenntt--llaabbeellss and aabbbbrreevviiaattee--llaabbeell--rraannggeess  com‐
     mands.   A label is not 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 two adjacent citations, the  for‐
     mer using the ]] flag and without any _c_l_o_s_i_n_g_‐_t_e_x_t_, and the latter using the
     [[  flag  and without any _o_p_e_n_i_n_g_‐_t_e_x_t_, may be sorted and merged even if the
     former’s _o_p_e_n_i_n_g_‐_t_e_x_t or the latter’s _c_l_o_s_i_n_g_‐_t_e_x_t is non‐empty.  (To  pre‐
     vent  these  operations,  use the dummy character escape sequence \\&& as the
     former’s _c_l_o_s_i_n_g_‐_t_e_x_t.)

   CCoommmmaannddss
     Commands are contained between lines starting with ..RR11 and ..RR22.  The --RR op‐
     tion prevents recognition of these lines.   When  _r_e_f_e_r  encounters  a  ..RR11
     line,  it  flushes  any accumulated references.  Neither ..RR11 nor ..RR22 lines,
     nor anything between them, is output.

     Commands are separated by newlines or semicolons.  A number sign (##) intro‐
     duces a comment that extends to the end of the line, but does  not  conceal
     the newline.  Each command is broken up into words.  Words are separated by
     spaces  or  tabs.  A word that begins with a (neutral) double quote ("") ex‐
     tends to the next double quote that  is  not  followed  by  another  double
     quote.   If  there  is no such double quote, the word extends to the end of
     the line.  Pairs of double quotes in a word beginning with a  double  quote
     collapse  to  one  double  quote.  Neither a number sign nor a semicolon is
     recognized inside double quotes.  A line can be continued by ending it with
     a backslash “\\”; this works everywhere except after a number sign.

     Each command _n_a_m_e that is marked with * has an associated negative  command
     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‐negative num‐
     bers; _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  surname
            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  hy‐
            phenated  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  references
            will  be  abbreviated to a label consisting of the first label, fol‐
            lowed 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 defaults 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 when‐
            ever 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 omit‐
            ted it will default to XX.  Only one field can be an annotation.

     aarrttiicclleess _s_t_r_i_n_g ...
            Each _s_t_r_i_n_g is a definite or indefinite article, and should  be  ig‐
            nored  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  data‐
            base _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 occur‐
            rence 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.
                   bracket-label \*([. \*(.] ", "

     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  in‐
            stead; 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  subsection
            “Label  expressions”  below  for a description of label expressions.
            This command is useful if you do not want  explicit  labels  in  the
            reference list, but instead want to handle any necessary disambigua‐
            tion by qualifying the date in some way.  The label used in the text
            would typically be some combination of the author and date.  In most
            cases  you  should  also use the nnoo--llaabbeell--iinn--rreeffeerreennccee command.  For
            example,
                   date-as-label D.+yD.y%a*D.-y
            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 behav‐
            ior, so the negative version of this command is more useful.   _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
            Configure use of “eett aall” in the evaluation of @@ expressions in label
            expressions.   If  _u is the number of authors needed to make the au‐
            thor sequence unambiguous and the total number of authors is _t_, then
            the last _t-_u authors will be replaced by _s_t_r_i_n_g provided that _t-_u is
            not less than _m and _t is not less than _n.  The default  behavior  is
            as follows.
                   et-al " et al" 2 3
            Note the absence of a dot from the end of the abbreviation, which is
            arguably  not  correct.  (_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 exactly
            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 refer‐
            ence’s label.  This is the default behavior, so the negative 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 nega‐
            tive 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 reference.

     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 description of  the
            <<>> label expression.

     mmoovvee--ppuunnccttuuaattiioonn*
            In the text, move any punctuation at the end of line past the label.
            We  recommend  employing  this  command  unless you are using super‐
            scripted numbers as labels.

     rreevveerrssee* _s_t_r_i_n_g
            Reverse the fields whose names are in _s_t_r_i_n_g.  An  optional  integer
            after  a  field  name  limits the number of such fields to the given
            count; no integer means no limit.

     sseeaarrcchh--iiggnnoorree* _f_i_e_l_d_s
            While searching for keys in databases for which no index exists, ig‐
            nore the contents of _f_i_e_l_d_s.  Initially, fields XXYYZZ are ignored.

     sseeaarrcchh--ttrruunnccaattee* _n
            Only require the first _n characters of keys to be given.  In  effect
            when  searching  for a given key words in the database are truncated
            to the maximum of _n and the length of the key.  Initially, _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  (usually
            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 authors from the label.  The
            sshhoorrtt--llaabbeell command will typically be used to specify a  label  con‐
            taining 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 automatically
            be accumulated.  _s_t_r_i_n_g should be a list of field names,  each  fol‐
            lowed  by  a number, indicating how many fields with the name should
            be used for sorting.  “++” 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 (tentative) label.  (Sub‐
            section “Label expressions” below describes the concept of a  tenta‐
            tive label.)

     ssoorrtt--aaddjjaacceenntt--llaabbeellss*
            Sort  labels  that are adjacent in the text according to their posi‐
            tion in the reference list.  This command should usually be given if
            the aabbbbrreevviiaattee--llaabbeell--rraannggeess command has been given, or if the  label
            expression contains a <<>> expression.  This has no effect unless ref‐
            erences are being accumulated.

   LLaabbeell eexxpprreessssiioonnss
     Label  expressions can be evaluated both normally and tentatively.  The re‐
     sult of normal evaluation is used for  output.   The  result  of  tentative
     evaluation,  called  the _t_e_n_t_a_t_i_v_e _l_a_b_e_l, is used to gather the information
     that normal evaluation needs to disambiguate the label.  Label  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  ap‐
     plies to normal evaluation, except where otherwise specified.

     _f_i_e_l_d [_n]
             is the _nth 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  authors  joined as specified by the jjooiinn--aauutthhoorrss command.  The
             whole of each author’s name is used.  However,  if  the  references
             are  sorted  by author (that is, the sort specification starts with
             “AA++”), then authors’ surnames will be used instead,  provided  that
             this  does not introduce ambiguity, and also an initial subsequence
             of the authors may be used instead of all the authors,  again  pro‐
             vided that this does not introduce ambiguity.  Given any two refer‐
             enced works with _n authors, the use of only the surname for the _nth
             author  of a reference is regarded as ambiguous if the other refer‐
             ence shares the first _n-1 authors, the _nth authors of  each  refer‐
             ence are not identical, but the _nth authors’ surnames _a_r_e the same.
             A  proper  initial  subsequence of the sequence of authors for some
             reference is considered to be ambiguous if  there  is  a  reference
             with some other sequence of authors which also has that subsequence
             as  a  proper  initial subsequence.  When an initial subsequence of
             authors is used, the remaining authors are replaced by  the  string
             specified by the eett--aall command; this command may also specify addi‐
             tional  requirements 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
             purposes have the same representation.

     %%_n
     %%aa
     %%AA
     %%ii
     %%II      The serial number of the reference formatted according to the char‐
             acter  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  tentatively
             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 digits
             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 toward 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 surname 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 evaluated.
             Thus ..aa is useful only when you want a field to be abbreviated 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 surname 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 catenation 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  adja‐
             cent  two‐part labels which have the same first part will be merged
             by appending the second part of the second label onto the first la‐
             bel    separated    by    the    string    specified     in     the
             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 series
     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 character).  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  classified 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, otherwise 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
     references  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 infor‐
     mation; 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  arguments  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

EExxiitt ssttaattuuss
     _r_e_f_e_r  exits with status 00 on successful operation, status 22 if the program
     cannot interpret its command‐line arguments, and status 11 if it  encounters
     an error during operation.

EEnnvviirroonnmmeenntt
     _R_E_F_E_R    Assign this variable a file name to override 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_4_._1_/_t_m_a_c_/_r_e_f_e_r_._t_m_a_c
            defines macros and strings facilitating integration with macro pack‐
            ages 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 expressions.

EExxaammpplleess
     We  can illustrate the operation of _r_e_f_e_r with a sample bibliographic data‐
     base 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)  brackets
     that  label with interpolations of the “[[..”  and “..]]”  strings; (c) calls a
     macro “]]--”; (d) defines strings and registers containing the label and bib‐
     liographic data for the reference; (e) calls a macro “]][[”; and (f) uses the
     llff request to restore the line numbers of the input.  As noted  in  subsec‐
     tion “Macro interface” above, it is the document’s responsibility to employ
     and  format  the  information  usefully.   Let  us  see  how  we might turn
     _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  label
     numbering,  so  we have manually specified a (superscripted) symbolic foot‐
     note for our non‐bibliographic aside.

SSeeee aallssoo
     “Refer —— A Bibliography System”, by Bill  Tuthill,  1983,  Computing  Ser‐
     vices, University of California, Berkeley.

     “Some  Applications of Inverted Indexes on the Unix System”, by M. E. Lesk,
     1978, AT&T Bell Laboratories Computing Science Technical Report No. 69.

     _i_n_d_x_b_i_b(1), _l_o_o_k_b_i_b(1), _l_k_b_i_b(1)

groff 1.24.1                       2026‐04‐22                           _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 system.
     _s_o_e_l_i_m eliminates source requests in _r_o_f_f(7) and other text 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 recursively, flattening a tree of
     documents.  By default, it writes _r_o_f_f 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 di‐
     agnostics 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  argu‐
     ments,  _s_o_e_l_i_m  reads the standard input stream.  The program writes to the
     standard output stream.

     _s_o_e_l_i_m reads the _i_n_c_l_u_d_e_d_‐_f_i_l_e argument as  GNU  _t_r_o_f_f  does.   It  ignores
     spaces  immediately  after “so”; to embed a sequence of one or more leading
     spaces in the argument, prefix the sequence with  a  neutral  double  quote
     ("").   Non‐leading  spaces are interpreted literally.  A backslash followed
     by a space (“\\ ”) also encodes a space, for compatibility with earlier ver‐
     sions of GNU _s_o_e_l_i_m.  If the included file name requires a  backslash,  use
     \\\\  or \\ee to embed it.  Any other escape sequence in _i_n_c_l_u_d_e_d_‐_f_i_l_e, includ‐
     ing “\\[[rrss]]”, prevents _s_o_e_l_i_m from replacing the source request.   AT&T  and
     descendant  versions  of  _s_o_e_l_i_m  have no means of embedding spaces in file
     names; they replace the first space encountered with a newline and stop in‐
     terpreting the request.

     The dot must be at the beginning of a line and must  be  followed  by  “ssoo”
     without  intervening  spaces or tabs for _s_o_e_l_i_m to handle it.  This conven‐
     tion 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 _i_n_c_l_u_d_e_d_‐_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  language;
     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.

     _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  formatter,
     _t_r_o_f_f(1).  _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 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 infor‐
     mation; 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 for _i_n_p_u_t_‐ and _i_n_c_l_u_d_e_d_‐_f_i_l_e_s_.  If speci‐
             fied 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 purpose.

     If both --rr and --tt are given, the last one specified controls.

EExxiitt ssttaattuuss
     _s_o_e_l_i_m exits with status 00 on successful operation, status 22 if the program
     cannot  interpret its command‐line arguments, and status 11 if it encounters
     an error during operation.

SSeeee aallssoo
     _g_r_o_f_f(1)

groff 1.24.1                       2026‐04‐22                          _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  formatting
     system.  _t_b_l is a _t_r_o_f_f(1) preprocessor that translates descriptions of ta‐
     bles  embedded  in _r_o_f_f(7) input into the language understood by _t_r_o_f_f.  It
     copies each _f_i_l_e’s contents to the  standard  output  stream,  transforming
     each _t_a_b_l_e _r_e_g_i_o_n between lines starting with ..TTSS and ..TTEE into instructions
     to the GNU _t_r_o_f_f formatter.  While GNU _t_b_l’s input syntax is highly compat‐
     ible 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  present,
     or if _f_i_l_e is “--”, _t_b_l reads the standard 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 table region encloses one
     or more table descriptions.  Within a table region, table descriptions  be‐
     yond  the  first must each be preceded by an input line beginning with ..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 subsequent pages (see below).

     (Experienced _r_o_f_f users should observe that _t_b_l is not a _r_o_f_f language  in‐
     terpreter:  the  default  control  character must be used, and no spaces or
     tabs are permitted between the control character and the macro name.  These
     _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 _t_r_o_f_f requests to  de‐
     fine  these macros as empty if their definitions do not exist when the for‐
     matter encounters a table region.)

     Each table region may begin with _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 options,
     keywords that influence the interpretation or rendering of the region as  a
     whole  or  all table entries within it indiscriminately.  Separate multiple
     region options with commas, spaces, or tabs.  Those that require  a  paren‐
     thesized  argument permit spaces and tabs between the option’s name and the
     opening parenthesis.  Options accumulate and cannot be unset within  a  re‐
     gion  once  declared;  if an option that takes a parameter is repeated, the
     last occurrence controls.  If present, the set of region  options  must  be
     terminated with a semicolon (;;).

     Any  of  the  aallllbbooxx, bbooxx, ddoouubblleebbooxx, ffrraammee, and ddoouubblleeffrraammee region options
     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.  GNU _t_b_l  recog‐
                      nizes ffrraammee as a synonym.

     cceenntteerr           Center  the  table region with respect to the line length,
                      reducing the indentation if necessary (with a  warning  at
                      formatting time) to make the table region fit; the default
                      is  to left‐align it.  GNU _t_b_l recognizes cceennttrree as a syn‐
                      onym.

     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,
                      respectively,  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.  GNU _t_b_l recognizes ddoouubblleeffrraammee as a synonym.

     eexxppaanndd           Spread  the table horizontally to fill the available space
                      (line length minus indentation) by increasing column sepa‐
                      ration.  Ordinarily, a table is made only as wide as  nec‐
                      essary  to  accommodate  the widths of its entries and its
                      column separations (whether specified or  default).   When
                      eexxppaanndd applies to a table that exceeds the available hori‐
                      zontal space, _t_b_l reduces column separation as far as nec‐
                      essary  (even to zero).  _t_b_l produces _t_r_o_f_f input that is‐
                      sues 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 has no effect on terminal de‐
                      vices.

     nnookkeeeepp           Don’t use _r_o_f_f diversions to  manage  page  breaks.   Nor‐
                      mally,  _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 format‐
                      ting time when the line length  and  indentation  or  page
                      length  is  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  type‐
     set.  The format specification is a series of column _d_e_s_c_r_i_p_t_o_r_s_.  Each de‐
     scriptor  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_.  Classi‐
     fiers are letters (recognized case‐insensitively) or  punctuation  symbols;
     modifiers consist of or begin with letters or numerals.  Spaces, tabs, new‐
     lines,  and commas separate descriptors.  Newlines and commas apply the de‐
     scriptors following them to a subsequent row of the table (enabling  column
     headings  to be centered or emboldened while the table entries for the data
     are not, for instance).  We term the resulting group of column  descriptors
     a  _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,  de‐
     scribed below, make separation necessary.

     The  classifier  selects  from one of several arrangements.  Some determine
     the positioning of table entries within a rectangular cell: centered, left‐
     aligned, numeric (aligned to a configurable decimal separator), and so  on.
     Others  perform  special  operations like drawing lines or spanning entries
     from adjacent cells in the table.  Except for “||”, any  classifier  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 conclude
     with  a dot “..” followed by a newline.  Each row definition applies in turn
     to one row of the table.  _t_b_l applies the last row definition  to  rows  of
     table data in excess of the row definitions.

     For  clarity in this document’s examples, we write classifiers in uppercase
     and modifiers in lowercase.  Thus,  “CCbbCCbb,,LLRR..”  defines  two  rows  of  two
     columns.   The  first  row’s entries are centered and boldfaced; the second
     and any further rows’ first and second columns are left‐ and right‐aligned,
     respectively.  Any rows of entries appended to the table data reuse the row
     definition “LLRR”.

     The row definition with the most column descriptors determines  the  number
     of  columns in the table; any row definition with fewer, GNU _t_b_l implicitly
     extends on the right‐hand side with LL descriptors as many times  as  neces‐
     sary 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 entries in
            the  column  with respect to the centered entry, then indent all en‐
            tries by one en.  Such “alphabetic” entries (hence the name  of  the
            classifier)  can be used in the same column as 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  deci‐
            mal numbers vertically at the units place.  If multiple decimal sep‐
            arators  are adjacent to a digit, it uses the rightmost one for ver‐
            tical alignment.  If there is no decimal  separator,  _t_b_l  uses  the
            rightmost  digit  for  vertical alignment; if no digits are present,
            _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, _t_b_l uses  the  left‐
            most for alignment.

            If NN‐classified entries share a column with LL or RR entries, _t_b_l cen‐
            ters  the  widest  NN  entry with respect to the widest LL or RR entry,
            preserving the alignment of NN entries with respect to each other.

            Decimal separators in _e_q_n equations within NN‐classified columns  can
            conflict  with  _t_b_l’s  use of them for alignment.  Specify the ddeelliimm
            region option to make _t_b_l ignore the data within _e_q_n delimiters.

     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.  _t_b_l  expects  an  empty
            table  entry  to  correspond  to  this classifier; if data are found
            there, it issues a diagnostic message.  If the entire row definition
            consists of these classifiers (only one is necessary), it is treated
            as a “__” occupying a row of table entries, and no corresponding data
            are expected.

     ==      Replace table entry with a double horizontal rule.  _t_b_l  expects  an
            empty  table  entry  to  correspond  to this classifier; if data are
            found there, it issues a diagnostic message.  If the entire row def‐
            inition consists of these classifiers (only one is necessary), it is
            treated as a “==” occupying a row of table  entries,  and  no  corre‐
            sponding data are expected.

     ||      Place  a  vertical rule (line) on the corresponding row of the table
            (if two of these are adjacent, a double vertical rule).  This  clas‐
            sifier  does not contribute to the column count and no table entries
            correspond to it.  A || 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.  Follow it with a format specification and table data, but
     _n_o_t  region  options.   The quantity of columns in a format thus introduced
     cannot increase relative to the previous format; in that case, you must end
     the table region and start another.  If that will not serve because the re‐
     gion uses box options or the columns align in an  undesirable  manner,  you
     must  design  the initial table format specification to include the maximum
     quantity of columns required, and use the SS horizontal spanning  classifier
     where necessary to achieve the desired columnar alignment.

     Spanning horizontally in the first column or vertically on the first row is
     an error.  _t_b_l does not support non‐rectangular span areas.

   CCoolluummnn mmooddiiffiieerrss
     Any  number  of  modifiers  can follow a column classifier.  Modifier argu‐
     ments, where accepted, are case‐sensitive.  If you apply a  given  modifier
     to  a  classifier  more than once, or apply conflicting modifiers, only the
     last occurrence has effect.  The modifier xx is mutually  exclusive  with  ee
     and  ww, but ee is not mutually exclusive with ww; if these are used in combi‐
     nation, 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”),  in‐
            stead of the center, of its range.  This is a GNU extension.

     ee, EE   Equalize  the  widths  of  columns with this modifier to that of the
            widest.  This modifier sets the default line length used in  a  text
            block.

     ff, FF   Select  the typeface for the table entry.  A font or style name (one
            or two characters not starting with a digit), font mounting position
            (a single digit), or a name or mounting position of  any  length  in
            parentheses,  must  follow.  The last form is a GNU extension.  (The
            parameter corresponds to that accepted by the _t_r_o_f_f fftt request.)   A
            one‐character  argument not in parentheses must end the row descrip‐
            tion or be separated by one or more spaces or tabs  from  what  fol‐
            lows.

     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 subsection
            “Text blocks” below).  This is a GNU extension.  A macro name of one
            or two characters, or a name of any length in parentheses, must fol‐
            low.  A one‐character macro name not in parentheses  must  be  sepa‐
            rated  by  one  or more spaces or tabs from what follows.  The named
            macro must be defined before the table region containing this column
            modifier is encountered.  The macro should contain only simple _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.  An integer _n with an optional leading sign  must
            follow.   If unsigned, the type size is set to _n points.  Otherwise,
            the type  size  is  incremented  or  decremented  per  the  sign  by
            _n  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 separa‐
            tion 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
            Documenter’s Workbench (DWB) 1.0 and Research Tenth Edition Unix ex‐
            tension.

     vv, VV   Set  the vertical spacing of a text block.  An integer _n with an op‐
            tional leading sign must follow.  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 number is a GNU extension.   (This  parameter  corresponds  to
            that accepted by the _t_r_o_f_f vvss request.)  If a vertical spacing modi‐
            fier  is  followed by a column separation modifier (see below), they
            must be separated by at least one space or tab.

     ww, WW   Set the column’s minimum width.  A number, either a  unitless  inte‐
            ger,  or  a _r_o_f_f horizontal measurement in parentheses, must follow.
            Parentheses are required if the width is to be followed  immediately
            by  an  explicit  column separation (alternatively, follow the width
            with one or more spaces or tabs).  If no unit is specified, ens  are
            assumed.   This modifier sets the default line length used in a text
            block.

     xx, XX   Expand the column.  After computing the  column  widths,  distribute
            any remaining line length evenly over all columns bearing this modi‐
            fier.  This is a Documenter’s Workbench (DWB) 3.3 extension.  Apply‐
            ing the 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 cal‐
            culation  purposes;  that  is, compute the column’s width using only
            the information in its descriptor.  This is a Documenter’s Workbench
            (DWB) 1.0 and Research Tenth Edition Unix extension.

     _n      A numeric suffix on a column descriptor sets the separation distance
            (in ens) from the succeeding column; the default separation  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 diagnostic from _t_b_l.

   TTaabbllee ddaattaa
     Place table data on lines after the format specification.  Each  text  line
     corresponds to a table row, except that a backslash at the end of a line of
     table  data  continues an entry on the next input line.  (Text blocks, dis‐
     cussed below, also spread table entries across multiple input lines.)   Ta‐
     ble  entries  within a row are separated in the input by a tab character by
     default; see the ttaabb region option above.  Excess entries in a row of table
     data (those that have no corresponding column descriptor, not even  an  im‐
     plicit one arising from rectangularization of the table), _t_b_l discards with
     a  diagnostic  message.  _t_b_l passes _r_o_f_f control lines through unaltered to
     its output.  If you wish to visibly mark an empty table entry in the  docu‐
     ment  source, populate it with the \\&& _r_o_f_f dummy character.  The table data
     are interrupted 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, broken,
     hyphenated, adjusted, or populated with supplemental 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 entry, 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 selection or vertical spacing, do not per‐
     sist between entries.

     _t_b_l interprets several forms of table entry specially.

     •  If  a table row contains only an underscore or equals sign (__ or ==), _t_b_l
        draws a a single or double horizontal rule (line), respectively,  across
        the table at that point.

     •  If a table entry contains only __ or == on an otherwise populated row, _t_b_l
        populates  its  cell  with  a  single or double horizontal rule, respec‐
        tively, that joins its neighbors.

     •  If a table entry contains only \\__ or \\== on an otherwise  populated  row,
        _t_b_l  populates its cell with a single or double horizontal rule, respec‐
        tively, that does _n_o_t (quite) join its neighbors.

     •  If a table entry contains only \\RR_x, where _x is any _r_o_f_f  ordinary,  spe‐
        cial,  or  indexed character, _t_b_l populates its cell with enough repeti‐
        tions of the glyph corresponding to _x to fill the column without joining
        its neighbors.

     •  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 es‐
     cape  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  rec‐
     ognized.   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 ta‐
     ble, too wide; the table then exceeds the line length of the page, and  be‐
     comes  ugly or is exposed to truncation by the output device.  When a table
     entry requires more conventional typesetting, breaking across more than one
     output line (and thereby increasing the height  of  its  row),  it  can  be
     placed within a _t_e_x_t _b_l_o_c_k_.

     _t_b_l interprets a table entry of “TT{{” at the end of an input line specially,
     as a token starting a text block.  Similarly, an entry “TT}}” at the start of
     an input line ends a text block.  Text block tokens can share an input line
     with other table data (preceding TT{{ and following TT}}).  Input lines between
     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 al‐
     ter its adjustment distinctly from other text in  the  document.   As  with
     other  table entries, when a text block ends, any alterations to formatting
     parameters are discarded.  They do not affect subsequent table entries, not
     even other text blocks.

     If 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’s 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.  Because _t_b_l uses a  diversion  to
     format  the  text block, its height and width are subsequently available in
     the _t_r_o_f_f registers ddnn and ddll, respectively.

   _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 _t_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.  A ##TT register is used internally.  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 be‐
     ginning  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
     Process  a  document  with  _t_b_l  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 endured
     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.

     •  GNU  _t_b_l considers all table rows when computing column widths, not just
        those occurring in the first 200 input lines of a region.  Similarly, it
        recognizes table continuation tokens (..TT&&) 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 region, it
     is necessary to call end macros instead of ending  macro  definitions  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 example,
     vertically aligning decimal separators fails if the numbers containing them
     occur as macro or string parameters; the alignment is performed by _t_b_l  it‐
     self,  which sees only \\$$11, \\$$22, and so on, and therefore can’t recognize a
     decimal separator that appears only 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  subse‐
     quent  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 num‐
     ber cannot take effect.  Consider copying the input line  counter  register
     “cc..”  and  restoring  its  value  at a convenient location after applicable
     arithmetic.

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

     --CC     Enable AT&T compatibility mode: recognize ..TTSS and ..TTEE even when fol‐
            lowed by a character other than space or newline, and interpret  the
            copy‐mode leader escape sequence \\aa as a leader character.

EExxiitt ssttaattuuss
     _t_b_l  exits  with  status 00 on successful operation, status 22 if the program
     cannot interpret its command‐line arguments, and status 11 if it  encounters
     an error during operation.

LLiimmiittaattiioonnss
     Within a _t_b_l region (except in text blocks or on _r_o_f_f control lines), avoid
     escape sequences that read the rest of the input line, as \\"" and \\!! do.

     Multi‐page  tables,  if  boxed and/or if you want their column headings re‐
     peated after page breaks, require support at the time the document is  for‐
     matted.  A convention for such support has arisen in macro packages such as
     _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 ar‐
     gument.  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 repeat‐
     ing 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 demonstration.

     _g_r_o_t_t_y(1) does not support double horizontal rules; it  uses  single  rules
     instead.   It  also ignores half‐line motions, so the uu column modifier has
     no effect.  On terminal devices (“_n_r_o_f_f mode”), horizontal  rules  and  box
     borders  occupy  a  full  vee of space; ddoouubblleebbooxx doubles that for borders.
     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 between columns in _n_r_o_f_f mode; using  double
     vertical  rules and/or reducing the column separation below the default can
     make them ugly or overstrike them with table data.

     A text block within a table must be able to fit on one page.

     Using \\aa to put leaders in table entries does not work in GNU  _t_b_l,  except
     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 (Control+A) or  define
     a string to use \\aa as it was designed: to be interpreted only in copy mode.

            .ds a \a
            .TS
            box center tab(;);
            Lw(2i)0 L.
            Population\*a;6,327,119
            .TE

                         ┌───────────────────────────────┐
                         │ Population..........6,327,119 │
                         └───────────────────────────────┘

     A  leading  or trailing “||” in a format specification, as in “||LLCCRR||..”, pro‐
     duces an en space between the rules and the content  of  adjacent  columns.
     If  such space is undesired (the rule should abut the content), you can in‐
     troduce “dummy” columns with zero separation and empty corresponding  table
     entries before and/or after.

            .TS
            center tab(#);
            R0|L C R0|L.
            _
            #levulose#glucose#dextrose#
            _
            .TE

     These  dummy  columns have zero width and are therefore invisible; unfortu‐
     nately they usually don’t work as intended on terminal devices.

EExxaammpplleess
     It can be easier to acquire the language of _t_b_l through examples than  for‐
     mal description, especially at first.

            .TS
            box center tab(#);
            Cb Cb
            L  L.
            Ability#Application
            Strength#crushes a tomato
            Dexterity#dodges a thrown tomato
            Constitution#eats a month‐old tomato without becoming ill
            Intelligence#knows that a tomato is a fruit
            Wisdom#chooses \f[I]not\f[] to put tomato in a fruit salad
            Charisma#sells tomato‐based fruit salads to hypercarnivores
            .TE

       ┌───────────────────────────────────────────────────────────────────┐
       │   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 tomato‐based fruit salads to hypercarnivores │
       └───────────────────────────────────────────────────────────────────┘

     The  AA  and NN column classifiers can be easier to grasp in visual rendering
     than in description.

            .TS
            center tab(;);
            CbS,LN,AN.
            Daily energy intake (in MJ)
            Macronutrients
            .\" assume 3 significant figures of precision
            Carbohydrates;4.5
            Fats;2.25
            Protein;3
            .T&
            LN,AN.
            Mineral
            Pu-239;14.6
            _
            .T&
            LN.
            Total;\[ti]24.4
            .TE

                                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 January
     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 im‐
     plementation.

     _g_r_o_f_f(1), _t_r_o_f_f(1)

groff 1.24.1                       2026‐04‐22                             _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 identifiers 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 descriptions.  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 informa‐
     tion 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 additional in‐
     formation 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  af‐
     ter 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; con‐
     sider 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 “spe‐
     cial” 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 infor‐
     mation; all exit afterward.

     --gg _g_f_‐_f_i_l_e
            Use the _g_f_‐_f_i_l_e produced by Metafont containing “ssppeecciiaall” and  “nnuumm‐‐
            ssppeecciiaall” commands to obtain additional font metric information.

     --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 sec‐
            ond component is _s_k_e_w_‐_c_h_a_r are ignored.

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

EExxiitt ssttaattuuss
     _t_f_m_t_o_d_i_t exits with status 00 on successful operation, status 22 if the  pro‐
     gram  cannot  interpret  its command‐line arguments, and status 11 if it en‐
     counters an error during operation.

FFiilleess
     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_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_4_._1_/_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_4_._1_/_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_4_._1_/_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_4_._1_/_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_4_._1_/_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_4_._1_/_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_4_._1_/_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_4_._1_/_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_4_._1_/_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_4_._1_/_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_4_._1_/_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_4_._1_/_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_4_._1_/_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_4_._1_/_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 charac‐
            ter 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.24.1                       2026‐04‐22                        _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 [--aabbccCCEEiiRRSSUUzz] [--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‐independent
     page description language detailed 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
     present, or if _f_i_l_e is “--”, _t_r_o_f_f reads the standard input stream.

     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)  com‐
     mand,  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  version
     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 exam‐
                 ple, “<beginning of page>”.

              •  Lines are broken where they would be in formatted output.

              •  Vertical motion, apart from that implied by  a  break,  is  not
                 represented.

              •  A  horizontal  motion  of any size is represented as one space.
                 Adjacent horizontal motions are not combined.  Supplemental in‐
                 ter‐sentence space (configured by the second  argument  to  the
                 ..ssss request) is not represented.

              •  A special character is rendered as its identifier between angle
                 brackets; for example, a hyphen appears as “<hy>”.

              The  above  description  should not be considered a specification;
              the details of --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,  be‐
              cause  _t_r_o_f_f’s  idea  of  line numbers can be confused by requests
              that append to macros.

     --cc       Disable multi‐color output and “ccoolloorr” request’s ability to enable
              it.

     --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 a one‐character
              identifier;  _s_t_r_i_n_g  can be of arbitrary length.  Such 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  char‐
              acter 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 directory
              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  default
              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:: iimmppoorrtt''”,
              “\\XX''ppss:: ffiillee''”, and “\\XX''ppddff:: ppddffppiicc''” device extension escape  se‐
              quences).   --II  may  be  specified  more  than  once;  each _d_i_r is
              searched in the given order.  To search the current working direc‐
              tory before others, add “--II ..” at the desired place; it is  other‐
              wise  searched last.  --II works similarly to, and is named for, the
              “include” option of Unix C compilers.

     --mm _m_a_c   Search for the macro package mac_._t_m_a_c and read it prior to any in‐
              put.  If not found, _t_m_a_c_.mac is attempted.  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 in‐
              clusive 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 formatting
              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  identifier;  _r_e_g_i_s_t_e_r  can  be  of arbitrary
              length.  Such 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 identifier.

     --RR       Prevent  loading  of  _t_r_o_f_f_r_c  and _t_r_o_f_f_r_c_-_e_n_d; this option can be
              useful for troubleshooting.

     --SS       Enable safer mode and ignore any subsequent --UU option.

     --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 ccff, ooppeenn, ooppeennaa, ppii, ppssoo, and
              ssyy requests, which are disabled by default because they  allow  an
              untrusted  input document to run arbitrary commands, put arbitrary
              content into _t_r_o_f_f output, or write to arbitrary file names.  (GNU
              _t_r_o_f_f does not, however, accept  newlines  (line  feeds)  in  file
              names  supplied  as arguments to requests.)  This option also adds
              the current directory to the macro package search path; see the --mm
              and --MM options above.

     --ww _c_a_t
     --WW _c_a_t   Enable and inhibit, respectively, warnings in category  _c_a_t_.   See
              section “Warnings” below.

     --zz       Suppress formatted output.

WWaarrnniinnggss
     GNU  _t_r_o_f_f divides its warning diagnostics into named, numbered categories.
     The --ww and --WW options use the associated names.  A power of two  character‐
     izes  each  category;  the wwaarrnn request and the ..wwaarrnn register respectively
     set and report the sum of enabled category codes.  Warnings of  each  cate‐
     gory are produced under the following circumstances.

                ┌───────────────────────┬──────────────────────────┐
                │ Bit   Code   Category │ Bit    Code     Category │
                ├───────────────────────┼──────────────────────────┤
                │   0      _1   cchhaarr     │  10      _1_0_2_4   rreegg      │
                │   1      _2   _u_n_u_s_e_d   │  11      _2_0_4_8   ttaabb      │
                │   2      _4   bbrreeaakk    │  12      _4_0_9_6   _u_n_u_s_e_d   │
                │   3      _8   ddeelliimm    │  13      _8_1_9_2   mmiissssiinngg  │
                │   4     _1_6   _u_n_u_s_e_d   │  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 or equal to, or adjusted such that
                         its length was exactly equal to, the output line length
                         “\\nn[[..ll]]”.  GNU _t_r_o_f_f reports the amount of  overset  or
                         underset   in   the  scaling  unit  configured  by  the
                         wwaarrnnssccaallee request in ttrrooffff mode, and in ens (‘nn’; char‐
                         acter cells) in nnrrooffff mode.  This category  is  enabled
                         by default.

     cchhaarr            1   No  user‐defined character of the requested name or in‐
                         dex exists and no mounted font defines a glyph for  it,
                         or  input  could  not be encoded for device‐independent
                         output.  This category is enabled by default.

     ccoolloorr      524288   An undefined color name was selected,  an  attempt  was
                         made  to  define  a  color  using an unrecognized color
                         space, an invalid channel value in a  color  definition
                         was  encountered,  or an attempt was made to redefine a
                         default color.

     ddeelliimm           8   The selected delimiter character was ambiguous  because
                         it  is also meaningful when beginning a numeric expres‐
                         sion, or the closing delimiter in  an  escape  sequence
                         was missing or mismatched.

                         A future _g_r_o_f_f release may reject ambiguous delimiters.
                         In  compatibility  mode,  ambiguous  delimiters are ac‐
                         cepted without warning.

     ddii            256   A ddii, ddaa, bbooxx, or bbooxxaa request was invoked  without  an
                         argument when there was no current diversion.

     eessccaappee      32768   An unsupported escape sequence was encountered.

     ffiillee      1048576   An attempt was made to read a file that does not exist.
                         or a stream remained open at formatter exit.  This cat‐
                         egory is enabled by default.

     ffoonntt       131072   A non‐existent font was selected.  This category is en‐
                         abled by default.

     iigg         262144   An  invalid  escape  sequence occurred in input ignored
                         using the iigg request.  This warning category  diagnoses
                         a  condition that is an error when it occurs in non‐ig‐
                         nored 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,  _t_r_o_f_f  issues  at most one warning for
                         each.

                         _t_r_o_f_f also uses this category to warn of an attempt  to
                         move  an  unplanted trap macro.  In such cases, the un‐
                         planted 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 absent.

     rraannggee          64   A numeric expression was out of range for its context.

     rreegg          1024   An undefined register was used.  When an undefined reg‐
                         ister is dereferenced, the formatter automatically  de‐
                         fines  it  with  a  value of 0.  So, unless it is later
                         deleted, GNU _t_r_o_f_f issues at most one warning for each.

     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 undefined
                         name longer than two characters is encountered and  the
                         first  two  characters of the name constitute a defined
                         name.  No request is invoked, no macro called,  and  an
                         empty  macro  is not defined.  This category is enabled
                         by default.  It never occurs in compatibility mode.

     ssyynnttaaxx        128   A  self‐contradictory  hyphenation  mode  or  character
                         flags  were  requested;  an empty or incomplete numeric
                         expression was encountered; an operand to a numeric op‐
                         erator was missing; an attempt was made to format char‐
                         acters or spaces on an input line after an output  line
                         continuation  escape sequence; a recognized but inappo‐
                         site escape sequence or unprintable character code  was
                         used in a device extension command; an attempt was made
                         to  define a recursive, empty, or nonsensical character
                         class; or a _g_r_o_f_f extension escape sequence  or  condi‐
                         tional  expression  operator was used while in compati‐
                         bility mode.

     ttaabb          2048   A tab character appeared in a parameterized escape  se‐
                         quence,  in  an unquoted macro argument, or where a re‐
                         quest expected a numeric expression argument.

     Two warning names group other warning categories for convenience.

     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 descendants, 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.

EExxiitt ssttaattuuss
     _t_r_o_f_f exits with status 00 on successful operation, status 22 if the  program
     cannot  interpret its command‐line arguments, and status 11 if it encounters
     a fatal error during operation, or is directed to abort by the input.

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  directo‐
     ries;  that  is,  a  list of directory names separated by the system’s path
     component separator character.  On Unix systems, this character is a  colon
     (:); on Windows systems, it is a semicolon (;).

     _G_R_O_F_F___F_O_N_T___P_A_T_H
            A  list of directories in which to seek the selected output device’s
            directory of device and font description files.  _t_r_o_f_f will scan di‐
            rectories given as arguments to  any  specified  --FF  options  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_4_._1_/_f_o_n_t),  and
            a compatibility directory (_/_u_s_r_/_l_i_b_/_f_o_n_t) after 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 options
            before these, then the current directory (only if in  unsafe  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_4_._1_/
            _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 us‐
            able by documents and macro packages.

     _T_Z     The time zone to use when converting the current time to human‐read‐
            able 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_4_._1_/_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_4_._1_/_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_4_._1_/_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_4_._1_/_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_4_._1_/_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  di‐
     rectory  by  default  for security reasons, even if the --UU option is speci‐
     fied.  Use the --MM command‐line option or  the  _G_R_O_F_F___T_M_A_C___P_A_T_H  environment
     variable to add these directories to the search path if necessary.

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 Lem‐
     berg, 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 reference
            of all predefined requests, registers, and escape sequences.

     _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  pointers
            to further related documentation.

groff 1.24.1                       2026‐04‐22                           _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 pairs a _g_r_o_f_f font name with an X  font  name
     as  an  X  Logical Font Description (XLFD) pattern.  The pair’s members are
     separated by spaces and/or tabs.  For example, an input _f_o_n_t_‐_m_a_p file  con‐
     sisting 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 cata‐
     log, and aborts if it cannot.  If necessary, the wildcards in the XLFD pat‐
     terns are populated with the arguments to the --rr and --ss options.  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  di‐
     rectory (or that specified by the --dd option) named for each _g_r_o_f_f font, and
     reports the mapping to the standard output stream.

OOppttiioonnss
     ----hheellpp displays a usage message, while --vv and ----vveerrssiioonn show version infor‐
     mation; 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.

EExxiitt ssttaattuuss
     _x_t_o_t_r_o_f_f  exits with status 00 on successful operation, status 22 if the pro‐
     gram cannot interpret its command‐line arguments, and status 11  if  it  en‐
     counters an error during operation.

FFiilleess
     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_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 de‐
            scription files, supplied with _g_r_o_f_f, of X11 core fonts  correspond‐
            ing 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.24.1                       2026‐04‐22                        _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  extensions
     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 abbrevi‐
     ation  of a font’s name and/or style.  For example, the ppss (PostScript) de‐
     vice 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 terminals) has 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’ processing to
     an internal library, _l_i_b_g_r_o_f_f, ensuring their consistent interpretation.

_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 directive must
     precede any ppaappeerrssiizzee directive; and (2) the cchhaarrsseett  directive  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.  Com‐
     ments 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 mea‐
             surements round 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 (notably
             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 (dep‐
             recated: 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  argu‐
             ment,  which  is  either  a standard paper format, a pair of dimen‐
             sions, or the name of a plain text file containing  either  of  the
             foregoing.   Recognized  paper  formats are the ISO and DIN formats
             AA00–AA77, BB00–BB77, CC00–CC77, and DD00–DD77; the  U.S.  formats  lleetttteerr,  lleeggaall,
             ttaabbllooiidd, lleeddggeerr, ssttaatteemmeenntt, and eexxeeccuuttiivvee; and the envelope 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  picas.
             Example:  “1122cc,,223355pp”.   An argument that starts with a digit is al‐
             ways treated as a custom paper format.

             Finally, the argument can be a file name (e.g., _/_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  at‐
             tempted against each other form.  No comment syntax is supported.

             More  than  one  argument can be specified; each is scanned in turn
             and the first valid paper specification used.

     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 command “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 devices
             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  de‐
             fault 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  com‐
             mands.

     uunniiccooddee
             The  output  device supports the complete Unicode repertoire.  This
             directive is useful only for devices which produce character  enti‐
             ties 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 description file’s
             cchhaarrsseett section, they either  override  the  default  mappings  for
             those  particular characters or add new mappings (normally for com‐
             posite characters).

             The uuttff88, hhttmmll, and xxhhttmmll output devices use this directive.

     uunniittwwiiddtthh _n
             Arbitrary basis with respect to which font metrics are  proportion‐
             ally scaled when rendering glyphs at a type size of one point.

     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 special characters in arguments to  device  ex‐
             tension commands.  The _g_r_o_h_t_m_l driver uses this directive.

     vveerrtt _n  The  vertical  motion  quantum is _n basic units.  Vertical measure‐
             ments round to multiples of _n_.

     cchhaarrsseett
             This directive and the rest of the file are ignored.  It is  recog‐
             nized  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  bbiiggggeesstt‐‐
     ffoonntt.

     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  ob‐
     tain further information about the device.

FFoonntt ddeessccrriippttiioonn ffiillee ffoorrmmaatt
     On typesetting output devices, each font is typically available at multiple
     sizes.   While paper measurements in the device description file are in ab‐
     solute units, measurements applicable to fonts must be proportional to  the
     type  size.   The font’s _u_n_i_t _w_i_d_t_h establishes a numerical basis that per‐
     mits all of its metrics to be expressed as  integers  if  rendered  at  one
     point.   When  the  formatter configures a type size, it scales the metrics
     linearly relative to that basis.  The unit width has no inherent  relation‐
     ship  to  the device resolution, and the same division procedure applies to
     all font metrics.  Observe that whatever unit might one select for the unit
     width, the division operation implied by scaling cancels it out, leaving  a
     dimensionless quantity.

     For  instance,  _g_r_o_f_f’s llbbpp device uses a uunniittwwiiddtthh directive with an argu‐
     ment 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 “MM” has a width of 2,963.  Thus, an “MM”  on  the  llbbpp  device  is
     2,963  ÷ 800 times the unit width, or approximately 3.7.  At a type size of
     10 points, a Times roman “MM” is therefore 37 units wide.

     A font description file has two sections.  The first is a sequence  of  di‐
     rectives, and is parsed similarly to the _D_E_S_C file described above.  Except
     for  the  directive  names that begin the second section, their ordering is
     immaterial.  Later directives of  the  same  name  override  earlier  ones,
     spaces and tabs are handled in the same way, and the same comment syntax is
     supported.  Empty lines are ignored throughout.

     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  integers  as  mounting
             positions  instead.   Further, a font named “00” cannot be automati‐
             cally mounted by the ffoonnttss directive of a _D_E_S_C file.)

     ssppaacceewwiiddtthh _n
             The width of an unadjusted inter‐word space is _n, relative  to  the
             device’s unit width.

     The  directives above must appear in the first section; those below are op‐
     tional.

     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 implementa‐
            tions, 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 the document attempts to format a glyph
            that is not present in the formatter’s currently selected font,  the
            glyph  is  sought in any mounted fonts that bear this property.  Of‐
            ten, such fonts are _u_n_s_t_y_l_e_d, having  no  heavy  (bold)  or  slanted
            (italic or oblique) variants.

     Other  directives in this section are ignored by GNU _t_r_o_f_f, but may be used
     by postprocessors to obtain further information about the font.

     The second section contains one to three subsections, which can  appear  in
     any  order, and any of which starts the second section.  Each starts with a
     directive on a line by itself.  A cchhaarrsseett subsection  is  mandatory  unless
     the  associated  _D_E_S_C file contains the uunniiccooddee directive.  Another subsec‐
     tion, kkeerrnnppaaiirrss, is optional.

     The directive cchhaarrsseett starts the character set  subsection.   (On  typeset‐
     ters,  this  directive  is  misnamed  since it starts a list of glyphs, not
     characters.)  It precedes a series of glyph  descriptions,  one  per  line.
     Each  such  glyph description comprises a set of fields separated by spaces
     or tabs and organized as follows.

            _n_a_m_e _m_e_t_r_i_c_s _t_y_p_e _i_n_d_e_x [_e_n_t_i_t_y_‐_n_a_m_e] [---- _c_o_m_m_e_n_t]

     _n_a_m_e identifies the glyph: a printable character _c corresponds to the _t_r_o_f_f
     ordinary character _c, and a multi‐character sequence not beginning with  \\,
     corresponds  to  the GNU _t_r_o_f_f special 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  requests.   The  _n_a_m_e “\\--” defines the minus sign glyph.  Fi‐
     nally, _n_a_m_e can be the  horizontal  motion  escape  sequences,  \\||  and  \\^^
     (“thin” and “hair” spaces, respectively), in which case only the width met‐
     ric  described  below  is  applied; a font can thus customize the widths of
     these spaces.

     The form of the _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]]]]]]]]]]

     Spaces,  tabs,  and  newlines are prohibited between these _s_u_b_f_i_e_l_d_s_, which
     are expressed as decimal integers.  The unit of measure is that established
     by the uunniittwwiiddtthh directive and scaled to the type size.   Unspecified  sub‐
     fields  default  to  0.   Since there is no associated binary format, these
     values are not required to fit into the C language data type _c_h_a_r  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 (upward is positive); if a glyph does not extend
     above the baseline, give it a zero height,  not  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 extends (downward is positive); if a  glyph
     does  not  extend  below the baseline, give it a zero depth, not a negative
     depth.  Italic corrections  apply  when  upright  and  slanted  (italic  or
     oblique)  styles  are  typeset  adjacently.   The  _i_t_a_l_i_c_‐_c_o_r_r_e_c_t_i_o_n is the
     amount of space to add after a slanted 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 to add
     before a slanted glyph to be preceded immediately by an upright 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 to add after a slanted glyph to
     be followed by a subscript; it should be less than the italic correction.

     For  fonts  used with typesetters, the _t_y_p_e field gives a featural descrip‐
     tion of the glyph: it is a bit mask recording whether the glyph is  an  as‐
     cender, descender, both, or neither.  When a \\ww escape sequence is interpo‐
     lated, these values are bitwise or‐ed together for each glyph and stored in
     the cctt register.  In font descriptions for terminals, all glyphs might have
     a type of zero, regardless of their appearance.

     0      means  the glyph lies entirely between the baseline and a horizontal
            line at the “x‐height” of the font, as with “a”, “c”, and “x”;

     1      means the glyph descends below the baseline, like “p”;

     2      means the glyph ascends above the font’s x‐height, like “A” or “b”);
            and

     3      means the glyph is both an ascender and a descender——this is true of
            parentheses in some fonts.

     The _i_n_d_e_x field is an integer that uniquely identifies a glyph  within  the
     font;  any  integer is accepted as input, (that is, any integer parsable by
     the C standard library’s _s_t_r_t_o_l(3) function) but no practical font  employs
     all  possible  values.   An _i_n_d_e_x is limited to the range of the system’s C
     language data type _i_n_t.  In a _t_r_o_f_f document, use the indexed character es‐
     cape sequence \\NN to specify a glyph by index.

     The _e_n_t_i_t_y_‐_n_a_m_e field defines an identifier for the glyph  that  the  post‐
     processor  uses  to print the _t_r_o_f_f glyph _n_a_m_e.  This field is optional; it
     was introduced so that the _g_r_o_h_t_m_l output driver could encode its character
     set.  For example, the glyph \\[[PPoo]] is represented by “&&ppoouunndd;;” in HTML 4.0.
     For efficiency, these data are now compiled directly 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.  When
     _a_f_m_t_o_d_i_t generates font description files for _g_r_o_p_d_f(1)  and  _g_r_o_p_s(1),  it
     writes the UTF‐16 code for the character to the comment field.

     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 preceding
     line.  Such aliases can be chained.

     A cchhaarrsseett--rraannggee subsection works like the cchhaarrsseett directive except that the
     glyph descriptions use a _n_a_m_e of the form uu_A_A_A_A....uu_F_F_F_F, where _A_A_A_A and _F_F_F_F
     are hexadecimal digit sequences; the specified metrics then  apply  identi‐
     cally to all glyphs in the designated range.

     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  for‐
     matted 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.  The unit  of  measure  is
     that  established  by  the uunniittwwiiddtthh directive and scaled to the type size.
     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_4_._1_/_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_4_._1_/_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  Lem‐
     berg,  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 page description lan‐
     guage 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 additional
     insights into the device and font description file formats and device‐inde‐
     pendent page description language.

     _g_r_o_f_f(1), subsection “Utilities”, lists programs available  for  describing
     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.24.1                       2026‐04‐22                      _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 device‐independent page description language

DDeessccrriippttiioonn
     The fundamental operation of the GNU  _t_r_o_f_f  formatter,  _t_r_o_f_f(1),  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
     positions  on  a  rectangular  page.  In the following discussion, the term
     _c_o_m_m_a_n_d refers to this device‐independent output  language,  never  to  the
     language  intended  for use by document authors.  Device‐independent output
     commands comprise several categories: glyph output; font, color,  and  text
     size  selection;  motion of the drawing position; page advancement; drawing
     of geometric primitives; and device extension  commands,  a  catch‐all  for
     other  operations.   The last includes directives to start and stop output,
     identify the intended output device, and embed URL hyperlinks in  supported
     output formats.

   BBaacckkggrroouunndd
     As  _g_r_o_f_f(1)  is a wrapper program around GNU _t_r_o_f_f and automatically calls
     an output driver, users seldom encounter this format under  normal  circum‐
     stances.   _g_r_o_f_f  offers  the option --ZZ to inhibit postprocessing such that
     GNU _t_r_o_f_f’s output is sent to the standard output stream just as it is when
     running GNU _t_r_o_f_f directly.

     The purpose of device‐independent output is to facilitate  the  development
     of  postprocessors  by providing a common programming interface for all de‐
     vices.  It is a distinct, and much simpler, language from that of the  for‐
     matter,  _t_r_o_f_f.  The device‐independent output can be thought of as a “page
     description language”.

     In the following discussion, the term _t_r_o_f_f _o_u_t_p_u_t describes what is output
     by GNU _t_r_o_f_f, while _p_a_g_e _d_e_s_c_r_i_p_t_i_o_n denotes the language accepted  by  the
     parser  that  interprets  this  output for the output drivers.  This parser
     handles whitespace more flexibly than AT&T _t_r_o_f_f’s  implementation,  recog‐
     nizes a GNU extension to the language, and supports a legacy compressed en‐
     coding  of  a  subset of commands for compatibility; otherwise, the formats
     are the same.  (The parser for device‐independent output can  be  found  in
     the _g_r_o_f_f sources at _s_r_c_/_l_i_b_s_/_l_i_b_d_r_i_v_e_r_/_i_n_p_u_t_._c_p_p.)

     When Brian Kernighan designed AT&T _t_r_o_f_f’s device‐independent page descrip‐
     tion language circa 1980, he had to balance readability and maintainability
     against  severe constraints on file size and transmission speed to the out‐
     put device.  A decade later, when  James  Clark  wrote  _g_r_o_f_f,  these  con‐
     straints were no longer as tight.

   SSyynnttaaxx
     _r_o_f_f’s  page  description  language  is a sequence of _t_o_k_e_n_s_: single‐letter
     commands or their arguments.  Some commands accept a subcommand as a  first
     argument, followed by one or more further arguments.

     AT&T device‐independent _t_r_o_f_f used whitespace minimally when producing out‐
     put.   GNU _t_r_o_f_f, in contrast, attempts to make its output more human‐read‐
     able.  The whitespace characters——tab, space, and newline——are always mean‐
     ingful.  They are never used to represent spacing in the document; that  is
     done  with horizontal (hh, HH) and vertical (vv, VV) positioning commands.  Any
     sequence of space and/or tab characters is equivalent to  a  single  space,
     separating commands from arguments and arguments from each other.  Space is
     required  only where omitting it would cause ambiguity.  A line break sepa‐
     rates commands.  The comment character is a pound/hash sign (##), and  marks
     the  remainder of the line as a comment.  A line comprising only whitespace
     after comment removal does nothing but separate input tokens.

     For example, the relative horizontal motion command (hh) and the command  to
     write one glyph (cc), each take a single argument; the former a signed inte‐
     ger,  and  the  latter  a printable ISO 646/“ASCII” character.  A series of
     such commands could validly occur without spaces on an input line, but  GNU
     _t_r_o_f_f follows each with a newline.

     Some  commands  have a more complex syntax; the GNU _t_r_o_f_f extension command
     for writing glyph sequences (tt) accepts a  variable  number  of  arguments.
     Those that draw geometric objects (DD) or control the device (xx) furthermore
     recognize  subcommand  arguments.   Such commands thus must end with a new‐
     line.  In GNU _t_r_o_f_f_, the device extension (sub)command “xx XX” uniquely  sup‐
     ports a line continuation syntax; a single input line contains any other.

   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  “ss”  (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 al‐
     ways 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  argu‐
     ment  is  already terminated by the next non‐digit character, which then is
     regarded as the first character of the next argument or command.

   OOuuttppuutt ssttrruuccttuurree
     Device‐independent _t_r_o_f_f output is organized into three parts: a header,  a
     body, and a trailer.

     The  task  of  the  header  is to set general device parameters.  GNU _t_r_o_f_f
     guarantees that its header consists of the following three lines:

            xx TT _d_e_v_i_c_e
            xx rreess _n _h _v
            xx iinniitt

     with the parameters _n, _h, and _v set as outlined in subsection “Device  Con‐
     trol  Commands” below.  The parser for the device‐independent page descrip‐
     tion language format is able to interpret additional  whitespace  and  com‐
     ments as well even in the header.

     The  body  contains  the document’s visible content.  Once an output driver
     interprets “xx iinniitt”, it prepares to handle commands in general.  Processing
     terminates when a “xx ssttoopp” command is encountered; the last line of any GNU
     _t_r_o_f_f page description output always contains such a command.

     Semantically, the body is page‐oriented.  The pp command starts a new  page.
     Positioning,  writing, and drawing commands are performed within a page, so
     they cannot occur before the first pp command.  The  output  driver  reckons
     absolute  positioning (by the HH and VV commands) with respect to the current
     page’s origin at the top left corner, and all other positioning relative to
     the drawing position on the page.

     The trailer advances the drawing position to the bottom of the page and in‐
     forms the device that the document (or “job”) has ended.

CCoommmmaanndd rreeffeerreennccee
     This section describes all page description output commands, both from AT&T
     _t_r_o_f_f as well as extension commands issued by GNU _t_r_o_f_f_.

   CCoommmmeenntt ccoommmmaanndd
     ##_a_n_y_t_h_i_n_g⟨line‐break⟩
            Apply comment annotation.  Ignore any characters from the ##  charac‐
            ter  up  to the next newline.  Each comment can be preceded by arbi‐
            trary syntactical space, and every command can be  terminated  by  a
            comment.

   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 white‐
     space.  Optionally, _s_y_n_t_a_c_t_i_c_a_l _s_p_a_c_e can be inserted  before,  after,  and
     between  the  command  letter and its arguments.  All of these commands are
     stackable, i.e., they can be preceded by other simple commands or  followed
     by  arbitrary  other  commands  on the same line.  A separating _s_y_n_t_a_c_t_i_c_a_l
     _s_p_a_c_e is necessary only when two integer arguments would clash  or  if  the
     preceding argument ends with a string argument.

     CC _i_d⟨white‐space⟩
            Typeset the glyph of the special character _i_d.  Trailing syntactical
            space  is  necessary  to  allow special character names of arbitrary
            length.  The drawing position is not advanced.

     cc _c    Typeset the glyph of the ordinary 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 allowed
            negative _n_; GNU _t_r_o_f_f does not produce such values, but _g_r_o_f_f’s out‐
            put 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 between
                   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, yel‐
                   low, 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 normally a
            non‐negative  integer.   The  drawing position is not advanced.  The
            hhttmmll and xxhhttmmll devices use this command with negative _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 ig‐
            nores it.  See vv and VV.

     pp _n    Begin a new page, setting its number to _n.  Each  page  is  indepen‐
            dent,  even  from those using the same number.  The vertical drawing
            position is set to 0.  All positioning, writing,  and  drawing  com‐
            mands  are interpreted in the context of a page, so a 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 “Compatibility” 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  optional  second
            integer  argument  is ignored (this allows the formatter to generate
            an even number of arguments).  Each glyph  is  set  at  the  current
            drawing  position, and the position is then advanced horizontally by
            the glyph’s width.  A glyph’s width is read from its metrics in  the
            font  description file, scaled to the current type size, and rounded
            to a multiple of the horizontal motion quantum.  Use the  CC  command
            to  emplace  glyphs of special characters.  The tt 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).

     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  horizontally  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  allowed
            negative _n_; GNU _t_r_o_f_f does not produce such values, but _g_r_o_f_f’s out‐
            put driver library handles them.

     ww      Indicate  an  inter‐word space.  No action is performed; the command
            is present to make the output more easily parsed.   Only  inter‐word
            spaces  on  an  output  line (be they breakable or not) are thus de‐
            scribed; those resulting from horizontal motion escape sequences are
            not.  GNU _t_r_o_f_f issues this command but _g_r_o_f_f’s  output  driver  li‐
            brary ignores it.  See hh and HH.

   GGrraapphhiiccss ccoommmmaannddss
     Each  graphics  or  drawing command in the page description language starts
     with the letter “DD”, followed by one or two characters that specify a  sub‐
     command;  this  is  followed by a fixed or variable number of integer argu‐
     ments that are separated by a single space character.  A “DD”,  command  may
     not be followed by another command on the same line (apart from a comment),
     so each “DD” command is terminated by a syntactical line break.

     GNU  _t_r_o_f_f output follows AT&T _t_r_o_f_f’s output conventions (no space between
     command and subcommand, all arguments are preceded by a single space  char‐
     acter),  but  _g_r_o_f_f’s parser allows optional space between the command let‐
     ters and makes the space before the first  argument  optional.   As  usual,
     each space can be any sequence of tab and space characters.

     Some  graphics  commands  can take a variable number of arguments.  In this
     case, they are integers representing a size measured in basic units uu.  The
     _h arguments stand for horizontal distances where positive means right, neg‐
     ative left.  The _v arguments stand for vertical  distances  where  positive
     means  down,  negative up.  All these distances are offsets relative to the
     current location.

     Each graphics command directly corresponds to a _t_r_o_f_f \\DD  escape  sequence.
     See subsection “Drawing commands” of _g_r_o_f_f(7).

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

     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 off‐
            set (_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 posi‐
            tion; then move the current position to the rightmost point  of  the
            circle.  An optional second integer argument is ignored (this allows
            the  formatter  to generate an even number of arguments).  This com‐
            mand is a GNU extension.

     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 posi‐
            tion to the rightmost point of the circle.

     DDEE _h _v⟨line‐break⟩
            Draw a solid ellipse in the current fill color with a horizontal di‐
            ameter of _h and a vertical diameter of _v  (both  integers  in  basic
            units  uu) with the leftmost point at the current position; then move
            to the rightmost point of the ellipse.  This command is a GNU exten‐
            sion.

     DDee _h _v⟨line‐break⟩
            Draw an outlined ellipse with a horizontal diameter of _h and a  ver‐
            tical  diameter of _v (both integers in basic units uu) with the left‐
            most 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 compo‐
            nents  are  specified as integer arguments between 0 and 65536.  The
            number of color components and their meaning vary for the  different
            color  schemes.   These commands are generated by GNU _t_r_o_f_f’s escape
            sequences “\\DD''FF ...''” \\MM (with no other corresponding graphics  com‐
            mands).  No position changing.  This command is a GNU 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, magenta, and yel‐
                   low.

            DDFFdd ⟨line‐break⟩
                   Set fill color for solid drawing objects to the default  fill
                   color value (black in most cases).  No component arguments.

            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, magenta, 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 command is superseded by “DDFFgg”.

            _n<0 or _n>1000
                   Set  the  filling  color to the color that is currently being
                   used for the text and the outline, see command mm.  For  exam‐
                   ple, the command sequence

                          mg 0 0 65536
                          Df -1

                   sets all colors to blue.

            This command is a GNU 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  reasons,  the
            position  is changed by adding the sum of all arguments with odd in‐
            dex to the current horizontal position and the even ones to the ver‐
            tical position.  Although this doesn’t make sense  it  is  kept  for
            compatibility.  This command is a _g_r_o_f_f extension.

     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 argu‐
            ments, but draws a solid polygon in the current  fill  color  rather
            than  an  outlined polygon.  The position is changed in the same way
            as with DDpp.  This command is a GNU 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 compatibility.  This command is a GNU ex‐
            tension.

   DDeevviiccee ccoonnttrrooll ccoommmmaannddss
     Each device control command starts with the letter “xx”, followed by a space
     character (optional or arbitrary space or tab in GNU _t_r_o_f_f) and  a  subcom‐
     mand letter or word; each argument (if any) must be preceded by a syntacti‐
     cal  space.   All “xx”, commands are terminated by a syntactical line break;
     no device control command can be followed by another command  on  the  same
     line (except a comment).

     The  subcommand  is basically a single letter, but to increase readability,
     it can be written as a word, i.e., an arbitrary sequence of characters ter‐
     minated by the next tab, space, or newline character.   All  characters  of
     the  subcommand  word  but  the first are simply ignored.  For example, GNU
     _t_r_o_f_f outputs the initialization command “xx ii” as “xx iinniitt” and the  resolu‐
     tion command “xx rr” as “xx rreess”.

     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 reports.
            This is useful for remembering the original  file  name  when  _g_r_o_f_f
            uses  its  internal piping mechanism.  The input file is not changed
            by this command.  This command is a GNU 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  “Com‐
            patibility” below.

     xxii ⟨line‐break⟩
            (_i_n_i_t control command)
            Initialize device.  This is the third command of the header.

     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 arguments are
            positive  integers  in  basic  units uu per inch.  This is the second
            command of the header.

     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 device‐independent _t_r_o_f_f output.

     xxtt ⟨line‐break⟩
            (_t_r_a_i_l_e_r control command)
            Generate  trailer  information, if any.  In ggrrooffff, this is currently
            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‐white‐
            space  characters terminated by whitespace.  The possible names cor‐
            respond to those of _g_r_o_f_f’s --TT option.  This is the first command of
            the header.

     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 otherwise.  This command
            is a GNU 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  fol‐
            lowing  this  command  starts with a ++ character this line is inter‐
            preted as a continuation line in the following sense.  The ++ is  ig‐
            nored,  but  a  newline character is sent instead to the device, the
            rest of the line is sent uninterpreted.  The  same  applies  to  all
            following lines until the first character of a line is not a ++ char‐
            acter.   This  command is generated by the _g_r_o_f_f escape sequence \\XX.
            Line continuation is a GNU extension.

   LLeeggaaccyy ccoommpprreesssseedd eennccooddiinngg
     AT&T _t_r_o_f_f primarily emitted glyphs by writing two digits (a  motion)  fol‐
     lowed  by a single character corresponding to a glyph.  This syntax is less
     a command itself than a compressed encoding of the cc and hh commands.

     _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 separating 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 al‐
            most unreadable.

     For modern high‐resolution devices, this command is impractical because the
     widths of the glyphs have a greater magnitude in basic units than two deci‐
     mal digits can represent.  In _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 pro‐
     vide greater functionality and superior troubleshooting capacity.

CCoommppaattiibbiilliittyy
     The page description language of AT&T _t_r_o_f_f  was  first  documented  in  “A
     Typesetter‐independent  TROFF”,  by  Brian  Kernighan, and by 1992 the AT&T
     _t_r_o_f_f manual was updated to incorporate a description of it.

     _g_r_o_f_f’s page description language is compatible with this specification ex‐
     cept in the following aspects.

     •  AT&T device‐independent _t_r_o_f_f’s quasi‐device independence is not yet im‐
        plemented.

     •  The printing hardware of the early 1980s differed from today’s.  _g_r_o_f_f’s
        output device names also differ from those of AT&T  _t_r_o_f_f  For  example,
        the  PostScript  device  in  AT&T _t_r_o_f_f_, ppoosstt (implemented by the driver
        command _d_p_o_s_t), has a resolution of only 720 units  per  inch,  suitable
        for  printers  of  decades  past.  _g_r_o_f_f’s ppss device has a resolution of
        72000 units per inch.  In principle, by implementing a rescaling  mecha‐
        nism, _g_r_o_f_f could come to emulate AT&T’s ppoosstt device.

     •  While  the  B‐spline  command DD~~ is reliably interpreted by _g_r_o_f_f’s page
        description language parser, some output drivers don’t implement drawing
        routines for it.

     •  In GNU _t_r_o_f_f_, the argument to the commands ss and xx HH  uses  an  implicit
        unit  of scaled points zz whereas AT&T _t_r_o_f_f uses spacing points pp.  This
        isn’t an incompatibility, but a compatible extension, for both units co‐
        incide for any device without a ssiizzeessccaallee directive in  its  _D_E_S_C  file,
        including all postprocessors from AT&T and _g_r_o_f_f’s text (_n_r_o_f_f‐mode) de‐
        vices.   _g_r_o_f_f  devices  that use ssiizzeessccaallee either do not exist for AT&T
        _t_r_o_f_f have a different name, or seem to have a different resolution.  So
        conflicts are very unlikely.

     •  The drawing position after  the  commands  “DDpp”,  “DDPP”,  and  “DDtt”,  are
        processed  is illogical.  Since old versions of GNU _t_r_o_f_f had this wart,
        we’ve retained it for compatibility, but may change it  in  the  future.
        Wrap these drawing commands with the \\ZZ escape sequence to both overcome
        the  illogical  positioning and keep your input working consistently re‐
        gardless of the wart’s presence in the implementation.

     The differences  between  _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_4_._1_/_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  page  description
     language  and that of GNU _t_r_o_f_f.  It has since been expanded and revised 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  Lem‐
     berg,  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 page description lan‐
     guage 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 page description language.

     _g_r_o_f_f(1)
            documents the --ZZ option and contains pointers to further _g_r_o_f_f docu‐
            mentation.

     _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 scaling parameters of _D_E_S_C (device description) files.

     _t_r_o_f_f(1)
            generates the language documented here.

     _r_o_f_f(7)
            presents historical aspects and the general structure of  _r_o_f_f  sys‐
            tems.

     _g_r_o_f_f___d_i_f_f(7)
            enumerates  differences between the output of AT&T _t_r_o_f_f and that of
            GNU _t_r_o_f_f.

     _g_x_d_i_t_v_i_e_w(1)
            is a viewer for device‐independent _t_r_o_f_f output.

     _R_o_f_f_._j_s
            is  a  viewer  for  device‐independent  _t_r_o_f_f  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.24.1                       2026‐04‐22                       _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) document
     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  in‐
     stalled  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.
     The  “tmac”  name  originated  in  early Unix culture as an abbreviation of
     “_t_r_o_f_f macros”.

     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.   A  macro  file’s name must have 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.
     Alternatively, a _g_r_o_f_f document requiring a macro file can load it with the
     mmssoo (“macro source”) request.

     Macro files are named for their most noteworthy application,  but  a  macro
     file need not define any macros.  It can restrict itself to defining regis‐
     ters and strings or invoking other _g_r_o_f_f requests.  It can even be empty.

     Encode  macro files in ISO 646:1991 IRV (US‐ASCII) or ISO Latin‐1 (8859‐1).
     To prepare for a future _g_r_o_f_f  release  supporting  UTF‐8  input,  restrict
     files  to  ISO  646  codes.  _s_o_e_l_i_m(1) by design does not interpret mmssoo re‐
     quests, and the encodings used by documents  employing  a  macro  file  can
     vary.

MMaaccrroo ppaacckkaaggeess
     Some  macro  packages (“major” or “full‐service”) assume responsibility for
     page layout and other critical functions; others (“supplemental” or “auxil‐
     iary”) do not.  GNU _r_o_f_f provides most major macro packages found  in  AT&T
     and  BSD Unix systems, an additional full‐service package, and many supple‐
     mental packages.  Multiple full‐service macro packages cannot  be  used  by
     the same document.  Auxiliary packages can, in general, be freely combined,
     though attention to their use of the _g_r_o_f_f language name spaces for identi‐
     fiers  (particularly  registers, macros, strings, and diversions) should be
     paid.  Name space management challenged AT&T _t_r_o_f_f users; GNU _t_r_o_f_f’s  sup‐
     port  for  arbitrarily long identifiers affords few excuses for name colli‐
     sions, apart from attempts at compatibility with the demands of  historical
     documents.

   MMaann ppaaggeess
     Two  full‐service macro packages are specialized for formatting Unix refer‐
     ence manuals; they do not  support  features  like  footnotes  or  multiple
     columnation.

     _a_n       constructs  man  pages  in  a format introduced by Seventh Edition
              Unix (1979).  Its macro interface is small, and the package widely
              used; see _g_r_o_f_f___m_a_n(7).

     _d_o_c      constructs man pages in a format introduced by 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    recognizes a document’s use of _a_n or _d_o_c and loads the correspond‐
              ing macro package.  Multiple man pages, in either format,  can  be
              handled; _a_n_d_o_c reloads each macro package as necessary.

   GGeenneerraall ffuullll‐‐sseerrvviiccee ppaacckkaaggeess
     The  following  packages each support composition of documents of any kind,
     from single‐page memos to lengthy monographs.  They are  similar  in  func‐
     tionality; select one that suits your taste.

     _m_e     originates in 2BSD (1978); see _g_r_o_f_f___m_e(7).

     _m_m     originates  in  Programmer’s  Workbench  (PWB)  Unix 1.0 (1977); see
            _g_r_o_f_f___m_m(7).

     _m_o_m    was contributed to _g_r_o_f_f in 2002, and freely exercises its many  ex‐
            tended features.  See _g_r_o_f_f___m_o_m(7).

     _m_s     originates in Sixth Edition Unix (1975); see _g_r_o_f_f___m_s(7).

   LLooccaalliizzaattiioonn ppaacckkaaggeess
     For  Western  languages, an auxiliary package for localization sets the hy‐
     phenation mode and loads hyphenation patterns and exceptions.  Localization
     files can also adjust the date format and provide translations  of  strings
     used  by  some of the full‐service macro packages; alter the input encoding
     (see the next section); and change the amount  of  supplemental  inter‐sen‐
     tence  space.  For Eastern languages, the localization file defines charac‐
     ter classes and sets flags on them.  By default, _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  encoding
            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 encoding
            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 orthography,
            and _d_e_n_._t_m_a_c does the same for the new  orthography  (“Rechtschreib‐
            reform”).

     _e_n     English.  Sets the input encoding to Latin‐1 by loading _l_a_t_i_n_1_._t_m_a_c.

     _e_s     Spanish;  localizes _m_a_n, _m_e, _m_m, _m_o_m, and _m_s.  Sets the input encod‐
            ing to Latin‐9 by loading _l_a_t_i_n_9_._t_m_a_c.

     _f_r     French; localizes _m_a_n, _m_e, _m_m, _m_o_m, and _m_s.  Sets the input encoding
            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.  Sets the input  encod‐
            ing to Latin‐1 by loading _l_a_t_i_n_1_._t_m_a_c.

     _j_a     Japanese.

     _p_l     Polish; localizes _m_a_n, _m_e, _m_m, _m_o_m, and _m_s.  Sets the input encoding
            to Latin‐2 by loading _l_a_t_i_n_2_._t_m_a_c.

     _r_u     Russian;  localizes _m_a_n, _m_e, _m_m, _m_o_m, and _m_s.  Sets the input encod‐
            ing to KOI8‐R by loading _k_o_i_8_‐_r_._t_m_a_c.

     _s_v     Swedish; localizes _m_a_n, _m_e, _m_m, _m_o_m, and _m_s.  Sets the input  encod‐
            ing  to Latin‐1 by loading _l_a_t_i_n_1_._t_m_a_c.  Some of the localization 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
     Localization  influences  automatic hyphenation in two distinct but related
     respects.  A macro file specific to a  character  coding  identifies  which
     character  codes  correspond  to letters expected in the language’s hyphen‐
     ation pattern files and sets up case equivalences  for  those  letters.   A
     language’s  macro  file determines which of these letters are equivalent to
     other letters for hyphenation purposes.

     For example, in  English,  the  letter  “ñ”  occurs  in  loan  words.   The
     _l_a_t_i_n_1_._t_m_a_c  and  _l_a_t_i_n_9_._t_m_a_c macro files define a hyphenation code for “ñ”
     and make “Ñ” equivalent to it.  The English localization file _e_n_._t_m_a_c  fur‐
     thermore  makes  “ñ” equivalent to “n”.  In Spanish (_e_s_._t_m_a_c), however, “ñ”
     and “n” are _n_o_t equivalent.  The language localization file loads an appro‐
     priate encoding localization file; a document need not do so directly.

     _l_a_t_i_n_1
     _l_a_t_i_n_2
     _l_a_t_i_n_5
     _l_a_t_i_n_9  support the ISO Latin‐1, Latin‐2, Latin‐5,  and  Latin‐9  encodings
             (8859‐1, 8859‐2, 8859‐9, and 8859‐15, respectively).

     _k_o_i_8_-_r  supports  the  KOI8‐R  encoding.   KOI8‐R  code points in the range
             0x80–0x9F are not valid input to GNU _t_r_o_f_f;  see  section  “Identi‐
             fiers” in _g_r_o_f_f(7).  This should be no impediment to practical doc‐
             uments, as these KOI8‐R code points do not encode letters, but box‐
             drawing symbols and characters that are better obtained via special
             character escape sequences; see _g_r_o_f_f___c_h_a_r(7).

   GGeenneerraall 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 with  the
                “--dd  ppaappeerr==_f_m_t” option to _t_r_o_f_f.  Valid _f_m_ts 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 envelopes,  are  in  portrait
                orientation:  the longer measurement is vertical.  Appending “l”
                (ell) to any of these  denotes  landscape  orientation  instead.
                This  macro  file  assumes one‐inch horizontal margins, and sets
                registers recognized by the _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  packages’  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, respectively, 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 typesetter (but not a terminal).

     _p_d_f_p_i_c     provides a single macro, PPDDFFPPIICC, that operates in two modes.  If
                it is not used with _g_r_o_p_d_f, the given _f_i_l_e must be a PDF; PPDDFFPPIICC
                then relies on the external program _p_d_f_t_o_p_s(1)  to  convert  the
                PDF to an encapsulated PostScript (EPS) file and calls the PPSSPPIICC
                macro  with which it shares an interface.  If output is to a PDF
                document, PPDDFFPPIICC uses the “ppddff:: ppddffppiicc” device extension command
                (see _g_r_o_p_d_f(1)); the given _f_i_l_e can then be a PDF or any graphic
                file format supported by _g_r_o_p_d_f.

                Since PPDDFFPPIICC needs to discover the width and height of the image
                (to check if sufficient room exists to place it on the page), it
                has dependencies on external programs as shown below.

                        ┌───────┬────────────┬─────────┬─────────────┐
                        │       │ _p_d_f_i_n_f_o(1) │ _f_i_l_e(1) │ _i_d_e_n_t_i_f_y(1) │
                        ├───────┼────────────┼─────────┼─────────────┤
                        │ _._p_d_f  │     ✓      │    ✓    │      ✓      │
                        ├───────┼────────────┼─────────┼─────────────┤
                        │ _._j_p_g  │     ✗      │    ✓    │      ✓      │
                        ├───────┼────────────┼─────────┼─────────────┤
                        │ _._j_p_2  │     ✗      │    ✗    │      ✓      │
                        ├───────┼────────────┼─────────┼─────────────┤
                        │ other │     ✗      │    ✗    │      ✓      │
                        └───────┴────────────┴─────────┴─────────────┘

                To include image formats such as PNG, PAM, and GIF,  _g_r_o_p_d_f  re‐
                lies upon PerlMagick modules to embed the graphic.  They are not
                needed for the types listed in the table above.

                If the required programs are not available, _f_i_l_e is treated as a
                PDF; failure is likely if it is not one.

     _p_i_c        supplies definitions of the macros PPSS, PPEE, PPFF, and PPYY, used 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.

     _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  extension
                command  supported  by  _g_r_o_p_d_f(1).  Using this package, _g_r_o_f_f _m_s
                documents 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 that 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 oddly terse to modern eyes.  The formatter’s --mm option was  the  main
     means  of  loading  a macro package, and its argument had to follow immedi‐
     ately without intervening space.  This looked like a long option name  pre‐
     ceded  by  a  single  minus——a  sensation in the computer stone age.  Macro
     packages therefore came to be known by names that started with  the  letter
     “m”,  which  was omitted from the name of the macro file as stored on disk.
     For example, the manuscript macro package was stored as _t_m_a_c_._s  and  loaded
     with the option --mmss.  It has since become conventional in operating systems
     to  use  a  suffixed  file name extension to suggest a file type or format,
     thus we see _r_o_f_f documents with names ending in _._m_a_n, _._m_e, and so on.

     _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  surprise  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 accommo‐
     dates 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.

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.   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 in‐
     stead, and vice versa.

     Alternatively,  one  could  include a macro file with the request “ssoo _f_i_l_e_‐
     _n_a_m_e”; the argument is resolved as _f_o_p_e_n(3) would, from the current working
     directory of the formatter.  This approach was inadequate to  locate  macro
     packages, since systems stored them in varying locations.  GNU _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.

     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 by specifying the  --ss  option  to  _g_r_o_f_f(1).
     _m_a_n(1)  librarian programs typically run _s_o_e_l_i_m automatically.  (As a rule,
     macro packages themselves do not require preprocessing.)

WWrriittiinngg mmaaccrrooss
     A _r_o_f_f(7) document is a text file that is enriched by predefined formatting
     constructs, such as requests, escape sequences, strings, numeric registers,
     and macros from a macro package.  _r_o_f_f(7) describes these elements.

     To give a document a personal style, it is most useful to extend the exist‐
     ing elements by defining some macros for repeating tasks;  the  best  place
     for this is near the beginning of the document or in a separate file.

     Macros  without  arguments  are  just  like strings.  But the full power of
     macros occurs when arguments are passed with  a  macro  call.   Within  the
     macro  definition, the arguments are available as the escape sequences \\$$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).

   DDrraaffttiinngg mmaaccrrooss
     One  approach  temporarily  disables escape sequences by bracketing a macro
     definition with eeoo and eecc requests.

            .eo
            .ds midpart was called with the following
            .de print_args
            \f[I]\$0\f[] \*[midpart] \n[.$] arguments: \$*
            ..
            .ec

     The above procedure has limitations; it is unsuitable for a macro that  re‐
     quires  certain  interpolations  at the time it is defined, or for indirect
     definitions of identifiers.  See section “Copy mode” of _g_r_o_f_f(7).  In  such
     cases,  you  might define and test the macro with the escape character dou‐
     bled before escape sequences that are interpreted even in copy  mode,  then
     bracket  it  with eeoo and eecc requests, un‐double the escape characters, then
     test again.

   TTiippss ffoorr mmaaccrroo ddeeffiinniittiioonnss
     •  Use only control lines in macro definitions; that is, start every  input
        line  with  a  control character.  _g_r_o_f_f’s nnoopp request makes use of text
        lines unnecessary.

               .de Text
               .  if (\\n[.$] == 0) \
               .    return
               .  nop \&\\$*\&
               ..

     •  Write a comment macro that works in  both  draft  and  non‐draft  modes;
        since  the escape character is disabled in draft mode, trouble might oc‐
        cur when comment escape sequences are used.

               .de c
               ..
               .c This is my comment.

     •  Comment lengthy macro definitions.

     •  Use empty requests, and indentation after control characters, to clarify
        a macro’s structure.

AAuutthhoorrss
     This document was written by Werner Lemberg 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  Lem‐
     berg,  is  the  primary _g_r_o_f_f manual.  You can browse it interactively with
     “info groff”.

     _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.24.1                       2026‐04‐22                      _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 device‐in‐
     dependent _t_r_o_f_f typesetting system.  See _r_o_f_f(7) for a survey of and  back‐
     ground 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  discus‐
     sion.  It is written in Texinfo; you can browse it interactively with “info
     groff”.   Additional formats, including plain text, HTML, TeX DVI, and PDF,
     may be available in _/_u_s_r_/_s_h_a_r_e_/_d_o_c_/_g_r_o_f_f_-_b_a_s_e.

     We apply the term “groff” to the language documented here, the  GNU  imple‐
     mentation of the overall system, the project that develops that system, and
     the command of that name.  In the first sense, _g_r_o_f_f is an extended dialect
     of the _r_o_f_f language, for which many similar implementations exist.

     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 pro‐
     gram that reads device and font  descriptions  (_g_r_o_f_f___f_o_n_t(5)),  interprets
     the  _g_r_o_f_f  language  expressed in input text, and translates it into a de‐
     vice‐independent page description language (_g_r_o_f_f___o_u_t(5)) that  is  usually
     then  post‐processed  by an output driver to produce PostScript, PDF, HTML,
     DVI, or terminal output.  We speak of “the formatter” when  describing  be‐
     havior that is generally true of _t_r_o_f_f and _n_r_o_f_f programs.

IInnppuutt ffoorrmmaatt
     Organize  input to GNU _t_r_o_f_f into lines separated by the Unix newline char‐
     acter (U+000A), using the character encoding  it  recognizes:  ISO  Latin‐1
     (8859‐1).   We  recommend  use  of  ISO 646:1991 IRV (US‐ASCII) or (equiva‐
     lently) the Basic Latin subset of ISO 10646 (Unicode); see _g_r_o_f_f___c_h_a_r(7).

     Some control characters (from the sets “C0 Controls” and “C1  Controls”  as
     Unicode  describes  them)  are invalid as input characters.  GNU _t_r_o_f_f dis‐
     cards them upon reading.  (It also emits a warning in category “input”; see
     section “Warnings” of _t_r_o_f_f(1).)  It processes a character sequence  “foo”,
     followed by an invalid character and then “bar”, as “foobar”.

     Invalid  input  characters  comprise  00xx0000, 00xx00BB, 00xx00DD–00xx11FF, and 00xx8800–00xx99FF.
     (Historically, control characters like ASCII STX, ETX, and BEL  (Control+B,
     Control+C,  and  Control+G)  respectively) have been observed in _r_o_f_f docu‐
     ments, particularly in macro packages employing them as delimiters with the
     output comparison operator to try to avoid collisions with the  content  of
     arbitrary  user‐supplied  parameters  (see  subsection “Conditional expres‐
     sions” below).  We discourage this expedient; in GNU _t_r_o_f_f it  is  unneces‐
     sary  (outside  of compatibility mode) because the program parses delimited
     arguments at a different input level than their surrounding  context.   See
     section  “Miscellaneous”  of  _g_r_o_f_f___d_i_f_f(7).)  GNU _t_r_o_f_f uses some of these
     code points for internal purposes, making non‐trivial the extension of  the
     program  to  accept UTF‐8 or other encodings that use characters from these
     ranges.

SSyynnttaaxx cchhaarraacctteerrss
     Several input characters are syntactically significant to _g_r_o_f_f.  The  most
     important of these distinguish _c_o_n_t_r_o_l _l_i_n_e_s_, which instruct the formatter,
     from _t_e_x_t _l_i_n_e_s that are formatted as output.

     .   A dot at the beginning of an input line marks it as a control line.  It
         can also follow the eell and nnoopp requests, and the condition in “iiff”, iiee,
         and “wwhhiillee” requests.  The control character invokes requests and calls
         macros by the name that follows it.  The cccc request can change the con‐
         trol 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_, recognized
         where the control character is.  It suppresses the  (first)  break  im‐
         plied  by  the  bbpp,  ccee,  ccff, ffii, ffll, “iinn”, nnff, rrjj, sspp, ttii, and ttrrff re‐
         quests.  The requested operation takes effect at the  next  break.   It
         makes  bbrr  and  bbrrpp  nilpotent.   The no‐break control character 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  char‐
         acters.  The requests “aass”, aass11, ccff, cchhaarr, ddss, ddss11, ffcchhaarr, ffsscchhaarr, mmssoo,
         mmssooqquuiieett,  nnxx,  “ooppeenn”,  ooppeennaa,  ppii,  sscchhaarr, “ssoo”, ssooqquuiieett, ssyy, and ttrrff
         strip a leading neutral double quote from their final arguments to  al‐
         low embedding of leading spaces.  All such arguments are “strings” in a
         general  sense, representing character sequences, file names, operating
         system commands, or parameters to an output device  extension  command.
         To  include a double quote inside a quoted argument, use the \\[[ddqq]] spe‐
         cial character escape sequence (which also serves to typeset the  glyph
         in text).

     \   A backslash introduces an escape sequence.  The escape character can be
         changed  with  the 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 current escape character.

     (   An  opening  parenthesis  is  special only in certain escape sequences;
         when recognized, it introduces an argument of exactly  two  characters.
         _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 includ‐
         ing a closing bracket.

     ]   A closing bracket is special only when  an  escape  sequence  using  an
         opening bracket as an argument delimiter is being interpreted.  It ends
         the argument (list).

     Additionally,  the Control+A character (U+0001) in text is interpreted as a
     _l_e_a_d_e_r (see below).

     Horizontal whitespace characters are significant  to  _g_r_o_f_f_,  but  trailing
     spaces on text lines are ignored.

     _s_p_a_c_e    On  control  lines  and  within bracketed escape sequences, spaces
              separate arguments.  On text lines, 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 punctua‐
              tion).  The amount of space between words and  sentences  is  con‐
              trolled 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 expanded  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  On text lines, a newline formats an inter‐word space and, if fill‐
              ing  is  enabled, triggers end‐of‐sentence recognition on the pre‐
              ceding text.  See section “Line continuation” below.

     _t_a_b      A tab character on a text line causes the drawing position to  ad‐
              vance to the next defined tab stop.

SSeenntteenncceess
     Configure  the  sets  of  characters  that potentially end sentences or are
     transparent to sentence endings with the ccffllaaggss request.  Use  the  ssss  re‐
     quest to change——or eliminate——supplemental inter‐sentence space.

TTaabbss aanndd lleeaaddeerrss
     The  formatter interprets input horizontal tab characters (“tabs”) and Con‐
     trol+A characters (“leaders”) into movements to the next  tab  stop.   Tabs
     simply  move to the next tab stop; leaders place enough periods to fill the
     space.  Tab stops are by default located every half inch measured from  the
     drawing position corresponding to the beginning of the input line; see sec‐
     tion  “Page geometry” of _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, respec‐
     tively.

LLiinnee ccoonnttiinnuuaattiioonn
     When filling is enabled, input and output line breaks generally do not cor‐
     respond.  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 at a space, or in
     the middle of a word, request invocation, macro call, or  escape  sequence.
     Input line continuation is invisible to the formatter, with two exceptions:
     the  ||  operator  recognizes the new input line, and the input line counter
     register ..cc increments.

     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  enabled.   An  intervening
     control  line  that  causes  a break overrides \\cc, flushing out the pending
     output line in the usual way.  The register ..iinntt  interpolates  a  positive
     value  only if the pending output line has been continued with \\cc; this da‐
     tum 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 lim‐
     ited.  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 ob‐
     jects 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 support.

     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.
     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 mech‐
     anism, the devices supported by  _g_r_o_t_t_y(1)  recognize  the  eight  standard
     ISO  6429/ECMA‐48 color names.  (These are known vulgarly as “ANSI” colors,
     after its X3.64 standard, now withdrawn.)

MMeeaassuurreemmeennttss
     Express numeric parameters that specify measurements as integers or decimal
     fractions with an optional scaling unit suffixed.  A _s_c_a_l_i_n_g _u_n_i_t is a let‐
     ter that immediately follows the magnitude of a measurement.  Digits  after
     the decimal point are optional.

     The  formatter  scales  measurements by the specified scaling unit, storing
     them internally (with any fractional part discarded) in basic  units.   The
     device resolution can therefore be obtained by storing a value of “11ii” to a
     register, then reading the register.

     uu      Basic unit; it is at least as small as any other 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.
     zz      Typographical point; like pp, but used only with type sizes, to over‐
            come a limitation of AT&T _t_r_o_f_f.
     ss      Scaled point.
     ff      Multiplication  by  65,536; scales decimal fractions in the interval
            [0, 1] to 16‐bit unsigned integers.

     The magnitudes of other scaling units depend on the text formatting parame‐
     ters in effect.

     mm      Em; an em is equal to the current type size in points.
     nn      En; on typesetters, an en is one‐half em, but  on  terminals  an  en
            equals an em.
     vv      Vee; distance between text baselines.
     MM      Hundredth of an em.

   MMoottiioonn qquuaannttaa
     The basic unit uu is not necessarily an output device’s smallest addressable
     length;  uu  can  be  smaller to avoid integer rounding errors.  The minimum
     distances that a device can work with in the horizontal and vertical direc‐
     tions are termed its _m_o_t_i_o_n _q_u_a_n_t_a_, stored in the ..HH and ..VV registers,  re‐
     spectively.  The formatter rounds measurements 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 ba‐
     sic units if interpreted in a measurement context.  But  it  is  convenient
     for many requests and escape sequences to infer a scaling unit for an argu‐
     ment  if  none is specified.  An explicit scaling unit (not after a closing
     parenthesis) can override an undesirable default.  Effectively, the default
     unit is suffixed to the  expression  if  a  scaling  unit  is  not  already
     present.   GNU  _t_r_o_f_f’s  use  of  integer arithmetic in numeric expressions
     should also be kept in mind.

NNuummeerriicc eexxpprreessssiioonnss
     When evaluated, a _n_u_m_e_r_i_c _e_x_p_r_e_s_s_i_o_n interpolates an  integer.   GNU  _t_r_o_f_f
     recognizes the following operators.

           +   addition
           -   subtraction
           *   multiplication
           /   truncating division
           %   modulus
     ────────────────────────────────────────────
     unary +   assertion, motion, incrementation
     unary -   negation, motion, decrementation
     ────────────────────────────────────────────
           ;   scaling
          >?   maximum
          <?   minimum
     ────────────────────────────────────────────
           <   less than
           >   greater than
          <=   less than or equal
          >=   greater than or equal
           =   equal
          ==   equal
     ────────────────────────────────────────────
           &   logical conjunction (“and”)
           :   logical disjunction (“or”)
           !   logical complementation (“not”)
     ────────────────────────────────────────────
         ( )   precedence
     ────────────────────────────────────────────
           |   boundary‐relative measurement

     _t_r_o_f_f provides a set of mathematical and logical operators familiar to pro‐
     grammers——as  well  as  some unusual ones——but supports only integer arith‐
     metic.  (Provision is made for interpreting and reporting decimal fractions
     in certain cases.)  The internal data type used for computing  results  de‐
     pends  on  the  host machine but is at least a 32‐bit signed integer, which
     suffices to represent magnitudes within a range of ±2 billion.  (If  that’s
     not  enough,  see  _g_r_o_f_f___t_m_a_c(5) for the _6_2_b_i_t_._t_m_a_c macro package.)  Arith‐
     metic saturates.  (If overflow would occur, GNU _t_r_o_f_f emits  a  warning  in
     category “rraannggee”.  See section “Warnings” of _t_r_o_f_f(1).)

     Arithmetic infix operators perform a function on the numeric expressions to
     their  left and right; they are ++ (addition), -- (subtraction), ** (multipli‐
     cation), // (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.  Division and modulus by zero are errors and abort evaluation of a
     numeric expression.

     Arithmetic unary operators operate  on  the  numeric  expression  to  their
     right;  they  are  -- (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  following
     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 extremum of two operands:  >>??  (maximum)
     and <<?? (minimum).

     Comparison  operators  comprise  <<  (less than), >> (greater than), <<== (less
     than or equal), >>== (greater than or equal), and == (equal,  with  a  synonym
     ====).   When  evaluating a comparison, the formatter replaces it with “00” if
     it is false and “11” if true.  In the _r_o_f_f  language,  positive  values  are
     true, others false.

     Operate  on  truth values with the logical operators && (logical conjunction
     or “and”) and :: (logical disjunction or “or”).  They evaluate as comparison
     operators do.  A logical complementation (“not”) operator,  !!,,  works  only
     within “iiff”, “iiee”, and “wwhhiillee” requests.  Furthermore, the formatter recog‐
     nizes  !! only at the beginning of a numeric expression not contained by an‐
     other numeric expression.  In other words, !! must be the “outermost” opera‐
     tor.  Its presence elsewhere causes the expression to evaluate false.  (GNU
     _t_r_o_f_f emits a warning in category  “nnuummbbeerr”.   See  section  “Warnings”  of
     _t_r_o_f_f(1).)   This  unfortunate limitation maintains compatibility with AT&T
     _t_r_o_f_f.  Test a numeric expression for falsity within a  complex  expression
     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 expression.
     They then indicate a motion relative to the drawing position:  positive  is
     down in vertical contexts, right in horizontal ones.

     ++  and  -- are also treated differently by the following requests and escape
     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 op‐
     erators, respectively.  To negate an expression in these contexts, subtract
     it from zero or include the unary minus in parentheses with its argument.

     A  leading  || operator indicates a motion relative not to the drawing posi‐
     tion but to a boundary.  For horizontal motions, the measurement  specifies
     a distance relative to a drawing position corresponding to the beginning of
     the  _i_n_p_u_t line.  By default, tab stops reckon movements 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  delimited  escape sequence \\BB tests its argument for validity as a nu‐
     meric expression.

     A register interpolated as an operand in a numeric expression must have  an
     Arabic format; luckily, this is the default.

     Because  spaces  separate  arguments to requests, spaces are not allowed in
     numeric expressions unless parentheses surround  the  (sub)expression  con‐
     taining them.

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  or  character
     class,  hyphenation  language  code, environment, or stream.  Valid identi‐
     fiers 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
     any Unicode Basic Latin character that is not a space and  not  the  escape
     character; recall section “Input format” above.

     An  identifier  with  a closing bracket (“]”) in its name can’t be accessed
     with bracket‐form escape sequences that expect an identifier as  a  parame‐
     ter.   Similarly,  the  identifier  “(”  can’t  be interpolated _e_x_c_e_p_t with
     bracket forms.

     Beginning a macro, string, or diversion name with the character “[” or  “]”
     forecloses  use  of the _r_e_f_e_r(1) preprocessor, which recognizes input lines
     starting with “.[” and “.]”  as bibliographic reference delimiters.

     The delimited escape sequence \\AA tests its  argument  for  validity  as  an
     identifier.

     The  formatter’s  handling  of  undefined identifiers is context‐dependent.
     There is no way to invoke an undefined request; such syntax is  interpreted
     as  a  macro  call  instead.  If the identifier is interpreted as a string,
     macro, or diversion name, the formatter defines it as  empty  and  interpo‐
     lates  nothing.  (GNU _t_r_o_f_f emits a warning in category “mmaacc”.  See section
     “Warnings” of _t_r_o_f_f(1).)  Similarly, if the identifier is interpreted as  a
     register  name,  the formatter initializes it to zero and interpolates that
     value.  GNU _t_r_o_f_f emits a warning in category “rreegg”; see section “Warnings”
     in _t_r_o_f_f(1), and subsection “Interpolating registers” and section “Strings”
     below.  Attempting to use an undefined typeface, special character or char‐
     acter class, color, environment, hyphenation language code, or stream  gen‐
     erally provokes an error diagnostic.

     Identifiers  for  requests,  macros, strings, and diversions share one name
     space; special characters and character classes another.  No  other  object
     types do.

CCoonnttrrooll cchhaarraacctteerrss
     The  formatter  recognizes  a control character only at the beginning of an
     input line, or at the beginning of a branch of a control structure request;
     see section “Control structures” below.

     A few requests cause a break implicitly; invoke them with the no‐break con‐
     trol character to prevent the break.  Break suppression is its sole  behav‐
     ioral  distinction.  Employing the no‐break control character to invoke re‐
     quests that don’t cause breaks is harmless but poor style.

     The control character “..” and the no‐break control  character  “''”  can  be
     changed  with the cccc and cc22 requests, respectively.  Within a macro defini‐
     tion, 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 unrecognized
     request  is  interpreted  as  a macro call.  Defining a macro with the same
     name as a request replaces the request.  Deleting a request name  with  the
     rrmm  request makes it unavailable.  The aallss request can alias requests, per‐
     mitting them to be wrapped  or  non‐destructively  replaced.   See  section
     “Strings” below.

     There  is  no inherent limit on argument length or quantity.  Most requests
     take one or more arguments, and ignore any they do not expect.   A  request
     may  be separated from its arguments by tabs or spaces, but only spaces can
     separate an argument from its successor.  Only  one  between  arguments  is
     necessary;  any excess is ignored.  GNU _t_r_o_f_f does not allow tabs for argu‐
     ment separation.  (Plan 9 _t_r_o_f_f does.)

     Generally, a space _w_i_t_h_i_n a request argument is not relevant, not  meaning‐
     ful, or is supported by bespoke provisions, as with the ttll request’s delim‐
     iters.  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.  Com‐
     monly, authors use them to indent the source of documents or macro files.

CCaalllliinngg mmaaccrrooss
     If a macro of the desired name does not exist when  called,  the  formatter
     creates  it and assigns it an empty definition.  (GNU _t_r_o_f_f emits a warning
     in category “mmaacc”.  See section “Warnings” in _t_r_o_f_f(1).)  Calling an  unde‐
     fined  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  neutral
     double quotes ‘""’.  Horizontal motion escape sequences are sometimes a bet‐
     ter choice for arguments to be formatted as text.

     The  foregoing raises the question of how to embed neutral double quotes or
     backslashes in macro arguments when _t_h_o_s_e characters are desired as  liter‐
     als.   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  available
     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 complex 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 occur
     intermixed with text and may appear in arguments to requests,  macros,  and
     other  escape  sequences.   An  escape sequence is introduced by the escape
     character, a backslash \\.  The next character selects  the  escape’s  func‐
     tion.

     Escape sequences vary in length.  Some take an argument, and of those, some
     have different syntactical forms for a one‐character, two‐character, or ar‐
     bitrary‐length  argument.  Others accept _o_n_l_y an arbitrary‐length argument.
     In the former scheme, a one‐character argument follows the function charac‐
     ter immediately, an opening parenthesis “((” introduces a two‐character  ar‐
     gument  (no  closing  parenthesis  is  used),  and an argument of arbitrary
     length is enclosed in brackets “[[]]”.  In the latter scheme,  the  user  se‐
     lects a delimiter character.  A few escape sequences are idiosyncratic, and
     support  both of the foregoing conventions (\\ss), designate their own termi‐
     nation sequence (\\??), consume input until the next newline (\\!!, \\"", \\##), or
     support an additional modifier character (\\ss again, and \\nn).   In  no  case
     can an escape sequence parameter contain an unescaped newline.

     If  the character that follows the escape character does not identify a de‐
     fined operation, the formatter ignores the escape  character.   (GNU  _t_r_o_f_f
     emits a warning in category “eessccaappee”.  See section “Warnings” in _t_r_o_f_f(1).)

     Escape  sequence interpolation is of higher precedence than escape sequence
     argument interpretation.  This rule affords flexibility in using escape se‐
     quences to construct parameters to other escape sequences.

     The escape character can be interpolated (\\ee).  Requests permit the  escape
     mechanism  to  be  deactivated  (eeoo)  and restored, or the escape character
     changed (eecc), and to save and restore it (eeccss and eeccrr).

DDeelliimmiitteerrss
     Some escape sequences that require parameters use delimiters.  The  neutral
     apostrophe  ''  is a popular choice and shown in this document.  The neutral
     double quote "" is also commonly seen.  Punctuation characters are the  best
     choice  (and  most portable to other _t_r_o_f_fs, except for those meaningful in
     numeric expressions; see below.

     The following escape sequences are not themselves delimited, and  thus  are
     allowed  as delimiters: \\_s_p_a_c_e, \\%%, \\||, \\^^, \\{{, \\}}, \\'', \\``, \\--, \\__, \\!!, \\??,
     \\)), \\//, \\,,, \\&&, \\::, \\~~, \\00, \\aa, \\cc, \\dd, \\ee, \\EE, \\pp, \\rr, \\tt, and  \\uu.   How‐
     ever,  we discourage using them this way; they can make the input confusing
     to read.  (The _e_q_n(1) and _t_b_l(1) preprocessors use parameterized  but  non‐
     delimited  special character escape sequences \\(( and \\[[ to bracket portions
     of their output.)  An invalid escape sequence is valid as  a  delimiter  if
     the character after the escape character would be valid.

     The  escape  sequences  \\DD, \\hh, \\HH, \\ll, \\LL, \\NN, \\RR, \\ss, \\SS, \\vv, and \\xx pro‐
     hibit delimiters that are meaningful in numeric expressions,  because  they
     accept  numeric  expressions  as  (or within) their arguments.  For consis‐
     tency, GNU _t_r_o_f_f prohibits the same delimiters in the argument  to  the  ttll
     request.  The “iiff”, iiee, and “wwhhiillee” requests each interpret their first ar‐
     gument as a conditional expression; only characters that are not meaningful
     as  operators  in that context can be used as output comparison delimiters.
     The following inputs are therefore invalid as delimiters in GNU _t_r_o_f_f.

            •  the numerals 0–9 and the decimal point “..”

            •  the (single‐character) operators ++--//**%%<<>>==&&::(())||

            •  any escape sequences other than \\%%, \\::, \\{{, \\}}, \\'', \\``,  \\--,  \\__,
               \\!!, \\//, \\cc, \\ee, and \\pp

     Delimiter syntax is flexible (and laborious to describe) primarily for his‐
     torical  reasons;  the  foregoing  restrictions need be kept in mind mainly
     when using GNU _t_r_o_f_f in AT&T compatibility mode.  Normally, 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 arguments you input, not those that result from  interpolation.   Typi‐
     cally,   ''   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 render‐
     ing  a  glyph  to  the output.  \\&& interpolates a dummy character, which is
     constitutive of output but invisible.  Its presence alters the  interpreta‐
     tion  context  of a subsequent input character, and enjoys several applica‐
     tions: preventing the insertion of extra  space  after  an  end‐of‐sentence
     character,  preventing  interpretation of a control character at the begin‐
     ning of an input line, preventing kerning between two glyphs,  and  permit‐
     ting  the  ttrr  request  to  remap a character to “nothing”.  \\)) works as \\&&
     does, except that it does not cancel a pending end‐of‐sentence state.

PPaaggee ccoonnttrrooll
     Discretionary page breaks can prevent the unwanted separation  of  content.
     A  new  page  number takes effect during page ejection; see subsection “The
     implicit page trap” below.  The bbpp request breaks  the  page,  incrementing
     the  page  number by one (or setting it per the supplied argument).  The nnee
     request forces a page break if insufficient vertical space is available (it
     asserts “needed” space).  ssvv requires vertical space as nnee does,  but  also
     _s_a_v_e_s it for later output by the ooss request.

     The  nnll  register interpolates the vertical drawing position as of the most
     recently typeset output line.  It does not necessarily (and often does not)
     represent that of the pending output line, because the formatter  does  not
     determine  the  position  of  its baseline until it is output.  Assigning a
     value to nnll sets the vertical drawing position in advance of further  modi‐
     fications  to  baseline  positioning arising from alterations to type size,
     changes to vertical spacing, or application of extra pre‐ or  post‐vertical
     spacing.

     When  the  formatter  starts,  the transition to the first page has not yet
     happened——nnll is negative.  If you plant a page location  trap  at  vertical
     position  “00” (idiomatically to format a header), you can assign a negative
     value to nnll to spring that trap even if the page has already  started  (see
     subsection “Page location traps” below).

CCoonnttrrooll ssttrruuccttuurreess
     _g_r_o_f_f  has  “if” and “while” control structures like other languages.  How‐
     ever, the syntax for grouping multiple input lines in the branches or  bod‐
     ies of these structures is unusual.

     They  have  a  common form: the request name is (except for eell “else”) fol‐
     lowed by a conditional expression _c_o_n_d_‐_e_x_p_r; the remainder of the line, _i_n_‐
     _p_u_t, is interpreted as if it were an input line.  Any  quantity  of  spaces
     between  arguments to requests serves only to separate them; leading spaces
     in _i_n_p_u_t are therefore not seen.  _i_n_p_u_t effectively _c_a_n_n_o_t be  omitted;  if
     _c_o_n_d_‐_e_x_p_r is true and _i_n_p_u_t is empty, the newline at the end of the control
     line is interpreted as a blank line (and therefore a blank text line).

     It  is frequently desirable for a control structure to govern more than one
     request, macro call, or text line, or combination of  the  foregoing.   The
     opening and closing brace escape sequences \\{{ 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 subsequent to
     the request’s conditional expression.  \\}} should  appear  on  a  line  with
     other  occurrences of itself as necessary to match \\{{ sequences.  It can be
     preceded by a control character, spaces, and tabs.  Input after  any  quan‐
     tity  of \\}} sequences on the same line is processed only if all the preced‐
     ing conditions to which they correspond are true.  Furthermore, a \\}}  clos‐
     ing  the body of a “wwhhiillee” request must be the last such escape sequence on
     an input line.

     GNU _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 under an internal
     name  and deletes it when the loop finishes.  The operation of a macro con‐
     taining a “wwhhiillee” request can slow significantly  if  its  body  is  large.
     Each  time  GNU  _t_r_o_f_f  interpolates  the  macro,  it parses and stores the
     “wwhhiillee” body again.   An  often  better  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, which is parsed only once (unless you redefine it).   To
     prevent  infinite  loops,  GNU _t_r_o_f_f limits the default number of available
     recursion levels to 1,000 or somewhat less (because things other than macro
     calls can be on the input stack).  You can disable this protective measure,
     or alter the limit, by setting the sslliimmiitt register.   See  section  “Debug‐
     ging” below.

   CCoonnddiittiioonnaall eexxpprreessssiioonnss
     The “iiff”, iiee, and “wwhhiillee” requests test the truth values of numeric expres‐
     sions.  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 val‐
     ues 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 character _g is defined.
              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) and is not a numeric ex‐
     pression, the formatter 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 comparands _s_1 and _s_2 produces the same output commands.
     Other delimiters can be used in place of the neutral apostrophes; see  sec‐
     tion  “Delimiters”  above.   _t_r_o_f_f  formats  _s_1  and _s_2 in separate scratch
     buffers; after comparison, it discards the resulting data.   The  resulting
     glyph  properties,  including  font  family,  style,  size, and slant, must
     match, but not necessarily the requests and/or escape sequences used to ob‐
     tain them.  Motions must match in orientation and magnitude to  within  the
     applicable  horizontal  or  vertical  motion  quantum  of the device, after
     rounding.

     Surround the comparands with \\?? to avoid formatting them; this causes  them
     to  be compared character by character, as with string comparisons in other
     programming languages.  Since GNU _t_r_o_f_f reads comparands protected with  \\??
     in  copy  mode, they need not be syntactically valid.  The escape character
     is still lexically recognized, however, and consumes the next character.

     The above operators can’t be combined with most others, but a leading  “!!”,
     not  followed  immediately  by  spaces  or tabs, complements an expression.
     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 con‐
     ditional evaluates true.  (This bizarre  behavior  maintains  compatibility
     with AT&T _t_r_o_f_f.)

     Conditional operators do not create _r_o_f_f language objects as interpolations
     with \\nn and \\** escape sequences do.

SSyynnttaaxx rreeffeerreennccee ccoonnvveennttiioonnss
     In  the following request and escape sequence specifications, most argument
     names were chosen to be descriptive.  GNU _t_r_o_f_f reads arguments named _c_h_a_r_‐
     _a_c_t_e_r_‐_s_e_q_u_e_n_c_e_, _c_o_m_m_a_n_d_, _c_o_n_t_e_n_t_s_, _f_i_l_e_, and _m_e_s_s_a_g_e in copy mode (see sec‐
     tion “Copy Mode” below) until the end of the input line.   A  _c_h_a_r_a_c_t_e_r_‐_s_e_‐
     _q_u_e_n_c_e  comprises  one  or  more  ordinary, special, or indexed characters;
     spaces; or escape sequences that interpolate only these.  We name  the  re‐
     maining  arguments  for clarity; they are also _c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e_s_.  A neu‐
     tral double quote ‘""’ can optionally prefix a _c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e_; the  for‐
     matter  discards  one if present, permitting initial embedded spaces in the
     argument.  _i_n_p_u_t refers to arbitrary character sequences (up to  a  newline
     or delimiter) that GNU _t_r_o_f_f fully interprets, in contrast to copy mode.

     A few denotations are more specific.

            _b          is  a  numerical expression evaluated as a Boolean; posi‐
                       tive values are true, others false.
            _c          denotes a single  character——ordinary,  special,  or  in‐
                       dexed.
            _c_o_m_m_a_n_d    is  an  instance  of _c_o_n_t_e_n_t_s (see below) to be passed to
                       the system as a  command  (potentially  with  arguments).
                       GNU _t_r_o_f_f strips a leading neutral double quote, allowing
                       embedded leading spaces.
            _c_o_n_t_e_n_t_s   is  arbitrary input, excluding an unescaped newline, read
                       in copy mode.  GNU _t_r_o_f_f strips a leading neutral  double
                       quote, allowing embedded leading spaces.
            _d_i_v        is a diversion identifier.
            _e_n_v        is an environment identifier.
            _f_i_l_e       is  an  instance of _c_o_n_t_e_n_t_s naming a file on the system.
                       GNU _t_r_o_f_f strips a leading neutral double quote, allowing
                       embedded leading spaces.  GNU _t_r_o_f_f does not accept  new‐
                       lines (line feeds) in file names supplied as arguments to
                       requests.
            _f_o_n_t       is a typeface specified as a font identifier, an abstract
                       style, or a mounting position.
            _i_d_e_n_t      is a valid _g_r_o_f_f identifier; its use often indicates that
                       the  operation  creates  an object of a type subsequently
                       referred to as _m_a_c_, _r_e_g_, _s_t_r_, and so forth.
            _m_a_c        is a macro identifier.
            _m_e_s_s_a_g_e    is an instance of _c_o_n_t_e_n_t_s to emit on the standard  error
                       stream.  GNU _t_r_o_f_f strips a leading neutral double quote,
                       allowing embedded leading spaces.
            _n          is  a numeric expression that evaluates to a non‐negative
                       integer.
            _±_N         is a numeric expression with a meaning dependent  on  its
                       sign; see below.
            _n_a_m_e       is  a macro, string, or diversion identifier, or the name
                       of a request.
            _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 out‐
                       put, as do control lines containing  requests  like  “..ttll
                       ////PPaaggee  %%////”  or  escape  sequences like “\\ll''11ii''”.  Macro
                       calls are not themselves productive, but their interpola‐
                       tions can be.
            _r_e_g        is a register identifier.
            _s_t_r        is a string identifier.
            _s_t_r_e_a_m     is an output stream identifier.

     If a numeric expression presented as _±_N starts with a ‘++’ sign,  an  incre‐
     ment  in  the  amount of of _N is applied to the value applicable to the re‐
     quest or escape sequence.  If it starts with a ‘--’  sign,  a  decrement  of
     magnitude  _N  is  applied instead.  Without a sign, _N replaces any existing
     value.  A _r_o_f_f formatter always interprets a leading minus sign in _N  as  a
     decrementation  operator,  not  an  algebraic sign.  To assign a register a
     negative value or the negated value  of  another  interpolation,  you  must
     force  the  formatter  to interpret “--” as a negation or minus, rather than
     decrementation, operator: enclose the “--” with its operand  in  parentheses
     or  subtract  the  expression of interest from zero.  If a prior value does
     not exist——the register was undefined——an increment or decrement applies as
     if to 0.

RReeqquueesstt sshhoorrtt rreeffeerreennccee
     Not all details of request behavior are outlined here.  See the _g_r_o_f_f  Tex‐
     info manual or, for features new to GNU _t_r_o_f_f, _g_r_o_f_f___d_i_f_f(7).

     ..aabb        Abort the formatter; exit with failure status.
     ..aabb _t_e_r_m_i_n_a_l_‐_m_e_s_s_a_g_e
                Abort  the formatter; write _t_e_r_m_i_n_a_l_‐_m_e_s_s_a_g_e to the standard er‐
                ror 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 _c  Assign format _c to register _r_e_g_, where _c is “ii”, “II”, “aa”,  “AA”,
                or a sequence of decimal digits whose quantity denotes the mini‐
                mum  width  in  digits  to be used when the register is interpo‐
                lated.  “ii” and “aa” indicate Roman numerals and basic Latin  al‐
                phabetics,  respectively,  in the lettercase specified.  The de‐
                fault is 00.
     ..aallnn _n_e_w_‐_r_e_g_i_s_t_e_r _e_x_i_s_t_i_n_g_‐_r_e_g_i_s_t_e_r
                Create alias (additional name) _n_e_w_‐_r_e_g_i_s_t_e_r  of  _e_x_i_s_t_i_n_g_‐_r_e_g_i_s_‐
                _t_e_r,  causing  the names to refer to the same stored object.  If
                _e_x_i_s_t_i_n_g_‐_r_e_g_i_s_t_e_r is undefined, the formatter  ignores  the  re‐
                quest.  GNU _t_r_o_f_f emits a warning in category “rreegg”.
     ..aallss _n_e_w_‐_n_a_m_e _e_x_i_s_t_i_n_g_‐_n_a_m_e
                Create  alias  (additional  name)  _n_e_w_‐_n_a_m_e  of request, string,
                macro, or diversion _e_x_i_s_t_i_n_g_‐_n_a_m_e, causing the names to refer to
                the same stored object.  If _e_x_i_s_t_i_n_g_‐_n_a_m_e is undefined, the for‐
                matter ignores the request.  GNU _t_r_o_f_f emits a warning in  cate‐
                gory  “mmaacc”.  If _n_e_w_‐_n_a_m_e already exists, its definition is lost
                unless already aliased.
     ..aamm _m_a_c    Append to macro _m_a_c until encountering “....” at the  start  of  a
                control line in the current conditional block.
     ..aamm _m_a_c _e_n_d_‐_m_a_c
                Append  to  macro  _m_a_c until _e_n_d_‐_m_a_c is called at the start of a
                control line in the current conditional block.  _e_n_d_‐_m_a_c can be a
                request.
     ..aamm11 _m_a_c   As ”aamm”, with compatibility mode disabled when the appendment to
                macro _m_a_c is interpreted.
     ..aamm11 _m_a_c _e_n_d_‐_m_a_c
                As “..aamm _m_a_c”, with compatibility mode disabled when the  append‐
                ment to macro _m_a_c is interpreted.
     ..aammii _s_t_r   Append  to  a macro indirectly——its name is in string _s_t_r——until
                encountering “....”.
     ..aammii _s_t_r _e_n_d_‐_m_a_c_‐_s_t_r
                Append to a macro indirectly.  As ”aamm”, but _s_t_r and  _e_n_d_‐_m_a_c_‐_s_t_r
                contain the names of the macro to be appended to, and that whose
                call ends the appendment, respectively.
     ..aammii11 _s_t_r  As  aammii, with compatibility mode disabled when the appendment is
                interpreted.
     ..aammii11 _s_t_r _e_n_d_‐_m_a_c_‐_s_t_r
                As aammii, with compatibility mode disabled when the appendment  is
                interpreted.
     ..aass _i_d_e_n_t  Create  string  _i_d_e_n_t with empty contents; no operation if _i_d_e_n_t
                already exists.
     ..aass _s_t_r _c_o_n_t_e_n_t_s
                Append _c_o_n_t_e_n_t_s to string _s_t_r.
     ..aass11 _i_d_e_n_t
                As “..aass _i_d_e_n_t”.
     ..aass11 _s_t_r _c_o_n_t_e_n_t_s
                As ”aass”, with compatibility mode disabled when the appendment to
                string _s_t_r is interpreted.
     ..aasscciiiiffyy _d_i_v
                Unformat ordinary characters, spaces, and some escape  sequences
                in  diversion  _d_i_v.  When transforming a glyph node back into an
                input sequence that demands expression as  a  special  character
                escape sequence, GNU _t_r_o_f_f uses the default escape character.
     ..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.   _s_p_e_c_i_a_l_‐
                _f_o_n_t must be a font name, not a mounting position.
     ..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 _m_a_c   Set blank line macro (trap) to _m_a_c.
     ..bbooxx       Stop  directing  output to current diversion; any pending output
                line is discarded.
     ..bbooxx _i_d_e_n_t
                Direct output to diversion _i_d_e_n_t, omitting a partially collected
                line.
     ..bbooxxaa      Stop appending output to current diversion; any  pending  output
                line is discarded.
     ..bbooxxaa _d_i_v  Append  output  to diversion _d_i_v, omitting a partially collected
                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 and force adjustment of the output line  per  the  current
                adjustment mode.
     ..bbrreeaakk     Break out of a ”wwhhiillee” 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 with‐
                out 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   Break and copy contents of _f_i_l_e as  “throughput”  to  GNU  _t_r_o_f_f
                output  (see  _g_r_o_f_f___o_u_t(5)).   Each line of _f_i_l_e is output as if
                preceded by \\!!, but is not interpreted by the formatter.  Unsafe
                request; disabled by default.
     ..ccffllaaggss _n _c...
                Assign properties encoded by  non‐negative  integer  _n  to  each
                character or class _c.  Spaces need not separate _c arguments.
     ..cchh _m_a_c    Unplant page location trap _m_a_c.
     ..cchh _m_a_c _v_e_r_t_i_c_a_l_‐_p_o_s_i_t_i_o_n
                Change  page location trap _m_a_c planted by wwhh by moving its loca‐
                tion to _v_e_r_t_i_c_a_l_‐_p_o_s_i_t_i_o_n (default scaling unit vv).
     ..cchhaarr _c    Define an ordinary, special, or indexed character _c as empty.
     ..cchhaarr _c _c_o_n_t_e_n_t_s
                Define an ordinary, special, or indexed character _c as _c_o_n_t_e_n_t_s_.
     ..cchhoopp _n_a_m_e
                Remove the last character from the macro, string,  or  diversion
                _n_a_m_e_.
     ..ccllaassss _i_d_e_n_t _c ...
                Define  a  (character)  class _i_d_e_n_t comprising the characters or
                range expressions _c, where each _c is an  ordinary,  special,  or
                indexed  character; or a _r_a_n_g_e _e_x_p_r_e_s_s_i_o_n_.  A class thus defined
                can then be referred to in a ccffllaaggss request in lieu  of  listing
                all the characters within it.
     ..cclloossee _s_t_r_e_a_m
                Close _s_t_r_e_a_m, making it unavailable for ”wwrriittee” requests.
     ..ccoolloorr     Enable  output  of  color‐related device‐independent output com‐
                mands.  It is enabled by default.
     ..ccoolloorr _b   Enable or disable  output  of  color‐related  device‐independent
                output commands per Boolean expression _b.
     ..ccoommppoossiittee _c
                Remove composite character mapping for character _c_.
     ..ccoommppoossiittee _c_1 _c_2
                Map  character  _c_1  to  _c_2 when _c_1 is a combining component in a
                composite character.
     ..ccoonnttiinnuuee  Skip the remainder of a “wwhhiillee” loop’s body, immediately retest‐
                ing its conditional expression.
     ..ccpp        Enable AT&T _t_r_o_f_f compatibility mode.  It  is  disabled  by  de‐
                fault.
     ..ccpp _b      Enable  or disable AT&T _t_r_o_f_f compatibility mode per Boolean ex‐
                pression _b.
     ..ccss _f      Disable constant‐width glyph spacing mode for font _f_.
     ..ccss _f _n    Enable constant‐width glyph spacing mode for font _f at _n/36 ems.
     ..ccss _f _n _p  Enable constant‐width glyph spacing mode for _f_o_n_t at  _n/36  ems,
                as if one em equals _p scaled points.
     ..ccuu        Continuously  underline  the output of the next productive input
                line.
     ..ccuu _n_p_l    Continuously underline the output of the next _n_p_l productive in‐
                put lines.  If _n_p_l=0, stop continuously underlining.
     ..ddaa        Stop appending output to current diversion.
     ..ddaa _d_i_v    Append output to diversion _d_i_v.
     ..ddee _i_d_e_n_t  Define macro _i_d_e_n_t until “....” occurs at the start of  a  control
                line in the current conditional block.
     ..ddee _i_d_e_n_t _e_n_d_‐_m_a_c
                Define  macro  _i_d_e_n_t  until  _e_n_d_‐_m_a_c is called at the start of a
                control line in the current conditional block.  _e_n_d_‐_m_a_c can be a
                request.
     ..ddee11 _i_d_e_n_t
                As ddee, with compatibility mode disabled when _m_a_c is interpreted.
     ..ddee11 _i_d_e_n_t _e_n_d_‐_m_a_c
                As “..ddee _i_d_e_n_t _e_n_d_‐_m_a_c”, with compatibility  mode  disabled  when
                _m_a_c is interpreted.
     ..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 synonym 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).
     ..ddeeii _s_t_r   Define macro indirectly.  As ddee, but interpolate string  _s_t_r  to
                obtain the macro’s name.
     ..ddeeii _s_t_r _e_n_d_‐_m_a_c_‐_s_t_r
                Define macro indirectly.  As ddee, but _s_t_r and _e_n_d_‐_m_a_c_‐_s_t_r contain
                the  names  of the macro to be defined, and that whose call ends
                the definition, respectively.
     ..ddeeii11 _s_t_r  As ddeeii, with compatibility mode disabled when the macro  is  in‐
                terpreted.
     ..ddeeii11 _s_t_r _e_n_d_‐_m_a_c_‐_s_t_r
                As  ddeeii,  with compatibility mode disabled when the macro is in‐
                terpreted.
     ..ddeevviiccee _c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e
                Embed _c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e into GNU _t_r_o_f_f output as parameters  to
                an  “xXX”” device extension command; see _g_r_o_f_f___o_u_t(5).  The output
                driver or other postprocessor interprets  _c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e  as
                it sees fit.
     ..ddeevviicceemm _n_a_m_e
                Write  contents  of  macro or string _n_a_m_e to _t_r_o_f_f output as the
                argument to a device extension command.
     ..ddii        Stop directing output to current diversion.
     ..ddii _i_d_e_n_t  Direct output to diversion _i_d_e_n_t.
     ..ddoo _n_a_m_e _a_r_g_u_m_e_n_t ...
                Interpret the string, request, diversion, or macro  _n_a_m_e  (along
                with  any  further  arguments) with compatibility mode disabled.
                Compatibility mode is restored (only if it was active) when  the
                interpolation of _n_a_m_e is interpreted.
     ..ddss _i_d_e_n_t  Create empty string named _i_d_e_n_t.
     ..ddss _i_d_e_n_t _c_o_n_t_e_n_t_s
                Create a string named _i_d_e_n_t containing _c_o_n_t_e_n_t_s_.
     ..ddss11 _i_d_e_n_t
     ..ddss11 _i_d_e_n_t _c_o_n_t_e_n_t_s
                As  ddss,  with compatibility mode disabled when the string is in‐
                terpreted.
     ..ddtt        Clear diversion trap.
     ..ddtt _v_e_r_t_i_c_a_l_‐_p_o_s_i_t_i_o_n _m_a_c
                Set the diversion trap to macro _m_a_c  at  _v_e_r_t_i_c_a_l_‐_p_o_s_i_t_i_o_n  (de‐
                fault 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        Interpolate  a newline if the conditional expression of the cor‐
                responding iiee request was false.
     ..eell _i_n_p_u_t  Interpret _i_n_p_u_t as if it were an input line if  the  conditional
                expression of the corresponding iiee request was false.
     ..eemm        Unset end‐of‐input macro.
     ..eemm _m_a_c    Call macro _m_a_c 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, creating
                it if necessary.
     ..eevvcc _e_n_v   Copy environment _e_n_v to the current one.
     ..eexx        Exit the formatter.
     ..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 _c      Set field delimiter to _c and pad glyph to space.
     ..ffcc _c_1 _c_2  Set field delimiter to _c_1 and pad glyph to _c_2.
     ..ffcchhaarr _c   Define fallback character _c as empty.
     ..ffcchhaarr _c _c_o_n_t_e_n_t_s
                Define fallback character _c as _c_o_n_t_e_n_t_s.   As  cchhaarr,  but  while
                that  request  hides  a glyph with the same name in the selected
                font, ffcchhaarr definitions are used only if the font lacks a  glyph
                for  _c.   GNU  _t_r_o_f_f performs this test before searching special
                fonts.
     ..ffccoolloorr    Restore previous fill color, or the default if there is none.
     ..ffccoolloorr _c_o_l
                Select _c_o_l as the fill color.
     ..ffii        Enable filling of output lines; a pending output line is broken.
                Sets \\nn[[..uu]].
     ..ffll        Flush any pending output line.
     ..ffpp _p_o_s _i_d
                Mount font with font description file name  _i_d  at  non‐negative
                position _p_o_s.
     ..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 _p_o_s.
     ..ffsscchhaarr _f _c
                Define fallback character _c specific to font _f as empty.
     ..ffsscchhaarr _f _c _c_o_n_t_e_n_t_s
                Define fallback character _c specific to font _f as _c_o_n_t_e_n_t_s.   As
                cchhaarr,  but GNU _t_r_o_f_f locates a character defined by ffsscchhaarr after
                any fonts named as arguments to the ffssppeecciiaall  are  searched  and
                before those named as arguments to the “ssppeecciiaall” request.
     ..ffssppeecciiaall _f
                Empty the list of fonts treated as special when _f is selected.
     ..ffssppeecciiaall _f _s ...
                Declare  each  font  _s  as special only when font ff is selected.
                GNU _t_r_o_f_f searches fonts specified as arguments to the “ssppeecciiaall”
                request after those given as arguments to the ffssppeecciiaall request.
     ..fftt
     ..fftt PP      Select the typeface _f_o_n_t_.  If _f_o_n_t is an integer, the  formatter
                interprets  it as a mounting position; the font mounted there is
                selected.  If that position refers to  an  abstract  style,  GNU
                _t_r_o_f_f  combines it with the default family (see ffaamm above and \\FF
                below) to make a resolved font name.  If _f_o_n_t is “DDEESSCC”, if  the
                mounting  position  is  not  an  abstract  style  and no font is
                mounted there, or the mounting position is negative,  GNU  _t_r_o_f_f
                ignores  the  request.   (It  also  emits  a warning in category
                “ffoonntt”, or “rraannggee”, as appropriate.  See section  “Warnings”  in
                _t_r_o_f_f(1).)  Also see \\ff ..
     ..ffttrr _f     Remove translation of font named _f.
     ..ffttrr _f_1 _f_2
                Translate font name _f_1 to _f_2.
     ..ffzzoooomm _f_o_n_t 00
                Stop magnifying _f_o_n_t.
     ..ffzzoooomm _f_o_n_t _z_o_o_m
                Set  magnification  of mounted _f_o_n_t to _z_o_o_m, a multiplier of the
                current type size in thousandths (default: 1000).
     ..ggccoolloorr    Restore previous stroke color, or the default if there is none.
     ..ggccoolloorr _c_o_l
                Select _c_o_l as the stroke color.
     ..hhcc        Reset the hyphenation character to \\%% (the default).
     ..hhcc _c      Change the hyphenation character to _c.
     ..hhccooddee _d_s_t_1 _s_r_c_1 [_d_s_t_2 _s_r_c_2] ...
                Set the hyphenation code of character _d_s_t_1 to that of _s_r_c_1,  and
                so on.
     ..hhllaa       Clear  the  environment’s  hyphenation language (disabling auto‐
                matic hyphenation).
     ..hhllaa _i_d_e_n_t
                Set the environment’s hyphenation language to _i_d_e_n_t.
     ..hhllmm       Set the consecutive automatically hyphenated line  limit  to  --11
                (the default), meaning “no limit”.
     ..hhllmm _n     Set the consecutive automatically hyphenated line limit to to _n_.
                A negative value means “no limit”.
     ..hhppff _f_i_l_e  Read hyphenation patterns from _f_i_l_e.
     ..hhppffaa _f_i_l_e
                Append hyphenation patterns from _f_i_l_e.
     ..hhppffccooddee _a _b [_c _d] ...
                _C_a_u_t_i_o_n_:  This  request  will be withdrawn in a future _g_r_o_f_f re‐
                lease.  Use hhccooddee instead.
                Define mappings  for  character  codes  in  hyphenation  pattern
                files.
     ..hhww _w_o_r_d ...
                Define  each argument _w_o_r_d (comprising ordinary, special, or in‐
                dexed characters) as a _h_y_p_h_e_n_a_t_i_o_n _e_x_c_e_p_t_i_o_n _w_o_r_d such that each
                occurrence of a hyphen‐minus “--” in _w_o_r_d indicates a hyphenation
                point.
     ..hhyy        Set automatic hyphenation mode to the value  of  the  ..hhyyddeeffaauulltt
                register.
     ..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.
     ..hhyyddeeffaauulltt _m_o_d_e
                Set hyphenation mode default to _m_o_d_e; see section  “Hyphenation”
                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
                that adjustment can be achieved by adding no more  than  _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
                Interpolate  a newline if _c_o_n_d_‐_e_x_p_r is true, otherwise skip to a
                corresponding eell request.
     ..iiee _c_o_n_d_‐_e_x_p_r _i_n_p_u_t
                If _c_o_n_d_‐_e_x_p_r is true, interpret _i_n_p_u_t as if  it  were  an  input
                line, otherwise skip to a corresponding eell request.
     ..iiff _c_o_n_d_‐_e_x_p_r
                Interpolate a newline if _c_o_n_d_‐_e_x_p_r is true.
     ..iiff _c_o_n_d_‐_e_x_p_r _i_n_p_u_t
                If  _c_o_n_d_‐_e_x_p_r is true, then interpret _i_n_p_u_t as if it were an in‐
                put line.
     ..iigg        Ignore input (except for side effects of \\RR on auto‐incrementing
                registers) until “....” occurs at the start of a control  line  in
                the current conditional block.
     ..iigg _e_n_d_‐_m_a_c
                Ignore input (except for side effects of \\RR on auto‐incrementing
                registers)  until  _e_n_d_‐_m_a_c  is  called at the start of a control
                line in the current conditional block.  _e_n_d_‐_m_a_c  can  be  a  re‐
                quest.
     ..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 _m_a_c
                Set  (or replace) an input line trap in the environment, calling
                _m_a_c after the next _n_p_l productive input lines  have  been  read.
                Lines  interrupted with the \\cc escape sequence are counted sepa‐
                rately.
     ..iittcc       Cancel any pending input line trap.
     ..iittcc _n_p_l _m_a_c
                As ”iitt”, but lines interrupted with the \\cc  escape  sequence  do
                not apply to the line count.
     ..kkeerrnn      Enable pairwise kerning.
     ..kkeerrnn _b    Enable or disable pairwise kerning per Boolean expression _b.
     ..llcc        Unset leader repetition character.
     ..llcc _c      Set leader repetition character to _c (default: “..”).
     ..lleennggtthh _r_e_g _c_o_n_t_e_n_t_s
                Compute the number of characters in _c_o_n_t_e_n_t_s and store the count
                in the register _r_e_g.
     ..lliinneettaabbss  Activate  line‐tabs  in  the environment.  It is disabled by de‐
                fault.
     ..lliinneettaabbss _b
                Activate or deactivate line‐tabs in the environment per  Boolean
                expression _b.
     ..llff _i_n_p_u_t_‐_l_i_n_e_‐_n_u_m_b_e_r
                Set  the input line number the formatter uses when reporting di‐
                agnostics.  The argument becomes the input line  number  of  the
                _n_e_x_t line the formatter reads.
     ..llff _i_n_p_u_t_‐_l_i_n_e_‐_n_u_m_b_e_r _c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e
                As  llff with one argument, but also update the reported file name
                to _c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e.
     ..llgg        Enable ligature mode 11.
     ..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 handling
                of lines with leading spaces.
     ..llssmm _m_a_c   Set the leading space macro (trap) to _m_a_c.
     ..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  scaling
                unit mm).
     ..mmcc        Cease writing margin character.
     ..mmcc _c      Begin  writing  margin  character  _c to the right of each output
                line at a distance of 10pp.
     ..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    Mark vertical drawing position in register _r_e_g.
     ..mmssoo _f_i_l_e  As ”ssoo”, except that GNU _t_r_o_f_f searches for the  specified  _f_i_l_e
                in  the  same directories as macro files; see _G_R_O_F_F___T_M_A_C___P_A_T_H in
                section “Environment” of _g_r_o_f_f(1) and --mm in section “Options” of
                the same page.
     ..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  bro‐
                ken.  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 (default 1), 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 counted by nnmm.
     ..nnnn _n      Suppress numbering of the next _n output lines counted by nnmm.  If
                _n=0, cancel suppression.
     ..nnoopp       Interpolate a newline.
     ..nnoopp _i_n_p_u_t
                Interpret _i_n_p_u_t 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,
                which may be any integer.
     ..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        Stop processing the input file and read the next, if any.
     ..nnxx _f_i_l_e   Stop processing the input file and read _f_i_l_e.
     ..ooppeenn _i_d_e_n_t _f_i_l_e
                Open  _f_i_l_e  for  writing and associate a stream named _i_d_e_n_t with
                it, making it available for ”wwrriittee” requests.   Unsafe  request;
                disabled by default.
     ..ooppeennaa _i_d_e_n_t _f_i_l_e
                As  “ooppeenn”, but if _f_i_l_e already exists, appends to it instead of
                overwriting it.  Unsafe request; disabled by default.
     ..ooss        Output vertical space that was saved by the ssvv request.
     ..oouuttppuutt _c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e
                Emit _c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e “transparently”  (directly)  to  _t_r_o_f_f’s
                output.
     ..ppcc        Reset page number character to ‘%%’.
     ..ppcc _c      Change the page number character used in titles to _c.
     ..ppcchhaarr _c ...
                Report,  to  the  standard  error stream, information about each
                character (be it ordinary, special,  or  indexed)  or  character
                class _c.  A character defined by a request (cchhaarr, ffcchhaarr, ffsscchhaarr,
                or sscchhaarr) reports its contents as a JSON‐encoded string, but the
                output is not otherwise in JSON format.
     ..ppccoolloorr    Report,  to  the standard error stream, each defined color name,
                its color space identifier, and channel  value  assignments.   A
                device’s  default  stroke and/or fill colors, “default”, are not
                listed since they are immutable and their details unknown to the
                formatter.
     ..ppccoolloorr _c_o_l ...
                Report, to the standard error  stream,  the  name,  color  space
                identifier, and channel value assignments of each color _c_o_l.
     ..ppccoommppoossiittee
                Report,  to  the  standard  error stream, the list of configured
                composite character mappings.  See the “ccoommppoossiittee” request.  The
                “from” code point is listed first, followed by its “to” mapping.
     ..ppeevv       Report the state of the current environment followed by that  of
                all other environments to the standard error stream.
     ..ppffpp       Report,  to the standard error stream, the list of occupied font
                mounting positions.  Occupied mounting positions are listed, one
                per line, in increasing order, followed by the typeface name; if
                the name corresponds to an abstract style, the entry ends there.
                Otherwise, the name of the font description file and the  font’s
                “internal name” datum, the meaning of which varies by output de‐
                vice, follow.
     ..ppffttrr      Report,  to the standard error stream, the list of font transla‐
                tions.
     ..pphhww       Report, to the standard error stream, the  list  of  hyphenation
                exception  words  associated  with  the hyphenation language se‐
                lected by the hhllaa request.  A “--” marks each hyphenation  point.
                A  word  prefixed with “--” is not hyphenated at all.  The report
                suffixes words to which automatic hyphenation  applies  (meaning
                those defined in a hyphenation pattern file rather than with the
                hhww request) with a tab and asterisk “**”.
     ..ppii _c_o_m_m_a_n_d
                Pipe  GNU  _t_r_o_f_f  output  through _c_o_m_m_a_n_d (which is read in copy
                mode) by passing it to _p_o_p_e_n(3).  Multiple ppii requests construct
                a multi‐stage pipeline in the same order as  the  formatter  en‐
                counters the requests.  Unsafe request; disabled 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).
     ..pplliinnee     Report, in JSON syntax to the standard error stream, the list of
                output nodes corresponding to the pending output line.  In JSON,
                a pair of empty brackets “[[ ]]”  represents  an  empty  list.   A
                _p_e_n_d_i_n_g  output line has not yet undergone adjustment, and lacks
                a line number and margin character (all as applicable).
     ..ppmm        Report, to the standard error stream, the names of  all  defined
                macros,  strings, and diversions and their lengths in characters
                or nodes.
     ..ppmm _n_a_m_e ...
                Report, to the standard error stream, the JSON‐encoded name  and
                contents of each macro, string, or diversion _n_a_m_e.
     ..ppnn _±_N     Set next page number.
     ..ppnnrr       Report  the  names,  values,  and  (as applicable) autoincrement
                amounts and assigned formats of all  defined  registers  to  the
                standard error stream.
     ..ppnnrr _r_e_g ...
                Report  the  name and value and, if its type is numeric, the au‐
                toincrement amount and assigned format, of each register _r_e_g  to
                the standard error stream.
     ..ppoo        Change  to  previous  page  offset.   The current page offset is
                available in register ..oo.
     ..ppoo _±_N     Alter page offset (default scaling unit mm).
     ..ppss        Restore 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 _p_o_s_t_s_c_r_i_p_t_‐_f_i_l_e
                Retrieve the bounding box of the PostScript image found in _p_o_s_t_‐
                _s_c_r_i_p_t_‐_f_i_l_e_, which must conform to Adobe’s Document  Structuring
                Conventions (DSC).  See registers llllxx, llllyy, uurrxx, uurryy.
     ..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,  which is passed to _p_o_p_e_n(3).  Unsafe request; dis‐
                abled by default.
     ..ppssttrreeaamm   Report, in JSON syntax to the standard error stream, the list of
                open streams, including the name of each open stream,  the  name
                of the file backing it, and its mode (writing or appending).
     ..ppwwhh       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 scal‐
                ing unit pp).
     ..rrcchhaarr _c...
                Remove definition of each ordinary, special, or indexed  charac‐
                ter  _c,  undoing  the effect of a cchhaarr, ffcchhaarr, or sscchhaarr request.
                Spaces need not separate _c arguments.  The character  definition
                removed  (if  any)  is  the  first encountered in the resolution
                process documented in section “Using Symbols” of _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.  Glyphs, which are defined by font de‐
                scription files, cannot be removed.
     ..rrdd        Read insertion from standard input stream, ringing terminal bell
                as prompt.
     ..rrdd _t_e_r_m_i_n_a_l_‐_m_e_s_s_a_g_e
                Read insertion from standard input stream, writing _t_e_r_m_i_n_a_l_‐_m_e_s_‐
                _s_a_g_e to standard error stream as prompt.
     ..rreettuurrnn    Stop interpreting an interpolated macro, skipping the  remainder
                of its definition.
     ..rreettuurrnn _i_n_p_u_t
                As rreettuurrnn, but perform the skip twice——once within the macro be‐
                ing interpreted and once in an enclosing macro.
     ..rrffsscchhaarr _f _c...
                Remove  each  fallback  special  character _c for font _f.  Spaces
                need not separate _c arguments.  See ffsscchhaarr.
     ..rrjj        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 input
                lines without filling, then break  again.   If  _n_p_l  ≤  0,  stop
                right‐aligning.
     ..rrmm _n_a_m_e ...
                Remove each 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 _r_e_g ...
                Remove each register _r_e_g.
     ..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   Define global fallback character _c as empty.
     ..sscchhaarr _c _c_o_n_t_e_n_t_s
                Define  global  fallback  character _c as _c_o_n_t_e_n_t_s.  As cchhaarr, but
                GNU _t_r_o_f_f locates a character defined with sscchhaarr after any fonts
                named as arguments to  the  “ssppeecciiaall”  request  and  before  any
                mounted special fonts.
     ..sshhcc       Reset the soft hyphen character to \\[[hhyy]].
     ..sshhcc _c     Set the soft hyphen character to _c.
     ..sshhiifftt     Shift  macro or string parameters one place _n places: argument _i
                becomes argument _i-_1; argument 1 becomes unavailable.
     ..sshhiifftt _n   Shift macro or string parameters _n places:  argument  _i  becomes
                argument _i-_n; arguments 1 to _n become unavailable.
     ..ssiizzeess _s_1 _s_2 ... _s_n [00]
                Set  available  type sizes to the list of values or ranges; each
                _si is interpreted in units of  scaled  points  (ss).   GNU  _t_r_o_f_f
                strips  a leading neutral double quote from _s_1; it reads each _si
                in copy mode.
     ..ssoo _f_i_l_e   Replace the request’s control line with the  contents  of  _f_i_l_e,
                “sourcing”  it.   GNU _t_r_o_f_f searches for _f_i_l_e in any directories
                specified by --II command‐line options, followed  by  the  current
                working  directory.   If  _f_i_l_e does not exist, the formatter ig‐
                nores the request.  (GNU  _t_r_o_f_f  emits  a  warning  in  category
                “ffiillee”.)
     ..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 until
                springing a page location trap.  If invoked  with  the  no‐break
                control  character, sspp moves the text baseline applicable to the
                entire pending output line.
     ..sspp _v_e_r_t_i_c_a_l_‐_d_i_s_t_a_n_c_e
                As sspp, but move by _v_e_r_t_i_c_a_l_‐_d_i_s_t_a_n_c_e instead of  11vv.   Inside  a
                diversion,  the formatter ignores any argument.  A negative _v_e_r_‐
                _t_i_c_a_l_‐_d_i_s_t_a_n_c_e cannot reduce the position of the  text  baseline
                below zero.  Applying the boundary‐relative measurement operator
                || operator to _v_e_r_t_i_c_a_l_‐_d_i_s_t_a_n_c_e_, as in “||_N”, moves to a position
                relative  to the page top for positive _N, and the bottom if _N is
                negative.
     ..ssppeecciiaall   Empty the list of special fonts designated by this request  when
                given arguments.
     ..ssppeecciiaall _s ...
                Declare  each font _s as special, irrespective of its description
                file, populating a list that GNU _t_r_o_f_f searches,  in  order,  to
                find  the glyph demanded.  GNU _t_r_o_f_f searches fonts specified as
                arguments to the “ssppeecciiaall” request after those  given  as  argu‐
                ments to the ffssppeecciiaall request.
     ..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 scal‐
                ing unit is mm.  At startup, sspprreeaaddwwaarrnn is inactive and _N is 3 m..
     ..ssss _n      Set minimum inter‐word  space  and  supplemental  inter‐sentence
                space sizes to _n 12ths of the selected font’s ssppaacceewwiiddtthh parame‐
                ter (default: 12).
     ..ssss _n _m    As  “..ssss  _n”,  but set supplemental inter‐sentence space size to
                _m 12ths of the selected font’s ssppaacceewwiiddtthh parameter.
     ..ssttrriinnggddoowwnn _s_t_r
                Replace each byte in the string named  _s_t_r  with  its  lowercase
                version.
     ..ssttrriinngguupp _s_t_r
                Replace  each  byte  in  the string named _s_t_r with its uppercase
                version.
     ..ssttyy _p_o_s _s_t_y_l_e
                Associate abstract _s_t_y_l_e with non‐negative font position _p_o_s.
     ..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 back‐
                ward 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 (de‐
                fault scaling unit vv).
     ..ssyy _c_o_m_m_a_n_d
                Execute _c_o_m_m_a_n_d (which is read in copy mode)  in  the  operating
                environment  by  passing  it to _s_y_s_t_e_m(3).  See register ssyyssttaatt.
                Unsafe request; disabled by default.
     ..ttaa        Clear tab stops.
     ..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 default), “CC” for
                centered, and “RR” for right‐aligned.
     ..ttaagg       Reserved for internal use.
     ..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        Write a newline to the standard error stream.
     ..ttmm _t_e_r_m_i_n_a_l_‐_m_e_s_s_a_g_e
                Send _t_e_r_m_i_n_a_l_‐_m_e_s_s_a_g_e, followed by a newline,  to  the  standard
                error  stream.   The  formatter reads the argument to the end of
                the input line in copy mode, but does _n_o_t remove a leading  dou‐
                ble quote; contrast ..ttmm11.
     ..ttmm11       As ttmm.
     ..ttmm11 _m_e_s_s_a_g_e
                As  ttmm, but removes a leading neutral double quote ‘""’ from _m_e_s_‐
                _s_a_g_e, permitting initial embedded spaces in it, and reads it  to
                the end of the input line in copy mode.
     ..ttmmcc       No operation.
     ..ttmmcc _m_e_s_s_a_g_e
                As ttmm11, but does not append 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  Break and copy contents of _f_i_l_e as  “throughput”  to  GNU  _t_r_o_f_f
                output (see _g_r_o_f_f___o_u_t(5)).  Unlike ccff, characters invalid as in‐
                put  to  GNU _t_r_o_f_f are discarded.  If _f_i_l_e’s contents do not end
                with a newline, ttrrff appends one.
     ..ttrriinn _a_b_c_d...
                As ttrr, except that aasscciiiiffyy ignores the translation when a diver‐
                sion is interpolated.
     ..ttrrnntt _a_b_c_d...
                As ttrr, except that translations are suppressed in  the  argument
                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 pro‐
                ductive 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
                Unformat  space characters and tabs in diversion _d_i_v, preserving
                font information.
     ..vvpptt       Enable vertical position traps.  They are enabled by default.
     ..vvpptt _b     Enable or disable vertical position traps per Boolean expression
                _b.
     ..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_c_a_l_i_n_g_‐_u_n_i_t
                Select scaling unit used in certain warnings (one of uu, ii, cc, pp,
                or  PP;  default:  ii).  Ignored on _n_r_o_f_f‐mode output devices, for
                which these diagnostics report the  vertical  page  location  in
                lines, and the horizontal page location in ens.
     ..wwhh _v_e_r_t_i_c_a_l_‐_p_o_s_i_t_i_o_n
                Remove  visible page location trap at _v_e_r_t_i_c_a_l_‐_p_o_s_i_t_i_o_n (default
                scaling unit vv).
     ..wwhh _v_e_r_t_i_c_a_l_‐_p_o_s_i_t_i_o_n _m_a_c
                Plant macro _m_a_c as page location trap at _v_e_r_t_i_c_a_l_‐_p_o_s_i_t_i_o_n  (de‐
                fault scaling unit vv), removing any visible trap already there.
     ..wwhhiillee _c_o_n_d_‐_e_x_p_r
                Interpolate newlines unless and until _c_o_n_d_‐_e_x_p_r evaluates false.
     ..wwhhiillee _c_o_n_d_‐_e_x_p_r _i_n_p_u_t
                Repeatedly  execute  _i_n_p_u_t  unless and until _c_o_n_d_‐_e_x_p_r evaluates
                false.
     ..wwrriittee _s_t_r_e_a_m _c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e
                Write _c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e, a  sequence  of  ordinary  characters,
                spaces,  or tabs, to _s_t_r_e_a_m, which must previously have been the
                subject of an “ooppeenn” (or ooppeennaa) request, followed by a  newline.
                GNU _t_r_o_f_f flushes the stream after writing to it.
     ..wwrriitteecc _s_t_r_e_a_m _c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e
                As ”wwrriittee”, but does not write a newline to the output.
     ..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”  (or  ooppeennaa)
                request.  GNU _t_r_o_f_f reads the contents of _n_a_m_e in copy mode.

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.

     The escape sequences \\ff, \\FF, \\HH, \\mm, \\MM, \\RR, \\ss, and \\SS are  not  tokenized
     when  GNU  _t_r_o_f_f reads its input.  \\RR updates only the formatter’s register
     dictionary, and does not contribute (directly) to output.  The others alter
     the environment (see section “Environments” below).  See the “GNU troff In‐
     ternals” section of the _g_r_o_f_f Texinfo manual.

     \\""     Comment; read everything up to the next newline  in  copy  mode  and
            discard it.
     \\##     Whole‐line  comment;  read  everything  up to and including the next
            newline in copy mode and discard it.
     \\**_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),  taking
            _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  catenation of all macro or string parameters, separated
            by spaces.
     \\$$@@    Interpolate catenation of all macro or string parameters, with  each
            surrounded by double quotes and separated by spaces.
     \\$$^^    Interpolate  catenation 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.
     \\%%     Mark a hyphenation point within a word.  At the beginning of a word,
            prevent it from being otherwise hyphenated.
     \\!!_c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e
            _T_r_a_n_s_p_a_r_e_n_t_l_y embed _c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e, up to and including the  end
            of  the line, into the current diversion, requests, macro calls, and
            escape sequences when reading them into a diversion.  Doing so  pre‐
            vents  them  from  taking effect until the diverted text is actually
            output.
     \\??_c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e\\??
            Transparently embed _c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e, up to its  own  next  occur‐
            rence on the input line, into a diversion, or unformatted as an out‐
            put comparand in a conditional expression.  Ignored in the top‐level
            diversion.
     \\_s_p_a_c_e  Move right one inter‐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 adjacent
             upright glyph on the left and an oblique glyph on the right.
     \\::      Non‐printing break point (similar to \\%%, but never produces  a  hy‐
             phen glyph).
     \\_n_e_w_l_i_n_e
             Continue current input line on the next.
     \\{{      Begin conditional input.
     \\}}      End conditional input.
     \\((_s_c    Interpolate  glyph  of special character with two‐character identi‐
             fier _s_c.
     \\[[_s_p_c_h_a_r]]
             Interpolate glyph of special character with identifier  _s_p_c_h_a_r  (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''_i_n_p_u_t''
             Interpolate 1 if _i_n_p_u_t is a valid identifier, and 0 otherwise.  Be‐
             cause  GNU  _t_r_o_f_f  ignores any input character with an invalid code
             when reading it, invalid identifiers are empty or  contain  spaces,
             tabs,  newlines,  or  escape  sequences  that interpolate something
             other than a sequence of ordinary characters.
     \\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''_i_n_p_u_t''
             Interpolate 1 if _i_n_p_u_t is a valid numeric expression, and 0  other‐
             wise.
     \\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  arbi‐
             trarily 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 (increment, decrement) the height of the current font, but  not
             its  width.   If  _N is zero, the formatter uses the font’s inherent
             height for its type size default scaling unit zz).
     \\kk_r     Store the horizontal drawing position, relative to that correspond‐
             ing to the start of the input line (ignoring page offset and inden‐
             tation), in register name _r.
     \\kk((_r_g   Store the horizontal drawing position, relative to that correspond‐
             ing to the start of the input line (ignoring page offset and inden‐
             tation), in register name _r_g.
     \\kk[[_r_e_g]]
             Store the horizontal drawing position, relative to that correspond‐
             ing to the start of the input line (ignoring page offset and inden‐
             tation), in register name _r_e_g.
     \\ll''_N[_c]''
             Draw horizontal line of length _N with character _c (default:  \\[[rruu]];
             default scaling unit mm).
     \\LL''_N[_c]''
             Draw  vertical  line  of length _N with character _c (default: \\[[bbrr]];
             default scaling unit vv).
     \\mm_c     Select stroke color with one‐character name _c.
     \\mm((_c_l   Select stroke color with two‐character name _c_l.
     \\mm[[_c_o_l_o_r]]
             Select stroke color with arbitrarily long name _c_o_l_o_r.
     \\mm[[]]    Restore previous stroke color.
     \\MM_c     Select fill color with one‐character name _c.
     \\MM((_c_l   Select fill color with two‐character name _c_l.
     \\MM[[_c_o_l_o_r]]
             Select fill color with arbitrarily long name _c_o_l_o_r.
     \\MM[[]]    Restore previous fill color.
     \\nn_r     Interpolate value of register with one‐character name _r.
     \\nn((_r_g   Interpolate value of register with two‐character name _r_g.
     \\nn[[_r_e_g]]
             Interpolate value of register with arbitrarily long name _r_e_g.
     \\NN''_n''   Format indexed character numbered _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 standard
             error stream the page number, four bounding box registers enclosing
             glyphs written since the previous \\OO escape sequence, the page off‐
             set, line length, image file name (if any), horizontal 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.  If _n is an unsigned “0”, restore the previous
             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.  If _n is an unsigned “00”, restore the  previ‐
             ous size.  Otherwise, as ppss request.
     \\ss[[_±_N]]
     \\ss_±[[_N]]
     \\ss''_±_N''
     \\ss_±''_N''  Set/increase/decrease the type size to/by _N scaled points.  If _n is
             an  unsigned  “0”  (with any number of leading zeroes), restore the
             previous size.  Otherwise, as ppss request.
     \\SS''_N''   Slant the glyphs of the currently selected font by @var{N} degrees.
             Positive values slant in the direction of text flow.  Only  integer
             values are possible.
     \\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 value of system environment variable with one‐character
             name _e as returned by _g_e_t_e_n_v(3).
     \\VV((_e_v   Interpolate value of system environment variable with two‐character
             name _e_v as returned by _g_e_t_e_n_v(3).
     \\VV[[_e_n_v]]
             Interpolate value of system environment variable  with  arbitrarily
             long name _e_n_v as returned by _g_e_t_e_n_v(3).
     \\ww''_i_n_p_u_t''
             Interpolate  the  width  of  _i_n_p_u_t, as interpreted, in basic units.
             This escape sequence allows several properties of formatted  output
             to be measured without writing it out.  The formatter processes _i_n_‐
             _p_u_t  in  a  dummy  environment:  this means that font and type size
             changes, for example, may occur within it without affecting  subse‐
             quent output.
     \\xx''_N''   Increase  vertical  spacing  of  pending  output line by _N vees (or
             specified units; negative before, positive after).
     \\XX''_c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e''
             Write _c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e to _t_r_o_f_f output as a device extension com‐
             mand.  The _g_r_o_f_f special character repertoire is unknown to  output
             drivers  outside of glyphs named in a device’s fonts, and even then
             they may not possess complete coverage of the names  documented  in
             _g_r_o_f_f___c_h_a_r(7).   Further,  escape sequences that produce horizontal
             or vertical motions, hyphenation breaks, or that are dummy  charac‐
             ters  may  appear in strings or be converted to nodes, particularly
             in diversions.  These are not representable when  interpolated  di‐
             rectly  into device‐independent output, as might be done when writ‐
             ing out tag names for PDF bookmarks, which can appear in a viewer’s
             navigation pane.

             So that documents or macro packages  do  not  have  to  laboriously
             “sanitize”  strings  destined for interpolation in device extension
             commands, this escape sequence performs certain transformations  on
             its  argument.   For  these transformations, character translations
             and definitions are ignored.

             GNU _t_r_o_f_f converts several ordinary characters that typeset as non‐
             basic Latin code points to code points outside that range  so  that
             they  are used consistently whether they are formatted as glyphs or
             used in a device control command argument.  These ordinary  charac‐
             ters are “''”, “--”, “^^”, “``”, and “~~”; others are written as‐is.

             Special  characters  that typeset as Unicode basic Latin characters
             are translated to basic Latin characters accordingly.  So that  any
             Unicode code point can be represented in device extension commands,
             for  example  in an author’s name in document metadata or as a use‐
             fully named bookmark or hyperlink anchor, GNU _t_r_o_f_f maps other spe‐
             cial characters to Unicode  special  character  notation.   Special
             characters  without  a Unicode representation, and escape sequences
             that do not interpolate a sequence of ordinary and/or special char‐
             acters, produce warnings in category “cchhaarr”.
     \\YY_n     Write contents of macro or string _n to _t_r_o_f_f output as a device ex‐
             tension command.
     \\YY((_n_m   Write contents of macro or string _n_m to _t_r_o_f_f output  as  a  device
             extension 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 device
             extension command.
     \\zz_c     Format character _c with zero width——without advancing  the  drawing
             position.
     \\ZZ''_i_n_p_u_t''
             Save  the  drawing  position,  format  _i_n_p_u_t, then restore it.  GNU
             _t_r_o_f_f ignores tabs and leaders in _i_n_p_u_t with an error diagnostic.

   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.
     Terminals in particular implement almost none.

     Rendering starts at the drawing position; when finished, the drawing  posi‐
     tion is left at the rightmost point of the object, even for closed figures,
     except  where  noted.   GNU _t_r_o_f_f draws stroked (outlined) objects 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 de‐
     fault 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  al‐
     ways  smaller  than an outlined one because the former is drawn only within
     its defined area, whereas strokes have a line thickness (set with \\DD''tt'').

     \\DD''~~ _h_1 _v_1 ... _h_n _v_n''
            Draw B‐spline to each point in sequence, leaving drawing position 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 bisector of the
            arc’s chord.
     \\DD''cc _d''
            Draw circle of diameter _d with its leftmost point at the drawing po‐
            sition.
     \\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 the 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 draw‐
            ing 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 minimum supported thickness.  A negative _n se‐
            lects a thickness proportional to the type size;  this  is  the  de‐
            fault.

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,  with‐
     out invoking requests or calling any other macros, one defines a string in‐
     stead.  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 invoked with only one argument, the named string
     becomes empty.  The formatter removes a leading neutral  double  quote  ‘""’
     from _c_o_n_t_e_n_t_s to permit the embedding of leading spaces.  It interprets any
     other  ‘""’ literally, but the wise author uses the special character escape
     sequence \\[[ddqq]] instead if the string might be interpolated  as  part  of  a
     macro argument; see section “Calling macros” above.

     The \\** escape sequence dereferences a string’s name, interpolating its con‐
     tents.   If the name does not exist, the formatter defines it as empty, in‐
     terpolates nothing, and emits a warning in  category  “mmaacc”.   See  section
     “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,  an  argument  containing  a  closing
     bracket  ]] must be enclosed in double quotes.  When defining strings, argu‐
     ment interpolations must be escaped if they  are  to  reference  parameters
     from  the calling context; see section “Parameters” below.  Any non‐initial
     neutral double quote "" is interpreted literally, but it is wise to use  the
     special  character escape sequence \\[[ddqq]] instead if the string might be in‐
     terpolated as part of a macro argument; see section “Calling macros” above.
     Strings are not limited to a single input line  of  text.   \\_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 new‐
     lines.  When filling is disabled, care is required to avoid overrunning the
     line  length  when  interpolating strings.  Conversely, when filling is en‐
     abled, it is not necessary to append \\cc to a string interpolation  to  pre‐
     vent a break afterward, as might be required in a macro argument.  Nor does
     a  string  require  use  of the GNU _t_r_o_f_f cchhoopp request to excise a trailing
     newline as is often done with diversions.  It is not possible  to  embed  a
     newline in a string that will be interpreted as such when the string is in‐
     terpolated.  To achieve that effect, use \\** to interpolate a macro instead;
     see section “Punning names” below.

     The  “aass”  request  is similar to ddss but appends to a string instead of re‐
     defining it.  If “aass” is invoked with only one argument,  no  operation  is
     performed (beyond dereferencing the string).

     Because  strings are similar to macros, they too can be defined to suppress
     AT&T _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  por‐
     tion of the string is later interpolated.

     _C_a_u_t_i_o_n_: These requests treat the remainder of the input line as their sec‐
     ond  argument,  including any spaces, up to a newline or comment escape se‐
     quence.  Ending string definitions (and appendments) with a  comment,  even
     an empty one, prevents unwanted space from creeping into them during source
     document  maintenance.  This rule and suggestion also applies to the second
     argument of the “lleennggtthh” request, to requests that define characters (cchhaarr,
     ffcchhaarr, ffsscchhaarr, and sscchhaarr), and to the file name or command arguments of the
     ccff, hhppff, hhppffaa, mmssoo, mmssooqquuiieett, nnxx, “ooppeenn”, ooppeennaa, ppii,  ppssoo,  “ssoo”,  ssooqquuiieett,
     and ttrrff requests.

     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 renaming, removal,
     and aliasing (rrnn, rrmm, aallss))..

     Redefinitions and appendments “write through” request, macro,  string,  and
     diversion  names.   To  replace an aliased object with a separately defined
     one, you must use the rrmm request on its name first.

RReeggiisstteerrss
     In the _r_o_f_f language, numbers and measurements can be stored in  _r_e_g_i_s_t_e_r_s_.
     Many  built‐in  registers  exist, supplying anything from components of the
     date to details of formatting parameters; some of these are read‐only.  You
     can also define your own.  See section “Identifiers”  above  regarding  the
     construction of valid names for registers.

     Each register (except read‐only ones) can be assigned a _f_o_r_m_a_t, causing its
     value  to interpolate with leading zeroes, in Roman numerals, or alphabeti‐
     cally.  Some read‐only registers are string‐valued, meaning that  they  in‐
     terpolate text and lack a format.

     Define  registers and update their values with the nnrr request or the \\RR es‐
     cape sequence.

     User‐defined registers can also be incremented or decremented by a  config‐
     ured  amount at the time they are interpolated.  The value of the increment
     is specified with a third argument to the nnrr request, and a special  inter‐
     polation  syntax, \\nn_±, alters and then retrieves the register’s value.  To‐
     gether, these features are called _a_u_t_o_‐_i_n_c_r_e_m_e_n_t.  (A negative  auto‐incre‐
     ment can be considered an “auto‐decrement”.)

     Many  predefined  registers are available.  The following presentation uses
     register interpolation syntax \\nn[[_n_a_m_e]] to  refer  to  a  register  _n_a_m_e  to
     clearly  distinguish it from a string or request _n_a_m_e; the symbols \\nn[[]] are
     _n_o_t part of the register name.  The register name space  is  separate  from
     that used for requests, macros, strings, and diversions.

   RReeaadd‐‐oonnllyy rreeggiisstteerrss
     Predefined  registers  whose  identifiers  start  with a dot are read‐only.
     Many are Boolean‐valued.

     _C_a_u_t_i_o_n_: Built‐in registers are subject to removal like  others;  once  re‐
     moved, they can be recreated only as normal writable registers and will not
     otherwise reflect the configuration of the formatter.

     A  register name is often associated with a request of the same name (with‐
     out the dot); exceptions are noted.

     \n[..$$]         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 macro be‐
                    ing interpreted (Boolean‐valued).
     \n[..cc]         Input line number; see llff and register “cc..”.
     \n[..CC]         AT&T _t_r_o_f_f 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;  positive
                    if glyph extends below the baseline.
     \n[..ccee]        Count  of  input lines remaining to be centered in the envi‐
                    ronment.
     \n[..cchhtt]       Height of last glyph formatted in the environment;  positive
                    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 reg‐
                    ister ..CC.
     \n[..ccsskk]       Skew  of  the  last  glyph formatted in the environment; see
                    register sskkww.
     \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 the environment’s default font  family  (string‐val‐
                    ued).
     \n[..ffnn]        Resolved  name  of font selected in the environment (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]    Height of the environment’s selected font; 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[..hhyyddeeffaauulltt]
                    Hyphenation mode default in environment.
     \n[..hhyymm]       Hyphenation margin in environment.
     \n[..hhyyss]       Hyphenation space adjustment threshold in environment.
     \n[..ii]         Environment’s indentation amount; see ”iinn”.
     \n[..iinn]        Indentation amount applicable to the output line pending  in
                    the environment; see ttii.
     \n[..iinntt]       The text most recently formatted in the environment was “in‐
                    terrupted” or continued with \\cc (Boolean‐valued).
     \n[..iitt]        Count  of input lines remaining in the environment’s pending
                    input trap.
     \n[..iittcc]       The environment’s pending input trap honors output line con‐
                    tinuation with \\cc (Boolean‐valued).
     \n[..iittmm]       Name of the macro associated with  the  pending  input  trap
                    (string‐valued).
     \n[..jj]         The environment’s adjustment mode encoded as an integer; see
                    aadd  and  nnaa.   Do not interpret or perform arithmetic on its
                    value.
     \n[..kk]         The environment’s 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 in the environment (Boolean‐val‐
                    ued).
     \n[..llll]        Line length applicable to the environment’s  pending  output
                    line.
     \n[..lltt]        Environment’s title line length.
     \n[..mm]         Stroke  color  (string‐valued);  see ggccoolloorr and \\mm.  The de‐
                    fault stroke color is named “ddeeffaauulltt”.
     \n[..MM]         Fill color (string‐valued); see ffccoolloorr and \\MM.  The  default
                    fill color is named “ddeeffaauulltt”.
     \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  in   the   environment
                    (Boolean‐valued).
     \n[..nnnn]        Count  of  lines remaining in the environment for which num‐
                    bering is suppressed while output line numbering is enabled.
     \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]        The environment’s type size in scaled points.
     \n[..ppssrr]       The  environment’s  most  recently  requested  type  size in
                    scaled points; see ppss and \\ss.
     \n[..ppvvss]       The environment’s post‐vertical line spacing.
     \n[..RR]         Maximum representable integer in GNU _t_r_o_f_f.
     \n[..rrjj]        Count of input lines remaining to be  right‐aligned  in  the
                    environment.
     \n[..ss]         The  environment’s type size in points as a decimal fraction
                    (string‐valued); see ppss and \\ss.
     \n[..SS]         Reserved.  Plan 9 _t_r_o_f_f uses this name for roughly the  same
                    purpose as GNU _t_r_o_f_f’s \n[..ttaabbss]
     \n[..ssllaanntt]     Slant in degrees of the environment’s selected font; see \\SS.
     \n[..ssrr]        The  environment’s  most  recently  requested  type  size in
                    points as a decimal fraction (string‐valued); see ppss and \\ss.
     \n[..ssss]        Size  of  the  environment’s  minimum  inter‐word  space  in
                    twelfths of the space width of the selected font.
     \n[..ssssss]       Size  of the environment’s supplemental inter‐sentence space
                    in twelfths of the space width of the selected font.
     \n[..ssttyy]       The environment’s selected abstract  style  (string‐valued);
                    see fftt and \\ff.
     \n[..tt]         Distance  to next vertical position trap; see wwhh and cchh.  If
                    no such traps exist between the  drawing  position  and  the
                    bottom  of  the page, _t_r_o_f_f interpolates the distance to the
                    page bottom.  Within a diversion, in the absence of a diver‐
                    sion trap, this distance is the  maximum  possible  vertical
                    position supported by the output device.
     \n[..TT]         An  output  device was explicitly selected (Boolean‐valued);
                    see _t_r_o_f_f --TT option.
     \n[..ttaabbss]      The environment’s tab stop settings (if  any)  suitable  for
                    use as argument to ttaa (string‐valued).
     \n[..ttrraapp]      Name  of  the next vertical position trap after the vertical
                    drawing position.  (string‐valued); see wwhh, cchh, and ddtt.
     \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 in the environment (Boolean‐valued);  see
                    ffii and nnff.
     \n[..UU]         Unsafe  mode  is  enabled (Boolean‐valued); see _t_r_o_f_f --UU op‐
                    tion.
     \n[..vv]         The environment’s 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 last 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  di‐
                    rected to the top‐level diversion.
     \n[..zzoooomm]      Magnification  of  the environment’s selected font (in thou‐
                    sandths; 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‐re‐
     lated 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 that at the start of
                    the input line.
     \n[llllxx]        Lower‐left  _x coordinate (in PostScript units) of PostScript
                    image; see ppssbbbb.
     \n[llllyy]        Lower‐left _y coordinate (in PostScript units) of  PostScript
                    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 formatted out‐
                    put on the page.  They are reset to -1 by \\OO00 or \\OO11.
     \n[rrssbb]        As register ssbb, adding maximum glyph height to measurement.
     \n[rrsstt]        As register sstt, adding maximum glyph depth to measurement.
     \n[ssbb]         Maximum displacement of text baseline below its original po‐
                    sition 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 envi‐
                    ronment by \\ww.
     \n[sstt]         Maximum displacement of text baseline above its original po‐
                    sition after rendering into dummy environment by \\ww.
     \n[ssyyssttaatt]     Return value of _s_y_s_t_e_m(3); see ssyy.
     \n[uurrxx]        Upper‐right _x coordinate (in PostScript units) of PostScript
                    image; see ppssbbbb.
     \n[uurryy]        Upper‐right _y coordinate (in PostScript units) of PostScript
                    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  specific
     typeface  that a device can render as glyphs at a desired size.  (Terminals
     and some typesetters have fonts that render at only one or two  sizes.   As
     examples,  take  the  _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  typefaces  into  _f_a_m_i_l_i_e_s  containing  each of these styles.
     (Font designers prepare families such that the styles share esthetic  prop‐
     erties.)   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
     typesetters, 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 the AT&T _t_r_o_f_f formatter, 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
     characterizes it, including its glyph repertoire and  the  _m_e_t_r_i_c_s  (dimen‐
     sions) of each glyph.  This information permits the formatter to accurately
     place  glyphs with respect to each other.  Before using a font description,
     the formatter associates it with a _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  cou‐
     pled to a specific font family, in GNU _t_r_o_f_f 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 user‐specified font name that combines family and style, or refers
     to a font that is not a member of a family, is already “resolved”.

     Fonts  often  have  trademarked names, and even Free Software fonts can re‐
     quire renaming upon modification.  _g_r_o_f_f maintains a convention that a  de‐
     vice’s serif font family is given the name TT (“Times”), its sans‐serif fam‐
     ily  HH  (“Helvetica”), and its monospaced family CC (“Courier”).  Historical
     inertia has driven _g_r_o_f_f’s font identifiers to  short  uppercase  abbrevia‐
     tions of font names, as with TTRR, TTBB, TTII, TTBBII, and a special 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 default mounting po‐
     sition,  and therefore style, is always 11 (RR).  By issuing appropriate for‐
     matter instructions, you can override these defaults before  your  document
     writes its first glyph.

     Terminals cannot change font families and lack special fonts.  They support
     style changes by overstriking, or by altering ISO 6429/ECMA‐48 _g_r_a_p_h_i_c _r_e_n_‐
     _d_i_t_i_o_n_s (character cell attributes).

     The  fftt  request and \\ff escape sequence select a typeface by name, abstract
     style, or mounting position.  The ffaamm request and \\FF  escape  sequence  set
     the  default  font family.  The ffttrr request translates one font name to an‐
     other; ffzzoooomm magnifies or reduces the typeface corresponding to a  resolved
     one.  ssttyy and ffpp associate abstract styles and font names with mounting po‐
     sitions.

   CChhaarraacctteerrss aanndd ggllyypphhss
     A  glyph is a graphical representation of a character.  Whereas a _c_h_a_r_a_c_t_e_r
     is an abstraction of semantic information, a _g_l_y_p_h is an intelligible  mark
     visible  on  screen or paper.  A character has many possible representation
     forms; for example, the character “A” can  be  written  in  an  upright  or
     slanted  typeface,  producing  distinct  glyphs.   Sometimes, a sequence of
     characters map to a single glyph:@: this is a _l_i_g_a_t_u_r_e——the most common  is
     ‘fi’.

     Space  characters  never  become glyphs in GNU _t_r_o_f_f.  If not discarded (as
     when trailing text lines), horizontal motions represent them in the output.

     The formatter supports three kinds of  character.   An  ordinary  character
     (see section “Identifiers” above) is the most commonly used, has no special
     syntax,  and typically represents itself.  (Depending on the breadth of the
     output device’s glyph repertoire, the characters '', --, ^^, ``, and ~~  can  be
     exceptions  to this rule.  "" and \\ are not exceptions, but because they are
     syntactically meaningful to the formatter, access to their glyphs  may  re‐
     quire  use of special characters (or changing or disabling the escape char‐
     acter).  See _g_r_o_f_f___c_h_a_r(7).   Interpolate  a  _s_p_e_c_i_a_l  _c_h_a_r_a_c_t_e_r  with  the
     “\\[[_x_x_x]]  or  “\\CC''_x_x_x''”  escape sequence syntax, where _x_x_x is an identifier.
     An _i_n_d_e_x_e_d _c_h_a_r_a_c_t_e_r bypasses  most  character‐to‐glyph  resolution  logic,
     uses the “\\NN''_i''syntax, and selects a glyph from the currently selected font
     by  its  integer‐valued position _i in the output device’s representation of
     that font.  (A device’s fonts do not necessarily arrange their  glyphs  ac‐
     cording to a standard character encoding.)

     _U_s_e_r_‐_d_e_f_i_n_e_d  _c_h_a_r_a_c_t_e_r_s  are  similar  to  string definitions (see section
     “Strings” above) and permit extension of or substitution within the charac‐
     ter repertoire.  Any ordinary, special, or indexed character can  be  user‐
     defined.   The  cchhaarr, ffcchhaarr, sscchhaarr, and ffsscchhaarr requests create user‐defined
     characters employed at various stages of the character‐to‐glyph  resolution
     process.

     In  a  _t_r_o_f_f system, a font description file lists all of the glyphs a par‐
     ticular font provides.  If the user requests a glyph not available  in  the
     currently  selected font, the formatter looks it up an ordered list of _s_p_e_‐
     _c_i_a_l _f_o_n_t_s_.  By default, the “ppss” (PostScript)  and  “ppddff”  output  devices
     support  the  two special fonts “SSSS” (slanted symbol) and “SS” (symbol); and
     these devices’ _D_E_S_C files arrange them such that the formatter searches the
     former before the latter.  Other output devices  use  different  names  for
     special  fonts.   Fonts mounted with the ffoonnttss keyword in the _D_E_S_C file are
     globally available.  GNU _t_r_o_f_f’s ssppeecciiaall and ffssppeecciiaall  requests  alter  the
     list of fonts treated as special on a general basis, or only when a certain
     font is currently selected, respectively.

     GNU  _t_r_o_f_f  employs  the  following procedure to resolve an input character
     into a glyph.  User‐defined characters make this resolution process  recur‐
     sive.   The  first step that succeeds ends the resolution procedure for the
     character being formatted, which may not be the last in the sequence inter‐
     polated by a user‐defined character.

     •      Interpolate the definition of any character defined by the cchhaarr  re‐
            quest and apply this procedure to each character in its definition.

     •      Check the current font for a glyph corresponding to the character.

     •      Interpolate  the  definition  of any user‐defined character matching
            defined by the ffcchhaarr request and apply this procedure to each  char‐
            acter in its definition.

     •      Check  whether  the current font has a font‐specific list of special
            fonts; if so, check the each font therein, in the  order  determined
            by  the  last applicable ffssppeecciiaall request, for a glyph corresponding
            to the character.

     •      Interpolate the definition of any character defined  by  the  ffsscchhaarr
            request for the currently selected font, and apply this procedure to
            each character in its definition.

     •      Check  each  font in the list configured by the most recently issued
            ssppeecciiaall request for a glyph corresponding to the character.

     •      Interpolate the definition of any character defined  by  the  sssscchhaarr
            request  and  apply  this procedure to each character in its defini‐
            tion.

     •      Finally, iterate through the list of mounted fonts by position.  For
            each mounted font, if that font bears  the  ssppeecciiaall  directive  (see
            _g_r_o_f_f___f_o_n_t(5)), check it for a glyph corresponding to the character.
            This  stage of the resolution process can sometimes lead to surpris‐
            ing results since the ffoonnttss directive in the _D_E_S_C  file  often  con‐
            tains  empty  positions  that are filled by a macro file or document
            employing the ffpp request after the formatter initializes.

   SSppeecciiaall ffoonnttss
     Special fonts are those that the formatter searches, in  mounting  position
     order,  when  it cannot find a requested glyph in the selected font.  Typi‐
     cally,  they  are  declared  as  such  in  their  description  files   (see
     _g_r_o_f_f___f_o_n_t(5)),  and contain unstyled glyphs.  The “Symbol” and “Zapf Ding‐
     bats” fonts of the PostScript and PDF standards are examples.   Ordinarily,
     only typesetters have special fonts.

     GNU  _t_r_o_f_f’s  ssppeecciiaall and ffssppeecciiaall requests permit a document to supplement
     the set of fonts the device configures for glyph search without  having  to
     use  the ffpp request to manipulate the list of mounting positions, which can
     be tedious——by default, GNU _t_r_o_f_f mounts 40 fonts at startup when using the
     ppss device.

HHyypphheennaattiioonn
     When filling, _g_r_o_f_f hyphenates words as needed at user‐specified and  auto‐
     matically  determined hyphenation points.  Explicitly hyphenated words such
     as “mother‐in‐law” are always eligible for breaking after each of their hy‐
     phens.  The hyphenation character \\%% 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 hyphen‐
     ation points automatically by default.

     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 details),  and  at  which
     positions  within that word automatically determined hyphenation points are
     permissible.  The localization macro files loaded by  _t_r_o_f_f_r_c  configure  a
     default hyphenation mode appropriate to the language.

     00      disables hyphenation.

     11      enables hyphenation except after the first and before the last char‐
            acter 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 or column, even  for
            explicitly  hyphenated words.  (Hyphenation is prevented if the next
            page location trap is closer to the vertical drawing  position  than
            the next text baseline would be.  See section “Traps” below.)

     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 hyphen‐
     ation character (“\\%%” by default) or the ..hhww request.

     Nonzero values are additive.  For example, mode 12 causes _g_r_o_f_f to  hyphen‐
     ate neither the last two nor the first two characters of a word.  Some val‐
     ues cannot be used together because they contradict; for instance, values 4
     and  16,  and values 8 and 32.  As noted, it is superfluous to add 1 to any
     non‐zero even mode.

     The places within a word that are eligible for hyphenation  are  determined
     by language‐specific data (hhllaa, hhppff, and hhppffaa) and lettercase relationships
     (hhccooddee  and  hhppffccooddee).   Furthermore,  hyphenation  of a word might be sup‐
     pressed 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
     GNU _t_r_o_f_f ties the set of hyphenation patterns to the hyphenation  language
     code  selected 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  localization
     files  for  several  languages;  See  subsection “Localization packages” of
     _g_r_o_f_f___t_m_a_c(5).  For Western languages, the localization file sets  the  de‐
     fault  hyphenation  mode and loads hyphenation patterns and exceptions.  By
     default, _t_r_o_f_f_r_c loads the localization file for English.

WWrriittiinngg mmaaccrrooss
     The ..ddee request defines a macro named for its argument.  If that  name  al‐
     ready exists as an alias, the target of the alias is redefined; see section
     “Strings”  above.  _t_r_o_f_f enters “copy mode” (see below), storing subsequent
     input lines as the definition.  If the  optional  second  argument  is  not
     specified, the definition ends with the control line “....” (two dots).  Tabs
     and  spaces  are permitted between the dots.  Alternatively, a second argu‐
     ment to ..ddee names a macro whose call (or request whose  invocation)  syntax
     ends  the  definition; this _e_n_d _m_a_c_r_o is then interpreted normally.  Spaces
     or tabs are permitted after the first control character in  the  line  con‐
     taining  this  ending token, but a tab immediately after the token prevents
     its recognition as the end of a macro definition.  Macro definitions can be
     nested if they use distinct end macros or if their ending tokens are suffi‐
     ciently escaped.  An end macro need not be  defined  until  it  is  called.
     This  fact  enables a nested macro definition to begin inside one macro and
     end inside another.

     Variants of ..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,  return‐
     ing 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; change its  value  with
     the  ..sshhiifftt  request, which dequeues parameters from the current list.  The
     \\$$00 escape sequence interpolates the name by which a macro was called.  Ap‐
     plying string interpolation to a macro does not change this name.

   CCooppyy mmooddee
     GNU _t_r_o_f_f processes certain requests in _c_o_p_y _m_o_d_e_: it copies ordinary, spe‐
     cial, and indexed characters as‐is; interpolates the escape  sequences  \\nn,
     \\gg,  \\$$, \\**, \\VV, and \\?? normally; discards comments \\"" and \\##; interpolates
     \\aa, \\ee, and \\tt, as the current leader, escape, or tab  character  with  re‐
     spectively;  represents  \\_n_e_w_l_i_n_e,  \\&&, \\__, \\||, \\^^, \\{{, \\}}, \\``, \\'', \\--, \\!!,
     \\cc, \\%%, \\_s_p_a_c_e, \\EE, \\)), \\~~, and \\:: in an encoded form, and copies other es‐
     cape sequences as‐is.  The term “copy mode” reflects its most  visible  ap‐
     plication  in requests that populate macros and strings, but other requests
     also use it when interpreting arguments that can’t  meaningfully  represent
     typesetting  operations.  For example, a font selection escape sequence has
     no meaning in a hyphenation pattern file name (hhppff) or a diagnostic message
     written to the terminal (ttmm).  The complement of copy mode——a _r_o_f_f  format‐
     ter’s behavior when not defining or appending to a macro, string, or diver‐
     sion——where all macros are interpolated, requests invoked, and valid escape
     sequences processed immediately upon recognition, can be termed _i_n_t_e_r_p_r_e_t_a_‐
     _t_i_o_n _m_o_d_e.

     The  escape  character (\\ by default) when used before itself _q_u_o_t_e_s an es‐
     cape character for later interpretation in an  enclosing  context.   Escape
     character quotation enables you to control whether the formatter interprets
     a  given  \\nn,  \\gg,  \\$$, \\**, \\VV, or \\?? escape sequence 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  character
     followed  by  a  backslash  from which the escape character has removed its
     special meaning.  Consequently, \\\\ is not best  considered  an  escape  se‐
     quence,  but  a  quoted  escape  character.  In any escape sequence \\_X that
     _t_r_o_f_f does not recognize, the formatter discards the escape  character  and
     outputs  _X_.   An  unrecognized escape sequence causes a warning in category
     “eessccaappee”, with two exceptions, \\\\ being one.  The other is \\.., which quotes
     the control character.  It is used to permit nested  macro  definitions  to
     end  without  a  named  macro  call to conclude them.  Without a syntax for
     quoting the control character, this would not be possible.  Outside of copy
     mode, _r_o_f_f documents should not use the \\\\ or \\.. character sequences;  they
     serve  only to obfuscate the input.  Use \\ee to represent the escape charac‐
     ter, \\[[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.  Given the input char‐
     acter sequence “\\\\” in a macro or string definition, the  formatter  inter‐
     prets each escape character in multiple contexts; once, when populating the
     macro  or  string,  where the first “\\” serves its quotation function——thus
     only one “\\” is stored in the definition.  (Verify this fact  with  the  ppmm
     request.)   The  formatter interprets the second “\\” as an escape character
     (assuming the escape character hasn’t been changed in  the  meantime)  each
     time  it  interpolates  the macro or string definition.  This fact leads to
     exponential growth in the quantity of escape characters required  to  quote
     and thereby delay interpolation of \\nn, \\gg, \\$$, \\**, \\VV, and \\?? at each nest‐
     ing level.  An alternative is to use \\EE, which represents an escape charac‐
     ter  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  pre‐
     maturely.   If the multiplicity of backslashes complicates 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 either on the page (wwhh, cchh)  or  in  the  current  diversion
     (ddtt)——together,  these  are  known as vertical position traps, which can be
     disabled and reënabled (vvpptt).

     A diversion is not formatted in the context of a page, so it lacks page lo‐
     cation 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 productive  input
     lines (iitt, iittcc); or at the end of input (eemm).

     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.

     The formatter passes no arguments to macros called by traps.

     Registers associated with trap management include  vertical  position  trap
     enablement  status  (\\nn[[..vvpptt]]), distance to the next trap (\\nn[[..tt]]), and the
     name of that trap (\\nn[[..ttrraapp]]); the count of lines remaining in the  pending
     input  trap (\\nn[[..iitt]]), the name of the macro associated with it (\\nn[[..iittmm]]),
     and whether that input trap honors the \\cc output line  continuation  escape
     sequence (\\nn[[..iittcc]]); amount of needed (..nnee‐requested) space that caused the
     most recent vertical position trap to be sprung (\\nn[[..nnee]]), amount of needed
     space  truncated from the amount requested (\\nn[[..ttrruunncc]]); page ejection sta‐
     tus (\\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 the top‐level diversion.  Many can be present; manage them with
     the wwhh and cchh requests.  Non‐negative page locations  given  to  these  re‐
     quests  set  the  trap relative to the top of the page; negative values set
     the trap relative to the bottom of the page.  It is not possible to plant a
     trap less than one basic unit from the page bottom: a location of  “-0”  is
     interpreted as “0”, the top of the page.  An existing _v_i_s_i_b_l_e trap (see be‐
     low)  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 reach‐
     able on the page and it is not hidden by another trap at the same  location
     already  planted  there.   (A  trap  planted at “20i” or “-30i” will not be
     sprung on a page of length “11i”.)

     A trap above the top or at or below the bottom of the page can be made vis‐
     ible by either moving it into the page area or increasing the  page  length
     so  that  the  trap  is on the page.  A negative trap value always uses the
     _c_u_r_r_e_n_t page length; the formatter does not convert it to an absolute  ver‐
     tical  position.  We can use the ppwwhh request to dump page location traps to
     the standard error stream; see section “Debugging” below.   GNU  _t_r_o_f_f  re‐
     ports their positions in basic units, and includes empty slots in the list,
     where  a trap had been planted but subsequently (re)moved, because they can
     affect the visibility of subsequently planted traps.

   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 (see below);
     its purpose is to eject the current page and start the next one.  It  works
     like  a  trap in some ways but not others.  It has no name, so it cannot be
     moved or deleted with wwhh or cchh requests.  You cannot hide it by placing an‐
     other trap at its location, and can move it only  by  redefining  the  page
     length  with  ppll.  Its operation is suppressed when vertical page traps are
     disabled with GNU _t_r_o_f_f_’_s vvpptt request.

DDiivveerrssiioonnss
     In _r_o_f_f systems it is possible to format text as if for output, but instead
     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 after a control
     character.   The  formatter uses the same name space 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 obscures the im‐
     portant  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  cap‐
     ture _f_o_r_m_a_t_t_e_d output.  Diversions also do not interpret arguments.  Appli‐
     cations  of  diversions include footnotes, tables of contents, indices, and
     “keeps” (preventing a page break from occurring at an inconvenient place by
     forcing a set of output lines to be set as a group).  For orthogonality  it
     is said that GNU _t_r_o_f_f populates 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 output is being “diverted” directly to the out‐
     put device).  The top‐level diversion has no name.

     Dereferencing an undefined diversion creates an empty  one  of  that  name.
     (GNU  _t_r_o_f_f  also emits a warning in category “mac”; see section “Warnings”
     of _t_r_o_f_f(1).)  A diversion does not exist for the purpose of  testing  with
     the  dd  conditional  expression 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.  The pending output
     line is diverted as well.  Switching to another environment  (with  the  eevv
     request)  before invoking ddii or ddaa avoids including any pending output line
     in the diversion.  (See section “Environments[” below.)

     Invoking ddii or ddaa without an argument stops diverting output to the  diver‐
     sion  named  by  the  most recent corresponding request.  Invoking ddii or ddaa
     without an argument when no diversion  is  being  populated  does  nothing.
     (GNU  _t_r_o_f_f  emits  a  warning  in category “di”; see section “Warnings” of
     _t_r_o_f_f(1).)

     bbooxx and bbooxxaa work similarly, but ignore partially  collected  lines.   Call
     any of these macros again without an argument to end the diversion.

     Diversion  requests can be nested.  The registers ..dd and ..zz report informa‐
     tion about the current diversion, and ddnn and ddll  about  the  most  recently
     closed one.  ..hh is meaningful in diversions, including the top‐level one.

     After  output to a (named) diversion stops, the formatter stores its verti‐
     cal and horizontal sizes, to the writable  registers  ddnn  and  ddll,  respec‐
     tively.   Only the lines just processed are counted: for the computation of
     ddnn and ddll, the requests ddaa and bbooxxaa are handled as if ddii and bbooxx  had  been
     used,  respectively——lines  that  have been already stored in the diversion
     (box) are not taken into account.

     The \\!! and \\?? escape sequences and oouuttppuutt request escape from a  diversion,
     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  “Identi‐
     fiers”  above.   Internally, the same mechanism is used to store them.  You
     can thus call a macro with string interpolation syntax and vice versa.  In‐
     terpolating a string does not hide existing macro arguments.  Place the se‐
     quence \\\\ at the end of a line in a macro definition or, within a macro de‐
     finition, immediately after the interpolation of a macro as  a  string,  to
     suppress the effect of a newline.

EEnnvviirroonnmmeennttss
     Environments  store most of the parameters that control text processing.  A
     default environment named “00” (zero) exists when exists when the  formatter
     starts  up;  formatting‐related  requests  and  escape sequences modify its
     properties.

     You can create new environments and switch among them.  Only one is current
     at any given time.  Active environments are managed using a _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 current environment; it remains  ac‐
     cessible  by  name and can be made current again by pushing it at any time.
     Environments cannot be renamed or deleted, and can only  be  modified  when
     current.   To  inspect the environment stack, use the ppeevv request; see sec‐
     tion “Debugging” below.

     Environments store the following information.

     •  a partially collected line, if any

     •  data about the most recently output  glyph  and  line  (registers  ..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 spac‐
        ing, indentation, line numbering, centering, right‐alignment,  underlin‐
        ing, hyphenation parameters)

     •  filling enablement; adjustment enablement and mode

     •  tab  stops; tab, leader, escape, control, no‐break control, hyphenation,
        and margin characters

     •  input line traps

     •  stroke and fill colors

     The eevv request (with an argument) pushes to and (without) pops from the en‐
     vironment stack, while eevvcc copies a named environment’s parameters  to  the
     current one.

PPoossttpprroocceessssoorr aacccceessss
     Beyond  the  ccff and ttrrff requests, two escape sequences and two requests en‐
     able documents to pass information directly to a postprocessor.  These  are
     useful  for exercising device‐specific capabilities that the _g_r_o_f_f language
     does not abstract or generalize; examples include the embedding  of  hyper‐
     links  and  image  files.  Device‐specific functions are documented in each
     output driver’s man page, such as _g_r_o_p_d_f(1), _g_r_o_p_s(1), or _g_r_o_t_t_y(1).

     The “ddeevviiccee” request and \\XX escape sequence embed their arguments into  GNU
     _t_r_o_f_f  output  as  parameters  to  an  “xx  XX” device extension command (see
     _g_r_o_f_f___o_u_t(5)).  The interpretation of such parameters is determined by  the
     output driver or other postprocessor.

     GNU  _t_r_o_f_f  also permits the interpolation of macro or string contents as a
     device extension command.  The ddeevviicceemm request and \\YY escape sequence  cor‐
     respond to “..ddeevviiccee \\**[[_n_a_m_e]]” and “\\XX''\\**[[_n_a_m_e]]”, respectively.  They differ
     from  their  counterparts in that GNU _t_r_o_f_f does not interpret the contents
     of the string or macro _n_a_m_e; further, _n_a_m_e may be a macro and thus  contain
     newlines.  (There is no way to embed a newline in the arguments to “ddeevviiccee”
     or  \\XX.)  The inclusion of newlines requires an extension to the AT&T _t_r_o_f_f
     device‐independent page description language, and their  presence  confuses
     drivers that do not know about it (see subsection “Device control commands”
     of _g_r_o_f_f___o_u_t(5)).

     Use of device extension commands early in a document (before the first text
     is formatted) can interfere with processing of page location traps.  If you
     experience problems when placing them early, precede the first with a dummy
     character escape sequence “\\&&”; recall section “Dummy Characters” above.

     The ttaagg and ttaaggaa requests are reserved for internal use.

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  targeted.
     Typesetter  output posed a greater challenge.  There exists a _g_r_o_f_f request
     ..uull (see above) that underlines subsequent source lines on  terminals,  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  de‐
     sired effect only on typesetters, and has other limitations.

     One could adapt _m_s’s approach to the construction of a macro as follows.
            .de UNDERLINE
            . ie n \\$1\f[I]\\$2\f[P]\\$3
            . el \\$1\Z'\\$2'\v'.25m'\D'l \w'\\$2'u 0'\v'-.25m'\\$3
            ..
     If  _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  selection
     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  posi‐
     tion,  enabling  overstriking.   Thus,  \\zz_c\\((uull formats _c with an underrule
     glyph on top of it.  Video terminals implement the underrule by  setting  a
     character cell’s underline attribute, so this technique works in both _n_r_o_f_f
     and _t_r_o_f_f modes.

     Long  words  may then look intimidating in the input; a clarifying approach
     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
     _g_r_o_f_f___d_i_f_f(7) documents 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 page description formats described by CSTR #54.  GNU _t_r_o_f_f pro‐
     vides an AT&T _t_r_o_f_f compatibility mode.  The ccpp request  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 diagnostics and
     supports several categories of warning; the output of these can  be  selec‐
     tively  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  emit‐
     ted when errors or warnings occur by means of _t_r_o_f_f(1)’s --bb option, or pro‐
     duced  on  demand with the bbaacckkttrraaccee request.  ttmm, ttmmcc, and ttmm11 can be used
     to emit customized diagnostic messages or for instrumentation  while  trou‐
     bleshooting.   eexx  and aabb cause early termination with successful and error
     exit codes respectively, to halt further processing when  continuing  would
     be  fruitless.  Examine the state of the formatter with requests that write
     lists of defined names——macros, strings, and  diversions——(ppmm);  characters
     (ppcchhaarr; experimental); colors (ppccoolloorr); composite character mappings (ppccoomm‐‐
     ppoossiittee);  environments  (ppeevv); occupied font mounting positions (ppffpp); font
     translations (ppffttrr); automatic hyphenation  codes  (ppcchhaarr)  and  exceptions
     (pphhww);  registers  (ppnnrr);  open  streams (ppssttrreeaamm); and page location traps
     (ppwwhh).  Requests can also disclose to the standard error stream the  inter‐
     nal  properties  and  representations  of  characters  and classes (ppcchhaarr),
     macros (and strings and diversions) (ppmm), and the list of output nodes cor‐
     responding to the pending input line (pplliinnee).

AAuutthhoorrss
     This document was written by Trent A. Fisher, Werner Lemberg, and G.  Bran‐
     den 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 Lem‐
     berg, 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 page description lan‐
     guage 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), provides
     additional  insights  into the device and font description file formats and
     device‐independent page description language.

     _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 printable 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 and escape sequences that pro‐
            duce glyphs.

     _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 page descrip‐
            tion language, and those of AT&T _t_r_o_f_f.

     _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 documents
            can take advantage of them, offers guidance on writing  macro  pack‐
            ages and using diversions, and includes historical information.

     _r_o_f_f(7)
            presents  a detailed history of _r_o_f_f systems and summarizes concepts
            common to them.

groff 1.24.1                       2026‐04‐22                           _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 mathematical
     documents.  _g_r_o_f_f works with _c_h_a_r_a_c_t_e_r_s_; an output device  renders  _g_l_y_p_h_s_.
     _g_r_o_f_f’s   input  character  set  is  restricted  to  that  defined  by  the
     ISO Latin‐1 (ISO 8859‐1) standard.  For ease  of  document  maintenance  in
     UTF‐8  environments,  it  is  advisable to use only the Unicode basic Latin
     code points; these correspond to ISO 646:1991 IRV (US‐ASCII), a  subset  of
     all  of the foregoing which has only 94 visible, printable code points.  In
     _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 typesetter’s
     glyph  repertoire  differed  from that of the computers that controlled 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  permits
     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 “Iden‐
     tifiers” in _g_r_o_f_f(7).  Our discussion uses the terms “glyph name” and “spe‐
     cial character name” interchangeably; we assume no  character  translations
     or redefinitions.

     This  document  lists all of the glyph names predefined by _g_r_o_f_f’s font de‐
     scription files and presents the systematic notation by  which  it  enables
     access  to  arbitrary  Unicode  code  points  and construction of composite
     glyphs.  Glyphs listed may be unavailable, or may vary in  appearance,  de‐
     pending  on  the output device and font chosen when the page was formatted.
     This page was rendered for device uuttff88 primarily using font RR.

     A few escape sequences that are not _g_r_o_f_f special characters  also  produce
     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 special characters represent
     glyphs that are not encoded in Unicode; examples include the baseline  rule
     \\[[rruu]] and the Bell System logo \\[[bbss]]..

     In  _g_r_o_f_f,  test  support  for any character (ordinary 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.

     While _g_r_o_f_f accepts eight‐bit encoded input, not all such code  points  are
     valid  as  input.   Character  codes 0, 11, 13–31, and 128–159 are invalid.
     (This is all C0 and C1 controls except for SOH  through  LF  [Control+A  to
     Control+J],  and  FF  [Control+L].)   Some of these code points are used by
     _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.  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.

     All of the following characters map to glyphs as you would expect.
           ┌───────────────────────────────────────────────────────────┐
           │ ! # $ % & ( ) * + , . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ? @ │
           │ A B C D E F G H I J K L M N O P Q R S T U V W X Y Z [ ] _ │
           │ a b c d e f g h i j k l m n o p q r s t u v w x y z { | } │
           └───────────────────────────────────────────────────────────┘
     The remaining ordinary characters surprise computing professionals and oth‐
     ers intimately familiar with the ISO character encodings.   The  developers
     of  AT&T _t_r_o_f_f chose mappings for them that would be useful for typesetting
     technical literature in a broad range of scientific disciplines: Bell  Labs
     used  the system to prepare AT&T’s patent filings with the U.S. government.
     Further,  the  prevailing  character  encoding  standard  in   the   1970s,
     USAS  X3.4‐1968  (ASCII), deliberately supported semantic ambiguity at some
     code points, and outright substitution at several others, to suit  the  lo‐
     calization demands of various national standards bodies.

     The table below presents the seven exceptional code points with their typi‐
     cal  keycap engravings, their glyph mappings and semantics in _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 partial exception be‐
     cause 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 special character  escape  sequence
     as  an  alternative  form so that the glyph can be easily included in macro
     arguments without requiring the user to master the quoting rules that  AT&T
     _t_r_o_f_f required in that context.  (Some requests, like ddss, also treat "" non‐
     literally  at  the  beginning of an argument.)  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 character 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 distinguish‐
     able  purposes  to  which it had already been put by the 1980s, including a
     hyphen, a minus sign, and  (alone  or  in  repetition)  dashes  of  varying
     widths.   For  best results in _r_o_f_f systems, use the “--” character 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 file name or 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  ex‐
     pressions,  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  sin‐
     gle  quote is typically needed only in technical content; typing words like
     “can’t” and “Anne’s” in a natural way will render correctly, because in or‐
     dinary prose an apostrophe is typeset either as a closing single  quotation
     mark  or  as  a  neutral single quote, depending on the capabilities of the
     output device.  By contrast, special character escape sequences  should  be
     used  for quotation marks unless portability to limited or historical _t_r_o_f_f
     implementations is necessary; on those systems, the input convention is  to
     pair  the grave accent with the apostrophe for single quotes, and to double
     both characters for double quotes.  AT&T _t_r_o_f_f defined no  special  charac‐
     ters  for  quotation  marks  or  the  apostrophe.   Repeated  single quotes
     (‘‘thus’’) will be visually distinguishable from double quotes (“thus”)  on
     terminal devices, and perhaps on others (depending on the font selected and
     its kerning configuration).
        ┌─────────────────────────────────────────────────────────────────┐
        │ AT&T _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  quota‐
     tion, or define them yourself (except in man pages).

     Using  Unicode basic Latin characters to compose boxes and lines is ill‐ad‐
     vised.  _r_o_f_f systems have dedicated features  for  drawing  horizontal  and
     vertical  lines,  the \\ll, \\LL, and \\DD escape sequences.  Also see subsection
     “Rules and lines” below.  Preprocessors like _t_b_l(1) and _p_i_c(1)  draw  boxes
     and  will  produce the best possible 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  Latin‐1 (8859‐1) allocated the additional space to
     what Unicode calls “C1 controls” (control characters) and the “Latin‐1 sup‐
     plement”.  The C1 controls are neither printable nor usable  as  GNU  _t_r_o_f_f
     input.

     GNU  _t_r_o_f_f  handles  two Latin‐1 supplement characters specially, and never
     produces them as output.

     NBSP   encodes a no‐break space; it maps to \\~~, the adjustable non‐breaking
            space escape sequence.

     SHY    encodes a soft hyphen; it maps to \\%%, the hyphenation control escape
            sequence.

     The remaining characters in the Latin‐1  supplement  represent  themselves.
     Although  they  can be specified directly with the keyboard on systems con‐
     figured to use Latin‐1 as the character encoding, it is more portable, both
     to other _r_o_f_f systems and to UTF‐8 environments, to use their special char‐
     acter escape sequences, shown below.  The glyph  descriptions  we  use  are
     non‐standard in some cases, for brevity.

     ¡  \[r!] inverted exclamation mark     Ñ  \[~N] N tilde
     ¢  \[ct] cent sign                     Ò  \[`O] O grave
     £  \[Po] pound sign                    Ó  \['O] O acute
     ¤  \[Cs] currency sign                 Ô  \[^O] O circumflex
     ¥  \[Ye] yen sign                      Õ  \[~O] O tilde
     ¦  \[bb] broken bar                    Ö  \[:O] O dieresis
     §  \[sc] section sign                  ×  \[mu] multiplication sign
     ¨  \[ad] dieresis accent               Ø  \[/O] O slash
     ©  \[co] copyright sign                Ù  \[`U] U grave
     ª  \[Of] feminine ordinal indicator    Ú  \['U] U acute
     «  \[Fo] left double chevron           Û  \[^U] U circumflex
     ¬  \[no] logical not                   Ü  \[:U] U dieresis
     ®  \[rg] registered sign               Ý  \['Y] Y acute
     ¯  \[a-] macron accent                 Þ  \[TP] uppercase thorn
     °  \[de] degree sign                   ß  \[ss] lowercase sharp s
     ±  \[+-] plus‐minus                    à  \[`a] a grave
     ²  \[S2] superscript two               á  \['a] a acute
     ³  \[S3] superscript three             â  \[^a] a circumflex
     ´  \[aa] acute accent                  ã  \[~a] a tilde
     µ  \[mc] micro sign                    ä  \[:a] a dieresis
     ¶  \[ps] pilcrow sign                  å  \[oa] a ring
     ·  \[pc] centered period               æ  \[ae] ae ligature
     ¸  \[ac] cedilla accent                ç  \[,c] c cedilla
     ¹  \[S1] superscript one               è  \[`e] e grave
     º  \[Om] masculine ordinal indicator   é  \['e] e acute
     »  \[Fc] right double chevron          ê  \[^e] e circumflex
     ¼  \[14] one quarter symbol            ë  \[:e] e dieresis
     ½  \[12] one half symbol               ì  \[`i] i grave
     ¾  \[34] three quarters symbol         í  \['i] e acute
     ¿  \[r?] inverted question mark        î  \[^i] i circumflex
     À  \[`A] A grave                       ï  \[:i] i dieresis
     Á  \['A] A acute                       ð  \[Sd] lowercase eth
     Â  \[^A] A circumflex                  ñ  \[~n] n tilde
     Ã  \[~A] A tilde                       ò  \[`o] o grave
     Ä  \[:A] A dieresis                    ó  \['o] o acute
     Å  \[oA] A ring                        ô  \[^o] o circumflex
     Æ  \[AE] AE ligature                   õ  \[~o] o tilde
     Ç  \[,C] C cedilla                     ö  \[:o] o dieresis
     È  \[`E] E grave                       ÷  \[di] division sign
     É  \['E] E acute                       ø  \[/o] o slash
     Ê  \[^E] E circumflex                  ù  \[`u] u grave
     Ë  \[:E] E dieresis                    ú  \['u] u acute
     Ì  \[`I] I grave                       û  \[^u] u circumflex
     Í  \['I] I acute                       ü  \[:u] u dieresis
     Î  \[^I] I circumflex                  ý  \['y] y acute
     Ï  \[:I] I dieresis                    þ  \[Tp] lowercase thorn
     Ð  \[-D] uppercase eth                 ÿ  \[:y] y dieresis

   SSppeecciiaall cchhaarraacctteerr eessccaappee ffoorrmmss
     Glyphs that lack a character code in the basic Latin repertoire to directly
     represent  them  are  entered  by  one  of several special character escape
     forms.  Such glyphs can be simple or composite, and accessed either by name
     or numerically by code point.  Code points and combining properties are de‐
     termined by character encoding standards, whereas glyph names as used  here
     originated  in  AT&T  _t_r_o_f_f special character escape sequences.  Predefined
     glyph names use only characters in the basic 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 supported 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 apos‐
            trophe, can be any character not occurring in _g_l_y_p_h_‐_n_a_m_e.  This syn‐
            tax form was introduced in later versions of AT&T device‐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 forego‐
            ing acute accent example can be expressed in in GNU _t_r_o_f_f as \\[[aaaa]].

     \\CC''_c'' and \\[[_c]] are not synonyms for the ordinary character “_c”, but request
     the special character named “\\_c”.  For example,  “\\[[aa]]”  is  not  “a”,  but
     rather  a  special character with the internal glyph name (used in font de‐
     scription files and diagnostic messages) \\aa, which is typically  undefined.
     The  only  such  glyph  name  _g_r_o_f_f predefines is the minus 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 ac‐
            cent, as in the word “café”, can be expressed as \\[[ee aaaa]].

     Normally, the formatter advances the drawing position after setting a  spe‐
     cial  character,  as  it does for ordinary ones.  _g_r_o_f_f’s ccoommppoossiittee request
     designates a special character as combining, suppressing advancement.

     You can obtain a report of mappings defined by the ccoommppoossiittee request on the
     standard error stream with  the  ppccoommppoossiittee  request.   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 certain spe‐
     cial characters to combining characters as shown  in  subsection  “Accents”
     below.

     Unicode encodes far more characters than _g_r_o_f_f has names for; special char‐
     acter  escape  forms based on numerical code points enable access to any of
     them.  Frequently used glyphs  or  glyph  combinations  can  be  stored  in
     strings,  and  new glyph names can be created _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, producing “˚”.

     Unicode code points can be composed as well; when they are, GNU  _t_r_o_f_f  re‐
     quires  NFD  (Normalization Form D), where all Unicode glyphs are maximally
     decomposed.  (Exception: precomposed characters in the  Latin‐1  supplement
     described  above are also accepted.  Do not count on this exception remain‐
     ing in a future GNU _t_r_o_f_f that accepts UTF‐8 input  directly.)   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 character
            escape sequences.  The code points of the base glyph and the combin‐
            ing 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  leading  ze‐
            roes.  This legacy numeric special character escape sequence is used
            to  map  characters  onto glyphs via the ttrriinn request 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 replace‐
              ment), _g_r_o_f_f attempts reasonable equivalency  on  all  output  de‐
              vices.

     IInnppuutt    shows the _g_r_o_f_f character (ordinary or special) that normally pro‐
              duces 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 Unicode  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 pur‐
              poses.  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 that are not uncommon in running text
              have “text variants”, which should work better  in  that  context.
              Conversely,  a  handful  of  glyphs that are normally drawn from a
              text font may be required in mathematical expressions.  Both  sets
              of  exceptions are noted in the tables where they appear (“Logical
              symbols” and “Mathematical symbols”).

   BBaassiicc LLaattiinn
     Apart from basic Latin characters with special mappings, described in  sub‐
     section  “Fundamental character set” above, a few others in that range have
     special character glyph names.  These were defined for  ease  of  input  on
     non‐U.S.  keyboards  lacking  keycaps  for them, or for symmetry with other
     special character glyph names serving a similar purpose.

     The vertical bar is overloaded; the \\[[bbaa]] and \\[[oorr]]  escape  sequences  may
     render  differently.   See  subsection “Mathematical symbols” below for un‐
     styled variants of the plus, minus, and equals signs  normally  drawn  from
     this range.

     Output   Input   Unicode   Notes
     ───────────────────────────────────────────────────────────────────────────
     "        \[dq]   u0022     neutral double quote
     #        \[sh]   u0023     number sign
     $        \[Do]   u0024     dollar sign
     '        \[aq]   u0027     apostrophe, neutral single quote
     /        \[sl]   u002F     slash, solidus +
     @        \[at]   u0040     at sign
     [        \[lB]   u005B     left square bracket
     \        \[rs]   u005C     reverse solidus
     ]        \[rB]   u005D     right square bracket
     ^        \[ha]   u005E     circumflex, caret, “hat”
     {        \[lC]   u007B     left brace
     |        |       u007C     bar +
     |        \[ba]   u007C     bar
     |        \[or]   u007C     bitwise or +
     }        \[rC]   u007D     right brace
     ~        \[ti]   u007E     tilde

   SSuupppplleemmeennttaarryy LLaattiinn lleetttteerrss
     Historically,  \\[[ssss]]  developed from a ligature of “sz”.  An uppercase 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
     The  non‐combining code point in parentheses is used when the special char‐
     acter 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 be‐
     low are short aliases for convenience.

     Output   Input   Unicode      Notes
     ───────────────────────────────────────────────────────────────────────────
     Á        \['A]   u0041_0301   A acute
     Ć        \['C]   u0043_0301   C acute
     É        \['E]   u0045_0301   E acute
     Í        \['I]   u0049_0301   I acute
     Ó        \['O]   u004F_0301   O acute
     Ú        \['U]   u0055_0301   U acute
     Ý        \['Y]   u0059_0301   Y acute
     á        \['a]   u0061_0301   a acute
     ć        \['c]   u0063_0301   c acute
     é        \['e]   u0065_0301   e acute
     í        \['i]   u0069_0301   i acute
     ó        \['o]   u006F_0301   o acute
     ú        \['u]   u0075_0301   u acute
     ý        \['y]   u0079_0301   y acute

     Ä        \[:A]   u0041_0308   A dieresis
     Ë        \[:E]   u0045_0308   E dieresis
     Ï        \[:I]   u0049_0308   I dieresis
     Ö        \[:O]   u004F_0308   O dieresis
     Ü        \[:U]   u0055_0308   U dieresis
     Ÿ        \[:Y]   u0059_0308   Y dieresis
     ä        \[:a]   u0061_0308   a dieresis
     ë        \[:e]   u0065_0308   e dieresis
     ï        \[:i]   u0069_0308   i dieresis
     ö        \[:o]   u006F_0308   o dieresis
     ü        \[:u]   u0075_0308   u dieresis
     ÿ        \[:y]   u0079_0308   y dieresis

     Â        \[^A]   u0041_0302   A circumflex
     Ê        \[^E]   u0045_0302   E circumflex
     Î        \[^I]   u0049_0302   I circumflex
     Ô        \[^O]   u004F_0302   O circumflex
     Û        \[^U]   u0055_0302   U circumflex
     â        \[^a]   u0061_0302   a circumflex
     ê        \[^e]   u0065_0302   e circumflex
     î        \[^i]   u0069_0302   i circumflex
     ô        \[^o]   u006F_0302   o circumflex
     û        \[^u]   u0075_0302   u circumflex

     À        \[`A]   u0041_0300   A grave
     È        \[`E]   u0045_0300   E grave
     Ì        \[`I]   u0049_0300   I grave
     Ò        \[`O]   u004F_0300   O grave
     Ù        \[`U]   u0055_0300   U grave
     à        \[`a]   u0061_0300   a grave
     è        \[`e]   u0065_0300   e grave
     ì        \[`i]   u0069_0300   i grave
     ò        \[`o]   u006F_0300   o grave
     ù        \[`u]   u0075_0300   u grave

     Ã        \[~A]   u0041_0303   A tilde
     Ñ        \[~N]   u004E_0303   N tilde
     Õ        \[~O]   u004F_0303   O tilde
     ã        \[~a]   u0061_0303   a tilde
     ñ        \[~n]   u006E_0303   n tilde
     õ        \[~o]   u006F_0303   o tilde

     Š        \[vS]   u0053_030C   S caron
     š        \[vs]   u0073_030C   s caron
     Ž        \[vZ]   u005A_030C   Z caron
     ž        \[vz]   u007A_030C   z caron

     Ç        \[,C]   u0043_0327   C cedilla
     ç        \[,c]   u0063_0327   c cedilla

     Å        \[oA]   u0041_030A   A ring
     å        \[oa]   u0061_030A   a ring

   QQuuoottaattiioonn mmaarrkkss
     The  neutral  double quote, useful in documenting programming languages, is
     also available as a special character for convenient embedding in macro ar‐
     guments; see subsection “Fundamental character set” above.

     Output   Input   Unicode   Notes
     ───────────────────────────────────────────────────────────────────────────
     „        \[Bq]   u201E     low double comma quote
     ‚        \[bq]   u201A     low single comma quote
     “        \[lq]   u201C     left double quote
     ”        \[rq]   u201D     right double quote
     ‘        \[oq]   u2018     single opening (left) quote
     ’        \[cq]   u2019     single closing (right) quote
     '        \[aq]   u0027     apostrophe, neutral single quote
     "        "       u0022     neutral double quote
     "        \[dq]   u0022     neutral double quote
     «        \[Fo]   u00AB     left double chevron
     »        \[Fc]   u00BB     right double chevron
     ‹        \[fo]   u2039     left single chevron
     ›        \[fc]   u203A     right single chevron

   PPuunnccttuuaattiioonn
     The Unicode name for U+00B7 is “middle dot”, which is unfortunately confus‐
     able with the _g_r_o_f_f mnemonic for the visually similar but semantically dis‐
     tinct multiplication dot; see subsection “Mathematical symbols” below.

     Output   Input   Unicode   Notes
     ───────────────────────────────────────────────────────────────────────────
     ¡        \[r!]   u00A1     inverted exclamation mark
     ¿        \[r?]   u00BF     inverted question mark
     ·        \[pc]   u00B7     centered period
     ——       \[em]   u2014     em‐dash +
     –        \[en]   u2013     en‐dash
     ‐        -       u2010     hyphen +
     ‐        \[hy]   u2010     hyphen +

   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‐invariant;  _g_r_o_f_f  maps
     them  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 formatter’s piling algorithm.  The following  macro
     offers a more general bracket‐building solution.
            .\" Make a pile centered vertically 0.5em above the baseline.
            .\" The first argument is placed at the top.
            .\" The pile is returned in string 'pile'.
            .eo
            .de pile-make
            .  nr pile-wd 0
            .  nr pile-ht 0
            .  ds pile-args
            .
            .  nr pile-# \n[.$]
            .  while \n[pile-#] \{\
            .    nr pile-wd (\n[pile-wd] >? \w'\$[\n[pile-#]]')
            .    nr pile-ht +(\n[rst] - \n[rsb])
            .    as pile-args \v'\n[rsb]u'\"
            .    as pile-args \Z'\$[\n[pile-#]]'\"
            .    as pile-args \v'-\n[rst]u'\"
            .    nr pile-# -1
            .  \}
            .
            .  ds pile \v'(-0.5m + (\n[pile-ht]u / 2u))'\"
            .  as pile \*[pile-args]\"
            .  as pile \v'((\n[pile-ht]u / 2u) + 0.5m)'\"
            .  as pile \h'\n[pile-wd]u'\"
            ..
            .ec

     Further  complicating  matters  is  that  some  glyphs representing bracket
     pieces in AT&T _t_r_o_f_f can be used for other mathematical  symbols  as  well;
     for  example,  \\((llff  and  \\((rrff provide the floor operator.  Some output de‐
     vices, 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  “Brack‐
     ets” 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 ordinary character __ 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 subsection “Mathe‐
     matical symbols” below.

     Output   Input   Unicode   Notes
     ───────────────────────────────────────────────────────────────────────────
     |        |       u007C     bar
     |        \[ba]   u007C     bar
     │        \[br]   u2502     box rule +
     _        _       u005F     underscore, low line +
     _        \[ul]   ‐‐‐       underrule +
     ‾        \[rn]   u203E     overline +
     _        \[ru]   ‐‐‐       baseline rule +
     ¦        \[bb]   u00A6     broken bar
     /        /       u002F     slash, solidus +
     /        \[sl]   u002F     slash, solidus +
     \        \[rs]   u005C     reverse solidus

   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  depending
     on  the device and font selected.  Unicode does not encode a discrete “bit‐
     wise or” sign: on typesetting devices, it is drawn shorter  than  the  bar,
     about  the  same  height as a capital letter.  Terminal devices unify \\[[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.   The
     plus‐minus,  multiplication,  and  division signs, \\[[++--]], \\[[mmuu]], and \\[[ddii]],
     are normally drawn from the special font, but have text font variants.  The
     plus, minus, and equals signs are normally drawn from text fonts, but  have
     special  font  variants.   Variants may differ in appearance or spacing de‐
     pending on the device and font selected.

     In AT&T _t_r_o_f_f, \\((rrnn (“root en extender”) served as the horizontal extension
     of the radical (square root) sign, \\((ssrr,  and  was  drawn  at  the  maximum
     height of the typeface’s bounding box, enabling it to double as an overline
     (see  subsection  “Rules  and lines” above).  A contemporary font’s radical
     sign might not ascend to such an extreme.  In _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  un‐
     styled counterparts.

     Output   Input          Unicode      Notes
     ───────────────────────────────────────────────────────────────────────────
     ½        \[12]          u00BD        one half symbol +
     ¼        \[14]          u00BC        one quarter symbol +
     ¾        \[34]          u00BE        three quarters symbol +
     ⅛        \[18]          u215B        one eighth symbol
     ⅜        \[38]          u215C        three eighths symbol
     ⅝        \[58]          u215D        five eighths symbol
     ⅞        \[78]          u215E        seven eighths symbol
     ¹        \[S1]          u00B9        superscript one
     ²        \[S2]          u00B2        superscript two
     ³        \[S3]          u00B3        superscript three

     +        +              u002B        plus
     +        \[pl]          u002B        special variant of plus + ***
     -        \[-]           u002D        minus
     −        \[mi]          u2212        special variant of minus + ***
     ∓        \[-+]          u2213        minus‐plus
     ±        \[+-]          u00B1        plus‐minus + ***
     ±        \[t+-]         u00B1        text variant of \\[[++--]]
     ⋅        \[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, obelus + ***
     ÷        \[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 lan‐
     guage  text;  normally,  the  uppercase letters have upright shape, and the
     lowercase ones are slanted.  For the latter, we include in parentheses  un‐
     der  “Unicode”  more appropriate code points from the Mathematical Alphanu‐
     meric Symbols block of the Supplementary Multilingual Plane.

     Output   Input   Unicode          Notes
     ───────────────────────────────────────────────────────────────────────────
     Α        \[*A]   u0391            uppercase alpha +
     Β        \[*B]   u0392            uppercase beta +
     Γ        \[*G]   u0393            uppercase gamma +
     Δ        \[*D]   u0394            uppercase delta +
     Ε        \[*E]   u0395            uppercase epsilon +
     Ζ        \[*Z]   u0396            uppercase zeta +
     Η        \[*Y]   u0397            uppercase eta +
     Θ        \[*H]   u0398            uppercase theta +
     Ι        \[*I]   u0399            uppercase iota +
     Κ        \[*K]   u039A            uppercase kappa +
     Λ        \[*L]   u039B            uppercase lambda +
     Μ        \[*M]   u039C            uppercase mu +
     Ν        \[*N]   u039D            uppercase nu +
     Ξ        \[*C]   u039E            uppercase xi +
     Ο        \[*O]   u039F            uppercase omicron +
     Π        \[*P]   u03A0            uppercase pi +
     Ρ        \[*R]   u03A1            uppercase rho +
     Σ        \[*S]   u03A3            uppercase sigma +
     Τ        \[*T]   u03A4            uppercase tau +
     Υ        \[*U]   u03A5            uppercase upsilon +
     Φ        \[*F]   u03A6            uppercase phi +
     Χ        \[*X]   u03A7            uppercase chi +
     Ψ        \[*Q]   u03A8            uppercase psi +
     Ω        \[*W]   u03A9            uppercase omega +

     α        \[*a]   u03B1 (u1D6FC)   lowercase alpha +
     β        \[*b]   u03B2 (u1D6FD)   lowercase beta +
     γ        \[*g]   u03B3 (u1D6FE)   lowercase gamma +
     δ        \[*d]   u03B4 (u1D6FF)   lowercase delta +
     ε        \[*e]   u03B5 (u1D700)   lowercase epsilon +
     ζ        \[*z]   u03B6 (u1D701)   lowercase zeta +
     η        \[*y]   u03B7 (u1D702)   lowercase eta +
     θ        \[*h]   u03B8 (u1D703)   lowercase theta +
     ι        \[*i]   u03B9 (u1D704)   lowercase iota +
     κ        \[*k]   u03BA (u1D705)   lowercase kappa +
     λ        \[*l]   u03BB (u1D706)   lowercase lambda +
     μ        \[*m]   u03BC (u1D707)   lowercase mu +
     ν        \[*n]   u03BD (u1D708)   lowercase nu +
     ξ        \[*c]   u03BE (u1D709)   lowercase xi +
     ο        \[*o]   u03BF (u1D70A)   lowercase omicron +
     π        \[*p]   u03C0 (u1D70B)   lowercase pi +
     ρ        \[*r]   u03C1 (u1D70C)   lowercase rho +
     σ        \[*s]   u03C3 (u1D70E)   lowercase sigma +
     τ        \[*t]   u03C4 (u1D70F)   lowercase tau +
     υ        \[*u]   u03C5 (u1D710)   lowercase upsilon +
     ϕ        \[*f]   u03D5 (u1D717)   lowercase phi +
     χ        \[*x]   u03C7 (u1D712)   lowercase chi +
     ψ        \[*q]   u03C8 (u1D713)   lowercase psi +
     ω        \[*w]   u03C9 (u1D714)   lowercase omega +

     ϵ        \[+e]   u03F5 (u1D716)   variant epsilon (lunate)
     ϑ        \[+h]   u03D1 (u1D717)   variant theta (cursive form)
     ϖ        \[+p]   u03D6 (u1D717)   variant pi (similar to omega)
     φ        \[+f]   u03C6 (u1D71B)   variant phi (curly shape)
     ς        \[ts]   u03C2 (u1D70D)   terminal lowercase sigma +

   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 idiosyncratic
     fifty years afterward.  (See section “History” of  _r_o_f_f(7)  for  more  con‐
     text.)  The face used by the Teletype Model 37 terminals of the Murray Hill
     Unix  Room  was  based  on ASCII, but assigned multiple meanings to several
     code points, as suggested by that standard.  Decimal 34  ("")  served  as  a
     dieresis  accent  and  neutral  double quotation mark; decimal 39 ('') as an
     acute accent, apostrophe, and closing (right) single quotation mark;  deci‐
     mal 45 (--) as a hyphen and a minus sign; decimal 94 (^^) as a circumflex ac‐
     cent  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 roman,  italic,
     and  bold  styles  available,  several ASCII characters were not present at
     all, nor was most of the Teletype’s extended character set.   AT&T  commis‐
     sioned a “special” font to retain their accustomed repertoire.

     A  representation  of  the coverage of the C/A/T’s text fonts follows.  The
     glyph resembling an underscore is a baseline rule, and  that  resembling  a
     vertical line is a box rule.  In italics, the box rule was not slanted.  We
     also  observe  that  the hyphen and minus sign were already “de‐unified” by
     the fonts provided; a decision whither to map an input “-” therefore had to
     be taken.

              ┌─────────────────────────────────────────────────────┐
              │ A B C D E F G H I J K L M N O P Q R S T U V W X Y Z │
              │ a b c d e f g h i j k l m n o p q r s t u v w x y z │
              │ 0 1 2 3 4 5 6 7 8 9 fi fl ffi ffl                   │
              │ ! $ % & ( ) ‘ ’ * + - . , / : ; = ? [ ] │           │
              │ • □ —— ‐ _ ¼ ½ ¾ ° † ′ ¢ ® ©                        │
              └─────────────────────────────────────────────────────┘

     The special font supplied the missing ASCII and Teletype  extended  glyphs,
     among  several  others.   The plus, minus, and equals signs appeared in the
     special font despite availability in text fonts “to insulate the appearance
     of equations from the choice of standard [read:  text]  fonts”——a  priority
     since  _t_r_o_f_f  was turned to the task of mathematical typesetting as soon as
     it was developed.

     We note that AT&T took the opportunity  to  de‐unify  the  apostrophe/right
     single  quotation mark from the acute accent (a choice ISO later duplicated
     in its 8859 series of standards).  A slash intended to be  mirror‐symmetric
     with  the  backslash  was also included, as was the Bell System logo; we do
     not attempt to depict the latter.

           ┌───────────────────────────────────────────────────────────┐
           │ _α _β _γ _δ _ε _ζ _η _θ _ι _κ _λ _μ _ν _ξ _ο _π _ρ _σ _ς _τ _υ _ϕ _χ _ψ _ω         │
           │ Γ Δ Θ Λ Ξ Π Σ Υ Φ Ψ Ω                                     │
           │ " ´ \ ^ _ ` ~ / < > { } # @ + − = ∗                       │
           │ ≥ ≤ ≡ ≈ ∼ ≠ ↑ ↓ ← → × ÷ ± ∞ ∂ ∇ ¬ ∫ ∝ √ ‾ ∪ ∩ ⊂ ⊃ ⊆ ⊇ ∅ ∈ │
           │ § ‡ ☜ ☞ | ○ ⎧ ⎩ ⎫ ⎭ ⎨ ⎬ ⎪ ⌊ ⌋ ⌈ ⌉                         │
           └───────────────────────────────────────────────────────────┘

     One ASCII character as rendered by the Model 37 was  apparently  abandoned.
     That device printed decimal 124 (|) as a broken vertical line, like Unicode
     U+00A6  (¦).  No equivalent was available on the C/A/T; the box rule \\[[bbrr]],
     brace vertical extension \\[[bbvv]], and “or” operator \\[[oorr]] were used  as  con‐
     textually appropriate.

     Devices  supported  by AT&T device‐independent _t_r_o_f_f exhibited some differ‐
     ences in glyph detail.  For example, on the Autologic  APS‐5  phototypeset‐
     ter, 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_4_._1_/_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 com‐
            posite  special character escape sequence.  See subsection “Accents”
            above.

     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_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 incre‐
            ment sign (U+2206) and upper‐ and lowercase Roman numerals.

AAuutthhoorrss
     This document was written by James Clark, with additions by Werner  Lemberg
     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  Lem‐
     berg,  is the primary _g_r_o_f_f manual.  Section “Using Symbols” may be of par‐
     ticular 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. Si‐
     monsen, J. Akkerhuis; EUUG Newsletter, Volume 9, No. 2, Summer 1989

     The Unicode Standard

     “7‐bit  Character  Sets”  by Tuomas Salste documents the inherent ambiguity
     and configurable code points of the ASCII encoding standard.

     “Nroff/Troff User’s Manual” by Joseph F. Ossanna, 1976, AT&T Bell Laborato‐
     ries Computing Science Technical Report No. 54, features  two  tables  that
     throw  light on the glyph repertoire available to “typesetter _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  origi‐
     nal document: several glyphs are obviously missing.  More subtly, lowercase
     Greek  letters  are  rendered  upright, not slanted as they appeared in the
     C/A/T’s special font and as expected by _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.24.1                       2026‐04‐22                      _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 a reimplementation  and  ex‐
     tension  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.  We also note here differences  arising  from  _g_r_o_f_f’s
     implementation  of  AT&T  _t_r_o_f_f features.  The following discussion assumes
     familiarity with those features; see _r_o_f_f(7) for background.  GNU _t_r_o_f_f can
     operate in a manner that increases support for documents written  for  AT&T
     _t_r_o_f_f; see section “Compatibility mode” below.

LLaanngguuaaggee
     GNU  _t_r_o_f_f features identifiers of arbitrary length; supports color output,
     non‐integral type sizes, user‐defined characters, and automatic hyphenation
     in languages other than English; adds more  conditional  expression  opera‐
     tors; recognizes additional scaling units and arithmetic operators; enables
     general file I/O (in “unsafe mode” only); and exposes more formatter state.

   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 registers, fonts,
     strings/macros/diversions,   environments,  special  characters,  character
     classes, streams, hyphenation language codes, and  colors  can  be  of  any
     length.   Anywhere AT&T _t_r_o_f_f supports a parameterized escape sequence that
     uses an opening parenthesis “(”  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_.  For example, _g_r_o_f_f ships
     with support for families containing each of the styles “RR”, “II”, “BB”,  and
     “BBII” (roman [upright], bold, italic [slanted], and bold‐italic).  So that a
     document  need  not  be coupled to a specific font family, an output device
     can associate a style in the abstract sense with a mounting position.  Thus
     the default family can combine with a style dynamically,  producing  a  _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, font names with the
     ffttrr request.

     Applying the requests ccss, bbdd, ttkkff, uuff, or ffssppeecciiaall to an abstract style af‐
     fects 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 mount‐
     ing positions (if any) are initially associated with abstract 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 lim‐
     ited.  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 interior 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.

   HHyypphheennaattiioonn
     GNU  _t_r_o_f_f uses a hyphenation algorithm and language‐specific pattern files
     (based on TeX’s) to decide which words can be hyphenated and  where.   AT&T
     _t_r_o_f_f’s hyphenation system (“suftab”) was specific to English.

     New requests permit finer control over hyphenation breaking; hyphenation of
     a  word  might be suppressed due to a limit on consecutive hyphenated lines
     (hhllmm), a minimum line length threshold (hhyymm), or because the line  can  in‐
     stead  be adjusted with additional inter‐word space (hhyyss).  The hhllaa request
     selects a hyphenation language, whereas hhppff and hhppffaa respectively load  and
     append  to the language’s hyphenation patterns.  If no hyphenation language
     is set or no patterns are loaded, GNU _t_r_o_f_f does not perform automatic  hy‐
     phenation.

     For  automatic  hyphenation  to work, the formatter must know which letters
     are equivalent.  For example, the letter “E” behaves  like  “e”;  only  the
     latter  typically  appears in hyphenation pattern files.  GNU _t_r_o_f_f expects
     characters that participate in automatic hyphenation to be assigned _h_y_p_h_e_n_‐
     _a_t_i_o_n _c_o_d_e_s that define these equivalence classes.  At startup,  GNU  _t_r_o_f_f
     assigns hyphenation codes to the letters “a”–“z”, applies the same codes to
     “A”–“Z”  in  one‐to‐one  correspondence,  and assigns a code of zero to all
     other characters.

     The hhccooddee request enables application of hyphenation  codes  to  characters
     outside  the  Unicode  basic  Latin set; without doing so, words containing
     such letters won’t hyphenate properly even if the corresponding hyphenation
     patterns contain them.  Localization files for the input character set  and
     language configure hyphenation codes; see _g_r_o_f_f___t_m_a_c(5).

     GNU  _t_r_o_f_f’s \\:: escape sequence works like \\%% but produces no hyphen if the
     word breaks at that location.

   FFrraaccttiioonnaall ttyyppee ssiizzeess aanndd nneeww ssccaalliinngg uunniittss
     When configuring the type size, AT&T _t_r_o_f_f ignored scaling units and inter‐
     preted all measurements in points.  Combined with integer arithmetic,  this
     design  choice made it impossible to support, for instance, ten‐and‐a‐half‐
     point type.  In GNU _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 size in points.

     A  _s_c_a_l_e_d  _p_o_i_n_t_, scaling unit ss, is equal to 1/_s_i_z_e_s_c_a_l_e points, where the
     device description file, _D_E_S_C, specifies _s_i_z_e_s_c_a_l_e and  otherwise  defaults
     to  1;  see _g_r_o_f_f___f_o_n_t(5).  GNU _t_r_o_f_f also defines the _t_y_p_o_g_r_a_p_h_i_c_a_l _p_o_i_n_t_,
     scaling unit zz, which explicitly specifies a type size of potentially  non‐
     integral measure.  The program multiplies typographical points by _s_i_z_e_s_c_a_l_e
     and  converts the value to an integer.  Arguments GNU _t_r_o_f_f interprets in zz
     units by default 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.  In GNU _t_r_o_f_f, the register \\nn[[..ss]] interpo‐
     lates the type size in  typographical  points  (zz),  whereas  the  register
     \\nn[[..ppss]]  interpolates  it in scaled points (ss).  “\\nn[[..ppss]]ss”, “\\nn[[..ss]]zz”, and
     “11mm” are co‐equal by definition.

     For example, if _s_i_z_e_s_c_a_l_e is 1000, then a scaled point is one thousandth 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 typographical 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  disallows  this.
     Similarly, it is nonsensical to use scaling units other than “pp”, “ss”, “zz”,
     or  “uu”,  in a numeric expression whose default scaling unit is “zz”, and so
     GNU _t_r_o_f_f disallows those as well.

     Output devices may be limited in the type sizes they can  employ.   The  ..ss
     and  ..ppss  registers represent the type size selected by the formatter as it
     understands a  device’s  capability.   the  read‐only  registers  ..ppssrr  and
     (string‐valued)  ..ssrr interpolate the last _r_e_q_u_e_s_t_e_d in scaled points and in
     points as a decimal fraction, respectively.  Like the  actual  current  and
     previous type size, the requested ones are properties of an environment.

     For  example,  if  a document requests a type size of 10.95 points, and the
     nearest size permitted by a ssiizzeess request (or by the ssiizzeess or ssiizzeessccaallee di‐
     rectives in the device’s _D_E_S_C file) is 11 points,  _g_r_o_f_f  uses  the  latter
     value.

     A further two new measurement units available in _g_r_o_f_f are “MM”, which indi‐
     cates hundredths of an em, and “ff”, which multiplies by 65,536.  The latter
     provides  convenient  fractions for color definitions with the ddeeffccoolloorr re‐
     quest.  For example, 0.5f equals 32768u.

   SSppeecciiaall ffoonnttss
     GNU _t_r_o_f_f’s “ssppeecciiaall” and ffssppeecciiaall requests permit a document to supplement
     the set of fonts the device configures for glyph search without  having  to
     use  the ffpp request to manipulate the list of mounting positions, which can
     be tedious——by default, GNU _t_r_o_f_f mounts 40 fonts at startup when using the
     ppss device.

   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 expressions _e_1 and _e_2.

     _e_1<<??_e_2  Interpolate the lesser of expressions _e_1 and _e_2.

     ((_c;;_e))   Interpolate  expression  _e using _c as the default scaling unit, ig‐
             noring scaling units in _e if _c is empty.

     Arithmetic in GNU _t_r_o_f_f saturates instead of wrapping.

   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; _c_h_r is an  ordinary,  special,
            or  indexed character, whether defined by a font description file or
            a request.

     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 an argument to the fftt re‐
            quest (that is, the default family  is  combined  with  an  abstract
            style and font translation is applied), 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 an abstract style _s_t_y is registered.  Font translations ap‐
            ply.

     vv      Always false.  This condition exists for compatibility with  certain
            other _t_r_o_f_f implementations.  (We refer to _v_t_r_o_f_f, a translator that
            converted  the  C/A/T  command stream produced by early‐vintage AT&T
            _t_r_o_f_f to a form suitable for Versatec and Benson‐Varian plotters.)

   DDrraawwiinngg ccoommmmaannddss
     GNU _t_r_o_f_f extends the \\DD escape sequence with drawing  commands  to  create
     filled  circles and ellipses, and polygons.  Stroked (outlined) objects are
     drawn with the stroke color and filled (solid) ones shaded  with  the  fill
     color.   These  are  independent  properties; if you want a filled, stroked
     figure, you must draw the same figure twice using each command.   A  filled
     figure  is smaller than a stroked one using the same parameters because the
     former is drawn only within its defined area, whereas strokes have  a  line
     thickness, set with another new drawing command.

   NNoottaattiioonnaall ccoonnvveennttiioonnss
     In  the request and escape sequence descriptions below, GNU _t_r_o_f_f reads ar‐
     guments named _c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e_, _c_o_m_m_a_n_d_, _c_o_n_t_e_n_t_s_, _f_i_l_e_, and  _m_e_s_s_a_g_e  in
     copy  mode until the end of the input line.  A _c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e comprises
     one or more ordinary, special, or indexed characters; spaces; or escape se‐
     quences that interpolate only these.  We name the remaining  arguments  for
     clarity; they are also _c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e_s_.  A neutral double quote ‘""’ can
     optionally  prefix  a  _c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e_;  the  formatter  discards one if
     present, permitting initial embedded spaces in the argument.

     _i_n_p_u_t refers to arbitrary character sequences (up to a  newline  or  delim‐
     iter) that GNU _t_r_o_f_f fully interprets, in contrast to copy mode.

   EEssccaappee sseeqquueenncceess
     _g_r_o_f_f  introduces  several  new escape sequences, extends the syntax of the
     AT&T _t_r_o_f_f escape sequences \\DD, \\ff, \\kk, \\nn, \\ss, \\$$, and \\**, and alters  the
     behavior  of  \\XX.   The following list collates escape sequences alphabeti‐
     cally at first, and then by symbol roughly in  Unicode  code  point  order.
     Neutral  apostrophes  ''  illustrate escape sequences with a user‐selectable
     delimiter.  Many others are available; see subsection  “Miscellaneous”  and
     section “Compatibility Mode” below.

     \\AA''_i_n_p_u_t''
               Interpolate  1  if  _i_n_p_u_t is a valid identifier, and 0 otherwise.
               Because GNU _t_r_o_f_f ignores any input  character  with  an  invalid
               code  when  reading  it, invalid identifiers are empty or contain
               spaces, tabs, newlines,  or  escape  sequences  that  interpolate
               something  other than a sequence of ordinary characters.  You can
               employ \\AA to validate a macro argument before using  it  to  con‐
               struct another escape sequence or identifier.

     \\BB''_i_n_p_u_t''
               Interpolate  1 if _i_n_p_u_t is a valid numeric expression, and 0 oth‐
               erwise.  You might use \\BB along with the “iiff” request  to  filter
               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 of axis lengths _h and _v,  with  its  leftmost
               point at the drawing position.

     \\DD''pp _h_1 _v_1 ... _h_n _v_n''
               Draw polygon with vertices at the 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.  _g_r_o_f_f does not specify how
               the output device must fill concave  or  self‐intersecting  poly‐
               gons.

     \\DD''tt _n''   Set line thickness of geometric objects to _n basic units.  A zero
               _n selects the minimum supported thickness.  A negative _n (the de‐
               fault) selects a thickness proportional to the type size.

     \\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 that will be
               interpolated at varying macro nesting depths.

     \\ff[[_f_n_t]]   Select typeface _f_n_t, which may be a mounting  position,  abstract
               style,  or font name.  \\ff[[]], \\ff[[PP]], and \\ffPP are synonyms; we rec‐
               ommend the first.

     \\FF_f
     \\FF((_f_m
     \\FF[[_f_m_l]]   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]]   Store the horizontal drawing position, relative  to  that  corre‐
               sponding to the start of the input line (ignoring page offset and
               indentation), in two‐character register name _r_g or arbitrary reg‐
               ister name _r_e_g.

     \\mm_c
     \\mm((_c_l
     \\mm[[_c_o_l]]   Set  stroke  color  to  _c_o_l.   \\mm[[]]  restores the previous stroke
               color, or the default if there is none.

     \\MM_c
     \\MM((_c_l
     \\MM[[_c_o_l]]   Set fill color to _c_o_l.  \\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 afore‐
                      mentioned 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 generates
                      these sequences when processing the document, using  _t_r_o_f_f
                      with  the ppss output device, Ghostscript, and the PNM tools
                      to produce images in PNG format.  These sequences 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, centered,
                      and inline alignments within the  document,  respectively.
                      _f_i_l_e  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[[00]]
     \\ss''00''     Restore the previous type size; no operation if there is none.

     \\ss[[_±_n]]
     \\ss_±[[_n]]
     \\ss''_±_n''
     \\ss_±''_n''    Set the type size to, or increment or decrement it  by,  _n  typo‐
               graphical points.

     \\VV_e
     \\VV((_e_v
     \\VV[[_e_n_v]]   Interpolate contents of the system environment variable _e_n_v (one‐
               character   name   _e,  two‐character  name  _e_v_)  as  returned  by
               _g_e_t_e_n_v(3).  \\VV is interpreted even in copy mode.

     \\XX''_c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e''
               Unlike AT&T _t_r_o_f_f, GNU _t_r_o_f_f performs some limited processing  of
               the  sequence  of  ordinary  characters,  special characters, and
               spaces in _c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e.

               The formatter’s special character repertoire is unknown to output
               drivers outside of glyphs named in a  device’s  fonts,  and  even
               then  they  may  not possess complete coverage of the names docu‐
               mented in _g_r_o_f_f___c_h_a_r(7).  Further, escape sequences that  produce
               horizontal  or  vertical motions, hyphenation breaks, or that are
               dummy characters may appear in strings or be converted to  nodes,
               particularly  in  diversions.  When they occur in a device exten‐
               sion command, they produce warnings in  category  “cchhaarr”.   These
               are  not representable when interpolated directly into device‐in‐
               dependent output, as might be done when writing out tag names for
               PDF bookmarks, which can appear in a  viewer’s  navigation  pane.
               This  is  also the case for a small number of special characters,
               such as \\[[rruu]], the baseline rule, that lack a Unicode definition.

               So that any Unicode code point can be represented in  device  ex‐
               tension  commands,  for  example  in an author’s name in document
               metadata or as a usefully named bookmark or hyperlink anchor, GNU
               _t_r_o_f_f transforms its argument to represent characters outside the
               Unicode Basic Latin range as Unicode  code  points  expressed  in
               _g_r_o_f_f’s  notation  for these, “\\[[uu_X_X_X_X]]”; see _g_r_o_f_f___c_h_a_r(7).  For
               these transformations, the formatter ignores  character  transla‐
               tions and definitions.

               GNU  _t_r_o_f_f  converts  several ordinary characters that typeset as
               non‐basic Latin code points to code points outside that range  so
               that  they  are  used  consistently whether they are formatted as
               glyphs or used in a device extension command argument.  These or‐
               dinary characters are “''”, “--”, “^^”, “``”,  and  “~~”;  others  are
               written as‐is.  Thus, “''” transforms to “\\[[uu22001199]]”.

               Contrariwise,  GNU _t_r_o_f_f translates special characters that type‐
               set as Unicode basic Latin characters to basic  Latin  characters
               accordingly.   Thus,  “\\[[ggaa]]”  transforms to “``”, “\\[[DDoo]]” to “$$”,
               and so on.

     \\YY_m
     \\YY((_m_a
     \\YY[[_m_a_c]]   Interpolate a macro or string as a device extension command.   As
               \\XX''\\**[[_m_a_c]]'',  except  that  GNU _t_r_o_f_f does not interpret the con‐
               tents of _m_a_c; further, _m_a_c can be a macro and thus  contain  new‐
               lines,  unlike  the  argument to \\XX ..  This inclusion of newlines
               requires an extension to the AT&T _t_r_o_f_f  device‐independent  page
               description language, and their presence confuses drivers that do
               not  know  about  it (see subsection “Device control commands” of
               _g_r_o_f_f___o_u_t(5)).

     \\ZZ''_i_n_p_u_t''
               Save the drawing position, format _i_n_p_u_t, then  restore  it.   GNU
               _t_r_o_f_f ignores tabs and leaders in _i_n_p_u_t with an error diagnostic.

     \\##        Read everything up to and including the next newline in copy mode
               and  discard it.  \\## 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.  In GNU _t_r_o_f_f, 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  of  the  right parenthesis, which is ugly.  Inserting \\// be‐
               tween them avoids this problem.  Consider  using  \\//  whenever  a
               slanted 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 follow‐
               ing glyph so that the distance between it and the preceding glyph
               is  correct if the latter is of upright shape.  For example, if a
               roman left parenthesis is immediately followed by an italic  “f”,
               then  in  many  fonts the bottom left portion of the “f” overlaps
               the bottom of the left parenthesis, which is ugly.  Inserting  \\,,
               between  them avoids this problem.  Consider using \\,, whenever an
               upright glyph is followed immediately by a slanted 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 “\\%%”).  The remainder of the
               word is subject to hyphenation as normal.

     \\??_c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e\\??
               Suppress formatting of _c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e_.  This feature has  two
               applications.

               Surround  operands  to  the output comparison operator with \\?? to
               compare them by character rather than as formatted output.  Since
               GNU _t_r_o_f_f reads comparands protected with \\?? in copy  mode,  they
               need  not  even  be  valid _g_r_o_f_f syntax.  The escape character is
               still lexically recognized, however, and consumes the next  char‐
               acter.

               When  used in a diversion, \\?? transparently embeds input, read in
               copy mode, until its own next occurrence on the input line.   Use
               \\!!  if  you want to embed newlines in a diversion.  Unlike \\!!, \\??
               is interpreted even in copy mode, and a _c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e in the
               top‐level diversion is not sent to device‐independent output.

     \\[[_c_h_a_r]]   Typeset the special character _c_h_a_r.  See _g_r_o_f_f___c_h_a_r(7).

     \\[[_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  adjustable,  unbreakable  space.   As  with  ordinary
               spaces, GNU _t_r_o_f_f discards any sequence of these at the end of an
               output line if a break occurs.

   RReessttrriicctteedd rreeqquueessttss
     To  mitigate  risks  from untrusted input documents, GNU _t_r_o_f_f disables the
     ccff, ppii, and ssyy requests by default.  Its --UU option enables  “unsafe  mode”,
     restoring their function (and enabling additional _g_r_o_f_f extension requests,
     “ooppeenn”, ooppeennaa, and ppssoo).

   AAlltteerreedd rreeqquueessttss
     ..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.  _s_p_e_c_i_a_l_‐_f_o_n_t
            must be a font name, not a mounting position.

     ..ccff [""]_f_i_l_e
            Break and copy the contents of _f_i_l_e as “throughput” to  GNU  _t_r_o_f_f’s
            output.   If a diversion is in use, GNU _t_r_o_f_f performs the copy only
            when the diversion is emitted.  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 diver‐
            sion is being written to; this behavior is so anomalous that it must
            be considered a bug.

            GNU _t_r_o_f_f removes a leading neutral double quote ‘""’ from the  argu‐
            ment,  permitting initial embedded spaces in it, and reads it to the
            end of the input line in copy mode.  If _f_i_l_e does not  exist  or  is
            not  readable,  a  warning in category “ffiillee” is emitted and the re‐
            quest has no other effect.

     ..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 as ddee11, aamm11,  ddss11,  and
            aass11,  respectively:  GNU _t_r_o_f_f inserts a _c_o_m_p_a_t_i_b_i_l_i_t_y _s_a_v_e token at
            the beginning of the macro, string, or appendment thereto as applic‐
            able and a _c_o_m_p_a_t_i_b_i_l_i_t_y _r_e_s_t_o_r_e token at its end, enabling compati‐
            bility mode during its interpolation.  Thus they  work  as  expected
            even if the interpolation context disables compatibility mode.

     ..hhyy _n  New  values  16 and 32 are available; the former enables hyphenation
            before the last character in a word, and the latter enables  hyphen‐
            ation  after  the  first character in a word.  If invoked without an
            argument, the mode configured by the hhyyddeeffaauulltt request is selected.

     ..llff _i_n_p_u_t_‐_l_i_n_e_‐_n_u_m_b_e_r [[""]_f_i_l_e_‐_i_d_e_n_t_i_f_i_e_r]
            In GNU _t_r_o_f_f the first argument becomes the input line number of the
            _n_e_x_t line the formatter reads.  It also removes  a  leading  neutral
            double  quote  ‘""’ from _f_i_l_e_‐_i_d_e_n_t_i_f_i_e_r_, permitting initial embedded
            spaces in it, and reads it to the end of  the  input  line  in  copy
            mode.

     ..nnxx [[""]_f_i_l_e]
            GNU _t_r_o_f_f removes a leading neutral double quote ‘""’ from _f_i_l_e, per‐
            mitting  initial  embedded  spaces in it, and reads it to the end of
            the input line in copy mode.

     ..ppii [""]_c_o_m_m_a_n_d
            GNU _t_r_o_f_f strips a leading neutral double quote from  the  argument,
            permitting initial embedded spaces in it.

     ..ppmm _n_a_m_e ...
            GNU  _t_r_o_f_f  reports,  to the standard error stream, the JSON‐encoded
            name and contents of each macro, string, or diversion _n_a_m_e.

     ..ssoo [""]_f_i_l_e
            GNU _t_r_o_f_f removes a leading neutral double quote ‘""’ from _f_i_l_e, per‐
            mitting initial embedded spaces in it, and reads it to  the  end  of
            the input line in copy mode.  GNU _t_r_o_f_f searches for _f_i_l_e in any di‐
            rectories specified by --II command‐line options, followed by the cur‐
            rent  working directory.  If _f_i_l_e does not exist or is not readable,
            GNU _t_r_o_f_f emits a warning in category “ffiillee”.

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

     ..ssyy [""]_c_o_m_m_a_n_d
            GNU  _t_r_o_f_f  strips a leading neutral double quote from the argument,
            permitting initial embedded spaces in it.

     ..ttaa [[_n_1 _n_2 ... _n_n ]TT _r_1 _r_2 ... _r_n]
            GNU _t_r_o_f_f supports an extended syntax to specify repeating tab stops
            after the “TT” mark.  These values are always taken as relative  dis‐
            tances  from  the  previous  tab stop.  This is the idiomatic way to
            specify tab stops at equal intervals in _g_r_o_f_f.  GNU _t_r_o_f_f’s  startup
            value is “TT 00..55ii”.

            The  syntax  summary  above instructs _g_r_o_f_f to set tabs at positions
            _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 rreeqquueessttss
     Several GNU _t_r_o_f_f requests work like AT&T _t_r_o_f_f’s “aass” and ddss requests, ac‐
     cepting an optional leading neutral double quote, notated ‘[""]’, in an  ar‐
     gument  that the formatter reads in copy mode to the end of the input line,
     permitting inclusion of leading spaces.

     ..aallnn _n_e_w_‐_r_e_g_i_s_t_e_r _e_x_i_s_t_i_n_g_‐_r_e_g_i_s_t_e_r
             Create alias (additional name) _n_e_w_‐_r_e_g_i_s_t_e_r  of  _e_x_i_s_t_i_n_g_‐_r_e_g_i_s_t_e_r,
             causing the names to refer to the same stored object.  If _e_x_i_s_t_i_n_g_‐
             _r_e_g_i_s_t_e_r  is  undefined,  the  formatter  ignores the request.  GNU
             _t_r_o_f_f produces a warning in category “rreegg”.  See section “Warnings”
             of _t_r_o_f_f(1) regarding the enablement and suppression  of  warnings.
             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_‐_n_a_m_e _e_x_i_s_t_i_n_g_‐_n_a_m_e
             Create alias (additional name) _n_e_w_‐_n_a_m_e of request, string,  macro,
             or  diversion _e_x_i_s_t_i_n_g_‐_n_a_m_e, causing the names to refer to the same
             stored object.  If _e_x_i_s_t_i_n_g_‐_n_a_m_e is undefined,  the  formatter  ig‐
             nores the request.  GNU _t_r_o_f_f produces a warning in category “mmaacc”.
             If  _n_e_w_‐_n_a_m_e  already  exists, its contents are lost unless already
             aliased.  See section “Warnings” of _t_r_o_f_f(1) regarding the  enable‐
             ment and suppression of warnings.  To remove an alias, invoke rrmm on
             its  name.  The object itself is not destroyed until it has no more
             names.

             When a request, macro, string, or diversion is  aliased,  redefini‐
             tions  and  appendments “write through” alias names.  To replace an
             alias with a separately defined object, remove its name first.

     ..aamm11 _n_a_m_e [_e_n_d_‐_n_a_m_e]
             As “aamm”, but GNU _t_r_o_f_f disables compatibility mode while interpret‐
             ing the appendment to _n_a_m_e_: it inserts a _c_o_m_p_a_t_i_b_i_l_i_t_y  _s_a_v_e  token
             at the beginning of the appendment, and a _c_o_m_p_a_t_i_b_i_l_i_t_y _r_e_s_t_o_r_e to‐
             ken  at  its  end.  The requests “aamm”, aamm11, ddee, and ddee11 can thus be
             intermixed freely since the compatibility save/restore  tokens  af‐
             fect 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 GNU _t_r_o_f_f disables compatibility mode while interpret‐
             ing the appendment to the macro named by  the  contents  of  string
             _n_a_m_e_; see aamm11 above.

     ..aass11 _n_a_m_e [[""]_c_o_n_t_e_n_t_s]
             As “aass”, but GNU _t_r_o_f_f disables compatibility mode while interpret‐
             ing  the  appendment to the string _n_a_m_e_: it inserts a _c_o_m_p_a_t_i_b_i_l_i_t_y
             _s_a_v_e token at the beginning of the appendment, and a  _c_o_m_p_a_t_i_b_i_l_i_t_y
             _r_e_s_t_o_r_e  token at its end.  The requests “aass”, aass11, ddss, and ddss11 can
             thus be intermixed freely since the compatibility save/restore  to‐
             kens  affect  only  the portions of the string 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
             (US‐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  interpolated.   Doing so can be useful in conjunction with
             the wwrriitteemm request.

             When transforming a glyph node back into an input sequence that de‐
             mands expression as a special character escape sequence, GNU  _t_r_o_f_f
             uses the default escape character.

             aasscciiiiffyy  cannot  return  all  nodes  in a diversion to their source
             equivalents: those produced by indexed characters (\\NN),  for  exam‐
             ple, remain nodes, so the result cannot be guaranteed to be a char‐
             acter sequence as a macro or string is.  Give the diversion name as
             an  argument  to  the  ppmm  request to inspect its contents and node
             list.  Glyph parameters such as the type face and size are not pre‐
             served; 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 de‐
             fined, _g_r_o_f_f executes _n_a_m_e when a blank line is encountered in  the
             input,  instead  of  the usual behavior.  A line consisting only of
             spaces is also treated as blank and subject to this  trap.   If  no
             argument  is  supplied, the default blank line behavior is (re‐)es‐
             tablished.

     ..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  re‐
             quests,  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 typograph‐
             ical break or the bbrr request.  See “ccoonnttiinnuuee”.

     ..bbrrpp    Break  and  force adjustment of the output line per the current ad‐
             justment mode.  Like bbrr, it does nothing if invoked  with  the  no‐
             break control character.

     ..ccffllaaggss _n _c...
             Assign properties encoded by non‐negative integer _n to each charac‐
             ter or class _c.  Spaces need not separate _c arguments.

             _n  is  the sum of any of the following.  Some combinations are non‐
             sensical, 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 overlapping
                    other  instances of itself horizontally.  Initially, charac‐
                    ters “\\[[uull]]\\[[rrnn]]\\[[rruu]]\\[[rraaddiiccaalleexx]]\\[[ssqqrrtteexx]]” have this  prop‐
                    erty.

             16     Mark the glyph associated with this character as overlapping
                    other  instances of itself vertically.  Initially, the char‐
                    acter “\\[[bbrr]]” has this property.

             32     Mark the character as transparent for the purpose of end‐of‐
                    sentence recognition.  In other  words,  an  end‐of‐sentence
                    character  followed  by  any  number of characters with this
                    property is treated as the end of a sentence if followed  by
                    a  newline or two spaces.  This is the same as having a zero
                    space    factor    in    TeX.      Initially,     characters
                    “''""))]]**\\[[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.  Initially,
                    no characters have this property.

             The remaining values were implemented for East Asian language  sup‐
             port;  those  who  use alphabetic scripts exclusively can disregard
             them.

             128    Prohibit a break before the character, but allow a break af‐
                    ter the character.  This works only in combination with val‐
                    ues 256 and 512 and has no effect otherwise.  Initially,  no
                    characters have this property.

             256    Prohibit  a break after the character, but allow a break be‐
                    fore the character.  This works  only  in  combination  with
                    values  128 and 512 and has no effect otherwise.  Initially,
                    no characters have this property.

             512    Allow a break before or after  the  character.   This  works
                    only  in  combination with values 128 and 256 and has no ef‐
                    fect otherwise.  Initially, no characters  have  this  prop‐
                    erty.

             In  contrast  to  values 2 and 4, the values 128, 256, and 512 work
             pairwise.  If, for example, the left character has value  512,  and
             the  right  character  128, no break will be automatically inserted
             between them.  If we use value 6 instead for the left character,  a
             break after the character can’t be suppressed since the neighboring
             character on the right doesn’t get examined.

     ..cchhaarr _c [[""]_c_o_n_t_e_n_t_s]
             Define  an  ordinary,  special, or indexed character _c as _c_o_n_t_e_n_t_s_.
             Omitting _c_o_n_t_e_n_t_s gives _c an empty definition.

             Defining (or redefining) a character _c creates a  formatter  object
             that  GNU _t_r_o_f_f recognizes like any other ordinary, special, or in‐
             dexed character on input, and produces _c_o_n_t_e_n_t_s  on  output.   When
             formatting  _c, GNU _t_r_o_f_f processes _c_o_n_t_e_n_t_s in a temporary environ‐
             ment and encapsulates the result in a node (see section “GNU  troff
             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); disabling compatibility mode and setting  the  es‐
             cape  character to to \\ while interpreting _c_o_n_t_e_n_t_s_.  Any embolden‐
             ing, constant spacing, or track  kerning  applies  to  this  object
             rather  than  to individual glyphs resulting from the formatting of
             _c_o_n_t_e_n_t_s_.

             A character defined by cchhaarr 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; sequences 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 automatic hyphenation.

             However, a user‐defined character _c does  not  participate  at  its
             boundaries in kerning adjustments or italic corrections.

             The formatter prevents infinite recursion by treating an occurrence
             of  a character in its own definition as if it were undefined; when
             interpolating such a character, GNU _t_r_o_f_f emits a warning in  cate‐
             gory “cchhaarr”.  (Mutually recursive character definitions are handled
             similarly.)

             The ttrr and ttrriinn requests take precedence if cchhaarr also applies to _c.
             The rrcchhaarr request removes character definitions.

     ..cchhoopp _n_a_m_e
             Remove  the  last  character  from  the macro, string, or diversion
             _n_a_m_e.  This is useful for removing the newline from the  end  of  a
             diversion that is to be interpolated as a string.  This request can
             be  used repeatedly on the same _n_a_m_e; see section “GNU troff Inter‐
             nals” 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 _i_d_e_n_t _c ...
             Define  a  character class (or simply “class”) _i_d_e_n_t comprising the
             members _c..., where each _c is  an  ordinary,  special,  or  indexed
             character; or a _r_a_n_g_e _e_x_p_r_e_s_s_i_o_n_.  A class thus defined can then be
             referred  to in a ccffllaaggss request in lieu of listing all the charac‐
             ters within it.

             Since class and special character names share the same name  space,
             we  recommend  starting and ending the class name with “[[” and “]]”,
             respectively, to avoid collisions with existing  special  character
             names  defined  by GNU _t_r_o_f_f or the user (with cchhaarr and related re‐
             quests).  This practice applies the presence of “]]”  in  the  class
             name  to  prevent  the  usage  of the special character escape form
             “\\[[...]]”, you must therefore access a class thus named via  the  \\CC
             escape sequence.

             An argument _c can alternatively be a _r_a_n_g_e _e_x_p_r_e_s_s_i_o_n 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  Unicode
             code points (according to the _g_r_o_f_f glyph list [GGL]), which deter‐
             mine  the  start  and  end values of the range.  If that conversion
             fails, GNU _t_r_o_f_f skips the range expression and any remaining argu‐
             ments.

     ..cclloossee _s_t_r_e_a_m
             Close the named _s_t_r_e_a_m, invalidating  it  as  an  argument  to  the
             “wwrriittee” request.  See “ooppeenn”.

     ..ccoommppoossiittee _c_1 _c_2
             Map  ordinary  or special character _c_1 to _c_2 when _c_1 is a combining
             component in a composite character.  Typically, ccoommppoossiittee  is  used
             to map a spacing character to a combining one.  See _g_r_o_f_f___c_h_a_r(7).

     ..ccoonnttiinnuuee
             Skip  the remainder of a “wwhhiillee” loop’s body, immediately retesting
             its conditional expression.  See “bbrreeaakk” above.

     ..ccoolloorr [_b]
             Enable or disable output of color‐related device‐independent output
             commands per Boolean expression _b.  It is enabled by  default,  and
             if _b is omitted.

     ..ccpp [_b]
             Enable or disable AT&T _t_r_o_f_f compatibility mode per Boolean expres‐
             sion  _b.   It  is disabled by default, and enabled if _b is omitted.
             In compatibility mode, long names are not recognized, and  the  in‐
             compatibilities 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”.  Each color component can be encoded as a  hexa‐
             decimal  value  starting  with  ## or ####.  The former indicates that
             each component is in the range 0–255 (0–FF), the latter  the  range
             0–65535 (0–FFFF).  Alternatively, a component can be specified as a
             decimal  fraction  in  the  range  0–1, interpreted using a default
             scaling unit of “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 re‐
             defined.   A device’s default stroke and fill colors are not neces‐
             sarily the same.

     ..ddee11 _i_d_e_n_t [_e_n_d_‐_n_a_m_e]
             As “ddee”, but GNU _t_r_o_f_f disables compatibility mode while interpret‐
             ing _n_a_m_e_: it inserts a _c_o_m_p_a_t_i_b_i_l_i_t_y _s_a_v_e token at the beginning of
             the macro definition, and a _c_o_m_p_a_t_i_b_i_l_i_t_y _r_e_s_t_o_r_e token at its end.
             See ..aamm11 above.

     ..ddeeii _n_a_m_e [_e_n_d_‐_n_a_m_e]
             Define macro indirectly, with the name of the macro to  be  defined
             in string _n_a_m_e and the name of the end macro terminating its defin‐
             ition in string _e_n_d_‐_n_a_m_e.

     ..ddeeii11 _n_a_m_e [_e_n_d_‐_n_a_m_e]
             As  ddeeii, but GNU _t_r_o_f_f disables compatibility mode while interpret‐
             ing the macro named by the contents of string _n_a_m_e_.   See  aamm11  and
             ddee11 above.

     ..ddeevviiccee [[""]_c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e]
             Embed  _c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e into GNU _t_r_o_f_f output as parameters to an
             “xXX”” device extension command; see _g_r_o_f_f___o_u_t(5).  The output driver
             or other postprocessor interprets  _c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e  as  it  sees
             fit.

     ..ddeevviicceemm _n_a_m_e
             Write contents of macro or string _n_a_m_e to _t_r_o_f_f output as the argu‐
             ment to a device extension command.

     ..ddoo _n_a_m_e [_a_r_g_u_m_e_n_t ...]
             Interpret the string, request, diversion, or macro _n_a_m_e (along with
             any  further arguments) with compatibility mode disabled.  Compati‐
             bility mode is restored (only if it was active) when the interpola‐
             tion of _n_a_m_e is interpreted; that is,  the  restored  compatibility
             state  applies  to the request or contents of the macro, string, or
             diversion _n_a_m_e, its arguments, and data read from files or pipes if
             _n_a_m_e is the “ssoo”, ssooqquuiieett, mmssoo, mmssooqquuiieett, or ppssoo request.

     ..ddss11 _n_a_m_e [[""]_c_o_n_t_e_n_t_s]
             As ddss, but GNU _t_r_o_f_f disables AT&T compatibility mode while  inter‐
             preting _n_a_m_e: it inserts a “compatibility save” token 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 charac‐
             ter 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  environment,
             except for:

             •  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‐align,  or  to
                underline  (with or without underlined spaces)——these are set to
                zero;

             •  the activation status of temporary indentation;

             •  input traps and their associated data;

             •  the activation status of line numbering (which  can  be  reacti‐
                vated with “..nnmm ++00”); and

             •  the count of consecutive hyphenated lines (set to zero).

             Copying an environment to itself discards the foregoing data.

     ..ffaamm [_f_m_l]
             Set  default  font  family  to _f_m_l.  With no argument, the previous
             font family is selected, and if none, the formatter’s default  fam‐
             ily.   This  default  is  “T” (Times), but can be overridden by the
             output device——see _g_r_o_f_f___f_o_n_t(5).  The default font family is asso‐
             ciated 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.  As cchhaarr, but  while  that
             request  hides  a  glyph  with  the same name in the selected font,
             ffcchhaarr definitions are used only if the font lacks a  glyph  for  _c.
             GNU _t_r_o_f_f performs this test before searching special fonts.

     ..ffccoolloorr [_c_o_l]
             Select  _c_o_l  as  the environment’s fill color, or, without an argu‐
             ment, restore the previous fill color, or the default if  there  is
             none.

     ..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.  As
             cchhaarr, but GNU _t_r_o_f_f locates a character defined by ffsscchhaarr after any
             fonts named as arguments to the ffssppeecciiaall are  searched  and  before
             those named as arguments to the “ssppeecciiaall” request.

     ..ffssppeecciiaall _f [_s ...]
             Declare  each font _s as special only when font ff is selected.  Ini‐
             tially, a font _f’s list of associated special fonts  is  empty  for
             all  _f_.   GNU  _t_r_o_f_f  searches  fonts specified as arguments to the
             “ssppeecciiaall” request after those given as arguments  to  the  ffssppeecciiaall
             request.  See “ssppeecciiaall”.

     ..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 opera‐
             tors, 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 be a non‐negative inte‐
             ger; it scales the magnification by thousandths with 1000 as a  ba‐
             sis.   If  _z_o_o_m  is missing or equal to zero or 1000, font _f is not
             magnified.  _f must be a resolved font name, not an  abstract  style
             or mounting position.

     ..ggccoolloorr [_c_o_l]
             Select  _c_o_l as the environment’s stroke color, or, without an argu‐
             ment, restore the previous stroke color, or the default if there is
             none.

     ..hhccooddee _d_s_t_1 _s_r_c_1 [_d_s_t_2 _s_r_c_2] ...
             Set the hyphenation code of character _d_s_t_1 to that of _s_r_c_1, and  so
             on.  _d_s_t_1 must be an ordinary character (other than a numeral) or a
             special  character,  and  _s_r_c_1 must be an ordinary character (other
             than a numeral) or a special character to which a hyphenation  code
             has  already been applied.  Assigning the code of an ordinary char‐
             acter to itself  effectively  creates  a  unique  hyphenation  code
             (which can then be copied to others).  hhccooddee ignores spaces between
             arguments.   If any argument is invalid, hhccooddee reports an error and
             stops reading them.

     ..hhllaa [_l_a_n_g]
             Set the hyphenation language to _l_a_n_g, or clear it if  there  is  no
             argument.  Hyphenation exceptions specified with the hhww request and
             hyphenation patterns and exceptions specified with the hhppff and hhppffaa
             requests are associated with the hyphenation language.  The hhllaa re‐
             quest  is  usually invoked 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  be‐
             low.

     ..hhllmm [_n]
             Set  the  consecutive  automatically hyphenated line limit to _n_.  A
             negative value means “no limit”.  Omitting _n implies a limit of --11.
             This value is associated with the environment.  Only  lines  output
             from  a  given environment count toward the maximum associated with
             that environment.  Hyphens resulting from \\%% 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.

             The _p_a_t_t_e_r_n_‐_f_i_l_e should have the same format as (simple)  TeX  pat‐
             tern files.  The following scanning rules are implemented.

             •  A percent sign starts a comment (up to the end of the line) even
                if preceded by a backslash.

             •  “Digraphs” like \\$$ 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  excep‐
                tions.

             •  \\eennddiinnppuutt is recognized also.

             •  For  backward  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 comment).

             Use  the  hhccooddee request (see above) to map the encoding used in hy‐
             phenation pattern files to _g_r_o_f_f’s input encoding.

             GNU _t_r_o_f_f ties the set of hyphenation patterns to  the  hyphenation
             language code selected 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.
             _g_r_o_f_f provides localization files for several languages;  See  sub‐
             section “Localization packages” of _g_r_o_f_f___t_m_a_c(5).  For Western lan‐
             guages, the localization file sets the default hyphenation mode and
             loads  hyphenation  patterns  and  exceptions.  By default, _t_r_o_f_f_r_c
             loads the localization file for English.

             A second call to hhppff (for the same language) replaces the old  pat‐
             terns with the new ones.

             Invoking hhppff causes an error if there is no hyphenation language.

             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 automat‐
             ically 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] ...
             _C_a_u_t_i_o_n_: This request will be withdrawn in a future _g_r_o_f_f  release.
             Use hhccooddee instead.

             Define mapping values for character codes in pattern files.  hhppff or
             hhppffaa  apply  the  mapping  after reading or appending to the active
             list of patterns.  Its arguments are pairs of character  codes——in‐
             tegers from 0 to 255.  The request maps character code _a to code _b,
             code  _c to code _d, and so on.  Character codes that would otherwise
             be invalid in GNU _t_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”.

     ..hhyyddeeffaauulltt _m_o_d_e
             Set hyphenation mode default to _m_o_d_e_.  When the hhyy request  is  in‐
             voked  without an argument, this mode is selected.  The hyphenation
             mode default is associated with the environment.   The  formatter’s
             default is 11 for AT&T _t_r_o_f_f compatibility.  _g_r_o_f_f locale files gen‐
             erally set a more appropriate one; see _g_r_o_f_f___t_m_a_c(5).

     ..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  hyphenation  margin
             is reset to its default value, 0.  The default scaling unit is “mm”.
             The hyphenation margin is associated with the environment.  A nega‐
             tive  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
             that adjustment can be achieved 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 environment.  A nega‐
             tive argument resets the hyphenation space adjustment threshold  to
             zero, emitting a warning in category “rraannggee”.

     ..iittcc n [_m_a_c]
             As  “iitt”,  but lines interrupted with the \\cc escape sequence do not
             apply to the line count.

     ..kkeerrnn [_b]
             Enable or disable pairwise kerning of glyphs in the environment per
             Boolean expression _b.  It is enabled by default, and if _b is  omit‐
             ted.

     ..lleennggtthh _r_e_g [[""]_c_o_n_t_e_n_t_s]
             Compute the number of characters in _c_o_n_t_e_n_t_s and store the count in
             the register _r_e_g.  If _r_e_g doesn’t exist, GNU _t_r_o_f_f creates it.

             _C_a_u_t_i_o_n_:  If  you interpolate a macro or diversion in _c_o_n_t_e_n_t_s (see
             section “Punning Names” in _g_r_o_f_f(7)),  the  lleennggtthh  request  counts
             characters  (or nodes) only up to the first newline, and leaves the
             rest on the input  stream.   In  conventional  circumstances,  that
             means  the remainder is interpreted, and may be formatted.  To dis‐
             cover the length of any string, macro, or diversion, use the ppmm re‐
             quest.  See section “Debugging” below.

     ..lliinneettaabbss [_b]
             Activate or deactivate line‐tabs in the environment per Boolean ex‐
             pression _b.  They are inactive by default, and activated  if  _b  is
             omitted.   When  line‐tabs are active, tab stops are computed rela‐
             tive to the start of the pending output line instead of the drawing
             position corresponding to the start of the input line.

     ..llssmm [_n_a_m_e]
             Set a leading space trap, calling the macro _n_a_m_e when GNU _t_r_o_f_f en‐
             counters leading spaces on a text line;  the  implicit  line  break
             that  normally  happens  in this case is suppressed.  The formatter
             stores the count of leading spaces on the  text  line  in  register
             llssnn,  and the amount of corresponding horizontal motion in register
             llssss, irrespective of whether a leading space trap is set.  When  it
             is,  GNU  _t_r_o_f_f  removes the leading spaces from the input line and
             produces no motion before calling _n_a_m_e.

             If no argument is supplied, GNU  _t_r_o_f_f  reëstablishes  the  default
             handling  of  leading  spaces on text lines (breaking the line when
             filling,  and  formatting  a  horizontal  motion  of  \\nn[[llssnn]]  word
             spaces).

     ..mmssoo [""]_f_i_l_e
             As  “ssoo”,  except that GNU _t_r_o_f_f searches for the specified _f_i_l_e in
             the same directories as macro files; see _G_R_O_F_F___T_M_A_C___P_A_T_H in section
             “Environment” of _g_r_o_f_f(1) and --mm in section “Options” of  the  same
             page.  If _f_i_l_e does not exist or is not readable, a warning in cat‐
             egory “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 [_i_n_p_u_t]
             Interpret  _i_n_p_u_t  as  if it were an input line.  nnoopp resembles “..iiff
             11”; it puts a break on the output if _i_n_p_u_t is empty.  Unlike  “iiff”,
             it  cannot  govern conditional blocks.  Its application is to main‐
             tain consistent indentation within macro definitions even when for‐
             matting output.

     ..nnrrooffff  Make the nn conditional expression evaluate true and tt  false.   See
             ttrrooffff.

     ..ooppeenn _i_d_e_n_t [""]_f_i_l_e
             Open  _f_i_l_e  for writing and associate a stream named _i_d_e_n_t with it,
             making it available for “wwrriittee” requests.  Unsafe request; disabled
             by default.  Also see wwrriitteecc and “cclloossee”.

     ..ooppeennaa _i_d_e_n_t [""]_f_i_l_e
             As “ooppeenn”, but appends to _f_i_l_e if  it  already  exists  instead  of
             overwriting it.

     ..oouuttppuutt [""]_c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e
             Emit  _c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e,  transparently  to GNU _t_r_o_f_f output; this
             usage is similar to that of \\!! when it occurs in the top‐level  di‐
             version.

     ..ppcchhaarr _c ...
             Report,  to the standard error stream, information about each char‐
             acter (be it ordinary, special, or indexed) or character  class  _c.
             A  character  defined  by a request (cchhaarr, ffcchhaarr, ffsscchhaarr, or sscchhaarr)
             reports its contents as a JSON‐encoded string, but  the  output  is
             not otherwise in JSON format.

     ..ppccoolloorr [_c_o_l ...]
             Report, to the standard error stream, each defined color named _c_o_l,
             its  color  space  identifier,  and  channel value assignments, or,
             without arguments, those of all defined colors.  A device’s default
             stroke and/or fill colors, “default”, are not listed since they are
             immutable and their details unknown to the formatter.

     ..ppccoommppoossiittee
             Report, to the standard error stream, the list of  configured  com‐
             posite character mappings.  See “ccoommppoossiittee” above.  The “from” code
             point is listed first, followed by its “to” mapping.

     ..ppeevv    Report the state of the current environment followed by that of all
             other environments to the standard error stream.

     ..ppffpp    Report,  to  the  standard  error stream, the list of occupied font
             mounting positions.  Occupied mounting positions  are  listed,  one
             per  line,  in  increasing order, followed by the typeface name; if
             the name corresponds to an abstract style, the  entry  ends  there.
             Otherwise,  the  name  of  the font description file and the font’s
             “internal name” datum, the meaning of which varies  by  output  de‐
             vice, follow.

     ..ppffttrr   Report,  to  the  standard  error stream, the list of font transla‐
             tions.  See ppffttrr above.   The  “from”  font  identifier  is  listed
             first, followed by its “to” translation.

     ..pphhww    Report,  to  the standard error stream, the list of hyphenation ex‐
             ception words associated with the hyphenation language selected  by
             the  hhllaa request.  A “--” marks each hyphenation point.  A word pre‐
             fixed with “--” is not hyphenated at all.  The report suffixes words
             to which automatic hyphenation applies (meaning those defined in  a
             hyphenation  pattern  file  rather than with the hhww request) with a
             tab and asterisk “**”.

     ..pplliinnee  Report, in JSON syntax to the standard error stream,  the  list  of
             output  nodes corresponding to the pending output line.  In JSON, a
             pair of empty brackets “[[ ]]” represents an empty list.   A  _p_e_n_d_i_n_g
             output line has not yet undergone adjustment, and lacks a line num‐
             ber and margin character (all as applicable).

     ..ppnnrr [_r_e_g ...]
             Report  the name and value and, if its type is numeric, the autoin‐
             crement amount and assigned format of each register _r_e_g, or,  with‐
             out  arguments, those of all defined registers, to the standard er‐
             ror 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 PostScript
             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, which is passed to _p_o_p_e_n(3).

     ..ppssttrreeaamm
             Report,  in  JSON  syntax to the standard error stream, the list of
             open streams, including the name of each open stream, the  name  of
             the file backing it, and its mode (writing or appending).

     ..ppwwhh    Report  the  names  and  vertical positions, in basic units, of all
             page location traps to the standard error stream.   GNU  _t_r_o_f_f  re‐
             ports  empty  slots  in the list, where a trap had been planted but
             subsequently (re)moved, because they can affect the  visibility  of
             subsequently planted traps.

     ..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  argu‐
             ment on the pending output line, the vertical spacing (vvss), the ex‐
             tra 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, special, or  indexed  character
             _c,  undoing  the effect of a cchhaarr, ffcchhaarr, or sscchhaarr request.  Spaces
             need not separate _c arguments.  The  character  definition  removed
             (if  any)  is the first encountered in the resolution process docu‐
             mented in section “Using Symbols” of _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.   Glyphs,  which  are defined by font description files,
             cannot be removed.

     ..rreettuurrnn [_i_n_p_u_t]
             Stop interpreting an interpolated macro, skipping to the end of its
             definition.  Do not confuse “rreettuurrnn” with rrtt.  If  called  with  an
             argument  _i_n_p_u_t_, GNU _t_r_o_f_f performs the skip twice——once within the
             macro being interpreted and once in an enclosing macro,  permitting
             a macro to wrap the request (as _t_r_a_c_e_._t_m_a_c does).

     ..rrffsscchhaarr _f _c ...
             Remove  each  fallback special character _c for font _f.  Spaces need
             not separate _c arguments.  See ffsscchhaarr.

     ..rrjj [_n]
             Break, right‐align the next _n (default: 1) input lines, then  break
             again.   rrjj  implies “..ccee 00”, and ccee implies “..rrjj 00”.  Invoking the
             request with the no‐break control character  suppresses  the  first
             break.

     ..rrnnnn _r_1 _r_2
             Rename  register _r_1 to _r_2.  If _r_1 doesn’t exist, the request is ig‐
             nored.

     ..sscchhaarr _c [[""]_c_o_n_t_e_n_t_s]
             Define global fallback character _c as _c_o_n_t_e_n_t_s.  As cchhaarr,  but  GNU
             _t_r_o_f_f  locates a character defined with sscchhaarr after any fonts named
             as arguments to the “ssppeecciiaall” request and before any  mounted  spe‐
             cial fonts.

     ..sshhcc [_c]
             Set  the  soft hyphen character, inserted when a word is hyphenated
             automatically or at a hyphenation character, to _c.  If _c  is  omit‐
             ted,  the  soft  hyphen character is set to the default, \\[[hhyy]].  If
             the selected glyph does not exist in the font in use at a potential
             hyphenation point, then the line is not broken at that point.  Nei‐
             ther character definitions (cchhaarr and similar) nor translations  (ttrr
             and  similar) are considered when assigning the soft hyphen charac‐
             ter.

     ..sshhiifftt [_n]
             Shift macro or string parameters _n places (by 1 if _n omitted):  ar‐
             gument _i becomes argument _i-_n; arguments 1 to _n become unavailable.
             Shifting  by a non‐positive amount, or outside of a macro or string
             definition, performs no operation.  The  register  ..$$  adjusts  its
             value accordingly.

     ..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  argument  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 [_s ...]
             Declare  each  font  _s  as special, irrespective of its description
             file, populating a list that GNU _t_r_o_f_f searches, in order, to  find
             the  glyph  demanded.   GNU  _t_r_o_f_f  mounts  each  font _s_.  Invoking
             ssppeecciiaall without arguments empties the list.  A font is not automat‐
             ically unmounted if a subsequent ssppeecciiaall request  removes  it  from
             the  list.  Initially, the list is empty.  GNU _t_r_o_f_f searches fonts
             specified as arguments to the “ssppeecciiaall” request after  those  given
             as arguments to the ffssppeecciiaall request.

     ..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” warns if _t_r_o_f_f must add 0.2 m or
             more to 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).  Spe‐
             cial characters (see _g_r_o_f_f___c_h_a_r(7)) will often transform in the ex‐
             pected way due to the regular naming convention for accented  char‐
             acters.  When they do not, use substrings and/or catenation.

     ..ssttyy _p_o_s _s_t_y_l_e
             Associate  abstract  _s_t_y_l_e  with  non‐negative  font mounting posi‐
             tion _p_o_s.

     ..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  in‐
             dices  _s_t_a_r_t  and  _e_n_d,  inclusively.   The  first character in the
             string has index 0.  Negative indices count backward from  the  end
             of  the  string: the last character has index -1, the character be‐
             fore the last has index -2, and so on.  If _e_n_d is  omitted,  --11  is
             implied.

     ..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, but removes a leading neutral double quote ‘""’ from _m_e_s_s_a_g_e,
             permitting initial embedded spaces in it.

     ..ttmmcc [[""]_m_e_s_s_a_g_e]
             As ttmm11, but does not append a newline.

     ..ttrrff _f_i_l_e
             Break and copy _f_i_l_e as “throughput” to GNU _t_r_o_f_f output, discarding
             characters  that are invalid as input; contrast with ccff.  Each line
             of _f_i_l_e is output as if preceded by \\!!, but is not  interpreted  by
             the  formatter.   If  _f_i_l_e does not end with a newline, ttrrff appends
             one.  Invoking the request with the no‐break control character sup‐
             presses the break.

     ..ttrriinn _a_b_c_d
             As the ttrr request, but the aasscciiiiffyy request uses the character  code
             (if any) before the character translation.

     ..ttrrnntt _a_b_c_d
             As  the  ttrr request, but the translations do not apply to text that
             is transparently throughput into a diversion with \\!!.

     ..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 [_b]
             Enable or disable vertical position traps per Boolean expression _b.
             They are enabled by default, and if _b is omitted.   Vertical  posi‐
             tion  traps are those set by the cchh, wwhh, and ddtt requests.  Vertical
             position trap enablement is global.

     ..wwaarrnn [_n]
             Select categories of warnings to be reported.  _n is the sum of  the
             numeric  codes  associated with each warning category that is to be
             enabled; all other categories are  disabled.   The  categories  and
             their   associated  codes  are  listed  in  section  “Warnings”  of
             _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_c_a_l_i_n_g_‐_u_n_i_t
             Select scaling unit used in certain warnings (one of uu, ii, cc, pp, or
             PP;  default:  ii).   Ignored on _n_r_o_f_f‐mode output devices, for which
             these diagnostics report the vertical page location in  lines,  and
             the horizontal page location in ens.

     ..wwhhiillee _c_o_n_d_‐_e_x_p_r _i_n_p_u_t
             Evaluate  the conditional expression _c_o_n_d_‐_e_x_p_r, and repeatedly exe‐
             cute _i_n_p_u_t unless and  until  _c_o_n_d_‐_e_x_p_r  evaluates  false.   _i_n_p_u_t_,
             which  is  often a conditional block, is referred to as the “wwhhiillee”
             request’s _b_o_d_y_.

             GNU _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 signifi‐
             cantly if its body is large.  Each time GNU _t_r_o_f_f interpolates  the
             macro,  it parses and stores the “wwhhiillee” body 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,
             which is parsed only once (unless you redefine it).  To prevent in‐
             finite loops, GNU _t_r_o_f_f limits the default number of available  re‐
             cursion levels to 1,000 or somewhat less (because things other than
             macro  calls can be on the input stack).  You can disable this pro‐
             tective measure, or alter the limit, by setting the  sslliimmiitt  regis‐
             ter.  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 [[""]_c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e]
             Write   _c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e,  a  sequence  of  ordinary  characters,
             spaces, or tabs read in copy mode, to _s_t_r_e_a_m, which must previously
             have been the subject of an “ooppeenn” (or ooppeennaa) request, followed  by
             a newline.  GNU _t_r_o_f_f flushes the stream after writing to it.

     ..wwrriitteecc _s_t_r_e_a_m [[""]_c_h_a_r_a_c_t_e_r_‐_s_e_q_u_e_n_c_e]
             As “wwrriittee”, but does not append a newline to _c_o_n_t_e_n_t_s.

     ..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” (or  ooppeennaa)  re‐
             quest.  GNU _t_r_o_f_f reads the contents of _n_a_m_e in copy mode.

   AAlltteerreedd rreeggiisstteerrss
     GNU  _t_r_o_f_f alters the semantics of two AT&T _t_r_o_f_f registers and imparts se‐
     mantics to two others that CSTR #54 documented as “reserved”.

     \\nn[[..RR]]
            Because GNU _t_r_o_f_f dynamically manages register  storage,  it  repur‐
            poses  the  ..RR  register  to  interpolate the maximum integer repre‐
            sentable in the formatter.  Favor its use over numeric literals with
            many zeroes or nines to indicate an arbitrary large quantity.

     \\nn[[..ss]]
            In GNU _t_r_o_f_f, the ..ss register is string‐valued; it interpolates  the
            type  size  in  typographical  points, which can be represented as a
            decimal fraction.

     \\nn[[..xx]]
            Interpolate major version number of  the  running  _t_r_o_f_f  formatter.
            For  example,  if  the  version  number  is 1.23.0, then \\nn[[..xx]] con‐
            tains 1.

     \\nn[[..yy]]
            Interpolate minor version number of  the  running  _t_r_o_f_f  formatter.
            For  example,  if  the  version  number  is 1.23.0, then \\nn[[..yy]] con‐
            tains 23.  Also see \\nn[[..YY]] below.

   NNeeww rreeggiisstteerrss
     GNU _t_r_o_f_f exposes more formatter state via many  new  read‐only  registers.
     Their names often correspond to the requests that affect them.

     \\nn[[..bbrr]]       Within  a  macro  definition,  interpolate  1 if the macro is
                   called with the “normal” control character (“.” by  default),
                   and  0  otherwise.  This facility allows requests to be reli‐
                   ably wrapped by a macro.  Interpolating the ..bbrr register out‐
                   side of a macro definition makes no sense.

     \\nn[[..CC]]        Interpolate 1 if AT&T _t_r_o_f_f compatibility mode is in  effect,
                   0 otherwise.  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  count of input lines remaining to be centered in
                   the environment.

     \\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 color output is enabled, 0 otherwise.

     \\nn[[..ccpp]]       Within a “ddoo” request, interpolate the saved value of compat‐
                   ibility 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  is  to  be
                   placed.

     \\nn[[..eevv]]       Interpolate  name  of current environment.  This is a string‐
                   valued register.

     \\nn[[..ffaamm]]      Interpolate name of the environment’s  default  font  family.
                   This is a string‐valued register.

     \\nn[[..ffnn]]       Interpolate  resolved  name of the font selected in the envi‐
                   ronment.  This is a string‐valued register.

     \\nn[[..ffpp]]       Interpolate next free non‐zero 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 the rescaled height of the environment’s selected
                   font, in scaled points.  It is zero if the font height is not
                   rescaled.  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 automatic hyphenation mode of the environment.

     \\nn[[..hhyyddeeffaauulltt]]
                   Interpolate hyphenation mode default of the environment.

     \\nn[[..hhyymm]]      Inteprolate hyphenation margin of the environment.

     \\nn[[..hhyyss]]      Interpolate hyphenation space adjustment threshold of the en‐
                   vironment.

     \\nn[[..iinn]]       Interpolate  indentation amount applicable to the output line
                   pending in the environment.

     \\nn[[..iinntt]]      Interpolate 1 if the text most recently formatted in the  en‐
                   vironment  was  “interrupted”  or continued with \\cc, 0 other‐
                   wise.

     \\nn[[..iitt]]       Interpolate count of input lines remaining  in  the  environ‐
                   ment’s pending input trap.

     \\nn[[..iittcc]]      Interpolate  1 if the environment’s pending input trap honors
                   the output line continuation escape sequence (\\cc),  0  other‐
                   wise.

     \\nn[[..iittmm]]      Interpolate  the  name of the macro associated with the envi‐
                   ronment’s pending input trap.  This is a string‐valued regis‐
                   ter.

     \\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  in  the  environ‐
                   ment, 0 otherwise.

     \\nn[[..llll]]       Interpolate line length applicable to the environment’s pend‐
                   ing output line.

     \\nn[[..lltt]]       Interpolate the environment’s title line length.

     \\nn[[..mm]]        Interpolate  name of the environment’s selected stroke color.
                   This is a string‐valued register.

     \\nn[[..MM]]        Interpolate name of the environment’s  selected  fill  color.
                   This is a string‐valued register.

     \\nn[[..nnee]]       Interpolate  amount  of  space demanded by the most recent nnee
                   request that sprang a page location trap.  See \\nn[[..ttrruunncc]].

     \\nn[[..nnmm]]       Interpolate 1 if output line numbering is enabled in the  en‐
                   vironment (even if temporarily suppressed), 0 otherwise.

     \\nn[[..nnnn]]       Interpolate  count  of lines remaining in the environment for
                   which numbering is suppressed while output line numbering  is
                   enabled.

     \\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,
                   0 otherwise.  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 the environment’s type size in scaled points.

     \\nn[[..ppssrr]]      Interpolate  the  environment’s  most recently requested type
                   size in scaled points.

     \\nn[[..ppvvss]]      Interpolate  the  environment’s  post‐vertical  line  spacing
                   amount.

     \\nn[[..rrjj]]       Interpolate  count  of  input  lines  remaining  to be right‐
                   aligned in the environment.

     \\nn[[..ssllaanntt]]    Interpolate slant in degrees of  the  environment’s  selected
                   font.  See \\SS.

     \\nn[[..ssrr]]       Interpolate  the  environment’s  most recently requested type
                   size in typographical points.  This is a string‐valued regis‐
                   ter.

     \\nn[[..ssss]]
     \\nn[[..ssssss]]      Interpolate values of the  environment’s  minimum  inter‐word
                   space and supplemental inter‐sentence space, respectively, in
                   twelfths of the space width of the selected font.

     \\nn[[..ssttyy]]      Interpolate  the  environment’s selected abstract font style,
                   if any.  This is a string‐valued register.

     \\nn[[..ttaabbss]]     Interpolate the environment’s tab stop settings (if any) in a
                   form suitable for passage to  the  ttaa  request.   This  is  a
                   string‐valued register.

     \\nn[[..ttrraapp]]     Interpolate the name of the next vertical position trap after
                   the  vertical drawing position.  This is a string‐valued reg‐
                   ister.

     \\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  motion
                   produced  by  the nnee request.  In other words, at the point a
                   trap is sprung, \\nn[[..ttrruunncc]] represents the difference 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 oth‐
                   erwise.

     \\nn[[..wwaarrnn]]     Interpolate  warning  mask.   See   section   “Warnings”   of
                   _t_r_o_f_f(1).

     \\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.  Also see \\nn[[..xx]] and \\nn[[..yy]] above.

     \\nn[[..zzoooomm]]     Interpolate magnification of the environment’s selected 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 high‐
              est and lowest vertical positions attained by the argument format‐
              ted by the \\ww escape sequence, doing what  AT&T  _t_r_o_f_f  documented
              \\nn[[sstt]] and \\nn[[ssbb]] as doing.

     \\nn[[sssscc]]  The  amount  of (possibly negative) horizontal space to add to the
              last glyph before a subscript.

     \\nn[[sskkww]]  How far to right of the center of the last glyph in the  \\ww  argu‐
              ment, to place the center of an accent from a roman font over that
              glyph.

     Other  writable  registers are as follows.  Those relating to date and time
     are initialized using _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  internal
                 input  stack  (default:  1000).   If  non‐positive, there is no
                 limit: recursion can  continue  until  program  memory  is  ex‐
                 hausted.

     \\nn[[yyeeaarr]]    Interpolate  Gregorian  year.  AT&T _t_r_o_f_f’s \\nn[[yyrr]] interpolates
                 the Gregorian year minus 1900.

   DDeelliimmiitteerrss
     AT&T _t_r_o_f_f recognized slightly varying sets of  delimiters  when  expecting
     numerical  expressions (as with the \\hh escape sequence), string expressions
     (as with the \\ww escape sequence and ttll request), and output comparisons (as
     in “..iiff ##ffoooo##bbaarr## ..ttmm mmaattcchh”).  GNU _t_r_o_f_f, when not in compatibility  mode,
     recognizes  a single consistent set of delimiters.  Compatibility mode emu‐
     lates AT&T _t_r_o_f_f only up to a point.  GNU _t_r_o_f_f accepts leaders and tabs as
     delimiters, as well as Control+D (EOT or EOF), Control+H (BS or backspace),
     and Control+L (FF or form feed), all of which,  when  used  as  delimiters,
     cause AT&T _t_r_o_f_f to behave in ways difficult to predict.

   MMiisscceellllaanneeoouuss
     A font not listed in the output device’s _D_E_S_C file’s ffoonnttss directive is au‐
     tomatically  mounted  at  the  next  available font position when it is se‐
     lected.  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, potentially
     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 interpola‐
     tions and other uses of delimiters, as in the ttll  request  and  the  output
     comparison operator (that is, input like ''ffoooo''bbaarr'' as a conditional expres‐
     sion),  so  the  only  characters you need to avoid using as delimiters are
     those that appear in the arguments you input, not any that result from  in‐
     terpolation.   Typically,  ''  works fine.  Use visible characters as delim‐
     iters in GNU _t_r_o_f_f, not US‐ASCII controls like BEL (Control+G).  The imple‐
     mentation of \\$$@@ ensures that the double quotes surrounding an argument ap‐
     pear at an interpolation depth different from that of the  arguments  them‐
     selves.  Similarly, in bracket‐form escape sequences like \\ff[[ZZCCMMII]],, a right
     bracket ]] does not end the sequence unless it occurs at the same interpola‐
     tion  depth  as the opening [[.  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 “sacrificed” by mapping it
     to  “nothing”,  drafting it into use as an unadjustable, 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 instead, which has been adopted by  every  other
     active  _t_r_o_f_f implementation 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  generally  unnecessary,
     but  might be employed to obtain an unbreakable space when the escape char‐
     acter will subsequently be disabled.

     GNU _t_r_o_f_f permits tabs and spaces after the first dot  on  a  control  line
     that ends a macro definition.

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 approach 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  formatted  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  optional  second
            integer  argument  is ignored (this allows the formatter to generate
            an even number of arguments).  Each glyph  is  set  at  the  current
            drawing  position, and the position is then advanced horizontally by
            the glyph’s width.  A glyph’s width is read from its metrics in  the
            font  description file, scaled to the current type size, and rounded
            to a multiple of the horizontal motion quantum.  Use the  CC  command
            to emplace glyphs of special 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  horizontally  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 argu‐
            ments 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 underlining
            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 extensions
     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.  Nor‐
             mally 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 ar‐
             gument  is  rounded to an integer multiple of the horizontal motion
             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  automatically  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.

     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 drivers
             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  vertical  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 se‐
     quence).  Thus after executing a DD command of the form DD_z _x1_y1..._x_n_y_n,  the
     drawing  position  increases by (_i_n=Σ1_x_i,_i_n=Σ1_y_i).  For the sake of compatibil‐
     ity, GNU _t_r_o_f_f follows this rule, even though it frustrates  extensions  to
     the  DD  command  that set drawing parameters rather than rendering objects,
     producing 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 ellipse,
     DDEE.  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 specified
     in  the  AT&T  “Troff User’s Manual”.  You can ensure predictable output by
     enclosing drawing commands in the zero‐motion escape sequence \\ZZ.

     GNU _t_r_o_f_f implements fill color selection 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  es‐
            cape  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  argu‐
     ment  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 new‐
     line; if it occurs, preserve the newline, discard the plus sign,  and  con‐
     tinue 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 command.  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  sup‐
     ports  several warning categories; the output of these can be selected with
     “wwaarrnn”.  Also 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  er‐
     rors  or warnings occur by means of GNU _t_r_o_f_f --bb option, or produced on de‐
     mand with the bbaacckkttrraaccee request.

     _g_r_o_f_f also adds more flexible diagnostic output  requests  (ttmmcc  and  ttmm11).
     Examine  the  state  of the formatter with requests that write lists of de‐
     fined colors (ppccoolloorr), composite character mappings (ppccoommppoossiittee),  environ‐
     ments  (ppeevv), font translations (ppffttrr), automatic hyphenation codes (ppcchhaarr)
     and exceptions (pphhww), registers (ppnnrr), open streams (ppssttrreeaamm), and page lo‐
     cation traps (ppwwhh).  Requests can  also  disclose  to  the  standard  error
     stream  the  internal  properties  and  representations  of  characters and
     classes (ppcchhaarr), macros (and strings and diversions) (ppmm), and the list  of
     output nodes corresponding to the pending input line (pplliinnee).

CCoommppaattiibbiilliittyy mmooddee
     Some syntactical and behavioral differences between AT&T and GNU _t_r_o_f_fs are
     thought  too  important  to  neglect; GNU _t_r_o_f_f therefore makes available a
     _c_o_m_p_a_t_i_b_i_l_i_t_y _m_o_d_e in an effort to keep documents prepared for  AT&T  _t_r_o_f_f
     rendering well.

     Identifiers of arbitrary length may be GNU _t_r_o_f_f’s most obvious innovation.
     AT&T  _t_r_o_f_f  interprets  “..ddssaabbccdd”  as defining a string “aabb” with contents
     “ccdd”.  Normally, GNU _t_r_o_f_f interprets this input as calling a  macro  named
     “ddssaabbccdd”.  AT&T _t_r_o_f_f also interprets \\**[[ and \\nn[[ as interpolating a string
     or  register, respectively, named “[[”.  GNU _t_r_o_f_f, however, normally inter‐
     prets “[[” as bracketing a long name (with “]]” at the distal end).  In  com‐
     patibility  mode,  GNU  _t_r_o_f_f interprets names in the traditional way, they
     thus can be two characters long at most.  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 ratio‐
     nale.  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 ex‐
     isting  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  inclu‐
     sion.   You cannot use the same register name everywhere lest you “clobber”
     the value from a preceding or enclosing context.  The two‐character  regis‐
     ter  name  space of AT&T _t_r_o_f_f is confining, but employing GNU _t_r_o_f_f’s more
     capacious one, as with “..nnrr __mmyy__ssaavveedd__CC \\nn((..CC” does not work in compatibil‐
     ity mode; the register name is too long.  Employing the “ddoo” request is  no
     help: “..ddoo nnrr __mmyy__ssaavveedd__CC \\nn((..CC” always saves zero to the register, because
     “ddoo” turns compatibility mode _o_f_f while it interprets its argument list.

     GNU  _t_r_o_f_f normally tracks the interpolation depth of escape sequence para‐
     meters and other delimited structures, but not in compatibility mode.   See
     section “Miscellaneous” above.

     The escape sequences \\ff, \\HH, \\mm, \\MM, \\RR, \\ss, and \\SS are transparent to con‐
     trol  character recognition at the beginning of an input line, or after the
     conditional expression of an “iiff” or  iiee  request,  only  in  compatibility
     mode.  That is, upon interpreting them, GNU _t_r_o_f_f normally no longer recog‐
     nizes  a control character on the input line; but in compatibility mode, it
     does, just like AT&T _t_r_o_f_f_.

     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  migrate to another \\ss form.  [Background: 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”.]

OOtthheerr ddiiffffeerreenncceess
     GNU _t_r_o_f_f does not emit output if it has nothing to format.   For  example,
     it  treats  an  input  document  consisting solely of nnrr and ttmm requests as
     empty, and produces nothing on its  standard  output  stream.   AT&T  _t_r_o_f_f
     does, creating a blank page.

     Use  of  C0  control  characters  in  identifiers is not portable; Solaris,
     Plan 9, and Heirloom Doctools  _t_r_o_f_fs  accept  Control+B,  Control+C,  Con‐
     trol+E, Control+F, and Control+G (only); DWB 3.3 _t_r_o_f_f does not.  GNU _t_r_o_f_f
     rejects C0 controls in identifiers with an error diagnostic.

     Formatters  that  don’t implement GNU _t_r_o_f_f extension request names tend to
     ignore them, and if they don’t support a GNU  _t_r_o_f_f  extension  escape  se‐
     quence,  they are liable to format its function selector character as text.
     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  Solaris  or  Docu‐
     menter’s  Workbench _t_r_o_f_fs, which both render it as “~~”.  The \\AA escape se‐
     quence (see subsection “Escape sequences” above) may be helpful in avoiding
     their use.

     AT&T _t_r_o_f_f discards trailing spaces from input lines, like GNU  _t_r_o_f_f,  but
     when it does so, AT&T _t_r_o_f_f also cancels end‐of‐sentence detection.  Use of
     the dummy character escape sequence \\&& is more portable.

     When  adjusting  output  lines 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  im‐
     plementations  adjust spaces from opposite ends on alternating output lines
     in this adjustment mode 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 im‐
     plementation 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  derived  from
     TeX.  Some versions of _t_r_o_f_f reserved meager storage for hyphenation excep‐
     tion  words  (arguments  to the hhww request); GNU _t_r_o_f_f has no such restric‐
     tion.  When the hhyy request is invoked without an argument, GNU  _t_r_o_f_f  sets
     the automatic hyphenation mode to the value of the ..hhyyddeeffaauulltt register; the
     AT&T  implementation sets it to “11”, which is not suitable in GNU _t_r_o_f_f for
     some languages, including English.

     Unlike GNU _t_r_o_f_f, AT&T _t_r_o_f_f does not recognize an occurrence of \\%% at  the
     beginning of a word as suppressing its hyphenation; instead, it (uselessly)
     marks  the  start  of the word as a potential hyphenation point, permitting
     output lines to end with hyphens that are not interior to a word.

     GNU _t_r_o_f_f handles the dummy character \\&& differently from AT&T  _t_r_o_f_f  when
     it  is followed by the hyphenation control escape sequence \\%% at the begin‐
     ning of a word.  GNU _t_r_o_f_f does not regard the dummy character  as  “start‐
     ing”  the word; AT&T _t_r_o_f_f does.  Further, Heirloom Doctools _t_r_o_f_f does not
     honor an explicit hyphenation point marked with  \\%%  after  a  word‐initial
     one.

     GNU  _t_r_o_f_f  interprets request arguments representing file names and system
     commands in the same way it does the _c_o_n_t_e_n_t_s argument to the ddss  and  “aass”
     requests:  it  removes a leading neutral double quote ‘""’ from the argument
     to the ccff, nnxx, ppii, “ssoo”, and ssyy  requests,  and  the  second  argument  (if
     present)  to  the llff request, permitting initial embedded spaces in it, and
     reads it to the end of the input line in copy mode.  This  difference  per‐
     mits the formatter to handle files with spaces in their names, but requires
     more care with trailing comments, and doubling of an initial neutral double
     quote “""” if the file name has one.

     The  existence  of  the ..TT string is a common feature of device‐independent
     _t_r_o_f_fs——DWB 3.3, Solaris, Heirloom Doctools, and Plan 9 _t_r_o_f_f  all  support
     it——but valid values are specific to each implementation.

     The  (read‐only) register ..TT interpolates 1 if GNU _t_r_o_f_f is run with the --TT
     option, and 0 otherwise.  In contrast, AT&T _t_r_o_f_f interpolated  1  only  if
     _n_r_o_f_f was the formatter and was run with --TT.

     AT&T _t_r_o_f_f ignored attempts to remove read‐only registers; GNU _t_r_o_f_f honors
     such requests.

     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 identifiers for their
     names.

     As noted above in “Fractional type  sizes  and  new  scaling  units”,  AT&T
     _t_r_o_f_f’s  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,  possibly  a  much smaller measurement.  AT&T’s behavior also means
     that “..ppss 1100pp” and “..ppss 1100zz” are portable.

     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 fail‐
     ure 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 does (uselessly).

     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 reports their lengths in characters
     or nodes if given no arguments, and otherwise dumps the JSON‐encoded  name,
     contents, and other properties of each named argument.

     AT&T  _t_r_o_f_f  ignores the ssss request if the output is a terminal device; GNU
     _t_r_o_f_f rounds down the values of minimum inter‐word  and  additional  inter‐
     sentence space each to the nearest multiple of 12.

     GNU  _t_r_o_f_f  distinguishes  characters from glyphs.  Characters can be ordi‐
     nary, special, or indexed, and populate strings and macros.  Characters _p_e_r
     _s_e have not (yet) been formatted.  Glyphs represent graphemes (supplied  by
     the output device) and populate diversions.  Formatting converts characters
     into (sequences of) glyphs.  GNU _t_r_o_f_f stores properties of the environment
     that affect how a glyph is rendered with the glyph node’s data.  Thus, sub‐
     sequent  formatting operations do not affect it, including bbdd, ccss, ttkkff, ttrr,
     and ffpp requests.  Normally, a macro or string contains only a list of char‐
     acters and a diversion contains only a list of  nodes.   However,  applying
     the  aasscciiiiffyy or uunnffoorrmmaatt requests to a diversion converts some of its nodes
     back into characters.  Where the formatter  cannot  recover  the  character
     representation  of a node, it stores a null character in the character list
     corresponding to a single node in the node  list.   Consequently,  a  glyph
     node  does  not  behave as a character does in macro interpolation: it does
     not inherit special properties that the character from which  it  was  con‐
     structed might have had.

     One  way  to format a backslash in most documents is with the \\ee escape se‐
     quence; this formats the glyph of the current escape character,  regardless
     of  whether  it is used in a diversion; it also works in both GNU _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 special character es‐
     cape sequence \\((rrss or \\[[rrss]], for “reverse solidus”, from its  name  in  the
     ECMA‐6  and ISO 10646 standards.  [AT&T _t_r_o_f_f _’_s font description files did
     not define the rrss special character, but those of its  descendant  Heirloom
     Doctools _t_r_o_f_f do, as of its 060716 release (July 2006).]

     To store an escape sequence in a diversion that is interpreted when the di‐
     version  is  interpolated, either use the traditional \\!! transparent output
     facility, or, if this is unsuitable, the new \\?? escape sequence.  See  sub‐
     section  “Escape  sequences” above and sections “Diversions” and “GNU troff
     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.

     Like  AT&T _t_r_o_f_f_, GNU _t_r_o_f_f maintains a buffer of device‐independent output
     commands, populating the buffer as formatted output accumulates.  GNU _t_r_o_f_f
     always flushes this buffer when processing a break; AT&T _t_r_o_f_f does so  ac‐
     cording  to  no  obvious schedule (perhaps, if the buffer is of fixed size,
     the formatter performs the flush when the buffer runs out of room).

     In the somewhat pathological case where a  diversion  exists  containing  a
     partially  collected  line  and a partially collected line at the top‐level
     diversion has never existed, AT&T _t_r_o_f_f outputs a partially  collected  but
     otherwise  empty  line  (as if “\\cc” were in the top‐level diversion) at the
     end of input; GNU _t_r_o_f_f does not.

   FFoorrmmaatttteerr oouuttppuutt iinnccoommppaattiibbiilliittiieess
     Its extensions notwithstanding, GNU _t_r_o_f_f’s page description  language  has
     some incompatibilities with that of AT&T _t_r_o_f_f, but better compatibility is
     sought;  problem reports and patches are welcome.  The following incompati‐
     bilities are known.

     •  The drawing position after rendering polygons is inconsistent with  AT&T
        _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 Lem‐
     berg, 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 page description  language  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 additional
     insights into the device and font description file  formats  and  page  de‐
     scription language.

     _g_r_o_f_f(1), _g_r_o_f_f(7), _r_o_f_f(7)

groff 1.24.1                       2026‐04‐22                      _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, controlled
     by  about  twenty  arguments.  The syntax is simple and similar to the HTML
     table model and nearly as flexible:  you  can  write  sequences  of  tokens
     (macro  calls  with  their arguments and content data), separated by blanks
     and beginning with a macro call, into the same  line  to  get  compact  and
     cleanly  arranged input.  An advantage of _h_d_t_b_l is that the tables are con‐
     structed 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) preprocessor.  A further advan‐
     tage 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 understand
     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 possi‐
     bilities 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 document, where
     each one must be started and ended with the .TBL and .ETB  macros,  respec‐
     tively.

     In  this  man  page,  we approximate the result of each example as terminal
     output to be as generic as possible since _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 sufficient, 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  table
     with two rows and two columns can be written as

            .TBL cols=2
            .  TR .TD 1*1 .TD 1*2
            .  TR .TD 2*1 .TD 2*2
            .ETB

     A terminal representation is

            +--------------------------+---------------------------+
            | 1*1                      | 1*2                       |
            +--------------------------+---------------------------+
            | 2*1                      | 2*2                       |
            +--------------------------+---------------------------+

     Here  we  see  a difference from HTML tables: The number of columns must be
     explicitly specified using the ‘cols=_m’ argument  (or  indirectly  via  the
     ‘width’ argument, see below).

     The  contents  of a table cell is arbitrary; for example, it can be another
     table, without restriction to the nesting depth.  A given table layout  can
     be  either constructed with suitably nested tables or with proper arguments
     to .TD and .TH, controlling column and row spanning.  Note,  however,  that
     this table

            .TBL
            .  TR
            .    TD
            .      nop 1*1 1*2
            .  TR
            .    TD
            .      TBL cols=2 border=
            .        TR
            .          TD
            .            nop 2*1
            .          TD
            .            nop 2*2
            .      ETB
            .ETB

     and this table

            .TBL cols=2
            .  TR
            .    TD colspan=2
            .      nop 1*1 1*2
            .  TR
            .    TD
            .      nop 2*1
            .    TD
            .      nop 2*2
            .ETB

     are  similar  but  not identical (the use of .nop is purely cosmetic to get
     proper indentation).

     The first table looks like

            +------------------------------------------------------+
            | 1*1 1*2                                              |
            +------------------------------------------------------+
            |                                                      |
            | 2*1                         2*2                      |
            |                                                      |
            +------------------------------------------------------+

     and the second one like

            +------------------------------------------------------+
            | 1*1 1*2                                              |
            +---------------------------+--------------------------+
            | 2*1                       | 2*2                      |
            +---------------------------+--------------------------+

     Here is the latter table in a more compact form.

            .TBL cols=2 .TR ".TD colspan=2" 1*1 1*2
            .            TR .TD 2*1 .TD 2*2 .ETB

     If a macro has one or more arguments (see below), and it is not starting  a
     line, everything belonging to this macro including the macro itself must be
     enclosed in double quotes.

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 arbi‐
     trary; 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 col‐
     ors defined by the user with the .defcolor request.  Argument values _d  are
     decimal  numbers with or without decimal point.  Argument values _m are nat‐
     ural 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 subsection.

     Most  of  the argument default values can be changed by the user by setting
     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 separator lines between the
                          table rows and cells.  ‘border=0’ suppresses the  sur‐
                          rounding  box border, but still allows separator lines
                          between cells and rows.
                          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  necessary
                          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 between 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  alignment.
                          ‘tal=c’: centered alignment.   ‘tal=r’:  right  align‐
                          ment.
                          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,  re‐
                          spectively)”.  If there are less width values than ta‐
                          ble  columns, the last width value is used for the re‐
                          maining cells.  The argument

                                 width='1.5i 10%'

                          for  example  indicates  that  the  first  column   is
                          1.5  inches  wide;  the remaining columns take 1/10 of
                          the column length each.
                          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 contents
                          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 cap‐
                          tion 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 re‐
            ally necessary and differs from .TD only in three default  settings,
            similar to the <TH> and <TD> HTML tags: The contents of .TH is hori‐
            zontally and vertically centered and typeset in boldface.

            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  ta‐
               ble  immediately, either at the current position or at the top of
               the next page if its height is larger than the remaining space on
               the page.

            •  Otherwise, if the table is higher than the remaining space on the
               page, it is printed at the top of the next page.

            •  If neither of the  two  above  constraints  hold,  the  table  is
               printed immediately at the place of its definition.

            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 ig‐
                          nored 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’ argument 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 omit‐
     ted, the defaults take place, which the user can change by setting the cor‐
     responding  default  registers or strings, as documented below.  Setting an
     argument with the .TBL macro has the same effect as setting it for all rows
     in the table.  Setting an argument with a .TR macro has the same effect  as
     setting it for all the .TH or .TD macro in this row.

     bgc=[_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 transpar‐
            ent.
            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  identi‐
            fier, such as A for Avant Garde or HN for Helvetica Narrow.
            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  re‐
            quest, the ‘fst’ argument can be used to specify the font family and
            font  style  together, for example ‘fst=HNBI’ instead of ‘ff=HN’ and
            ‘fst=BI’.
            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 separa‐
            tor line.   ‘hl=s’:  a  single  separator  line  between  the  rows.
            ‘hl=d’: a double separator line.

            The  thickness  of  the  separator  lines  is the half of the border
            thickness, but at least 0.1 inches.  The distance between the double
            lines is equal to the line thickness.

            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 separator 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 an‐
     other example setup in the “minimal Page setup” section.

     A table which does not fit on a partially filled page is printed  automati‐
     cally  on  the  top of the next page if you append the little utility macro
     t*hm to the page header macro of your document’s main macro  package.   For
     example, say

            .am pg@top
            .  t*hm
            ..

     if you use the _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 au‐
     thor.

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.24.1                       2026‐04‐22                     _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 docu‐
     ment formatting system.  It is used to compose manual pages  (“man  pages”)
     like  the  one you are reading.  This document presents the macros themati‐
     cally; for those needing only a quick reference, the following table  lists
     them alphabetically, with references to appropriate subsections below.

     Readers  who  are  not  already  experienced  _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  typeset‐
     ting 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
     ..HHPP     Begin hanging paragraph      Paragraphing 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
     ..SSHH     Section heading              Document structure macros
     ..SSMM     Small                        Font style macros
     ..SSSS     Subsection heading           Document structure macros
     ..SSYY     Synopsis start               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                 Synopsis macros

     We  discuss other macros (AATT, DDTT, OOPP, PPDD, SSBB, and UUCC) in subsection “Depre‐
     cated features” below.

     Throughout Unix documentation, a manual entry is referred to  simply  as  a
     “man page”, regardless of its length, without gendered implication, and ir‐
     respective of the macro package selected for its composition.

   MMaaccrroo rreeffeerreennccee pprreelliimmiinnaarriieess
     A  tagged  paragraph  describes  each  macro.  We present coupled pairs to‐
     gether, as with EEXX and EEEE.  If you require an empty macro argument, specify
     it as a pair of neutral double quotes ("""").  Most macro arguments are  for‐
     matted 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 headings (SSHH), one of
     which is mandatory and many of which are conventionally  expected,  facili‐
     tate location of material by the reader and aid the man page writer to dis‐
     cuss  all  essential  aspects of the topics presented.  Subsection headings
     (SSSS) are optional and permit sections that grow long to develop in  a  con‐
     trolled  way.   Many  technical  discussions benefit from examples; lengthy
     ones, especially those reflecting multiple lines of input to or output from
     the system, are usefully bracketed by EEXX and EEEE.  When none of the  forego‐
     ing  meets  a  structural  demand,  use  RRSS/RREE  to  inset a region within a
     (sub)section.

     ..TTHH _i_d_e_n_t_i_f_i_e_r _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]]]
            Break the page, reset the page number to 1 (unless the  --rrCC11  option
            is  given),  and  use  the arguments to populate the page header and
            footer.  Together, _i_d_e_n_t_i_f_i_e_r and the _s_e_c_t_i_o_n of the manual to which
            it belongs can uniquely identify a _m_a_n document on the system.   See
            _m_a_n(1) or _i_n_t_r_o(1) for the manual sectioning applicable to your sys‐
            tem.  _i_d_e_n_t_i_f_i_e_r and _s_e_c_t_i_o_n are positioned at the left and right in
            the  header;  the latter is set after the former, in parentheses and
            without space.  _f_o_o_t_e_r_‐_m_i_d_d_l_e is centered in  the  footer.   By  de‐
            fault,  _f_o_o_t_e_r_‐_i_n_s_i_d_e  is positioned at the bottom left.  Use of the
            double‐sided layout option --rrDD11 places _f_o_o_t_e_r_‐_i_n_s_i_d_e at  the  bottom
            left  on  recto  (odd‐numbered) pages, and the bottom right on verso
            (even‐numbered) pages.  By default, the outside footer is  the  page
            number.   Use  of the continuous‐rendering option --rrccRR==11 replaces it
            with _i_d_e_n_t_i_f_i_e_r 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 sup‐
            plies text for it.  If _i_d_e_n_t_i_f_i_e_r or _f_o_o_t_e_r_‐_i_n_s_i_d_e would overrun the
            space available in the header and/or footer, this package may abbre‐
            viate them with ellipses.  _g_r_o_f_f _m_a_n suppresses headers and  footers
            in HTML output.

            A valid _m_a_n document calls TTHH only 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.  Given no argument, SSHH plants
            a  one‐line  input trap; text on the next line becomes _h_e_a_d_i_n_g_‐_t_e_x_t_.
            The heading text is set in bold (or the font specified by the string
            HHFF), and, on typesetters, 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; see  subsection  “Horizontal
            and  vertical  spacing” below.  Text lines after the call are 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 does much of the layout of material within
            sections.  For example, a section called “Name” or “NAME”  must  ex‐
            ist,  must  be the first section after the 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 tools like _m_a_k_e_w_h_a_t_i_s(8) or _m_a_n_d_b(8) to index them.

     ..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  sec‐
            tion  heading  and an ordinary paragraph (PP).  Given no argument, SSSS
            plants a one‐line input trap; text on the next line becomes _s_u_b_h_e_a_d_‐
            _i_n_g_‐_t_e_x_t_.  The subheading text is set 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; see
            subsection “Horizontal and vertical spacing” below.  Text lines  af‐
            ter the call are set as an ordinary paragraph (PP).

     ..EEXX
     ..EEEE    Begin and end example.  After EEXX, filling is disabled (and, on type‐
            setters,  a monospaced font family is selected).  Calling EEEE enables
            filling (and restores the previous family).

            Ninth Edition Unix introduced  the  EEXX  and  EEEE  extensions.   Docu‐
            menter’s  Workbench (DWB), Heirloom Doctools, and Plan 9 _t_r_o_f_fs, and
            _m_a_n_d_o_c (since 1.12.2) support them.  Solaris _t_r_o_f_f does not.

     ..RRSS [_i_n_s_e_t_‐_a_m_o_u_n_t]
            Start new relative inset.  _m_a_n saves any current  inset  amount  and
            moves  right  by: _i_n_s_e_t_‐_a_m_o_u_n_t_, if specified; the _i_n_d_e_n_t_a_t_i_o_n amount
            of the preceding IIPP, TTPP, or HHPP macro call if no (sub‐)sectioning  or
            ordinary  paragraphing macro has intervened; or the amount of the IINN
            register.  RRSS calls can nest; each increments by 1 the _l_e_v_e_l used by
            RREE.  The level prior to any RRSS call is 1.

     ..RREE [_i_n_s_e_t_‐_l_e_v_e_l]
            End a relative inset, reducing it to that of _i_n_s_e_t_‐_l_e_v_e_l (or by 1 if
            not specified) and restoring the corresponding inset amount.

   PPaarraaggrraapphhiinngg mmaaccrrooss
     These macros break the output line.  An _o_r_d_i_n_a_r_y paragraph (PP) indents  all
     output  lines  by  the same amount.  A hanging paragraph (HHPP) is a cosmetic
     variant of PP with a hanging indent.  Definition lists frequently  occur  in
     man  pages;  these  can be set as _t_a_g_g_e_d _p_a_r_a_g_r_a_p_h_s_, which have one (TTPP) or
     more (TTQQ) leading tags followed by a paragraph that has an  additional  in‐
     dentation.   The  indented  paragraph  (IIPP) macro can continue the indented
     content of a narrative started with TTPP, or present an itemized  or  ordered
     list.   If  a paragraphing macro has been called since SSHH or SSSS, all except
     TTQQ follow the break with vertical space (in an  amount  configured  by  the
     deprecated  PPDD macro); see subsection “Horizontal and vertical spacing” be‐
     low.  Except for TTQQ, these macros reset the type size, hyphenation, and ad‐
     justment to (configured) defaults, and the font style to roman.

     ..PP
     ..LLPP
     ..PPPP    Begin a new paragraph; these macros are synonymous.  Any indentation
            from use of IIPP, TTPP, or HHPP is cleared.  The inset amount, as affected
            by RRSS and RREE, is not.

     ..HHPP [_i_n_d_e_n_t_a_t_i_o_n]
            Set a paragraph with a hanging indentation.  Text  on  output  lines
            after the first is indented by _i_n_d_e_n_t_a_t_i_o_n_, if specified, and by the
            amount of the IINN register otherwise.

            _C_a_u_t_i_o_n_:  A  hanging  indentation  cannot  be expressed naturally in
            (pure) HTML, a hanging paragraph is not distinguishable from an  or‐
            dinary one if it formats on only one output line, and non‐_r_o_f_f‐based
            man  page interpreters may treat HHPP as an ordinary paragraph anyway.
            Thus, information or distinctions you mean to express with  indenta‐
            tion may be lost.

     ..TTPP [_i_n_d_e_n_t_a_t_i_o_n]
            Set  an indented paragraph with a leading unindented tag.  The macro
            plants a one‐line input trap that honors  the  \\cc  escape  sequence;
            text  on  the  next  line  becomes the tag, set without indentation.
            Text on subsequent lines is indented 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, plus
            the “tag spacing” stored in the TTSS register (see  section  “Options”
            below)  is  wider  than the indentation, the package breaks the line
            after the tag.

     ..TTQQ    Set an additional tag for a paragraph tagged  with  TTPP,  planting  a
            one‐line input trap as with TTPP.

            TTQQ  is  a  GNU extension supported by Heirloom Doctools _t_r_o_f_f (since
            Git snapshot 151218) and _m_a_n_d_o_c  (since  1.14.5)  but  not  by  DWB,
            Plan 9, or Solaris _t_r_o_f_fs.

     ..IIPP [_m_a_r_k [_i_n_d_e_n_t_a_t_i_o_n]]
            Set  an  indented  paragraph  with  an optional mark.  Arguments, if
            present, are handled as with TTPP, except that the _m_a_r_k argument to IIPP
            cannot include a macro call, and the tag separation amount stored in
            the TTSS register is not enforced.

   SSyynnooppssiiss mmaaccrrooss
     Use SSYY and YYSS to summarize syntax using familiar Unix  conventions.   Heir‐
     loom  Doctools  _t_r_o_f_f (since Git snapshot 151218) and _m_a_n_d_o_c (since 1.14.5)
     support these GNU extensions; DWB, Plan 9, and Solaris _t_r_o_f_fs do not.

     ..SSYY _k_e_y_w_o_r_d [_s_u_f_f_i_x]
            Begin synopsis.  Adjustment and automatic hyphenation are  disabled.
            If SSYY has already been called without a corresponding YYSS, a break is
            performed.   _k_e_y_w_o_r_d and any _s_u_f_f_i_x are set in bold.  When _s_u_f_f_i_x is
            present, the package sets the next word after it without intervening
            space.  If a break is required in subsequent text  (up  to  a  para‐
            graphing,  sectioning,  or YYSS macro call), lines after the first are
            indented.  Unless the previous synopsis’s indentation is reused (see
            YYSS below), output lines after the first indent by the width  of  the
            pending  output  line up to the end of _k_e_y_w_o_r_d plus a space, if _k_e_y_‐
            _w_o_r_d is the only argument, and up to the end of _s_u_f_f_i_x otherwise.

     ..YYSS [_r_e_u_s_e_‐_i_n_d_e_n_t_a_t_i_o_n]
            End synopsis, breaking the line and restoring  indentation,  adjust‐
            ment,  and  hyphenation to their previous states.  If an argument is
            given, the indentation corresponding to  the  previous  SSYY  call  is
            reused by the next SSYY call instead of being computed.

   HHyyppeerrlliinnkk mmaaccrrooss
     Man page cross references are best presented with MMRR.  Mark email addresses
     with MMTT/MMEE and other sorts of URI with UURR/UUEE.  To hyperlink text, 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 disabled with the UU reg‐
     ister (see section “Options” below), _g_r_o_f_f _m_a_n renders these  URIs  between
     angle brackets (⟨⟨ ⟩⟩) after the linked text.

     MMTT,  MMEE, UURR, and UUEE are GNU extensions supported by Heirloom Doctools _t_r_o_f_f
     (since Git snapshot 151218) and _m_a_n_d_o_c (UURR/UUEE  since  1.12.3;  MMTT/MMEE  since
     1.14.2)  but not by DWB, Plan 9 (original), or Solaris _t_r_o_f_fs.  Plan 9 from
     User Space’s _t_r_o_f_f implements MMRR.

     Prepare arguments to MMRR, MMTT, and UURR for typesetting; they can appear in the
     output.  Use special character escape sequences  to  encode  Unicode  basic
     Latin characters where necessary, particularly the hyphen‐minus.

     ..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 _m_a_n_u_a_l_‐_s_e_c_t_i_o_n is absent, the package omits the  sur‐
            rounding  parentheses.   If _t_r_a_i_l_i_n_g_‐_t_e_x_t (typically punctuation) is
            specified, it follows the closing  parenthesis  without  intervening
            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.  If _m_a_n_u_a_l_‐_s_e_c_‐
            _t_i_o_n is present, 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 intervening 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, except
            when _a_d_d_r_e_s_s appears as a TTPP paragraph tag.

     ..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 enabled 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, except when _u_r_i appears as a TTPP paragraph tag.

     If  a  UURR/UUEE  or MMTT/MMEE pair occurs in a TTPP tag and hyperlinking is unavail‐
     able, _g_r_o_f_f _m_a_n sets the link target at the beginning of the indented para‐
     graph, not as part of the tag, unless there is no link text.

   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  may  instead  render  under‐
     scored  on  terminals.   SSMM sets text at a smaller type size, which differs
     visually from regular‐sized text only on typesetters.  The macros  BBII,  BBRR,
     IIBB,  IIRR,  RRBB,  and RRII set their odd‐ and even‐numbered arguments as text in
     the alternating styles their names indicate, with no space separating them.

     The default type size and family for typesetters is 10‐point Times,  except
     on  the  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.  Given no argument,  BB  plants  a  one‐line  input
            trap;  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.  Given no argument, II  plants
            a  one‐line  input trap; text on the next line, which can be further
            formatted with a macro, is set in an italic or oblique face.

     ..SSMM [_t_e_x_t]
            Set _t_e_x_t one point smaller than the default type  size  on  typeset‐
            ters.   Given  no argument, SSMM plants a one‐line input trap; text on
            the next line, which can be further formatted with a macro,  is  set
            smaller.

     Unlike the above font style macros, the font style alternation macros below
     set  no input traps; they must be given arguments to have effect.  They ap‐
     ply italic corrections as appropriate.

     ..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 package sets all text inboard of the left edge of the output medium  by
     the  amount of the _p_a_g_e _o_f_f_s_e_t_; see register PPOO in section “Options” below.
     Headers, footers (both set with TTHH), and section headings (SSHH) lie  at  the
     page  offset.   _g_r_o_f_f _m_a_n indents subsection headings (SSSS) by the amount in
     the SSNN register.

     Ordinary paragraphs not within an RRSS/RREE  inset  region  are  inset  by  the
     amount stored in the BBPP register; see section “Options” below.  The IINN reg‐
     ister  configures  the default indentation amount used by RRSS (as the _i_n_s_e_t_‐
     _a_m_o_u_n_t), IIPP, TTPP, and HHPP; an overriding argument is a  number  plus  an  op‐
     tional  scaling unit.  If no scaling unit is given, the _m_a_n package assumes
     “n”.  An indentation specified in a call to IIPP, TTPP, or  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  en‐
     tirely.

     Several macros insert vertical space: SSHH, SSSS, TTPP, PP (and its synonyms), IIPP,
     and  HHPP.  They then enable _n_o_‐_s_p_a_c_e _m_o_d_e_; see _g_r_o_f_f(7).  The default inter‐
     section and inter‐paragraph spacing is 1v for terminals and 0.4v for  type‐
     setters.  (The deprecated macro PPDD can change this vertical spacing, but we
     discourage  its use.)  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 sec‐
     tion “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).  _g_r_o_f_f _m_a_n
     supports others 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 docu‐
             ment 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 ad‐
     ministrator 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 footers.  Be‐
     cause 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 typically consist of “sp” and
     “tl” requests.  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 discouraged.

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

            The inside footer is populated per the value of _s_y_s_t_e_m_.

                   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 trans‐
            lates poorly to HTML, under which exact space control and tabulation
            are not readily available.  Thus, information or  distinctions  that
            you  use  tab  stops  to express are likely to be lost.  If you feel
            tempted to change the tab stops such that calling this  macro  later
            to  restore  them  is  desirable,  consider  composing a table using
            _t_b_l(1) instead.

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

            Use of this quasi‐semantic macro, an extension whose name originated
            in DWB _t_r_o_f_f, is deprecated; _g_r_o_f_f’s interface differs.  Neither can
            easily be used to annotate options that take optional  arguments  or
            options  whose  arguments have internal structure (such as a mixture
            of literal and variable components).  One could  work  around  these
            limitations with font selection escape sequences, but font style al‐
            ternation  macros are preferable; they are more flexible and perform
            italic corrections on typesetters.

     ..PPDD [_v_e_r_t_i_c_a_l_‐_s_p_a_c_e]
            Configure  the  amount  of  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,  in‐
            ter‐paragraph  spacing  resets  to its default value; see subsection
            “Horizontal and vertical spacing” above.

            Use of this presentation‐oriented macro is  deprecated.   It  trans‐
            lates  poorly  to HTML, under which exact control of inter‐paragraph
            spacing is not readily available.  Thus, information or distinctions
            that you use PPDD to express are likely to be lost.

     ..SSBB [_t_e_x_t]
            Set _t_e_x_t in bold and (on typesetters) one point smaller than the de‐
            fault type size.  Given no argument,  SSBB  plants  a  one‐line  input
            trap;  text  on the next line, which can be further formatted with a
            macro, is set smaller and in bold.  Use of this macro, an  extension
            originating  in SunOS 4.0 _t_r_o_f_f, is deprecated.  SSMM without an argu‐
            ment, followed immediately by “BB _t_e_x_t”,  produces  the  same  output
            more  portably.  The macros’ order is interchangeable; put _t_e_x_t with
            the latter.

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

            The inside footer is populated per the value of _v_e_r_s_i_o_n_.

                   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 Volume 1 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 supplied by the system.
     The package supported the macros listed in this page not described  as  ex‐
     tensions,  except  PP and the deprecated AATT and UUCC.  It documented no regis‐
     ters and defined only RR and SS strings.

     UUCC appeared in 3BSD (1980).  Unix System III (1980) introduced  PP  and  ex‐
     posed  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 Unix (1986) introduced EEXX  and
     EEEE.   SunOS  4.0 (1988) added SSBB.  Unix System V (1988) incorporated the llqq
     and rrqq strings.

     Except for EEXX/EEEE, James Clark implemented the foregoing features  in  early
     versions  of  _g_r_o_f_f_.  Later, _g_r_o_f_f 1.20 (2009) resurrected EEXX/EEEE and origi‐
     nated SSYY/YYSS, TTQQ, MMTT/MMEE, and UURR/UUEE.  Plan 9 from User Space’s  _t_r_o_f_f  intro‐
     duced MMRR in 2020, and incorporated the llqq and rrqq strings in 2025.

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  consis‐
     tent  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  align‐
              ment  (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.

     --rrBBPP==_b_a_s_e_‐_p_a_r_a_g_r_a_p_h_‐_i_n_s_e_t
              Set the inset amount for ordinary paragraphs not within  an  RRSS/RREE
              inset.  The default is 5n.

     --rrccRR==11   Enable  continuous  rendering.   Output is not paginated; instead,
              one (potentially very long) page is produced.  This is the default
              for terminal and HTML devices.  Use --rrccRR==00 to disable it on termi‐
              nals; 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.

     --rrCCHHEECCKKSSTTYYLLEE==_n
              Report problems with usage of this macro package exhibited by  the
              input  at  verbosity  level  _n, where _n is an integer in the range
              0–3, inclusive; 00 disables the messages and is the default.   This
              feature  is a development and debugging aid for man page maintain‐
              ers; the problems diagnosed, and range and meanings  of  the  sup‐
              ported levels, are subject to change.

     --rrCCSS==11   Set  section  headings  (the  argument(s) to SSHH) in full capitals.
              This transformation is off by default because it discards  letter‐
              case distinctions.

     --rrCCTT==11   Set  the  man  page  identifier (the first argument to TTHH) in full
              capitals in headers and footers.  This transformation  is  off  by
              default because it discards lettercase distinctions.

     --rrDD11     Enable  double‐sided  layout,  formatting footers for even and odd
              pages differently; see the description of TTHH in subsection  “Docu‐
              ment 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 - 1v”.

     --ddHHFF==_h_e_a_d_i_n_g_‐_f_o_n_t
              Select the font used for section and subsection headings; the  de‐
              fault  is “BB” (bold style of the default family).  Any valid argu‐
              ment 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 section
              “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 default indentation amount used by IIPP, TTPP, and HHPP, and the
              inset amount used by RRSS.  The default is 7n on terminals and  7.2n
              on  typesetters.  Use only integer multiples of unit “n” on termi‐
              nals for consistent indentation.

     --rrLLLL==_l_i_n_e_‐_l_e_n_g_t_h
              Set line length; the default is 80n on terminals and 6.5i on type‐
              setters.

     --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
              Select the font used for man page identifiers in TTHH calls and top‐
              ics named in MMRR calls; the default is “II” (italic style of the de‐
              fault family).  Any valid argument to _g_r_o_f_f’s “ft” request may  be
              used.   If the MMFF string ends in “I”, the package assumes it to be
              an oblique typeface, and applies italic corrections before and af‐
              ter man page topics and identifiers.

     --rrPP_n     Start enumeration of pages at _n.  The default is 1.

     --rrPPOO==_p_a_g_e_‐_o_f_f_s_e_t
              Set page offset; the default is 0 on terminals and 1i on  typeset‐
              ters.

     --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_.
              The default is 3n.

     --rrTTSS==_s_e_p_a_r_a_t_i_o_n
              Require the given _s_e_p_a_r_a_t_i_o_n between a TTPP paragraph’s tag and  its
              body.  The default is 2n.

     --rrUU00     Disable  generation of URI hyperlinks in output drivers capable of
              them, making the arguments to MMTT and UURR calls visible as formatted
              text.  _g_r_o_h_t_m_l(1), _g_r_o_p_d_f(1), and _g_r_o_t_t_y(1) enable  hyperlinks  by
              default (the last only if not in its legacy output mode).

     --rrXX_p     Number successors of page _p as _pa, _pb, _pc, and so forth.  The reg‐
              ister  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_4_._1_/_t_m_a_c_/_a_n_._t_m_a_c
            Most _m_a_n macros are defined in this file.  It also loads  extensions
            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_4_._1_/_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 pack‐
            age  is  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 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  reloads  each  macro package as necessary.
            Page‐local redefinitions of names used by the _m_a_n or  _m_d_o_c  packages
            prior  to  TTHH  or DDdd calls are “clobbered” by the reloading process.
            If you want to provide your own definition of an extension macro  to
            ensure its availability, the _a_n_-_e_x_t_._t_m_a_c entry below offers advice.

     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_t_m_a_c_/_a_n_-_e_x_t_._t_m_a_c
            Definitions  of macros described above as extensions (and not depre‐
            cated) are contained in this file; in some cases, they  are  simpler
            versions of definitions appearing in _a_n_._t_m_a_c, and are ignored 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 copylefted.  To reduce the risk
            of  name space collisions, string and register names begin only with
            “mm”.  We encourage man page authors who are concerned  about  porta‐
            bility  to  legacy Unix systems to copy these definitions into their
            pages, and maintainers of _t_r_o_f_f implementations or  work‐alike  sys‐
            tems  that format man pages to re‐use them.  To ensure reliable ren‐
            dering, define them after your page calls TTHH; see the discussion  of
            _a_n_d_o_c_._t_m_a_c  above.   Further,  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(8)  or _m_a_n_d_b(8) implementations that easily give up scan‐
            ning for indexing material.

     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_t_m_a_c_/_m_a_n_._t_m_a_c
            is a wrapper enabling the package to be loaded with the  option  “--mm
            mmaann”.

     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_t_m_a_c_/_m_a_n_d_o_c_._t_m_a_c
            is  a  wrapper  enabling _a_n_d_o_c_._t_m_a_c to be loaded with the option “--mm
            mmaannddoocc”.

     _/_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
     James Clark wrote the initial GNU implementation of the _m_a_n macro  package.
     Later,  Werner  Lemberg  supplied  the  SS, LLTT, and ccRR registers, the last a
     4.3BSD‐Reno _m_d_o_c(7) feature.  Larry Kollar added the FFTT, HHYY, and SSNN  regis‐
     ters;  the  HHFF string; and the PPTT and BBTT macros in _g_r_o_f_f 1.19 (2003).  Lem‐
     berg and Eric S. Raymond contributed EEXX/EEEE, MMTT/MMEE, UURR/UUEE, TTQQ, and an  early
     version  of the SSYY/YYSS macros to _g_r_o_f_f 1.20 (2009).  G. Branden Robinson im‐
     plemented the AADD and MMFF strings; CCSS, CCTT, and UU registers; and the MMRR  macro
     for  _g_r_o_f_f  1.23 (2023), and the BBPP, PPOO, and TTSS registers and a revised im‐
     plementation of the SSYY/YYSS macros for _g_r_o_f_f 1.24 (2026).

     Susan G. Kleinmann wrote the initial version of this document for  the  De‐
     bian  GNU/Linux system.  Lemberg imported it to _g_r_o_f_f_.  He and Robinson re‐
     vised and updated  it.   Raymond  and  Robinson  documented  the  extension
     macros.

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 BSD’s alternative macro package 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)

groff 1.24.1                       2026‐04‐22                       _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 docu‐
     ment formatting system.  It is used to compose manual pages  (“man  pages”)
     like  the  one you are reading.  This document presents the macros themati‐
     cally; for those needing only a quick reference, the following table  lists
     them alphabetically, with references to appropriate subsections below.  Ex‐
     perienced _m_a_n authors may prefer _g_r_o_f_f___m_a_n(7).

     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
     ..HHPP     Begin hanging paragraph      Paragraphing 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
     ..SSHH     Section heading              Document structure macros
     ..SSMM     Small                        Font style macros
     ..SSSS     Subsection heading           Document structure macros
     ..SSYY     Synopsis start               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                 Synopsis macros

     We  discuss other macros (AATT, DDTT, OOPP, PPDD, SSBB, and UUCC) in subsection “Depre‐
     cated features” below.

     Throughout Unix documentation, a manual entry is referred to  simply  as  a
     “man page”, regardless of its length, without gendered implication, and ir‐
     respective of the macro package selected for its composition.

     A man page employs the Unix line‐ending convention (U+000A only).  Some ba‐
     sic  Latin  characters have special meaning to _r_o_f_f_; see subsection “Porta‐
     bility” below.

   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) collects words
     from the input and _f_i_l_l_s output lines with as many as can 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_.  Breaks can occur at explicit hyphens, at \\%% or  \\::  escape
     sequences  (see  subsection “Portability” below), or at predetermined loca‐
     tions in a word 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_,  then potentially _a_d_j_u_s_t_e_d with more space to a consistent
     length (see the --ddAADD option).  _r_o_f_f(7) details these processes.   The  for‐
     matter  prepares  output for _t_e_r_m_i_n_a_l_s or for more capable _t_y_p_e_s_e_t_t_e_r_s that
     can change the type size and font family.

     A _r_o_f_f document can contain _c_o_n_t_r_o_l _l_i_n_e_s_, which start with a  dot  (..)  or
     neutral apostrophe ('').  All other input lines are _t_e_x_t _l_i_n_e_s to be format‐
     ted.   A _m_a_c_r_o collects control and/or text lines to ease document composi‐
     tion.  _m_a_n is a _m_a_c_r_o _p_a_c_k_a_g_e_.  To call a macro, put its name after  a  dot
     on  a control line.  Some macros interpret _a_r_g_u_m_e_n_t_s_, words that follow its
     name.  A newline, unless  escaped  (see  subsection  “Portability”  below),
     marks  the  end of the macro call.  A control line with no macro name on it
     is called an _e_m_p_t_y _r_e_q_u_e_s_t_; it does nothing.

     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 spe‐
     cially.  For _m_a_n documents that follow the advice in section  “Portability”
     below,  this  means  that  control lines using the empty request and uncom‐
     mented input lines ending with an escaped newline do not spring  the  trap;
     anything else does (but see the TTPP macro description).

   MMaaccrroo rreeffeerreennccee pprreelliimmiinnaarriieess
     A  tagged  paragraph  describes  each  macro.  We present coupled pairs to‐
     gether, as with EEXX and EEEE.  Square brackets surround optional  macro  argu‐
     ments.  If a macro accepts multiple arguments, those containing space char‐
     acters  must  be double‐quoted to be interpreted correctly.  If you require
     an empty macro argument, specify it as a  pair  of  neutral  double  quotes
     ("""").   See section “Notes” below for examples of cases where better alter‐
     natives to empty arguments in macro calls are available.  Most macro  argu‐
     ments  are formatted as text in the output; exceptions are noted.  We iden‐
     tify some macros as _e_x_t_e_n_s_i_o_n_s to the set originally implemented.  They are
     not supported everywhere; see subsection “Use of extensions” below.

   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 headings (SSHH), one of
     which  is  mandatory and many of which are conventionally expected, facili‐
     tate location of material by the reader and aid the man page writer to dis‐
     cuss all essential aspects of the topics  presented.   Subsection  headings
     (SSSS)  are  optional and permit sections that grow long to develop in a con‐
     trolled way.  Many technical discussions  benefit  from  examples;  lengthy
     ones, especially those reflecting multiple lines of input to or output from
     the  system, are usefully bracketed by EEXX and EEEE.  When none of the forego‐
     ing meets a structural demand,  use  RRSS/RREE  to  inset  a  region  within  a
     (sub)section.

     ..TTHH _i_d_e_n_t_i_f_i_e_r _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]]]
            Break  the  page, reset the page number to 1 (unless the --rrCC11 option
            is given), and use the arguments to populate  the  page  header  and
            footer.   _r_o_f_f systems refer to these collectively as “titles”.  To‐
            gether, _i_d_e_n_t_i_f_i_e_r and the _s_e_c_t_i_o_n of the manual to which it belongs
            can uniquely identify a _m_a_n document on the  system.   This  use  of
            “section” has nothing to do with the section headings otherwise dis‐
            cussed  in  this  page;  it arises from the organizational scheme of
            printed and bound Unix manuals.  See _m_a_n(1) or _i_n_t_r_o(1) for the man‐
            ual sectioning applicable to your system.   _i_d_e_n_t_i_f_i_e_r  and  _s_e_c_t_i_o_n
            are  positioned  at  the left and right in the header; the latter is
            set after the former, in parentheses and without space.  _f_o_o_t_e_r_‐_m_i_d_‐
            _d_l_e is centered in the footer.  By default, _f_o_o_t_e_r_‐_i_n_s_i_d_e  is  posi‐
            tioned  at  the  bottom left.  Use of the double‐sided layout option
            --rrDD11 places _f_o_o_t_e_r_‐_i_n_s_i_d_e at the bottom left on recto (odd‐numbered)
            pages, and the bottom right on verso (even‐numbered) pages.  By  de‐
            fault,  the  outside footer is the page number.  Use of the continu‐
            ous‐rendering option --rrccRR==11 replaces it with _i_d_e_n_t_i_f_i_e_r 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 supplies text for it.  If _i_d_e_n_t_i_f_i_e_r
            or _f_o_o_t_e_r_‐_i_n_s_i_d_e would overrun the space  available  in  the  header
            and/or footer, this package may abbreviate them with ellipses (......).
            _g_r_o_f_f _m_a_n suppresses headers and footers in HTML output.

            A valid _m_a_n document calls TTHH only 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 modification to the source  document,  in  ISO  8601
            format  (_Y_Y_Y_Y‐_M_M‐_D_D),  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.  Given no argument, SSHH plants
            a one‐line input trap; text on the next line  becomes  _h_e_a_d_i_n_g_‐_t_e_x_t_.
            The heading text is set in bold (or the font specified by the string
            HHFF),  and,  on typesetters, 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; see subsection “Horizontal
            and vertical spacing” below.  Text lines after the call are  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 does much of the layout of  material  within
            sections.   For  example, a section called “Name” or “NAME” must ex‐
            ist, must be the first section after the 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 tools like _m_a_k_e_w_h_a_t_i_s(8) or _m_a_n_d_b(8) to index them.

     ..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 sec‐
            tion heading and an ordinary paragraph (PP).  Given no  argument,  SSSS
            plants a one‐line input trap; text on the next line becomes _s_u_b_h_e_a_d_‐
            _i_n_g_‐_t_e_x_t_.  The subheading text is set 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; see
            subsection  “Horizontal and vertical spacing” below.  Text lines af‐
            ter the call are set as an ordinary paragraph (PP).

     ..EEXX
     ..EEEE    Begin and end example.  After EEXX, filling is disabled (and, on type‐
            setters, a monospaced font family is selected).  Calling EEEE  enables
            filling (and restores the previous family).

            Example  regions are useful for formatting code, shell sessions, and
            text file contents.  An example region is not a  “literal  mode”  of
            any  sort:  special character escape sequences must still be used to
            produce correct glyphs for '', --, \\, ^^,  ``,  and  ~~  (see  subsection
            “Portability”  below).  Sentence endings are still detected and sup‐
            plemental inter‐sentence space applied.  If the amount of supplemen‐
            tal inter‐sentence spacing is altered, the  rendering  of,  for  in‐
            stance, regular expressions using .. or ?? followed by multiple spaces
            can  change.   Use the dummy character escape sequence \\&& before the
            spaces.

            Ninth Edition Unix introduced  the  EEXX  and  EEEE  extensions.   Docu‐
            menter’s  Workbench (DWB), Heirloom Doctools, and Plan 9 _t_r_o_f_fs, and
            _m_a_n_d_o_c (since 1.12.2) support them.  Solaris _t_r_o_f_f does not.

     ..RRSS [_i_n_s_e_t_‐_a_m_o_u_n_t]
            Start new relative inset.  _m_a_n saves any current  inset  amount  and
            moves  right  by: _i_n_s_e_t_‐_a_m_o_u_n_t_, if specified; the _i_n_d_e_n_t_a_t_i_o_n amount
            of the preceding IIPP, TTPP, or HHPP macro call if no (sub‐)sectioning  or
            ordinary  paragraphing macro has intervened; or the amount of the IINN
            register.  RRSS calls can nest; each increments by 1 the _l_e_v_e_l used by
            RREE.  The level prior to any RRSS call is 1.

     ..RREE [_i_n_s_e_t_‐_l_e_v_e_l]
            End a relative inset, reducing it to that of _i_n_s_e_t_‐_l_e_v_e_l (or by 1 if
            not specified) and restoring the corresponding inset amount.

   PPaarraaggrraapphhiinngg mmaaccrrooss
     These macros break the output line.  An _o_r_d_i_n_a_r_y paragraph  (PP)  like  this
     one  indents all output lines by the same amount.  A hanging paragraph (HHPP)
     is a cosmetic variant of PP with a hanging indent.   Definition  lists  fre‐
     quently  occur  in  man pages; these can be set as _t_a_g_g_e_d _p_a_r_a_g_r_a_p_h_s_, which
     have one (TTPP) or more (TTQQ) leading tags followed by a paragraph that has an
     additional indentation.  The indented paragraph (IIPP) macro can continue the
     indented content of a narrative started with TTPP, or present an itemized  or
     ordered  list.  If a paragraphing macro has been called since SSHH or SSSS, all
     except TTQQ follow the break with vertical space (in an amount configured  by
     the  deprecated PPDD macro); see subsection “Horizontal and vertical spacing”
     below.  Except for TTQQ, these macros reset the type size,  hyphenation,  and
     adjustment to (configured) defaults, and the font style to roman.

     ..PP
     ..LLPP
     ..PPPP    Begin a new paragraph; these macros are synonymous.  Any indentation
            from use of IIPP, TTPP, or HHPP is cleared.  The inset amount, as affected
            by RRSS and RREE, is not.

     ..HHPP [_i_n_d_e_n_t_a_t_i_o_n]
            Set  a  paragraph  with a hanging indentation.  Text on output lines
            after the first is indented by _i_n_d_e_n_t_a_t_i_o_n_, if specified, and by the
            amount of the IINN register otherwise.

            _C_a_u_t_i_o_n_: A hanging indentation  cannot  be  expressed  naturally  in
            (pure)  HTML, a hanging paragraph is not distinguishable from an or‐
            dinary one if it formats on only one output line, and non‐_r_o_f_f‐based
            man page interpreters may treat HHPP as an ordinary paragraph  anyway.
            Thus,  information or distinctions you mean to express with indenta‐
            tion may be lost.

     ..TTPP [_i_n_d_e_n_t_a_t_i_o_n]
            Set an indented paragraph with a leading unindented tag.  The  macro
            plants  a  one‐line  input  trap that honors the \\cc escape sequence;
            text on the next line becomes  the  tag,  set  without  indentation.
            Text  on  subsequent lines is indented 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,  plus
            the  “tag  spacing” stored in the TTSS register (see section “Options”
            below) is wider than the indentation, the package  breaks  the  line
            after the tag.

            The  line  containing the tag can include a macro call, for instance
            to set the tag in bold with BB.  TTPP was used to write the first para‐
            graph of this description of TTPP, and IIPP the subsequent one.

     ..TTQQ    Set an additional tag for a paragraph tagged  with  TTPP,  planting  a
            one‐line input trap as with TTPP.

            TTQQ  is  a  GNU extension supported by Heirloom Doctools _t_r_o_f_f (since
            Git snapshot 151218) and _m_a_n_d_o_c  (since  1.14.5)  but  not  by  DWB,
            Plan 9, or Solaris _t_r_o_f_fs.

            The description of PP, LLPP, and PPPP above was written using TTPP and TTQQ.

     ..IIPP [_m_a_r_k [_i_n_d_e_n_t_a_t_i_o_n]]
            Set  an  indented  paragraph  with  an optional mark.  Arguments, if
            present, are handled as with TTPP, except that the _m_a_r_k argument to IIPP
            cannot include a macro call, and the tag separation amount stored in
            the TTSS register is not enforced.

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

   SSyynnooppssiiss mmaaccrrooss
     Use SSYY and YYSS to summarize syntax using familiar Unix  conventions.   Heir‐
     loom  Doctools  _t_r_o_f_f (since Git snapshot 151218) and _m_a_n_d_o_c (since 1.14.5)
     support these GNU extensions; DWB, Plan 9, and Solaris _t_r_o_f_fs do not.

     ..SSYY _k_e_y_w_o_r_d [_s_u_f_f_i_x]
            Begin synopsis.  Adjustment and automatic hyphenation are  disabled.
            If SSYY has already been called without a corresponding YYSS, a break is
            performed.   _k_e_y_w_o_r_d and any _s_u_f_f_i_x are set in bold.  When _s_u_f_f_i_x is
            present, the package sets the next word after it without intervening
            space.  If a break is required in subsequent text  (up  to  a  para‐
            graphing,  sectioning,  or YYSS macro call), lines after the first are
            indented.  Unless the previous synopsis’s indentation is reused (see
            YYSS below), output lines after the first indent by the width  of  the
            pending  output  line up to the end of _k_e_y_w_o_r_d plus a space, if _k_e_y_‐
            _w_o_r_d is the only argument, and up to the end of _s_u_f_f_i_x otherwise.

     ..YYSS [_r_e_u_s_e_‐_i_n_d_e_n_t_a_t_i_o_n]
            End synopsis, breaking the line and restoring  indentation,  adjust‐
            ment,  and  hyphenation to their previous states.  If an argument is
            given, the indentation corresponding to  the  previous  SSYY  call  is
            reused by the next SSYY call instead of being computed.

     Interleave  multiple  SSYY/YYSS  blocks with paragraphing macros to distinguish
     differing modes of operation of a complex command like  _t_a_r(1).   Omit  the
     paragraphing  macro  to  indicate  synonymous ways of invoking a particular
     mode of operation.  Paragraphing macros can similarly  manage  grouping  of
     function synopses.

     _g_r_o_f_f’s  own  command‐line interface illustrates most specimens of synopsis
     syntax one may encounter.

            .SY groff
            .RB [ \-abcCeEgGijklNpRsStUVXzZ ]
            .RB [ \-d\~\c
            .IR ctext ]
            .RB [ \-d\~\c
            .IB string =\c
            .IR text ]
            .RB [ \-D\~\c
            .IR fallback-encoding ]
            _(_a_n_d _s_o _o_n _s_i_m_i_l_a_r_l_y_)
            .RI [ file\~ .\|.\|.]
            .YS
            .
            .
            .P
            .SY groff
            .B \-h
            .YS
            .
            .SY groff
            .B \-\-help
            .YS
            .
            .
            .P
            .SY groff
            .B \-v
            .RI [ option\~ .\|.\|.\&]
            .RI [ file\~ .\|.\|.]
            .YS
            .
            .SY groff
            .B \-\-version
            .RI [ option\~ .\|.\|.\&]
            .RI [ file\~ .\|.\|.]
            .YS

     Given the foregoing input, _g_r_o_f_f _m_a_n produces the following output.

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

     Several features of the above example are of note.

     •  The empty request (.), which does nothing, vertically spaces  the  input
        file  for readability by the document maintainer; see subsection “Porta‐
        bility” below regarding blank lines.

     •  Command and option names are presented in bboolldd to cue the user that they
        should be input literally.

     •  Option dashes are specified with the \\-- escape sequence; this is an  im‐
        portant  practice  to  make them clearly visible and to facilitate copy‐
        and‐paste from the rendered man page to a shell prompt or text file.

     •  Option arguments and command operands are presented in _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 input.

     •  Symbols that are neither to be  typed  literally  nor  replaced  at  the
        user’s  discretion appear in the roman style; brackets surround optional
        arguments, and an ellipsis indicates that the previous syntactic element
        may be repeated arbitrarily.  Where whitespace separates optional  argu‐
        ments, a space precedes the ellipsis.

     •  The non‐breaking adjustable space escape sequence \\~~ prevents the output
        line from breaking within the option brackets; see subsection “Portabil‐
        ity” 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 further
        text  is  to follow after space on the output line, keeping its last pe‐
        riod from being interpreted as the end of a sentence because it is  fol‐
        lowed  by  characters that are transparent to end‐of‐sentence detection,
        and/or a newline, which would in turn normally cause  the  formatter  to
        place  supplemental  inter‐sentence  space  after  it.   See  subsection
        “Portability” below.

     We might synopsize the standard C library function _b_s_e_a_r_c_h(3) as follows.

            .P
            .B void *\c
            .SY bsearch (
            .BI const\~void\~* key ,
            .BI const\~void\~* base ,
            .BI size_t\~ nmemb ,
            .BI int\~(* compar )\c
            .B (const\~void\~*, const\~void\~*));
            .YS

     _g_r_o_f_f _m_a_n produces the following result.

            vvooiidd **bbsseeaarrcchh((ccoonnsstt vvooiidd **_k_e_y,, ccoonnsstt vvooiidd **_b_a_s_e,, ssiizzee__tt _n_m_e_m_b,,
                          iinntt ((**_c_o_m_p_a_r))((ccoonnsstt vvooiidd **,, ccoonnsstt vvooiidd **))));;

   HHyyppeerrlliinnkk mmaaccrrooss
     Man page cross references like _l_s(1) are  best  presented  with  MMRR.   Mark
     email addresses with MMTT/MMEE and other sorts of URI with UURR/UUEE.  To hyperlink
     text,  terminals  and  pager programs must support ECMA‐48 OSC 8 escape se‐
     quences (see _g_r_o_t_t_y(1)).  When device support is  unavailable  or  disabled
     with  the UU register (see section “Options” below), _g_r_o_f_f _m_a_n renders these
     URIs between angle brackets (⟨⟨ ⟩⟩) after the linked text.

     MMTT, MMEE, UURR, and UUEE are GNU extensions supported by Heirloom Doctools  _t_r_o_f_f
     (since  Git  snapshot  151218)  and _m_a_n_d_o_c (UURR/UUEE since 1.12.3; MMTT/MMEE since
     1.14.2) but not by DWB, Plan 9 (original), or Solaris _t_r_o_f_fs.  Plan 9  from
     User Space’s _t_r_o_f_f implements MMRR.

     Prepare arguments to MMRR, MMTT, and UURR for typesetting; they can appear in the
     output.   Use  special  character  escape sequences to encode Unicode basic
     Latin characters where necessary, particularly the hyphen‐minus.  (See sub‐
     section “Portability” below.)  URIs can be lengthy; rendering them can  re‐
     sult  in jarring adjustment or variations in line length, or _t_r_o_f_f warnings
     when one is longer than an output line.  The  application  of  non‐printing
     break  point  escape 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
     output line, and the latter helps the reader to avoid mistakenly interpret‐
     ing  a  dot at the end of a line as a period (or multiple dots as an ellip‐
     sis).  Thus,
            .UR http://\:example\:.com/\:fb8afcfbaebc74e\:.cc
     has several potential break points in the URI shown.  Consider adding break
     points before or after at signs in email addresses, and question marks, am‐
     persands, and number signs in HTTP(S) URIs.

     ..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 _m_a_n_u_a_l_‐_s_e_c_t_i_o_n is absent, the package omits the sur‐
            rounding parentheses.  If _t_r_a_i_l_i_n_g_‐_t_e_x_t (typically  punctuation)  is
            specified,  it  follows  the closing parenthesis without intervening
            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.  If _m_a_n_u_a_l_‐_s_e_c_‐
            _t_i_o_n is present, 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 intervening 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,  except
            when _a_d_d_r_e_s_s appears as a TTPP paragraph tag.

            When rendered by _g_r_o_f_f to a PostScript device,

                   Contact
                   .MT fred\:.foonly@\:fubar\:.net
                   Fred Foonly
                   .ME
                   for more information.

            formats as “Contact Fred Foonly ⟨fred.foonly@fubar.net⟩ for more in‐
            formation.”.

     ..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 enabled 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, except when _u_r_i appears as a TTPP paragraph tag.

            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 .

            formats as “The GNU Project of the Free  Software  Foundation  hosts
            the _g_r_o_f_f home page ⟨https://www.gnu.org/software/groff/⟩.”.

     If  a  UURR/UUEE  or MMTT/MMEE pair occurs in a TTPP tag and hyperlinking is unavail‐
     able, _g_r_o_f_f _m_a_n sets the link target at the beginning of the indented para‐
     graph, not as part of the tag, unless there is no link text.

   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  may  instead  render  under‐
     scored  on  terminals.   SSMM sets text at a smaller type size, which differs
     visually from regular‐sized text only on typesetters.  The macros  BBII,  BBRR,
     IIBB,  IIRR,  RRBB,  and RRII set their odd‐ and even‐numbered arguments as text in
     the alternating styles their names indicate, with no space separating them.

     Because font styles are presentational rather  than  semantic,  conflicting
     traditions  have  arisen regarding which font styles should be used to mark
     file or path names, environment variables, and inlined literals.

     The default type size and family for typesetters is 10‐point Times,  except
     on  the  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.  Given no argument,  BB  plants  a  one‐line  input
            trap;  text  on the next line, which can be further formatted with a
            macro, is set in bold.

            Use bold for literal portions of syntax synopses,  for  command‐line
            options  in  running text, and for literals that are major topics of
            the subject under discussion; for example, this page uses  bold  for
            macro,  string, and register names.  In an EEXX/EEEE example of interac‐
            tive 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.  Given no argument, II  plants
            a  one‐line  input trap; text on the next line, which can be further
            formatted with a macro, is set in an italic or oblique face.

            Use italics for file and path names, for environment variables,  for
            C  data  types,  for enumeration or preprocessor constants in C, for
            variant (user‐replaceable) portions  of  syntax  synopses,  for  the
            first occurrence (only) of a technical concept being introduced, for
            names  of journals and of literary works longer than an article, and
            anywhere a parameter requiring replacement by the  user  is  encoun‐
            tered.   An  exception  involves  variant  text in a context already
            typeset in italics, such as file or path names with replaceable com‐
            ponents; in such cases, follow the convention of mathematical typog‐
            raphy: set the file or path name in italics as usual but  use  roman
            for  the  variant  part  (see IIRR and RRII below), and italics again in
            running roman text when referring to the variant material.

     ..SSMM [_t_e_x_t]
            Set _t_e_x_t one point smaller than the default type  size  on  typeset‐
            ters.   Given  no argument, SSMM plants a one‐line input trap; text on
            the next line, which can be further formatted with a macro,  is  set
            smaller.

            _N_o_t_e_:  terminals  render  _t_e_x_t  at normal size instead.  Do not rely
            upon SSMM to communicate semantic information distinct from using  ro‐
            man  style  at normal size; it is hidden from readers using such de‐
            vices.

     Observe what is _n_o_t prescribed for setting in bold or italics  above:  ele‐
     ments  of “synopsis language” such as ellipses and brackets around options;
     proper names and adjectives; titles of anything other than major  works  of
     literature;  identifiers  for standards documents or technical reports such
     as CSTR #54, RFC 1918, Unicode 16, or POSIX.1‐2024;  acronyms;  and  occur‐
     rences after the first of a technical term.

     Use italics for emphasis rarely, and bold almost never.  Brief specimens of
     literal text, such as article titles, inline examples, mentions of individ‐
     ual  characters  or  short strings, and (sub)section headings in man pages,
     are suitable for quotation; see the \\[[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.  They ap‐
     ply italic corrections as appropriate.  If a space is  required  within  an
     argument,  first consider whether the same result could be achieved with as
     much clarity by using single‐style macros on separate input lines.  When it
     cannot, double‐quote an  argument  containing  embedded  space  characters.
     Setting all three different styles within a word presents challenges; it is
     possible with the \\cc and/or \\ff escape sequences.  See subsection “Portabil‐
     ity” 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.

                   Set an ellipsis on the math axis with the GNU extension macro
                   .BR cdots .

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

                   .I file
                   is
                   .RB \[lq] \- \[rq],
                   .I groff
                   reads the standard input stream.

     ..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  package sets all text inboard of the left edge of the output medium by
     the amount of the _p_a_g_e _o_f_f_s_e_t_; see register PPOO in section “Options”  below.
     Headers,  footers  (both set with TTHH), and section headings (SSHH) lie at the
     page offset.  _g_r_o_f_f _m_a_n indents subsection headings (SSSS) by the  amount  in
     the SSNN register.

     Ordinary  paragraphs  not  within  an  RRSS/RREE  inset region are inset by the
     amount stored in the BBPP register; see section “Options” below.  The IINN reg‐
     ister configures the default indentation amount used by RRSS (as  the  _i_n_s_e_t_‐
     _a_m_o_u_n_t),  IIPP,  TTPP,  and  HHPP; an overriding argument is a number plus an op‐
     tional scaling unit.  If no scaling unit is given, the _m_a_n package  assumes
     “n”;  that  is,  roughly the width of a letter “n” in the font current when
     the macro is called——see section “Measurements” in _g_r_o_f_f(7).   An  indenta‐
     tion  specified  in  a  call to IIPP, TTPP, or 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 inset amount and indentation are related but distinct  parameters  with
     the  same  defaults.  The former is manipulated by RRSS and RREE (and by SSHH and
     SSSS, which reset it to the default).  Indentation is controlled by the para‐
     graphing macros (though, again, SSHH and SSSS reset it); it is imposed  by  the
     TTPP,  IIPP,  and 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 with RRSS and started another or‐
            dinary paragraph with PP.  We observe that all of its lines are inset
            and indented the same; contrast with a first‐line indentation.

            ttaagg    This  tagged  paragraph,  set with TTPP, is still within the RRSS
                   region, but lines after the first have a supplementary inden‐
                   tation that the tag lacks.

                   A paragraph like this one, set with IIPP, appears 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.   Both the inset amount (RRSS) and indentation (IIPP)
                   affect this paragraph.
                   ┌───────────────────────────────────┐
                   │ This table is affected both by    │
                   │ the inset amount and indentation. │
                   └───────────────────────────────────┘

            •      This indented paragraph is marked with a bullet,  contrasting
                   the inset amount and the indentation; only the former affects
                   the mark, but both affect the text of the paragraph.

            This  ordinary  (PP)  paragraph resets the indentation, but the inset
            amount is unchanged.
            ┌─────────────────────────────┐
            │ This table is affected only │
            │ by the inset amount.        │
            └─────────────────────────────┘

     Finally, we have ended the relative inset by using RREE,  which  (because  we
     used  only  one  RRSS/RREE  pair)  has restored the inset amount to its initial
     value.  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 HHPP; the result
     may not be comprehensible on an output device you fail to check,  or  which
     is  developed  in  the  future.  Consider the table preprocessor _t_b_l(1) in‐
     stead.

     Several macros insert vertical space: SSHH, SSSS, TTPP, PP (and its synonyms), IIPP,
     and HHPP.  They then enable _n_o_‐_s_p_a_c_e _m_o_d_e_; see _g_r_o_f_f(7).  The default  inter‐
     section  and inter‐paragraph spacing is 1v for terminals and 0.4v for type‐
     setters.  “v” is a unit of vertical distance, where 1v is the distance  be‐
     tween  adjacent  text  baselines.  (The deprecated macro PPDD can change this
     vertical spacing, but we discourage its use.)  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 sec‐
     tion “Files” below.

   SSttrriinnggss
     The following strings are defined for use in man pages.  _g_r_o_f_f _m_a_n supports
     others for configuration of rendering parameters; see section “Options” be‐
     low.

     \\**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 docu‐
             ment 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.

     A contemporary man page needs none of the above.  \\**SS is superfluous;  type
     size  changes are invisible on terminals, and macros that change it restore
     its original value afterward.  Better alternatives exist for the rest; sim‐
     ply use the \\[[rrgg]], \\[[llqq]], \\[[rrqq]], and \\[[ttmm]]  special  character  escape  se‐
     quences directly.  Unless you are aiming for a pathological level of porta‐
     bility——perhaps composing a man page for consumption on simulators of 1980s
     Unix  systems (or Solaris _t_r_o_f_f, though even it supports “\\((rrgg”)——avoid us‐
     ing the above strings.

   UUssee ooff eexxtteennssiioonnss
     To ensure that your man page formats reliably on a wide variety of viewers,
     write it solely with the macros described in this page (except for the ones
     identified as deprecated, which you should avoid).  Macros described as ex‐
     tensions might be unsupported by a formatter that is important to your  au‐
     dience.   Nevertheless, _g_r_o_f_f’s extensions are present because they perform
     tasks that are otherwise difficult or tedious to achieve portably.  If  you
     require  an  extension  but expect your man page to be rendered on a system
     that doesn’t support it, write a configuration test to measure  a  property
     of  the system, and use _m_4(1), _s_e_d(1), or a similar tool to generate a _._m_a_n
     file from a _._m_a_n_._i_n file, defining page‐local versions of extension  macros
     only where necessary.  You can copy extension macro definitions from _g_r_o_f_f;
     see _a_n_-_e_x_t_._t_m_a_c in section “Files” below.

     For example, we might put a line
            @DEFINE_MR@
     in our _m_a_n document at the end of the “Name” section, test a system for the
     availability  of  the  _g_r_o_f_f  _m_a_n MMRR macro, remove the line if the macro is
     present, and “inline” a definition otherwise, as follows.  (This version is
     slightly simplified and does not attempt to disable hyphenation  when  set‐
     ting arguments to MMRR.)
            have_MR=$(echo .pm | troff -man 2>&1 | grep 'MR[[:space:]]')
            if [ -n "$have_MR" ]
            then
              sed '/@DEFINE_MR@/d' myprog.man.in > myprog.man
            else
              sed 's/@DEFINE_MR@/.de MR\
            .  ie \\\\n(.$=1 .I \\\\$1\
            .  el .IR \\\\$1 (\\\\$2)\\\\$3\
            ../' myprog.man.in > myprog.man
            fi
     (The  profusion  of backslashes is due to its status as an escape character
     in both _r_o_f_f and _s_e_d.)

     If the foregoing method is too much trouble, you could  apply  the  radical
     technique  of reading your man page using every formatter of interest, con‐
     firming satisfactory output from each.  Test  documentation  for  syntactic
     validity and semantic correctness, just as you would test code.

   PPoorrttaabbiilliittyy
     GNU  _t_r_o_f_f expects its input to contain Unicode basic Latin code points ex‐
     clusively.  One can _m_a_i_n_t_a_i_n  it  in  a  more  convenient  encoding,  using
     _p_r_e_c_o_n_v(1), as with _g_r_o_f_f(1)’s --kk option, to generate a basic Latin version
     that employs special character escape sequences to access other glyphs.

     AT&T  _t_r_o_f_f’s  _m_a_n  package and those of many of its descendants format man
     pages using a line length of 65 ens (character cells) on terminals, whereas
     _g_r_o_f_f _m_a_n uses 80 ens (and _m_a_n_d_o_c(1) 78).  Readers with low vision may also
     benefit from the narrower line length.  Inspect your documents with  “nnrrooffff
     --tt --rr LLLL==6655nn --mmaann” to ensure that their output lines don’t overrun.

     In  _r_o_f_f  systems, elemental functions called _r_e_q_u_e_s_t_s and _e_s_c_a_p_e _s_e_q_u_e_n_c_e_s
     control formatting operations.  A request appears on a  control  line.   An
     escape sequence starts with a backslash (\\) and can appear almost anywhere.
     However, use of _r_o_f_f requests (apart from the empty request “..”) risks poor
     rendering  when  a page is processed by non‐_r_o_f_f formatters that attempt to
     interpret page sources.  (Historically, this  was  commonly  attempted  for
     HTML  conversion.)   Many  of  these programs don’t interpret the full _r_o_f_f
     language (let alone extensions): they may be incapable of handling  numeric
     expressions,  control  structures,  or  register, string, and macro defini‐
     tions, causing a document’s contents to be  presented  incomprehensibly  or
     omitted  entirely.  If your document uses formatter requests, or escape se‐
     quences not shown below, it accepts responsibility for restoring  formatter
     state to what the _m_a_n macro package expects.

     Do  not  put  blank  (empty) lines in a man page source document.  They can
     produce excessive space in the output, or  less  than  is  attempted;  some
     _m_a_n(1) programs “squeeze” multiple blank output lines into one.

     The  wise _m_a_n author quotes 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.  This restriction also applied to the
     BB, II, SSMM, and font style alternation macros.

     Exercise restraint with escape sequences as with requests.  Some escape se‐
     quences  are however required for correct typesetting even in man pages and
     usually do not cause portability problems.  Several of these render  glyphs
     corresponding  to  punctuation code points in the Unicode basic Latin range
     (U+0020–U+007F) that are handled specially in _r_o_f_f input;  the  escape  se‐
     quences below must be used to render them correctly and portably when docu‐
     menting material that uses them as literals——namely, any of the set '' -- \\ ^^
     ``  ~~  (apostrophe,  dash  or  hyphen‐minus, backslash, caret, grave accent,
     tilde).

     \\""        Comment.  The formatter ignores everything after the double quote
               to the end of the input line.  Place  whole‐line  comments  on  a
               control line immediately after the empty request (“..”).

     \\_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.   Splitting  excessively
               long input lines can ease document maintenance.

     \\%%        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.  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.

               \\:: is a GNU extension also supported by Heirloom  Doctools  _t_r_o_f_f
               050915 (September 2005), _m_a_n_d_o_c 1.13.1 (2014‐08‐10), and _n_e_a_t_r_o_f_f
               (commit 399a4936, 2014‐02‐17), but not by DWB, Plan 9, or Solaris
               _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.

               \\~~  is  a GNU extension also supported by Heirloom Doctools _t_r_o_f_f
               050915 (September 2005),  _m_a_n_d_o_c  1.9.14  (2009‐11‐16),  _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  DWB  or  Solaris
               _t_r_o_f_fs.

     \\&&        Dummy  character.   Prefix an input line with it 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 typesetters.

     \\cc        End a text line without inserting space or  attempting  a  break.
               Nothing  on  the input line after this escape sequence is format‐
               ted.  \\cc is useful when three font styles are needed in a  single
               word, as in a command synopsis.

                      .RB [ \-\-stylesheet=\c
                      .IR name ]

               \\cc  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

               Normally, if filling is enabled, the formatter treats the end  of
               a  text  line like a space.  It checks for the end of a sentence,
               and _m_a_y break the output line (if not, it inserts  an  adjustable
               space).   If  filling  is  disabled, the formatter _w_i_l_l break the
               output line, as in EEXX/EEEE examples.  The formatter interprets  the
               next  input  line  as usual, recognizing control lines, including
               macro calls (contrast with \\_n_e_w_l_i_n_e).

               The \\ff font selection escape sequence is an  alternative  to  \\cc;
               see below.  Using \\cc to continue a TTPP paragraph tag across multi‐
               ple  input  lines  renders  incorrectly with _g_r_o_f_f 1.22.3, _m_a_n_d_o_c
               1.14.1, older versions of these programs, and perhaps  with  some
               other formatters.

     \\ee        Format  the  _r_o_f_f  escape character on the output; widely used in
               man pages to render a backslash glyph.  It works reliably as long
               as the “ec” request is not used, which should never happen in man
               pages, and it is slightly more portable than  the  more  explicit
               \\[[rrss]] (“reverse solidus”) special character escape sequence.

     \\ffBB, \\ffII, \\ffRR, \\ffPP
               Switch to bold, italic, roman, or back to the previous style, re‐
               spectively.   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, paragraph,
               example, 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 be‐
     low,  but  its descendants, like DWB, 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).  _g_r_o_f_f’s ex‐
     tended notation  for  special  characters,  \\[[_x_x]],  is  also  supported  by
     _m_a_n_d_o_c(1),  Heirloom  Doctools _t_r_o_f_f, and _n_e_a_t_r_o_f_f, but not DWB, Plan 9, or
     Solaris _t_r_o_f_fs.

     \\--     Minus sign.  \\-- produces the basic Latin hyphen‐minus (U+002D) spec‐
            ifying Unix command‐line options and frequently used in file  names.
            “--”  is  a  hyphen  in _r_o_f_f; some output devices format it as U+2010
            (hyphen).

     \\[[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).  Employ it in macro calls
            to work around interpretation of ‘""’ as an argument delimiter.

                   .TP
                   .BI "split \[dq]" text \[dq]

     \\[[llqq]]
     \\[[rrqq]]  Left  and right double quotation marks.  Use these for paired direc‐
            tional double quotes, “like this”.

     \\[[eemm]]  Em dash.  Use for an interruption——such as this one——in a sentence.

     \\[[eenn]]  En dash.  Use to separate the ends of a range, as  between  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  format
            “^^” as U+02C6 (modifier letter circumflex accent).

     \\[[rrss]]  Reverse  solidus  (backslash).   The backslash is the default escape
            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).

     For maximum portability, avoid escape sequences (including special  charac‐
     ters) not listed above.

   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  ad‐
     ministrator  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  footers.   Be‐
     cause  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 typically consist of  “sp”  and
     “tl”  requests.   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 discouraged.

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

            The inside footer is populated per the value of _s_y_s_t_e_m_.

                   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  trans‐
            lates poorly to HTML, under which exact space control and tabulation
            are  not  readily available.  Thus, information or distinctions that
            you use tab stops to express are likely to be  lost.   If  you  feel
            tempted  to  change the tab stops such that calling this macro later
            to restore them is  desirable,  consider  composing  a  table  using
            _t_b_l(1) instead.

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

            Use of this quasi‐semantic macro, an extension whose name originated
            in DWB _t_r_o_f_f, is deprecated; _g_r_o_f_f’s interface differs.  Neither can
            easily  be  used to annotate options that take optional arguments or
            options whose arguments have internal structure (such as  a  mixture
            of  literal  and  variable components).  One could work around these
            limitations with font selection escape sequences, but font style al‐
            ternation macros are preferable; they are more flexible and  perform
            italic corrections on typesetters.

     ..PPDD [_v_e_r_t_i_c_a_l_‐_s_p_a_c_e]
            Configure  the  amount  of  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, in‐
            ter‐paragraph spacing resets to its default  value;  see  subsection
            “Horizontal and vertical spacing” above.

            Use  of  this  presentation‐oriented macro is deprecated.  It trans‐
            lates poorly to HTML, under which exact control  of  inter‐paragraph
            spacing is not readily available.  Thus, information or distinctions
            that you use PPDD to express are likely to be lost.

     ..SSBB [_t_e_x_t]
            Set _t_e_x_t in bold and (on typesetters) one point smaller than the de‐
            fault  type  size.   Given  no  argument, SSBB plants a one‐line input
            trap; text on the next line, which can be further formatted  with  a
            macro,  is set smaller and in bold.  Use of this macro, an extension
            originating in SunOS 4.0 _t_r_o_f_f, is deprecated.  SSMM without an  argu‐
            ment,  followed  immediately  by  “BB _t_e_x_t”, produces the same output
            more portably.  The macros’ order is interchangeable; put _t_e_x_t  with
            the latter.

            _N_o_t_e_:  terminals render _t_e_x_t in bold at the normal size instead.  Do
            not rely upon SSBB to communicate semantic information  distinct  from
            using  bold  style  at  normal size; it is hidden from readers using
            such devices.

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

            The inside footer is populated per the value of _v_e_r_s_i_o_n_.

                   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 Volume 1 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 supplied by the system.
     The package supported the macros listed in this page not described  as  ex‐
     tensions,  except  PP and the deprecated AATT and UUCC.  It documented no regis‐
     ters and defined only RR and SS strings.

     UUCC appeared in 3BSD (1980).  Unix System III (1980) introduced  PP  and  ex‐
     posed  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 Unix (1986) introduced EEXX  and
     EEEE.   SunOS  4.0 (1988) added SSBB.  Unix System V (1988) incorporated the llqq
     and rrqq strings.

     Except for EEXX/EEEE, James Clark implemented the foregoing features  in  early
     versions  of  _g_r_o_f_f_.  Later, _g_r_o_f_f 1.20 (2009) resurrected EEXX/EEEE and origi‐
     nated SSYY/YYSS, TTQQ, MMTT/MMEE, and UURR/UUEE.  Plan 9 from User Space’s  _t_r_o_f_f  intro‐
     duced MMRR in 2020, and incorporated the llqq and rrqq strings in 2025.

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  consis‐
     tent  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  align‐
              ment  (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.

     --rrBBPP==_b_a_s_e_‐_p_a_r_a_g_r_a_p_h_‐_i_n_s_e_t
              Set the inset amount for ordinary paragraphs not within  an  RRSS/RREE
              inset.  The default is 5n.

     --rrccRR==11   Enable  continuous  rendering.   Output is not paginated; instead,
              one (potentially very long) page is produced.  This is the default
              for terminal and HTML devices.  Use --rrccRR==00 to disable it on termi‐
              nals; 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.

     --rrCCHHEECCKKSSTTYYLLEE==_n
              Report problems with usage of this macro package exhibited by  the
              input  at  verbosity  level  _n, where _n is an integer in the range
              0–3, inclusive; 00 disables the messages and is the default.   This
              feature  is a development and debugging aid for man page maintain‐
              ers; the problems diagnosed, and range and meanings  of  the  sup‐
              ported levels, are subject to change.

     --rrCCSS==11   Set  section  headings  (the  argument(s) to SSHH) in full capitals.
              This transformation is off by default because it discards  letter‐
              case distinctions.

     --rrCCTT==11   Set  the  man  page  identifier (the first argument to TTHH) in full
              capitals in headers and footers.  This transformation  is  off  by
              default because it discards lettercase distinctions.

     --rrDD11     Enable  double‐sided  layout,  formatting footers for even and odd
              pages differently; see the description of TTHH in subsection  “Docu‐
              ment 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 - 1v”.

     --ddHHFF==_h_e_a_d_i_n_g_‐_f_o_n_t
              Select the font used for section and subsection headings; the  de‐
              fault  is “BB” (bold style of the default family).  Any valid argu‐
              ment 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 section
              “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 default indentation amount used by IIPP, TTPP, and HHPP, and the
              inset amount used by RRSS.  The default is 7n on terminals and  7.2n
              on  typesetters.  Use only integer multiples of unit “n” on termi‐
              nals for consistent indentation.

     --rrLLLL==_l_i_n_e_‐_l_e_n_g_t_h
              Set line length; the default is 80n on terminals and 6.5i on type‐
              setters.

     --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
              Select the font used for man page identifiers in TTHH calls and top‐
              ics named in MMRR calls; the default is “II” (italic style of the de‐
              fault family).  Any valid argument to _g_r_o_f_f’s “ft” request may  be
              used.   If the MMFF string ends in “I”, the package assumes it to be
              an oblique typeface, and applies italic corrections before and af‐
              ter man page topics and identifiers.

     --rrPP_n     Start enumeration of pages at _n.  The default is 1.

     --rrPPOO==_p_a_g_e_‐_o_f_f_s_e_t
              Set page offset; the default is 0 on terminals and 1i on  typeset‐
              ters.

     --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_.
              The default is 3n.

     --rrTTSS==_s_e_p_a_r_a_t_i_o_n
              Require the given _s_e_p_a_r_a_t_i_o_n between a TTPP paragraph’s tag and  its
              body.  The default is 2n.

     --rrUU00     Disable  generation of URI hyperlinks in output drivers capable of
              them, making the arguments to MMTT and UURR calls visible as formatted
              text.  _g_r_o_h_t_m_l(1), _g_r_o_p_d_f(1), and _g_r_o_t_t_y(1) enable  hyperlinks  by
              default (the last only if not in its legacy output mode).

     --rrXX_p     Number successors of page _p as _pa, _pb, _pc, and so forth.  The reg‐
              ister  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_4_._1_/_t_m_a_c_/_a_n_._t_m_a_c
            Most _m_a_n macros are defined in this file.  It also loads  extensions
            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_4_._1_/_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 pack‐
            age  is  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 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  reloads  each  macro package as necessary.
            Page‐local redefinitions of names used by the _m_a_n or  _m_d_o_c  packages
            prior  to  TTHH  or DDdd calls are “clobbered” by the reloading process.
            If you want to provide your own definition of an extension macro  to
            ensure its availability, the _a_n_-_e_x_t_._t_m_a_c entry below offers advice.

     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_t_m_a_c_/_a_n_-_e_x_t_._t_m_a_c
            Definitions  of macros described above as extensions (and not depre‐
            cated) are contained in this file; in some cases, they  are  simpler
            versions of definitions appearing in _a_n_._t_m_a_c, and are ignored 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 copylefted.  To reduce the risk
            of  name space collisions, string and register names begin only with
            “mm”.  We encourage man page authors who are concerned  about  porta‐
            bility  to  legacy Unix systems to copy these definitions into their
            pages, and maintainers of _t_r_o_f_f implementations or  work‐alike  sys‐
            tems  that format man pages to re‐use them.  To ensure reliable ren‐
            dering, define them after your page calls TTHH; see the discussion  of
            _a_n_d_o_c_._t_m_a_c  above.   Further,  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(8)  or _m_a_n_d_b(8) implementations that easily give up scan‐
            ning for indexing material.

     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_t_m_a_c_/_m_a_n_._t_m_a_c
            is a wrapper enabling the package to be loaded with the  option  “--mm
            mmaann”.

     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_t_m_a_c_/_m_a_n_d_o_c_._t_m_a_c
            is  a  wrapper  enabling _a_n_d_o_c_._t_m_a_c to be loaded with the option “--mm
            mmaannddoocc”.

     _/_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.

                   .\" Put only one space after the end of a sentence.
                   .ss 12 0 \" See groff(7).
                   .\" Keep pages narrow even on wide terminals.
                   .if n .if \n[LL]>80n .nr LL 80n

            On multi‐user systems, it is more considerate to users whose prefer‐
            ences may differ from the administrator’s to be less aggressive with
            such settings, or to permit  their  override  with  a  user‐specific
            _m_a_n_._l_o_c_a_l file.  Place the requests below at the end of the site‐lo‐
            cal file to manifest courtesy.
                   .soquiet \V[XDG_CONFIG_HOME]/man.local
                   .soquiet \V[HOME]/.man.local
            However,  a security‐sandboxed _m_a_n(1) program may lack permission to
            open such files.

NNootteess
     Some tips on composing and troubleshooting your man pages follow.

     • What’s the difference between a man page topic and identifier?

       A single man page may document several related but distinct topics.   For
       example,  _p_r_i_n_t_f(3)  and  _f_p_r_i_n_t_f(3) are often presented together.  More‐
       over, multiple programming languages have functions named  “printf”,  and
       may  document  these  in a man page.  The identifier is intended to (with
       the section) uniquely identify a page on the system; it  may  furthermore
       correspond closely to the file name of the document.

       The  _m_a_n(1)  librarian  makes access to man pages convenient by resolving
       topics to man page identifiers.  Thus, you can type  “mmaann  ffpprriinnttff”,  and
       other  pages can refer to it, without knowing whether the installed docu‐
       ment uses “printf”, “fprintf”, or even “c_printf” as its identifier.

     • Some ASCII characters look funny or copy and paste wrong.

       On devices with large glyph repertoires, like UTF‐8‐capable terminals and
       PDF, GNU _t_r_o_f_f, like AT&T _t_r_o_f_f before it, maps several keycaps  to  code
       points  outside  the Unicode basic Latin range (historically “ASCII”) be‐
       cause that usually results in better  typography  in  the  general  case.
       When  documenting  GNU/Linux  command or C language syntax, however, this
       translation is sometimes not desirable.

       TToo ggeett aa ““lliitteerraall””......   ......sshhoouulldd bbee iinnppuutt..
       ────────────────────────────────────────────
                           '   \[aq]
                           -   \-
                           \   \[rs]
                           ^   \[ha]
                           `   \[ga]
                           ~   \[ti]
       ────────────────────────────────────────────

       If a neutral double quote (") is needed in a macro argument, you can  use
       \\[[ddqq]]  to  get  it.   Do  _n_o_t use \\[[aaqq]] for an ordinary apostrophe (as in
       “can’t”) or \\-- for an ordinary hyphen (as in “word‐aligned”).

     • Do I ever need to use an empty macro argument ("")?

       Probably not.  When this seems necessary, often a shorter or clearer  al‐
       ternative is available.

              IInnsstteeaadd ooff......               ......sshhoouulldd bbee ccoonnssiiddeerreedd..
       ────────────────────────────────────────────────────────────────
       .TP ""                         .TP
       ────────────────────────────────────────────────────────────────
       .BI "" _i_t_a_l_i_c_‐_t_e_x_t _b_o_l_d_‐_t_e_x_t   .IB _i_t_a_l_i_c_‐_t_e_x_t _b_o_l_d_‐_t_e_x_t
       ────────────────────────────────────────────────────────────────
       .TH foo 1 "" "foo 1.2.3"       .TH foo 1 _y_y_y_y‐_m_m‐_d_d "foo 1.2.3"
       ────────────────────────────────────────────────────────────────
       .IP "" 4n                      .IP
       ────────────────────────────────────────────────────────────────
       .IP "" 4n                      .RS 4n
       _p_a_r_a_g_r_a_p_h                      .P
       ...                            _p_a_r_a_g_r_a_p_h
       ...                            .RE
       ────────────────────────────────────────────────────────────────
       .B one two "" three            .B one two three

       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 keeps both up to date.

       IIPP is sometimes ill‐understood and misused, especially when no mark argu‐
       ment is supplied——an indentation argument is not required.  By setting an
       explicit indentation, you may be overriding the  reader’s  preference  as
       set  with  the --rrIINN option.  If your page renders adequately without one,
       use the simpler form.  If you need to indent  multiple  (unmarked)  para‐
       graphs, consider setting an inset region with RRSS and RREE instead.

       In  the last example, the empty argument does have a subtly different ef‐
       fect than its suggested replacement: the empty argument causes  an  addi‐
       tional space character to be interpolated between the arguments “two” and
       “three”——but  it  is  a regular breaking space, so it can be discarded at
       the end of an output line.  It is better not to be  subtle,  particularly
       with space, which can be overlooked in source and rendered forms.

     • RRSS doesn’t indent relative to my indented paragraph.

       The  RRSS macro determines the _i_n_s_e_t _a_m_o_u_n_t_, the position at which an _o_r_d_i_‐
       _n_a_r_y paragraph (PP and its synonyms) is set; the value of the IINN  register
       determines its default amount.  This register also determines the default
       indentation  used  by  IIPP, TTPP, and HHPP.  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 ordinary (PP)
       paragraph.

       Another approach to tagged paragraphs places an RRSS call immediately after
       the tag; this also forces a break regardless of the  tag’s  width,  which
       some  authors prefer.  Follow‐up paragraphs under the tag can then be set
       with PP instead of IIPP.  Remember to use RREE to end the indented region  be‐
       fore  starting  the  next  tagged  paragraph  (at the appropriate nesting
       level).

     • RREE doesn’t move the inset back to the expected level.

       RREE takes an inset  _l_e_v_e_l  as  an  argument,  unlike  RRSS’s  inset  _a_m_o_u_n_t_.
       “..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  desire
       symmetry in your macro calls, simply issue one RREE without an argument for
       each RRSS that precedes it.

       The  SSHH  and SSSS sectioning macros clear relative insets; RREE calls 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  “Horizontal  and
       vertical spacing” above.

         IInnsstteeaadd ooff......     ......sshhoouulldd bbee ccoonnssiiddeerreedd..
       ─────────────────────────────────────────────
       .IP \[bu] 4n        .IP \[bu] 4n
       _p_a_r_a_g_r_a_p_h           _p_a_r_a_g_r_a_p_h
       .IP \[bu] 4n        .IP \[bu]
       _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 “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,  how‐
       ever,  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 hypothetical string EELL that con‐
       tained an ellipsis, but not the trailing dummy character \\&&,  would  then
       need to be suffixed with the latter when not ending a sentence.

           IInnsstteeaadd ooff......              ......ddoo tthhiiss..
       ──────────────────────────────────────────────────
       .ds EL \&.\|.\|.         Arguments are
       Arguments are            .IR src‐file\~ .\|.\|.\&
       .IR src‐file\~ \*(EL\&   .IR dest‐dir .
       .IR dest‐dir .
       ──────────────────────────────────────────────────

       The first column practices a false economy; the savings in typing is off‐
       set  by the cost of obscuring even the suggestion of an ellipsis to a ca‐
       sual reader of the source document, and reduced portability  to  non‐_r_o_f_f
       man page formatters that cannot handle string definitions.

       Unicode  defines  an ellipsis code point, and some fonts have an ellipsis
       glyph, which some man pages have accessed non‐portably with the  font‐de‐
       pendent  \\NN escape sequence.  We discourage their use; on terminals, they
       may crowd the dots into a half‐width character cell, and do not render at
       all if the output device lacks the glyph.  In synopses, missing  ellipses
       can mislead the reader.  Dots and space are universally supported.

     • When and how should I use quotation marks?

       As  noted  above in subsection “Font style macros”, apply quotation marks
       to “brief specimens of literal text, such as article titles, inline exam‐
       ples, mentions of individual characters or short strings,  and  (sub)sec‐
       tion  headings in man pages”.  Multi‐word literals, such as Unix commands
       with arguments, when set inline (as opposed to displayed between  EEXX  and
       EEEE),  should  be  quoted to ensure that the boundaries of the literal are
       clear even when the material is stripped of font styling by, for example,
       copy‐and‐paste operations.  _g_r_o_f_f, Heirloom Doctools _t_r_o_f_f, _n_e_a_t_r_o_f_f, and
       _m_a_n_d_o_c support all of the special characters \\[[ooqq]], \\[[ccqq]], \\[[llqq]],  \\[[rrqq]],
       \\[[aaqq]],  and  \\[[ddqq]]  described  in  subsection  “Portability” above.  DWB,
       Plan 9, and Solaris _t_r_o_f_fs do not.  Interpolating the strings  \\**((llqq  and
       \\**((rrqq  portably  yields directional double quotation marks, if available,
       in all these formatters (though _n_e_a_t_r_o_f_f does  not  supply  a  _m_a_n  macro
       package), but they cannot reliably be used in macro arguments.

       Obtaining  directional  single  quotation  marks  is more of a challenge.
       Historically, man pages used `` and '',, which _t_r_o_f_f rendered on typesetters
       as ‘ and ’, exclusively for them.  However, in recent  years,  some  dis‐
       tributors  of _g_r_o_f_f have chosen to override the meanings of these charac‐
       ters in man pages, remapping them  to  their  Unicode  Basic  Latin  code
       points.   Unfortunately, `` and '' are the _o_n_l_y reliable means of obtaining
       directional single quotation marks in AT&T _t_r_o_f_f; in that implementation,
       often no special character escape sequences exist to obtain  them.   Fur‐
       ther,  AT&T  _t_r_o_f_f’s  special character identifiers, like its font names,
       were device‐specific.  To achieve quotation portably in  man  pages  ren‐
       dered  both by AT&T and more modern _t_r_o_f_fs, consider adding a preamble to
       your page after the TTHH call as follows.

              .ie \n(.g \{\
              .  ds oq \[oq]\"
              .  ds cq \[cq]\"
              .\}
              .el \{\
              .  ds oq `\"
              .  ds cq '\"
              .\}

       You must then use the \\** escape sequence  to  interpolate  the  quotation
       mark strings.

              The command
              .RB \*(oq "while !\& git pull; do sleep 10; done" \*(cq
              retries an update from the repository until it succeeds.

       If  this  procedure  seems  complex,  petition your distributor to revert
       their remapping of the ` and ' characters.

     • Escape sequences of the form \\[[_x_x]] don’t format correctly.

       The \\[[_x_x]] special character escape sequence is a GNU _t_r_o_f_f extension also
       supported by _m_a_n_d_o_c_, Heirloom Doctools _t_r_o_f_f_, and _n_e_a_t_r_o_f_f_.  DWB, Plan 9,
       and Solaris _t_r_o_f_fs don’t implement it.  If your man page requires  porta‐
       bility  to  these  formatters,  spell such escape sequences as “\\((_x_x”; no
       closing  parenthesis  is  used.   _x_x  must  be  exactly  two  characters;
       _g_r_o_f_f___c_h_a_r(7) lists portable special character identifiers.

AAuutthhoorrss
     James  Clark wrote the initial GNU implementation of the _m_a_n macro package.
     Later, Werner Lemberg supplied the SS, LLTT, and  ccRR  registers,  the  last  a
     4.3BSD‐Reno  _m_d_o_c(7) feature.  Larry Kollar added the FFTT, HHYY, and SSNN regis‐
     ters; the HHFF string; and the PPTT and BBTT macros in _g_r_o_f_f 1.19  (2003).   Lem‐
     berg  and Eric S. Raymond contributed EEXX/EEEE, MMTT/MMEE, UURR/UUEE, TTQQ, and an early
     version of the SSYY/YYSS macros to _g_r_o_f_f 1.20 (2009).  G. Branden Robinson  im‐
     plemented  the AADD and MMFF strings; CCSS, CCTT, and UU registers; and the MMRR macro
     for _g_r_o_f_f 1.23 (2023), and the BBPP, PPOO, and TTSS registers and a  revised  im‐
     plementation of the SSYY/YYSS macros for _g_r_o_f_f 1.24 (2026).

     Susan  G.  Kleinmann wrote the initial version of this document for the De‐
     bian GNU/Linux system.  Lemberg imported it to _g_r_o_f_f_.  He and Robinson  re‐
     vised  and  updated  it.   Raymond  and  Robinson  documented the extension
     macros.  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 BSD’s alternative macro package 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)

groff 1.24.1                       2026‐04‐22                 _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
     ggrrooffff__mmddoocc —— 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  semantically‐ori‐
     ented  package  for writing Unix manual pages with _t_r_o_f_f(1).  Its predeces‐
     sor, 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 discretion has led to divergent styling prac‐
     tices 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 interpo‐
     late common noun phrases.  The _m_a_n_u_a_l _d_o_m_a_i_n offers semantic macros  corre‐
     sponding  to  the  terminology  used by practitioners in discussion of Unix
     commands, routines, and files.  Manual domain macros  distinguish  command‐
     line arguments and options, function names, function parameters, pathnames,
     variables,  cross references to other manual pages, and so on.  These terms
     are meaningful both to the author and the readers of a manual page.  It  is
     hoped  that the resulting increased consistency of the man page corpus will
     enable easier translation to future documentation tools.

     Throughout Unix documentation, a manual entry is referred to  simply  as  a
     “man page”, regardless of its length, without gendered implication, and ir‐
     respective of the macro package selected for its composition.

GGeettttiinngg ssttaarrtteedd
     The  _m_d_o_c  package attempts to simplify man page authorship and maintenance
     without requiring mastery of the _r_o_f_f  language.   This  document  presents
     only  essential  facts about _r_o_f_f_. For further background, including a dis‐
     cussion of basic typographical concepts  like  “breaking”,  “filling”,  and
     “adjustment”,  see  _r_o_f_f(7).   Specialized units of measurement 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 transforma‐
     tion of input on the left to rendered output on the  right.   Consider  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 document, 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 characters 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 immedi‐
     ately 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, precede it with the ‘\&’ escape sequence; this  is
     a dummy character, not formatted for output.  The backslash is the _r_o_f_f es‐
     cape  character;  it can appear anywhere and it always followed by at least
     one more character.  If followed by a newline, the  backslash  escapes  the
     input  line  break;  you  can  thus keep input lines to a reasonable length
     without affecting their interpretation.

     Macros in GNU _t_r_o_f_f accept an unlimited number of arguments;  other  _t_r_o_f_fs
     often  can’t  handle more than nine.  In some cases, arguments may continue
     or extend onto 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  argument
     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  defined  to  be
     callable)  will  be  called with the remaining arguments when it is encoun‐
     tered.  In such cases, the argument, although the name of a macro,  is  not
     preceded by a dot.  Macro calls can thus be nested.  This approach to macro
     argument  processing  is a unique characteristic of the _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, a macro that parses its argument  list  for  other  macro
     names  is  termed _p_a_r_s_e_d; macros that permit other macros to call them thus
     are described as _c_a_l_l_a_b_l_e.  This usage is a technical _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 arguments 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 argu‐
     ments 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 example, 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  stan‐
     dards mandate the inclusion of types _a_n_d identifiers in the parameter lists
     of  function  definitions,  each  ‘Fn’ parameter 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 character, and  will  not
     break  a  line there as it would a word space when the output line is full.
     This method is useful for macro arguments that are not expected to straddle
     an output line boundary, but has a drawback: this space does not adjust  as
     others  do when the output line is formatted.  An alternative is to use the
     unbreakable space escape sequence, ‘\~’, which cannot break  but  does  ad‐
     just.   This _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 aanndd ootthheerr ggllyypphhss
     When you need the _r_o_f_f escape character ‘\’ to appear in  the  output,  use
     ‘\e’ or ‘\[rs]’ instead.  Strictly, ‘\e’ formats the current escape charac‐
     ter;  it  works  reliably  as long as no _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 _s_p_e_c_i_a_l _c_h_a_r_a_c_‐
     _t_e_r escape sequence that explicitly formats the  “reverse  solidus”  (back‐
     slash) glyph.  In general, use special character escape sequences to format
     characters  outside the ISO 646 (“ASCII”) or Unicode Basic Latin range, and
     to format correct glyphs for the characters ‘"’, “'”, ‘-’,  ‘^’,  ‘`’,  and
     ‘~’.  _g_r_o_f_f___c_h_a_r(7) presents the formatter’s special character identifiers,
     annotating  those that are portable to legacy systems.  Section “Predefined
     strings” below lists characters commonly used by _m_d_o_c documents.

   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 re‐
     quests to space the source document for maintenance.

     Leading  spaces  cause  a break and are formatted.  Avoid this behaviour if
     possible.  Similarly, do not put more than one space between  words  in  an
     ordinary  text  line;  they are not “normalized” to a single space as other
     text formatters might do.

     Don’t try to use the neutral double quote character ‘"’ to represent itself
     in an argument.  Use the special character escape sequence ‘\[dq]’ to  for‐
     mat  it.   Avoid  using  ‘\[dq]’ for conventional quotation; see subsection
     “Enclosure and quoting macros” below.

     If your document must be portable to legacy systems  like  4.4BSD,  special
     character  escape  sequences  shown  here in the form \\[[_x_x] must be spelled
     \\((_x_x instead.  No version of _g_r_o_f_f or _m_a_n_d_o_c requires the latter form.

     As a typesetting system,  _r_o_f_f  distinguishes  hyphens,  minus  signs,  and
     dashes of various widths.  When inputting a hyphen or dash (“hyphen‐minus”)
     (Unicode U+002D) that should be usable in URLs or copy‐and‐paste operations
     to  shell  prompts  or  program  code, prefix it with the escape character:
     ‘\-’.

     The formatter attempts to detect the ends of sentences and by default  puts
     the equivalent of two spaces between sentences on the same output line; see
     _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 han‐
     dles punctuation characters specially in macro arguments.  This will be ex‐
     plained in section “General syntax” below.

     A comment in the source file of a man page can  begin  with  ‘.\"’  at  the
     start  of an input line, ‘\"’ after other input, or ‘\#’ anywhere (the last
     is a _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 identifier [section‐id [section‐keyword‐or‐title]]
           .Os [package‐or‐operating system [version‐or‐release]]
           .Sh Name
           .Nm topic
           .Nd summary‐description
           .\" The next heading is used in sections 2 and 3.
           .\" .Sh Library
           .\" The next heading is used in sections 1‐4, 6, 8, and 9.
           .Sh Synopsis
           .Sh Description
           .\" Uncomment and populate the following sections as needed.
           .\" .Sh "Implementation notes"
           .\" The next heading is used in sections 2, 3, and 9.
           .\" .Sh "Return values"
           .\" The next heading is used in sections 1, 3, 6, and 8.
           .\" .Sh Environment
           .\" .Sh Files
           .\" The next heading is used in sections 1, 6, and 8.
           .\" .Sh "Exit status"
           .\" .Sh Examples
           .\" The next heading is used in sections 1, 4, 6, 8, and 9.
           .\" .Sh Diagnostics
           .\" .Sh Compatibility
           .\" The next heading is used in sections 2, 3, 4, and 9.
           .\" .Sh Errors
           .\" .Sh "See also"
           .\" .Sh Standards
           .\" .Sh History
           .\" .Sh Authors
           .\" .Sh Caveats
           .\" .Sh Bugs

     The first items in the template are the commands .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  discussed  in
     section  “Page  structure  domain”,  which follows section “Manual domain”.
     Familiarize yourself with manual domain macros first; we use them to illus‐
     trate the use of page structure domain macros.

CCoonnvveennttiioonnss
     In the descriptions of macros below, square brackets surround optional  ar‐
     guments.   An ellipsis (‘...’) represents repetition of the preceding argu‐
     ment zero or more times.  Alternative values of a parameter  are  separated
     with  ‘|’.   If  a  mandatory parameter can take one of several alternative
     values, use braces to enclose the set, with spaces and ‘|’  separating  the
     items.
           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 opera‐
     tion modes, particularly if the list of valid optional arguments is  depen‐
     dent 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 newline 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 emitted for many com‐
     mands if the first argument is itself a macro, since it cancels the  effect
     of  the  preceding one.  On rare occasions, you might want to format a word
     along with surrounding brackets as a literal.
           ..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 measurements,
     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 des‐
     ignate  the  page  identifier and section of the manual, date of last revi‐
     sion, and the operating system or  software  project  associated  with  the
     page.   Call each once at the beginning of the document.  They populate the
     page headers and footers, “titles” in _r_o_f_f parlance.

     ..DDdd _d_a_t_e
             This first macro of any _m_d_o_c manual records the  last  modification
             date of the document source.  Arguments are catenated 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 English,  _d_a_y  an
             integer without a leading zero, and _y_e_a_r the four‐digit year.  This
             localism  is not enforced, however.  _g_r_o_f_f recommends ISO 8601 for‐
             mat, _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 _i_d_e_n_t_i_f_i_e_r [_s_e_c_t_i_o_n_‐_i_d [_s_e_c_t_i_o_n_‐_k_e_y_w_o_r_d_‐_o_r_‐_t_i_t_l_e]]
             _i_d_e_n_t_i_f_i_e_r and _s_e_c_t_i_o_n_‐_i_d together should uniquely indicate the man
             page  on  the  system.  A _s_e_c_t_i_o_n_‐_i_d that begins with an integer in
             the range 1–9 or is one of the words ‘unass’, ‘draft’,  or  ‘paper’
             selects  a  predefined  section  title.   This use of “section” has
             nothing to do with the section headings otherwise discussed in this
             page; it arises from the organizational scheme of printed and bound
             Unix manuals.

             In this implementation, the following titles are defined for  inte‐
             gral section numbers.

                   1   General Commands Manual
                   2   System Calls Manual
                   3   Library Functions Manual
                   4   Kernel Interfaces Manual
                   5   File Formats Manual
                   6   Games Manual
                   7   Miscellaneous Information Manual
                   8   System Manager’s Manual
                   9   Kernel Developer’s Manual

             A  section title may be arbitrary or one of the following abbrevia‐
             tions.

                   USD     User’s Supplementary Documents
                   PS1     Programmer’s Supplementary Documents
                   AMD     Ancestral Manual Documents
                   SMM     System Manager’s Manual
                   URM     User’s Reference Manual
                   PRM     Programmer’s Manual
                   KM      Kernel Manual
                   IND     Manual Master Index
                   LOCAL   Local Manual
                   CON     Contributed Software Manual

             For compatibility, ‘MMI’ can be  used  for  ‘IND’,  and  ‘LOC’  for
             ‘LOCAL’.  Values from the previous table will specify a new section
             title.  If _s_e_c_t_i_o_n_‐_k_e_y_w_o_r_d_‐_o_r_‐_t_i_t_l_e designates a computer architec‐
             ture  recognized  by  _g_r_o_f_f _m_d_o_c, its value is prepended to the de‐
             fault section title as specified by the second parameter.   By  de‐
             fault, the following architecture keywords are defined.

                 acorn26, acorn32, algor, alpha, amd64, amiga, amigappc, arc,
                 arm, arm26, arm32, armish, atari, aviion, beagle, bebox, cats,
                 cesfic, cobalt, dreamcast, emips, evbarm, evbmips, evbppc,
                 evbsh3, ews4800mips, hp300, hp700, hpcarm, hpcmips, hpcsh,
                 hppa, hppa64, i386, ia64, ibmnws, iyonix, landisk, loongson,
                 luna68k, luna88k, m68k, mac68k, macppc, mips, mips64, mipsco,
                 mmeye, mvme68k, mvme88k, mvmeppc, netwinder, news68k, newsmips,
                 next68k, ofppc, palm, pc532, playstation2, pmax, pmppc,
                 powerpc, prep, rs6000, sandpoint, sbmips, sgi, sgimips, sh3,
                 shark, socppc, solbourne, sparc, sparc64, sun2, sun3, tahoe,
                 vax, x68k, x86_64, xen, zaurus

             If  a  section title is not determined after the above matches have
             been attempted, _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  content
             are  shown below.  Observe how ‘\&’ prevents the numeral 2 from be‐
             ing used to look up a predefined section title.

               .Dt foo 2       →  foo(2)     System Calls Manual      foo(2)
               .Dt foo 2 m68k  →  foo(2)   m68k System Calls Manual   foo(2)
               .Dt foo 2 baz   →  foo(2)     System Calls Manual      foo(2)
               .Dt foo \&2 baz →  foo(2)             baz              foo(2)
               .Dt foo "" baz  →  foo                baz                 foo
               .Dt foo M Z80   →  foo(M)             Z80              foo(M)

             _r_o_f_f strings define section titles  and  architecture  identifiers.
             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  distribution.
             When  composing  a man page to be included in the base installation
             of an operating system, do not provide an argument; _m_d_o_c will  sup‐
             ply  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  sec‐
             tion  “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 nomenclature for  the  software  specified.
             In the following table, recognized _v_e_r_s_i_o_n_‐_o_r_‐_r_e_l_e_a_s_e arguments for
             some  predefined  operating  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 di‐
             agnostic emitted.  Otherwise, unrecognized arguments are  displayed
             verbatim  in  the  page  footer.  For instance, this page uses “..OOss
             ggrrooffff 11..2244..11” 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 lan‐
     guage  used  to describe commands, subroutines and related files.  Slightly
     different variations of this language are used to describe the  three  dif‐
     ferent  aspects  of writing a man page.  First, there is the description of
     _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  ver‐
     bal 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 gen‐
     eral 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 example, the user
     has to replace the meta expressions given in angle brackets with real  file
     names.  Note that in this document meta arguments are used to describe _m_d_o_c
     commands;  in  most  man pages, meta variables are not specifically written
     with angle brackets.  The macros that formatted the above example:

           .Nm filter
           .Op Fl flag
           .Ao Ar infile Ac Ao Ar outfile Ac

     In the third case, discussion of commands and command syntax includes  both
     examples  above,  but  may  add  more  detail.   The arguments ⟨_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 confusion,
     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  com‐
     mand line was produced from:

           .Nm make
           .Op Fl eiknqrstv
           .Op Fl D Ar variable
           .Op Fl d Ar flags
           .Op Fl f Ar makefile
           .Op Fl I Ar directory
           .Op Fl j Ar max_jobs
           .Op Ar variable Ns = Ns Ar value
           .Bk
           .Op Ar target ...
           .Ek

     The ‘.Bk’ and ‘.Ek’ macros are explained in “Keeps”.

   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 whitespace:

           ..AArr ssppttrr ,, ppttrr )) ,,

     The result is:

           _s_p_t_r, _p_t_r),

     The  punctuation  is  now recognized and output in the default font distin‐
     guishing it from the argument strings.  To remove the special meaning  from
     a punctuation character, escape it with ‘\&’.

     The following punctuation characters are recognized by _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  char‐
     acter 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 acci‐
     dental evaluation of these characters, escape them with ‘\&’.  Typical syn‐
     tax is shown in the first manual domain macro displayed below, ‘.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.

           UUssaaggee:: ..AArr [⟨argument⟩] ...

                    ..AArr                    _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 ffiillee ...... ddeesstt‐‐ddiirr  _f_i_l_e ... _d_e_s_t_‐_d_i_r
                    ..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 ex‐
     ception that the ‘.Cm’ macro does not assert a dash in front of every argu‐
     ment.  Traditionally flags are marked by the preceding dash, however,  some
     commands  or  subsets  of  commands do not use them.  Command modifiers may
     also be specified in conjunction with interactive commands such  as  editor
     commands.  See “Flags”.

     The default width is 10n.

   DDeeffiinneedd VVaarriiaabblleess
     A variable (or constant) that is defined in an include file is specified 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 section two  man‐
     ual 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        _D_I_S_P_L_A_Y
                    ..EEvv PPAATTHH ..         _P_A_T_H.
                    ..EEvv PPRRIINNTTEERR )) )) ,,  _P_R_I_N_T_E_R)),

     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  al‐
     ready  been  presented and a break has not occurred, leaving vertical space
     between one function declaration and the next.

     In a section titled “Synopsis”, the  ‘In’  macro  represents  the  ##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 enclosed
     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 anywhere
     else in the man page without problems, but its main purpose is  to  present
     the  function  type  (in BSD kernel normal form) for the “Synopsis” of sec‐
     tions two and three.  (It causes a break, allowing the function name to ap‐
     pear on the next line.)

           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’ (func‐
     tion  open) and ‘.Fc’ (function close) may be used with ‘.Fa’ (function ar‐
     gument).

     Example:

           .Ft int
           .Fo res_mkquery
           .Fa "int op"
           .Fa "char *dname"
           .Fa "int class"
           .Fa "int type"
           .Fa "char *data"
           .Fa "int datalen"
           .Fa "struct rrec *newrr"
           .Fa "char *buf"
           .Fa "int buflen"
           .Fc

     Produces:

           _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 declaration will begin the
     line.  If more than one function is presented in the “Synopsis” section and
     a function type has not been given, a break will  occur,  leaving  vertical
     space between the current and prior function names.

     The default width values of ‘.Fn’ and ‘.Fo’ are 12n and 16n, respectively.

   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; otherwise
           the value -1 is returned and the global variable _e_r_r_n_o is set to in‐
           dicate the error.

     The --ssttdd option is valid only for manual page sections 2 and 3.  Currently,
     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.   Cur‐
     rently, 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 function
     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  decryp‐
                          tion (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 section
     “Files” below.

     In a section titled “Library”, ‘Lb’ causes a break before and after its ar‐
     guments.

   LLiitteerraallss
     The ‘Li’ literal macro may be used for special  characters,  symbolic  con‐
     stants,  and  other  syntactical items that should be typed exactly as dis‐
     played.

           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 identifies the document’s central  topic.   Upon  its  first
     call,  it  has  the  peculiarity  of remembering its argument.  When subse‐
     quently called without arguments, ‘Nm’ regurgitates this initial  name  for
     the  sole  purpose  of  making less work for the document’s author.  Use of
     ‘Nm’ is also appropriate when presenting a command synopsis for  the  topic
     of  a  man page in section 1, 6, or 8.  Its behavior changes when presented
     with arguments of various forms.

                    ..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 importance in
     the discussion.  Cross references to other man page topics should use ‘Xr’;
     including a second argument for the section number enables them to  be  hy‐
     perlinked.  By default, cross‐referenced topics are set in italics to avoid
     cluttering the page with boldface.

     The default width is 10n.

   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, respectively.

   PPaatthhnnaammeess
     The ‘.Pa’ macro formats file specifications.  If called without  arguments,
     ‘_~’ (recognized by many shells) is output, representing the user’s home di‐
     rectory.

           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”)
           --iissooCC--22002233      ISO/IEC 9899:2024 (“ISO C23”)

     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”)
           --pp11000033..11--22002244   IEEE Std 1003.1‐2024 (“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 section
     titled “Synopsis”, ‘Vt’ causes a break (useful for old‐style C variable de‐
     clarations).

           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 section), 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’  command
     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’ command
     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’  command
     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  entire
                           block of text.
           LLii | --lliitteerraall   Same  as  if  the ‘.Li’ macro was used for the entire
                           block of text.
           SSyy | --ssyymmbboolliicc  Same as if the ‘.Sy’ macro was used  for  the  entire
                           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 en‐
     close one or more strings between a  pair  of  characters  like  quotes  or
     parentheses.   The  terms  quoting  and  enclosure are used interchangeably
     throughout this document.  Most of the one‐line  enclosure  macros  end  in
     small letter ‘q’ to give a hint of quoting, but there are a few irregulari‐
     ties.   For  each  enclosure  macro, there is a pair of opening and closing
     macros that end with the lowercase letters ‘o’ and ‘c’ respectively.

     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 or Literal         “string” or string
     .Qq     .Qo    .Qc     Straight Double Quote     "string"
     .Sq     .So    .Sc     Single Quote              ‘string’

     All macros ending with ‘q’ and ‘o’ have a default width value of 12n.

     ..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 pro‐
               gram,  _m_d_o_c  supports  two  other  macros  that are now obsolete.
               ‘.Es’ uses its first and second parameters as opening and closing
               marks which are then used to enclose the arguments of ‘.En’.  The
               default width value is 12n for both macros.

     ..EEqq       The first and second arguments of this macro are the opening  and
               closing strings respectively, followed by the arguments to be en‐
               closed.

     ..QQll       The  quoted‐or‐literal  macro  behaves  differently  in _t_r_o_f_f and
               _n_r_o_f_f modes.  When formatting with _n_r_o_f_f(1), _m_d_o_c quotes the  ar‐
               guments.  With _t_r_o_f_f, _m_d_o_c sets them in a constant‐width font.

               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  func‐
               tion.

     ..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 argument 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 posi‐
     tion and its first parameter.  For example, it is useful for old style  ar‐
     gument lists where there is no space between the flag and argument:

           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 docu‐
     ment.

           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 ti‐
                   tled “See also”, it causes a break and begins  collection  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 arguments in
     the usual way.  Only the ‘.Tn’ macro is handled properly  as  a  parameter;
     other  macros  will cause strange output.  ‘.%B’ and ‘.%T’ can be used out‐
     side of the ‘.Rs/.Re’ environment.

     Example:

           .Rs
           .%A "Matthew Bar"
           .%A "John Foo"
           .%T "Implementation Notes on foobar(1)"
           .%R "Technical Report ABC-DE-12-345"
           .%Q "Drofnats College"
           .%C "Nowhere"
           .%D "April 1991"
           .Re

     produces

           Matthew Bar and John Foo, _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_), Techni‐
           cal 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 imple‐
     mented similarly to all other  macros  opening  and  closing  an  enclosure
     (without  inserting  characters, of course).  This means that the following
     is true for those macros also.

     Here is an example of ‘.Xo’ using the space mode macro to turn spacing off:

           .Bd -literal -offset indent
           .Sm off
           .It Xo Sy I Ar operation
           .No \en Ar count No \en
           .Xc
           .Sm on
           .Ed

     produces

           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  vari‐
     able.

           .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 au‐
     thor writing the manual page.  The ‘.Sh’ macro is parsed but not  generally
     callable.   It  can be used as an argument in a call to ‘.Sh’ only; it then
     reactivates the default font for ‘.Sh’.

     The default width is 8n.

     ..SShh NNaammee           The ‘.Sh Name’ macro is mandatory.   If  not  specified,
                        headers,  footers,  and page layout defaults will not be
                        set and things will be rather unpleasant.  The _N_a_m_e sec‐
                        tion consists of at least three items.  The first is the
                        ‘.Nm’ name macro naming the subject  of  the  man  page.
                        The  second  is the name description macro, ‘.Nd’, which
                        separates the subject name from the third item, which is
                        the description.  The description  should  be  the  most
                        terse  and  lucid  possible,  as  the space available is
                        small.

                        ‘.Nd’ first prints ‘-’, then all its arguments.

     ..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 ei‐
                        ther ‘.Nm’, ‘.Cd’, or ‘.Fn’ (and possibly ‘.Fo’,  ‘.Fc’,
                        ‘.Fd’, and ‘.Ft’).  The function name macro ‘.Fn’ is re‐
                        quired for manual page sections 2 and 3; the command and
                        general  name macro ‘.Nm’ is required for sections 1, 5,
                        6, 7, and 8.  Section 4 manuals require a  ‘.Nm’,  ‘.Fd’
                        or  a  ‘.Cd’  configuration device usage macro.  Several
                        other macros may be necessary to  produce  the  synopsis
                        line as shown below:

                              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” sec‐
                        tion is a brief paragraph on the  command,  function  or
                        file,  followed by a lexical list of options and respec‐
                        tive explanations.  To create such  a  list,  the  ‘.Bl’
                        (begin  list),  ‘.It’  (list  item) and ‘.El’ (end list)
                        macros are used (see “Lists and Columns” below).

     ..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 section 2
                        and 3 library functions; see “Return Values”.

     The following ‘.Sh’ section headings are part of the preferred manual  page
     layout  and  must  be used appropriately to maintain consistency.  They are
     listed in the order in which they would be used.

     ..SShh EEnnvviirroonnmmeenntt    The _E_n_v_i_r_o_n_m_e_n_t section should reveal any related  envi‐
                        ronment variables and clues to their behavior and/or us‐
                        age.

     ..SShh FFiilleess          Files  which are used or created by the man page subject
                        should be listed via the ‘.Pa’ macro in the “Files” sec‐
                        tion.

     ..SShh EExxaammpplleess       There are several ways to create examples.  See  subsec‐
                        tion “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 sec‐
                        tion 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 func‐
                        tions (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 accommodated.

                        It is recommended that the cross references be sorted by
                        section  number, then alphabetically by name within each
                        section, then separated by commas.  Example:

                        _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  adhere  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  stan‐
                        dards 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 op‐
                        tional contact information.  Explicitly indicate whether
                        the person authored the initial manual page or the soft‐
                        ware or whatever the person is being credited for.

     ..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 argument 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 prevents breaks in the
     middle  of  options.   In  the example for mmaakkee command‐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  (leave  the  right  margin
                             ragged).
          --cceenntteerreedd          Center  lines  between  the  current left and right
                             margin.  Note that each single line is centered.
          --uunnffiilllleedd          Do not fill; break lines where  their  input  lines
                             are  broken.  This can produce overlong lines with‐
                             out warning messages.
          --ffiilllleedd            Display a filled block.  Text  is  filled  and  ad‐
                             justed; the left and right margins are straight.
          --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  display  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 following
                             strings, the string is interpreted to indicate  the
                             level  of  indentation for the forthcoming 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 dis‐
                                         plays  will  line  up.  The indentation
                                         value is normally 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 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 in‐
                             dicators 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 cur‐
                             rent font (for _n_r_o_f_f output, both  scaling  indica‐
                             tors  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 offset.
          --ccoommppaacctt           Suppress  insertion  of vertical space before begin
                             of display.

     ..EEdd  End display (takes no arguments).

   LLiissttss aanndd CCoolluummnnss
     There are several types of lists which may be initiated with the ‘.Bl’  be‐
     gin‐list  macro.   Items  within the list are specified with the ‘.It’ item
     macro, and each list must end with the ‘.El’ macro.  Lists  may  be  nested
     within  themselves and within displays.  The use of columns inside of lists
     or lists inside of columns is untested.

     In addition, several list attributes may be specified such as the width  of
     a  tag, the list offset, and compactness (blank lines between items allowed
     or disallowed).  Most of this document has been formatted with a tag  style
     list (--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 (start‐
              ing with the second‐level list):

                    .Bl -enum -offset indent -compact
                    .It
                    Item one goes here
                    .Bl -enum -nested -compact
                    .It
                    Item two goes here.
                    .It
                    And item three here.
                    .El
                    .It
                    And item four here.
                    .El

              Result:

                    1.   Item one goes here.
                         1.1.   Item two goes here.
                         1.2.   And item three here.
                    2.   And item four here.

     --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  refer‐
                          ences by the process to pages not loaded in core.
                    UID   numerical user‐id of process owner
                    PPID  numerical  id of parent of process priority (non‐posi‐
                          tive when in non‐interruptible wait)

              The raw text:

                    .Bl -tag -width "PPID" -compact -offset indent
                    .It SL
                    sleep time of the process (seconds blocked)
                    .It PAGEIN
                    number of disk I/O operations resulting from references
                    by the process to pages not loaded in core.
                    .It UID
                    numerical user-id of process owner
                    .It PPID
                    numerical id of parent of process priority
                    (non-positive when in non-interruptible wait)
                    .El

     --ddiiaagg    Diag lists create section four diagnostic lists and are similar 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 unlike
                            tagged paragraph labels.

              And the unformatted text which created it:

                    .Bl -hang -offset indent
                    .It Em Hanged
                    labels appear similar to tagged lists when the
                    label is smaller than the label width.
                    .It Em Longer hanged list labels
                    blend into the paragraph unlike
                    tagged paragraph labels.
                    .El

     --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 manuals.   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 constrained.

                    _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 arguments 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,  in‐
              terpret ⟨_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 preprocessor.

     Other keywords:

     --wwiiddtthh ⟨_s_t_r_i_n_g⟩   If  ⟨_s_t_r_i_n_g⟩ starts with a ‘.’ (dot) immediately followed
                       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 docu‐
                       ment use this option.

                       Example:

                             .Bl -tag -width ".Fl test Ao Ar string Ac"
                             .It Fl test Ao Ar string Ac
                             This is a longer sentence to show how the
                             .Fl width
                             flag works in combination with a tag list.
                             .El

                       gives:

                       --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; afterward, all variables are re‐
                       stored again.  However, boxes (used for enclosures) can’t
                       be saved in GNU _t_r_o_f_f(1);  as  a  consequence,  arguments
                       must always be _b_a_l_a_n_c_e_d to avoid nasty errors.  For exam‐
                       ple,  do not write ‘.Ao Ar string’ but ‘.Ao Ar string Xc’
                       instead  if  you  really  need  only  an  opening   angle
                       bracket.)

                       Otherwise,  if  ⟨_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 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
                       ⟨_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 width value as‐
                       sociated  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  (normally
                       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  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 indica‐
                       tors 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  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.   Finally,  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 groff@gnu.org and include a specimen with its  prove‐
     nance.

     ..BBtt  formats boilerplate text.

                ..BBtt  → is currently in beta test.

          It is neither callable nor parsed and takes no arguments.  Its default
          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 single
          digit) which is bad typographical behaviour.  Instead, set the  return
          value with the rest of the code, using ‘\~’ to tie the return value to
          the previous word.

          Its default width is 12n.

     ..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 contents
          of _f_i_l_e.  It is neither callable nor parsed.

     ..LLkk  Embed hyperlink.  This is a GNU extension  introduced  in  _g_r_o_f_f  1.17
          (April 2001).

                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 en‐
          tries”.

          Its default width is 6n.

     ..MMtt  Embed email address.  This is a GNU extension introduced in _g_r_o_f_f 1.17
          (April 2001).

                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 parameter 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 default
          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   .Em NaN   not a number (slanted)
     \*(Ba    |         |         |     |         bar (upright)

     Some  column  headings  are shorthand for standardized character encodings;
     “7‐bit” for ISO 646:1991 IRV (US‐ASCII), “8‐bit” for ISO Latin‐1  (8859‐1),
     and  “UCS”  for ISO 10646 (Unicode character set).  Historically, _m_d_o_c con‐
     figured the string definitions to fit the capabilities expected of the out‐
     put device.  Old typesetters lacked directional  double  quotes,  producing
     repeated directional single quotes ‘‘like this’’; early versions of _m_d_o_c in
     fact  defined the ‘Lq’ and ‘Rq’ strings this way.  Nowadays, output drivers
     take on the responsibility of glyph substitution, as they possess  relevant
     knowledge  of their available repertoires.  The ‘Ba’ and ‘Na’ strings imply
     a mandatory typeface: upright (roman) in the former, and slanted  (italics)
     with the latter.

DDiiaaggnnoossttiiccss
     The  debugging macro ‘.Db’ offered by previous versions of _m_d_o_c is unavail‐
     able 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 mes‐
     sages, making the package more robust and more verbose.

     The  remaining  debugging  macro is ‘.Rd’, which dumps the package’s global
     register and string contents to the standard error stream.  A  normal  user
     will never need it.

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 consis‐
     tent with output device capabilities  and  reader  preferences,  man  pages
     should never manipulate them.

     Setting string ‘AD’ configures the adjustment mode for most formatted text.
     Typical values are ‘b’ for adjustment to both margins (the default), or ‘l’
     for  left  alignment  (ragged right margin).  Any valid argument to _g_r_o_f_f’s
     ‘ad’ request may be used.  See _g_r_o_f_f(7) for less‐common 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  (defined
     with ‘.Dt’) can be presented in full capitals by setting the registers ‘CS’
     and ‘CT’, respectively, to 1.  These transformations are off by default be‐
     cause they discard case distinction information.

     Setting  register  ‘D’ to 1 enables double‐sided page layout, which is only
     distinct when not continuously rendering.  It places the page number at the
     bottom right on odd‐numbered (recto) pages, and at the bottom left on even‐
     numbered (verso) pages, swapping places with the arguments to ‘.Os’.
           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 rendering is enabled.  The
     default is “-0.5i - 1v”.

     The ‘HF’ string sets the font used for section and subsection headings; the
     default is ‘B’ (bold style of the default family).  Any valid  argument  to
     _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 ‘BP’ and ‘SN’.
           ggrrooffff --TTuuttff88 --rrBBPP==44nn --rrSSNN==22nn --mmddoocc ffoooo..mmaann | lleessss --RR
     The default paragraph and subsection heading indentation amounts are 5n and
     3n, respectively.  Section headings are set with an indentation of zero.

     The line and title lengths can be changed by setting the registers ‘LL’ and
     ‘LT’, respectively:
           ggrrooffff --TTuuttff88 --rrLLLL==110000nn --rrLLTT==110000nn --mmddoocc ffoooo..mmaann | lleessss --RR
     If not set, both registers default to 80n for  terminal  devices  and  6.5i
     otherwise.

     The  ‘MF’  string  sets  the font used for man page identifiers in document
     headers and footers and in the formatted output of the ‘Xr’ macro.  The de‐
     fault is ‘I’ (italic style of the default family).  Any valid  argument  to
     _g_r_o_f_f’s ‘ft’ request may be used.

     Setting the ‘P’ register starts enumeration of pages at its value.  The de‐
     fault is 1.

     The ‘PO’ register configures the page offset.  The default is device‐depen‐
     dent; typically 0 for terminal devices and 1i otherwise.

     To  change  the  document font size to 11p or 12p, set register ‘S’ accord‐
     ingly:
           ggrrooffff --TTddvvii --rrSS1111 --mmddoocc ffoooo..mmaann >> ffoooo..ddvvii
     Register ‘S’ is ignored when formatting for terminal devices.

     By default, _g_r_o_f_f hyperlinks the formatted text of  ‘Lk’,  ‘Mt’,  and  ‘Xr’
     calls  on output devices that support hyperlinking (“html”, “pdf”, and ter‐
     minal devices).  Set the ‘U’ register to 0 to disable this feature.

     Setting the ‘X’ register to a page number _p numbers its successors  as  _paa,
     _pbb,  _pcc, 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_4_._1_/_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 de‐
             finitions,  taking advantage of the fact that pages using them must
             call TTHH or DDdd, respectively, before any other macros.  A user  typ‐
             ing, 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_4_._1_/_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_4_._1_/_t_m_a_c_/_d_o_c_-_o_l_d_._t_m_a_c
             implements a legacy version of the _m_d_o_c package; it was  superseded
             in  4.4BSD  (1994)  and  is needed only to render certain man pages
             from 4.3BSD‐Reno.

     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_t_m_a_c_/_m_d_o_c_._t_m_a_c
             is a wrapper enabling the package to be loaded with the option  “--mm
             mmddoocc”.

     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_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 produc‐
             tion  of  formatted  output.   It  includes  strings  of  the  form
             ‘doc-volume-ds-_X’  and  ‘doc-volume-as-_X’ for manual section titles
             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_4_._1_/_t_m_a_c_/_m_d_o_c_/_d_o_c_-_n_r_o_f_f
             defines parameters appropriate for rendering to terminal devices.

     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_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 devices.

     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_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  libraries,  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 operat‐
             ing system release (sometimes omitted along with the ‘-’  preceding
             it),  _S  an identifier for a standards body or committee, _I one for
             an issue of a standard promulgated by _S, and _L a keyword  identify‐
             ing 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 mandoc project maintains an independent implementation of the _m_d_o_c lan‐
     guage  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 some‐
     times looks ridiculous if output lines are being filled.

     The list and display macros do not do any keeps  and  certainly  should  be
     able to.

     As  of _g_r_o_f_f 1.23, ‘Tn’ no longer changes the type size; this functionality
     may return in a future release.

groff 1.24.1                       2026‐04‐22                      _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  docu‐
     ment  formatting  system.  The _m_e package of macro definitions for the _r_o_f_f
     language provides a convenient facility for preparing technical  papers  in
     various  formats.   This version is based on the _m_e distributed 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 con‐
     junction with this package; however, the following may  be  used  with  im‐
     punity  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 asterisk ** 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 productive input 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’s _p 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 productive input 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 productive input lines

     Except on title pages (produced by calling ttpp), _m_e suppresses the output of
     vertical space at the tops of pages (after the output of any page  header);
     the  sspp  request  thus does not work there.  You can instead call bbll or en‐
     close the desired spacing request in a diversion, for instance  by  calling
     ((bb  and  ))bb.  _m_e also intercepts the llll request; see the “_m_e Reference Man‐
     ual” 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  repur‐
     posed.

   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 (current environment only)
     xxpp   output index

     Some  macros  are provided for “old” _r_o_f_f(1) compatibility.  The “_m_e Refer‐
     ence 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   catenated 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_4_._1_/_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_4_._1_/_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_4_._1_/_t_m_a_c_/_m_e_._t_m_a_c
            is a wrapper enabling the package to be loaded with the  option  “--mm
            mmee”.

NNootteess
     Some  early  _r_o_f_f  macro  packages  limited their names to a single letter,
     which followed the formatter’s mm option, resulting  in  “names”  like  _-_m_m,
     _-_m_s, _-_m_v, and _-_m_n.  _m_e’s “e” stands for “Eric P. Allman”, the author of the
     original macro package and the technical papers documenting it.

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 Lem‐
     berg, 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.24.1                       2026‐04‐22                        _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 _m_m macro package distributed with the _g_r_o_f_f document formatting  system
     is suitable for the composition of letters, memoranda, reports, and books.

     Call  an _m_m macro at the beginning of a document to initialize the package.
     A simple _m_m document might use only PP for paragraphing.  Set  numbered  and
     unnumbered  section headings with HH and HHUU, respectively.  Change the style
     of the typeface with BB, II, and RR; you can alternate styles  within  a  word
     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.  LLBB begins a list with  cus‐
     tomizable layout parameters.  DDSS and DDFF start static and floating displays,
     respectively; DDEE terminates either.

     _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 3.3 (“DWB”), with the following limitations
     and changes.

     •  Omitted features include the logo and company name strings, }}ZZ  and  ]]SS,
        respectively;  the encoded company site location addresses recognized as
        the third argument to the AAUU macro; the PPvv (“private” heading) register;
        and the OOKK (other keywords) and PPMM (proprietary markings) macros.

     •  _g_r_o_f_f _m_m implements the CCSS (output cover page or “sheet”) macro only for
        memorandum type 4.

     •  The _g_r_a_p preprocessor is not explicitly supported; _g_r_o_f_f _m_m  defines  no
        GG11 or GG22 macros.

     •  Registers AA, CC, TT, and UU, set from the _t_r_o_f_f or _n_r_o_f_f command lines with
        DWB, are not recognized.

     •  When setting the registers LL or WW from the command line, use an explicit
        scaling unit to avoid surprises.

     •  The  LLee register defaults to 11, consistently with LLff, LLtt, and LLxx in DWB;
        equations captioned with EECC appear in tables of contents produced by TTCC.

     •  The LLii register configures the text indentation of RRLL  list  items;  DWB
        used a hard‐coded value of 6 ens.

     •  _g_r_o_f_f  _m_m  uses the same adjustment and font style defaults in _n_r_o_f_f and
        _t_r_o_f_f modes.

     •  Cut marks are not supported.

     DWB supported only seven heading levels.  As a compatible extension,  _g_r_o_f_f
     _m_m supports fourteen, introducing new registers HH88 through HH1144, and affect‐
     ing the interpretation of the HHFF and HHPP strings.

     _g_r_o_f_f  _m_m  features a citation (or “bookmark”) system, permitting the docu‐
     ment to make (customizable) internal references like “See chapter  5,  page
     128.”.   Forward  references  require  two‐pass  formatting.  See the IINNIITTRR
     macro description below and _m_m_r_o_f_f(1).

     Macro, register, and string descriptions in this  page  frequently  mention
     each  other;  most references are to macros.  Where a register or string is
     referenced, its type is explicitly identified.  _m_m’s macro names  are  usu‐
     ally in full capitals; registers and strings tend to have mixed‐case names.

     Except where noted, _m_m assumes that horizontal measurements are reckoned in
     ens  (scaling unit nn) and vertical ones in vees (scaling unit vv).  _g_r_o_f_f _m_m
     permits use of non‐integral _t_y_p_o_g_r_a_p_h_i_c_a_l _p_o_i_n_t_s (scaling unit zz).  Use ex‐
     plicit scaling units for clarity and predictable behavior.

   DDooccuummeenntt ssttyylleess
     _g_r_o_f_f _m_m offers three 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 correspondence (business  let‐
     ters, for example).  The MMTT memorandum type mechanism implements a group of
     formal  styles  historically used by AT&T Bell Laboratories.  Your document
     can select at most one of these approaches; when used,  each  disables  the
     others.

   LLooccaalliizzaattiioonn
     _g_r_o_f_f _m_m is designed to be easily localized.  For languages other than Eng‐
     lish,  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_4_._1_/_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_4_._1_/_t_m_a_c_/_m_s_e_._t_m_a_c  illustrates  how to adapt the output to a
     national standard using its ISO 3166 territory code.  Such  a  package  can
     define  a  string that causes a macro file _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_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_4_._1_/_t_m_a_c_/_m_m_/_l_o_c_a_l_e is loaded instead.   No
     diagnostic is produced if these files do not exist.

   RReeggiisstteerrss aanndd ssttrriinnggss
     Much  _m_m  behavior  can be configured by registers and strings.  The nnrr re‐
     quest assigns a value to a register.

            ..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.  Pre‐
     fixing _n with a plus or minus sign increments or decrements  (respectively)
     its  existing value.  If assignment of a (possibly) negative _n is required,
     further prefix it with a zero or enclose it in parentheses.  If _i is speci‐
     fied, the register’s value automatically changes by _i prior  to  interpola‐
     tion 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 interpo‐
     lation escape sequence.  The brackets around _i_d_e_n_t are literal.

     Many of the registers _m_m provides are as Boolean‐valued, meaning that  they
     are  considered  “true”  (on, enabled) when they have a positive value, and
     “false” (off, disabled) otherwise.

     Define strings with the 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 se‐
     quence (\\"") so that extraneous spaces do not intrude during document  main‐
     tenance.   To  include  leading spaces in _c_o_n_t_e_n_t_s, prefix it with a double
     quote.  Interpolate strings with the \\** escape sequence.

            \\**[[_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 request.

            ..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
     _m_m  assumes  that  the  font styles RR (roman), II (italic), and BB (bold) are
     mounted at font positions 11, 22, and 33, respectively.  Use the ffpp request to
     mount substitute fonts at these positions as  desired.   The  default  font
     family  is  “TT” (Times).  To select a different one, invoke _g_r_o_f_f’s ffaamm re‐
     quest or use its --ff command‐line option.

MMaaccrrooss
     Double‐quote macro arguments that contain space characters.  An  explicitly
     empty  argument  may  be specified with an empty pair of double quotes; for
     example, the following macro call has three arguments.

            .XX "foo bar" "" baz

     Some macros are documented as causing a page break; this does not occur  if
     such a macro is called when the drawing position is already at the top of a
     page (after a page heading, if any).

     _H_o_o_k macros are undefined by default; _m_m calls them to enable customization
     of its behavior.  (DWB termed these “exits”.)

     Macro  names  longer than two characters are extensions; some shorter names
     were not part of DWB’s published interface but are  documented  aspects  of
     _g_r_o_f_f _m_m_.

     11CC [11]  Format  page  text in one column (the default layout).  The page is
             broken.  A 11 argument 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 [_o_r_g_‐_n_a_m_e]
             Specify a memorandum’s organizational affiliation.  At most one can
             be declared; _o_r_g_‐_n_a_m_e is used by  MMTT  memoranda  and  available  to
             cover pages.  See CCOOVVEERR.

     AAFFXX     Define  this hook macro to assume responsibility for formatting the
             affiliated firm name defined by AAFF in memorandum types 0 and 4  and
             documents  using  the _m_s cover page style.  If not defined (the de‐
             fault), internally defined macros handle this task; see  subsection
             “Internals”  and  section “Files” below.  Applications include set‐
             ting the firm name in a different font family or at a  larger  type
             size,  drawing  a  rule across the page, and including a logo image
             using  _g_r_o_f_f’s  PPDDFFPPIICC  or  PPSSPPIICC  macros.   See  MMTT,  CCOOVVEERR,   and
             _g_r_o_f_f___t_m_a_c(5).

     AALL [_n_u_m_b_e_r_‐_f_o_r_m_a_t [_t_e_x_t_‐_i_n_d_e_n_t [11]]]
             Begin  an auto‐incrementing numbered list, where item numbers start
             at one and are followed by a dot.  _n_u_m_b_e_r_‐_f_o_r_m_a_t assigns the regis‐
             ter format (see above) _m_m uses for the list item enumerators.   The
             default  is  00.   A  _t_e_x_t_‐_i_n_d_e_n_t argument overrides register LLii.  A
             third argument suppresses the vertical space that normally precedes
             each list item; see register LLsspp.  Vertical space in the amount  of
             LLsspp precedes the list itself, but does not accumulate with pre‐item
             space  when this list is nested in another.  AALL calls LLBB; use LLII to
             declare list items, and LLEE to end the list.

     AAPPPP [_s_e_q_u_e_n_c_e_‐_n_u_m_b_e_r [_t_i_t_l_e]]
             Begin an appendix.  If _s_e_q_u_e_n_c_e_‐_n_u_m_b_e_r is  omitted,  it  increments
             (or  is  initialized to 11, if necessary).  The register format used
             for _s_e_q_u_e_n_c_e_‐_n_u_m_b_e_r is “A”.  The page is broken.  The register  AApphh
             determines  whether  an  appendix  heading is then formatted.  This
             heading uses the string AApppp followed  by  _s_e_q_u_e_n_c_e_‐_n_u_m_b_e_r.   Appen‐
             dices  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 _s_e_q_u_e_n_c_e_‐_n_u_m_b_e_r _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  loca‐
             tion  of  the  abstract on the cover page of a memorandum (see MMTT).
             CCOOVVEERR, by contrast, ignores _p_l_a_c_e_m_e_n_t by default, but can  be  cus‐
             tomized to interpret it.

             _pp_ll_aa_cc_ee_mm_ee_nn_tt   EEffffeecctt
             0           The  abstract  appears  on page 1 and cover page if the
                         document is a “released paper”  memorandum  (“..MMTT  44”);
                         otherwise, it appears on page 1 without a cover page.
             1           The  abstract  appears  only on the cover page (“..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, 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 re‐
             duces the line length by twice this amount.  The default is 00.

     AATT _t_i_t_l_e ...
             Specify author’s title(s).  If present, AATT must appear  just  after
             the  corresponding author’s AAUU.  Each _t_i_t_l_e occupies an output line
             beneath the author’s name in the signature block used by LLTT letters
             (see SSGG) and in MMTT memoranda.  The _m_s cover page style also formats
             these data.

     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 in‐
             formation is used by cover pages, MMTT memoranda,  and  SSGG.   Further
             arguments comprise initials, location, department, telephone exten‐
             sion,  room  number or name, and up to three additional items.  Re‐
             peat 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, respectively, beneath them.  Above these rules,
             _m_m formats the text in the string LLeettaapppp;  a  second  argument  re‐
             places this text with one vee of vertical space.  See LLTT.

     AAVVLL [_n_a_m_e]
             As  AAVV, but omitting the approval notation (the LLeettaapppp string), the
             date rule, and the label below the date rule (the LLeettddaattee string).

     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  previous
             font, without space between the arguments.  If no arguments, switch
             font to bold style.

     BB11      Begin  boxed  static  display.  The text is indented by 11nn, and the
             line length reduced by 22nn.  See DDSS.  This is a _g_r_o_f_f _m_m extension.

     BB22      End boxed static display.  See BB11.  This is a _g_r_o_f_f _m_m 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.   _m_m  marks each item with the string BBUU.  A
             _t_e_x_t_‐_i_n_d_e_n_t argument overrides register PPii.  A second argument sup‐
             presses the vertical space that normally precedes each  list  item;
             see register LLsspp.  Vertical space in the amount of LLsspp precedes the
             list  itself, but does not accumulate with pre‐item space when this
             list is nested in another.  BBLL calls LLBB; use  LLII  to  declare  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, without
             space between the arguments.

     BBSS      Begin bottom block.  _m_m collects input into the bottom block  until
             the document calls BBEE, and outputs it 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 should
             supply its own mark.  The line is always  broken  after  the  mark;
             contrast  VVLL.   A _t_e_x_t_‐_i_n_d_e_n_t argument overrides register PPii; _m_a_r_k_‐
             _i_n_d_e_n_t sets the distance from the indentation of the  current  list
             to  the  mark.  A third argument suppresses the vertical space that
             normally precedes each list item; see register LLsspp.  Vertical space
             in the amount of LLsspp precedes the list itself, but does not accumu‐
             late with pre‐item space when this list is nested in another.   BBVVLL
             calls LLBB; 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_4_._1_/_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 that of the  _m_s  pack‐
             age.  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
             .AF
             .TL
             .AU
             .AT
             .\" Add additional AU and AT calls as needed.
             .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.  _m_m marks each item with the string EEMM.  A _t_e_x_t_‐
             _i_n_d_e_n_t  argument  overrides  register  PPii.   A second argument sup‐
             presses the vertical space that normally precedes each  list  item;
             see register LLsspp.  Vertical space in the amount of LLsspp precedes the
             list  itself, but does not accumulate with pre‐item space when this
             list is nested in another.  DDLL calls LLBB; use  LLII  to  declare  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.  _m_m collects input into a display until the
             document calls DDEE.  The display is output on a single  page  unless
             it  is  taller than the height of the page.  DDSS can be nested (con‐
             trast 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‐align each line.
             RB       Right‐align the whole display as a block.

             The values “L”, “I”, “C”, and “CB” can also be  specified  as  “0”,
             “1”, “2”, and “3”, respectively, for compatibility with DWB.

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

             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  vertical  space before and after the display.
             Set register DDss to “0” to suppress it.

     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.  A caption comprises the string CCaappeecc 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 format.  _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 spec‐
             ifying 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.

             _m_m centers equation captions irrespective of the alignment  of  any
             enclosing display.

             Specifying _r_e_f_‐_n_a_m_e stores the equation number as if by “..SSEETTRR _r_e_f_‐
             _n_a_m_e  \\nn[[EEcc]]”.   Recognition  of this argument is a _g_r_o_f_f _m_m exten‐
             sion.

             The package lists captioned equations in a table of  contents  (see
             TTCC)  if  the  Boolean  register LLee is true.  The string LLee captions
             this list.

     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 nor‐
             mal 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 nor‐
             mal  page  header  on even‐numbered pages.  See PPHH.  EEHH defines the
             string TTPPeehh.

     EENN      End mathematical expression input preprocessed by _e_q_n(1); see EEQQ.

     EEOOPP     _g_r_o_f_f _m_m calls this hook macro in lieu of normal page  footer  lay‐
             out.  The package uses a separate environment to format headers and
             footers.  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.  The text _n_a_m_e (or de‐
             fault text) is formatted inside the box; no attempt is made to size
             the box to fit the text.  An application of this macro is to  indi‐
             cate  the  placement  of an image to be determined later, or exter‐
             nally composited in postprocessing.  --LL as the first argument left‐
             aligns the box; the default is to center it.  See PPIICC.

     EEQQ [_l_a_b_e_l]
             Start mathematical expression input preprocessed by _e_q_n(1).  EEQQ and
             EENN macro calls bracket an equation region.  Such  regions  must  be
             contained  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  ap‐
             pears  aligned to the right and centered vertically within the dis‐
             play; see register EEqq.  If multiple _e_q_n regions occur within a dis‐
             play, 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 CCaappeexx precedes the
             exhibit number and any _t_i_t_l_e_.  _m_m centers  exhibit  captions  irre‐
             spective of the alignment of any enclosing display.

             The  package  lists  captioned exhibits in a table of contents (see
             TTCC) if the Boolean register LLxx is true.   The  string  LLxx  captions
             this list.

     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 for‐
             mal closing of a letter or memorandum.  See LLTT and MMTT.

     FFDD [_a_r_g [11]]
             Configure display of footnotes.  The first argument encodes enable‐
             ment of automatic hyphenation, adjustment to both margins, indenta‐
             tion  of  footnote text, and left‐ vs. right‐alignment of the foot‐
             note label within the space allocated for it.

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

             A second argument resets  footnote  numbering  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 CCaappffgg  precedes  the
             figure  number and any _t_i_t_l_e_.  _m_m centers figure captions irrespec‐
             tive of the alignment of any enclosing display.

             The package lists captioned figures in a table of contents (see TTCC)
             if the Boolean register LLff is true.  The string  LLff  captions  this
             list.

     FFSS [_m_a_r_k]
             Start  footnote.  _m_m collects input into a footnote until the docu‐
             ment calls FFEE, outputting it when  the  vertical  drawing  position
             nears  the page bottom.  By default, _m_m automatically numbers foot‐
             notes starting at 1; the number is available in register FFttnnuumm and,
             with a trailing period, in string FF.  If desired, interpolate  this
             string  in  the body text to format the footnote mark.  _m_m interpo‐
             lates string FF prior to the footnote text.   Footnotes  are  verti‐
             cally  separated  by the product of registers FFss and LLsspp.  In _g_r_o_f_f
             _m_m, footnotes may be used in displays.

             A _m_a_r_k argument, which need not be numeric,  replaces  the  default
             footnote  mark, leaving the string FF unchanged.  In that event, you
             must explicitly write any footnote mark to appear in  the  footnote
             itself.

     GGEETTHHNN _r_e_f_‐_n_a_m_e [_s_t_r_i_n_g]
             Interpolate  _r_e_f_‐_n_a_m_e’s  heading  mark, or, if _s_t_r_i_n_g is specified,
             store it there.  In neither case does GGEETTHHNN suffix  the  interpola‐
             tion with space.  See IINNIITTRR.

     GGEETTPPNN _r_e_f_‐_n_a_m_e [_s_t_r_i_n_g]
             Interpolate  _r_e_f_‐_n_a_m_e’s  page  number,  or, if _s_t_r_i_n_g is specified,
             store it there.  In neither case does GGEETTPPNN suffix  the  interpola‐
             tion with space.  See IINNIITTRR.

     GGEETTRR _r_e_f_‐_n_a_m_e
             Retrieve location data for reference _r_e_f_‐_n_a_m_e, call GGEETTHHNN and GGEETTPPNN
             to  populate  strings  QQrrffhh and QQrrffnn, respectively, and interpolate
             string QQrrff as an internal reference to it.  See IINNIITTRR.

     GGEETTSSTT _r_e_f_‐_n_a_m_e [_s_t_r_i_n_g]
             Interpolate _r_e_f_‐_n_a_m_e’s auxiliary reference datum, or, if _s_t_r_i_n_g  is
             specified,  store  it there.  In neither case does GGEETTSSTT suffix the
             interpolation with space.  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 calls LLCC to clear  any
             lists,  then  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  incre‐
             ments  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 for‐
             matted as a paragraph; calling PP is unnecessary.

             The optional _t_i_t_l_e 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 in‐
             terpolate the FF string; specify a footnote  mark  explicitly.   See
             FFSS.

             Heading  behavior  is  configurable.  Several registers set _t_h_r_e_s_h_‐
             _o_l_d_s_, where heading levels at or below a threshold value  are  han‐
             dled in one way, and those above it another.  For example, _m_m popu‐
             lates  a  table of contents (see TTCC) with the title of a heading if
             its level is within the CCll register threshold.

             _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 within 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 at which a break
             occurs after the heading, and register HHss sets a  threshold  within
             which  vertical  space  follows  it.  If the heading level is above
             both of these, and the paragraph is not  numbered,  _m_m  produces  a
             _r_u_n_‐_i_n  _h_e_a_d_i_n_g;  paragraph  text  follows on the same output line.
             Otherwise, register HHii configures the  indentation  of  text  after
             headings.   Threshold  register  HHcc permits centering; _m_m centers a
             heading with a level within both of the HHbb and HHcc thresholds.

             _H_e_a_d_i_n_g _t_y_p_e_f_a_c_e _a_n_d _s_i_z_e_.  The HHFF string configures the fonts used
             for heading marks and titles at each level.  The string HHPP likewise
             assigns a type size to each heading  level.   The  hook  macros  HHXX
             and/or HHZZ can control the vertical spacing used by headings.

             _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 coun‐
             ters 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 regis‐
             ter.  Heading numbers are not suffixed with a trailing  dot  except
             when  only the first level is output; to omit a dot in this case as
             well, clear the 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_.  HH calls HHXX, HHYY, and HHZZ  hook  macros
             to further customize headings.  These can change the heading’s _m_a_r_k
             (the numbered portion before any heading title), its vertical spac‐
             ing,  and its vertical space requirements (for instance, to require
             a minimum quantity of subsequent output lines on the page, breaking
             the page otherwise).  Define hook macros in expectation of the fol‐
             lowing parameters.  The argument _d_e_c_l_a_r_e_d_‐_l_e_v_e_l is the _l_e_v_e_l  argu‐
             ment  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 unnumbered headings.  _t_i_t_l_e_‐_s_u_f_f_i_x is the catena‐
             tion of the corresponding arguments 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_‐_s_u_f_f_i_x
                    _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 heading
                           to be typeset.  If that amount is not available,  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_‐_s_u_f_f_i_x
                    _m_m calls HHYY after determining 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_‐_s_u_f_f_i_x
                    _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, selecting the default, “\%”,  if  called
             without argument.

     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 _t_i_t_l_e [_s_u_f_f_i_x]
             Set an unnumbered section heading with _t_i_t_l_e and, as a _g_r_o_f_f _m_m ex‐
             tension,  an optional _s_u_f_f_i_x_.  The heading is treated as a numbered
             heading of the level stored in register HHuu, but no heading mark  is
             output; 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 previous
             font, without space between the arguments.  If no arguments, 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.  The arguments give each
             recipient a name and title.  _m_m collects input into the inside  ad‐
             dress  until the document calls IIEE, then outputs it.  You can spec‐
             ify multiple recipients with empty IIAA/IIEE pairs; _m_m  uses  only  the
             last address.  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 spe‐
             cially 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 character.
             The entry’s location information is arranged as configured  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  interpolating
             the  string  IInnddeexx.   It then disables filling and calls 22CC; after‐
             ward, it restores filling and calls 11CC.

             Define macros to customize this behavior.  IINNDDPP calls TTXXIINNDD  before
             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  se‐
             lects  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, _g_r_o_f_f _m_m calls it for each index entry  with
             the arguments given to IINNDD.

     IINNIITTRR _f_i_l_e_‐_n_a_m_e_‐_p_r_e_f_i_x
             Initialize  the internal reference macros.  Internal references are
             written to the standard error stream, which  should  be  redirected
             into a file named file‐name‐prefix_._q_r_f.  _m_m_r_o_f_f(1) handles this and
             the  two  formatting passes it requires.  The first pass identifies
             internal references; the second includes them.   See  SSEETTRR,  GGEETTHHNN,
             GGEETTPPNN, and GGEETTSSTT.

     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.

     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_‐_o_r_‐_f_o_r_m_a_t [_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.

             _m_m  tracks  the nesting level of lists; the outermost is 0.  It in‐
             dents each list item (text formatted after an LLII call) by  _t_e_x_t_‐_i_n_‐
             _d_e_n_t_.   The  mark is left‐aligned at _m_a_r_k_‐_i_n_d_e_n_t, and padded on the
             left with _p_a_d ens of space.  _t_y_p_e determines the mark’s format.

             _tt_yy_pp_ee   OOuuttppuutt ffoorr aa mmaarrkk ““xx””
             0      x
             1      x.
             2      x)
             3      (x)
             4      [x]
             5      <x>
             6      {x}

             If _t_y_p_e is 00, _m_a_r_k_‐_o_r_‐_f_o_r_m_a_t specifies each item’s mark (which  can
             be  overridden  by  an argument to LLII).  If _m_a_r_k_‐_o_r_‐_f_o_r_m_a_t is empty
             (or the dummy character “\\&&”) _m_m sets items at _m_a_r_k_‐_i_n_d_e_n_t  with  a
             hanging indent at _t_e_x_t_‐_i_n_d_e_n_t_.

             If  _t_y_p_e  is greater than zero, _m_m supplies an automatically incre‐
             menting numeric mark, and interprets _m_a_r_k_‐_o_r_‐_f_o_r_m_a_t as  a  register
             format.

             A  _t_y_p_e of --11 causes _g_r_o_f_f _m_m to break the line after the mark even
             if it fits within _t_e_x_t_‐_i_n_d_e_n_t_; this is a _g_r_o_f_f _m_m extension.

             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, ei‐
             ther all (the default) or only those from the current level down to
             _l_i_s_t_‐_l_e_v_e_l if specified.

     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 [_p_a_d_‐_p_r_e_f_i_x]]
             Begin a list item.  _m_m collects input into a list  item  until  the
             document  terminates  the  current  list or calls LLII again.  By de‐
             fault, the item’s text is preceded by any mark  configured  by  the
             current  list.   If _m_a_r_k is the only argument, it replaces the mark
             configured in the corresponding LLBB call.  If the width of the  mark
             plus any _p_a_d specified in the LLBB call exceeds the text indentation,
             _g_r_o_f_f  _m_m warns and uses one en of padding between the mark and the
             text.  The presence of a second argument prefixes _m_a_r_k to  the  LLBB‐
             configured mark and, as a _g_r_o_f_f _m_m extension, conditionally puts an
             unbreakable  space  between  the prefix and mark per the argument’s
             Boolean value.

     LLOO _o_p_t_i_o_n [_v_a_l_u_e]
             Specify letter options; see LLTT.  By default, _m_m recognizes the fol‐
             lowing _o_p_t_i_o_n values.  See IIAA  regarding  the  inside  address  and
             string DDTT regarding the date.

             _oo_pp_tt_ii_oo_nn   MMeeaanniinngg aanndd 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 confidential 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 confidential  no‐
                      tation (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 be‐
             low).  A letter begins with the writer’s address (WWAA/WWEE),  followed
             by  the date (NNDD), the inside address (IIAA/IIEE), the body of the let‐
             ter (PP and other general‐purpose _m_m  macros),  the  formal  closing
             (FFCC),  the signature (SSGG), and notations (NNSS/NNEE).  Any of these ex‐
             cept the body text may be omitted.  Letter options  specified  with
             LLOO  add  further  annotations, which are extensible; see subsection
             “Internals” below.

             _ss_tt_yy_ll_ee   DDeessccrriippttiioonn
             BL      Blocked: the writer’s address, date,  formal  closing,  and
                     signature  are  indented to the center of the line.  Every‐
                     thing else is left‐aligned.
             SB      Semi‐blocked: as BBLL, but the first line of  each  paragraph
                     is indented by \\nn[[PPii]] ens.
             FB      Fully blocked: everything is left‐aligned.
             SP      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.
             NNCCOOLL moves to the next column, and 11CC returns to single‐column lay‐
             out.  MMCC is a _g_r_o_f_f _m_m extension, generalizing 22CC.  See MMUULLBB for an
             alternative.

     MMLL _m_a_r_k [_t_e_x_t_‐_i_n_d_e_n_t [11]]
             Start a _m_a_r_k_e_d _l_i_s_t_; the _m_a_r_k argument precedes each  item.   _t_e_x_t_‐
             _i_n_d_e_n_t  overrides  the default indentation of the list items, which
             is the width of _m_a_r_k plus one en.  A third argument suppresses  the
             vertical  space that normally precedes each list item; see register
             LLsspp.  Vertical space in the amount of LLsspp precedes the list itself,
             but does not accumulate with  pre‐item  space  when  this  list  is
             nested  in another.  MMLL calls LLBB; 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 developed,
             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_4_._1_/_t_m_a_c_/_m_m_/type_._M_T and
             load  it  with  the  mmssoo request.  Memorandum types 0 to 5 are sup‐
             ported; any other value of _t_y_p_e is mapped to type 6.  Omitting _t_y_p_e
             implies 11.  _a_d_d_r_e_s_s_e_e sets a string analogous to one used  by  AT&T
             cover page macros not implemented in _g_r_o_f_f _m_m.

             _tt_yy_pp_ee     DDeessccrriippttiioonn
             0        normal memorandum; no caption
             1        captioned “TECHNICAL MEMORANDUM”
             2        captioned “INTERNAL MEMORANDUM”
             3        captioned “ADMINISTRATIVE MEMORANDUM”
             4        released paper
             5        external letter
             _s_t_r_i_n_g   captioned _s_t_r_i_n_g

             See CCOOVVEERR for a more flexible cover page 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 normal.

     MMUULLBB _c_w_1 _s_p_1 [_c_w_2 _s_p_2] ... _c_w_n
             Begin alternative multi‐column mode.  All column widths _c_wi must be
             specified, as must the amount of  space  _s_pi  between  each  column
             pair.   MMUULLBB  uses  a diversion and operates in a separate environ‐
             ment.

     MMUULLEE    End alternative multi‐column mode and emit the columns.

     MMUULLNN    Start next column in alternative column mode.

     NNCCOOLL    Start 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).  _m_m calls NNDD itself when initializ‐
             ing.

     NNEE      End notation begun with NNSS; filling is enabled.

     nnPP [_t_y_p_e]
             As  PP,  but set a paragraph number in the form _x._y_y, where _x is the
             number of the second heading level, and _y_y increments with each  nnPP
             call;  its  value is not reset when the second‐level heading number
             changes.  _m_m uses a register format of “00” for _y_y_.

     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 output, and
             filling is disabled until the document calls NNEE.  Typically, a list
             of names or attachments lies within NNSS/NNEE.  If _c_o_d_e  is  absent  or
             does  not match one of the values listed under the LLeettnnss string de‐
             scription 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 nor‐
             mal 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 nor‐
             mal page header on odd‐numbered pages.  See  PPHH.   OOHH  defines  the
             string TTPPoohh.

     OOPP      Ensure  that subsequent text is formatted at the top of an odd‐num‐
             bered page; no page break is performed if the drawing  position  is
             already there.

     PP [_t_y_p_e]
             Begin new paragraph.  If _t_y_p_e is missing or 00, PP sets the paragraph
             fully  left-aligned.   A  _t_y_p_e of 11 indents the first line by \\[[PPii]]
             ens.  Set the register PPtt to select a default paragraph indentation
             style.  The register PPss determines the amount of vertical space be‐
             tween paragraphs.

             To set a paragraph with a hanging indent, use VVLL with  the  desired
             indentation as the argument, LLII (with no argument), and LLEE.

     PPEE      End picture input preprocessed by _p_i_c(1); see PPSS.

     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  de‐
             fines 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.  To  suppress  a  header  on  the
             first  page,  call  this  macro prior to formatting any text in the
             document.  Also see register NN.

     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 respec‐
             tive locations on the line.  A “%%” character in _a_r_g is replaced  by
             the page number.  If the argument is absent, no page header is set.
             The default page header is
                    "''- % -''"
             which  centers  the page number between hyphens and formats nothing
             at the upper left and right.  Header macros call  PPXX  (if  defined)
             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  argu‐
             ments align the picture or indent it by _n.  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      Start picture input preprocessed by _p_i_c(1).

     PPYY      As PPEE, but with “flyback”, returning the drawing position to  where
             it was prior to the picture.  This is a _g_r_o_f_f _m_m 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 pre‐
             vious font, without space between the arguments.  If no  arguments,
             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, without
             space between the arguments.

     RRDD [_p_r_o_m_p_t [_d_i_v [_s_t_r]]]
             Write _p_r_o_m_p_t (if specified, a tab and colon “:” to the standard er‐
             ror stream and read response from standard input stream, optionally
             into a diversion _d_i_v and/or string _s_t_r_.  Interpolate the saved text
             by calling its name like a macro.  If _s_t_r_i_n_g is present, the  input
             is also stored in a string of that name.

     RRFF      End a bibliographic reference citiation started with RRSS.  See RRPP.

     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  an auto‐incrementing numbered list, where item numbers start
             at one and set between square  brackets.   A  _t_e_x_t_‐_i_n_d_e_n_t  argument
             overrides  register  LLii.  A second argument suppresses the vertical
             space that normally precedes each  list  item;  see  register  LLsspp.
             Vertical  space  in the amount of LLsspp precedes the list itself, but
             does not accumulate with pre‐item space when this list is nested in
             another.  RRLL calls LLBB; use LLII to declare list items, and LLEE to  end
             the  list.  “RL” is a mnemonic for “reference list”, but this macro
             has no relationship with _m_m’s bibliographic reference list  facili‐
             ties.

     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  list,  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 references
             are output; the register RRppeejj configures this behavior, and a  sec‐
             ond  argument  overrides  its  value.  TTCC calls RRPP automatically if
             references have accumulated.

             _g_r_o_f_f _m_m calls LLBB to format the reference list;  the  RRppffmmtt  string
             configures  the  list’s  appearance.  Setting register LLss to 00 sup‐
             presses spacing after the list.  The string RRpp contains the  refer‐
             ence list caption.

     RRPPXX     This  hook  macro assumes responsibility for formatting the heading
             of the reference page that RRPP produces.  If not  defined  (the  de‐
             fault),  _m_m  sets the reference list caption in the string RRpp after
             two vees of space, centered in italics, followed by another vee  of
             space.

     RRSS [_r_e_f_e_r_e_n_c_e_‐_s_t_r_i_n_g]
             Begin citation of an automatically numbered bibliographic reference
             entry.  _m_m collects input into a reference entry until the document
             calls  RRFF.   A  subsequent  RRPP  call emits the accumulated entries.
             References are numbered starting at 1; the register ::RR  stores  the
             most recently assigned number.  Interpolate the string RRff where the
             reference  mark  should  be, then place the entry between RRSS and RRFF
             calls on text lines after the reference mark.  The RRffssttyyllee register
             determines whether the mark is bracketed, superscripted,  or  both.
             If _r_e_f_e_r_e_n_c_e_‐_s_t_r_i_n_g is specified, _m_m also stores the reference mark
             in a string of that name.

     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 mea‐
             surement, using an appropriate scaling unit and an optional ++ or  --
             prefix to increment or decrement the current value.  An argument of
             PP  restores  the previous value, CC retains the current value, and DD
             requests the default.  _m_m treats an empty or omitted argument 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; _g_r_o_f_f _m_m assumes
             11.  Invoke the nnaa request as desired to temporarily suspend adjust‐
             ment.  HH and HHUU, and SSAA when called without a  _m_o_d_e  argument,  re‐
             store the default adjustment.

     SSEETTRR _r_e_f_‐_n_a_m_e [_s_t_r_i_n_g]
             Create  reference  _r_e_f_‐_n_a_m_e,  storing its heading and page numbers.
             If _s_t_r_i_n_g is present, _g_r_o_f_f _m_m saves it as an auxiliary  datum  for
             retrieval by GGEETTSSTT.  See IINNIITTRR.

     SSGG [_a_r_g [11]]
             Output  author  signature  block(s) in LLTT letters and MMTT memoranda.
             The format of a signature block depends on the letter or memorandum
             type.  See subsection “Internals” below.

             LLTT letters emit a signature for one author at most (see  WWAA).   The
             author’s  title, if any, is set on the next line, indented to align
             with the name, except in letter type “SP”, where it is set in  full
             capitals (like the name) after a comma and space.

             Memorandum  type  4  uses  no signature block.  In other memoranda,
             each of an author’s titles is set on a subsequent line, indented to
             align with the name.  They furthermore encode a secretarial annota‐
             tion including the location, department, and initials specified  in
             each  author’s AAUU call, followed by any _a_r_g, writing it at the left
             margin preceding the last author’s name, or preceding the first  if
             a second SSGG argument is present.

     SSKK [_n]  Skip  _n  pages.  If _n is 00 or omitted, _m_m breaks the page if neces‐
             sary.  Otherwise, _m_m prints _n pages, blank except for  any  headers
             and footers.

     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, without space between the arguments.

     SSPP [_d_i_s_t_a_n_c_e]
             Space downward by _d_i_s_t_a_n_c_e_.  Multiple SSPP calls in sequence  produce
             only  the largest of the specified _d_i_s_t_a_n_c_e_s_.  SSPP accepts boundary‐
             relative motions specified with a prefixed || operator, but not neg‐
             ative ones.

             SSPP has no effect when the drawing position is at  the  top  of  the
             page.   Put  the dummy character escape sequence \\&& (followed by \\cc
             if desired to prevent a break) on a text line prior to an  SSPP  call
             to overcome this restriction.

     TTAABB     Reset tab stops to every 5 ens.  The ttaa request customizes them.

     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  CCaappttbb  precedes  the
             table number and any _t_i_t_l_e_.  _m_m centers table captions irrespective
             of the alignment of any enclosing display.

             The  package lists captioned tables in a table of contents (see TTCC)
             if the Boolean register LLtt is true.  The string  LLtt  captions  this
             list.

     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  ref‐
             erences  are pending (see RRSS), calls RRPP.  It then begins a new page
             with the contents caption, stored in the string CCaappttcc, 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 regis‐
             ter), along with its associated page number.  By  default,  _m_m  in‐
             dents  an entry by an amount corresponding to its heading level and
             the maximum heading length encountered at that  heading  level;  if
             defined,  the  string  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  heading  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 argument is true, the leader is replaced
             with horizontal motion in the same amount.  For entries above head‐
             ing 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  the document calls TTCC with at most four arguments, _m_m calls the
             hook macro TTXX prior to formatting the contents caption, and TTYY  (if
             defined) _i_n_s_t_e_a_d of formatting the contents caption.

             _m_m then presents lists of figures, tables, equations, and exhibits,
             in  that order.  A list appears only if at least one such captioned
             item is present, and if its corresponding register (LLee, LLff, LLtt,  or
             LLxx) is set.  TTXX_x_x and TTYY_x_x macros, where _x_x is “FG”, “TB”, “EC”, or
             “EX”,  and  strings CCaappffgg, CCaappttbb, CCaappeecc, and CCaappeexx analogously con‐
             figure the output of each captioned list.

     TTEE      End _t_b_l(1) table.  See TTSS.

     TTHH      Mark the end of a TTSS/TTEE table heading.  When a table spans multiple
             pages, the heading repeats at the top of each page.  _g_r_o_f_f _m_m  does
             not implement the NN argument supported by DWB.

     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.   _m_m  collects input into the title until a
             subsequent AAUU call and formats it as directed by the MMTT  memorandum
             type  or cover page macros.  _m_m saves _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 for use in all memorandum types except 4.

     TTMM _n_u_m_b_e_r ...
             Declare technical memorandum number(s) used with MMTT memoranda.

     TTPP      _m_m calls this hook macro in lieu of normal page header layout.  The
             package uses a separate environment to format headers and  footers.
             See EEOOPP.

             SSttrriinnggss aavvaaiillaabbllee ttoo TTPP
             ────────────────────────
             TTPPhh     argument to PPHH
             TTPPeehh    argument to EEHH
             TTPPoohh    argument to OOHH

     TTSS [HH]  Start _t_b_l(1) table.  Argument “H” tells _m_m that the table’s heading
             should repeat after page breaks.  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 display of verbatim content.  _f_o_r_m_a_t controls several parame‐
             ters.   Add  up  the  values of desired features; the default is 00.
             Further arguments configure the _t_y_p_e_‐_s_i_z_e in  typographical  points
             (on  typesetting devices), and the face (_f_o_n_t).  On typesetting de‐
             vices, the default face is CCRR (Courier roman), a  monospaced  font:
             all glyphs are equally wide.

             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 argu‐
                     ments 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.  A _t_e_x_t_‐_i_n_d_e_n_t  argument  overrides  register
             PPii;  _m_a_r_k_‐_i_n_d_e_n_t sets the distance from the indentation of the cur‐
             rent list to the mark.  A third argument  suppresses  the  vertical
             space  that  normally  precedes  each  list item; see register LLsspp.
             Vertical space in the amount of LLsspp precedes the list  itself,  but
             does not accumulate with pre‐item space when this list is nested in
             another.   RRLL calls LLBB; use LLII to declare list items, and LLEE to end
             the list.

     VVMM [--TT] [_t_o_p [_b_o_t_t_o_m]]
             Configure vertical margins.

             Without a --TT argument, increment the top and bottom margins by  _t_o_p
             and  _b_o_t_t_o_m, respectively.  If absent, set the corresponding margin
             to zero.

             With the --TT argument, set the top and bottom  margins  to  _t_o_p  and
             _b_o_t_t_o_m,  respectively.  If absent, set the respective margin to the
             default (top: 77vv, bottom: 66vv).

             We recommend defining the hook macros TTPP and/or EEOOPP if using --TT and
             setting top and/or bottom margin to values less than  the  default.
             _g_r_o_f_f _m_m exposes this undocumented DWB macro to enable greater 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.  _m_m collects input into the
             writer’s address until the document calls WWEE, then outputs it.  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 subsequent
                      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.  We present their
     contents in quotation marks.

     AAbbssttrraacctt  “ABSTRACT”

     AApppp       “APPENDIX”

     AAppppttxxtt    stores the _t_i_t_l_e argument to the most recent AAPPPP call.

     AAuummtt      lists  space‐separated  indices of positional arguments to the AAUU
               macro that should be suppressed from appearance in  the  document
               heading  on  the first page of MMTT memorandum types 0–3 and 6.  By
               default, it is undefined; all arguments are formatted except  the
               second (author initials).

     BBUU        interpolates a bullet mark, \\[[bbuu]].

     CCaappeecc     “Equation”

     CCaappeexx     “Exhibit”

     CCaappffgg     “Figure”

     CCaappttbb     “Table”

     CCaappttcc     “CONTENTS”

     CCii        assigns  indentation amounts used by each heading level listed in
               a table of contents,  in  one‐to‐one  correspondence,  overriding
               those computed by TTCC.  Each word must be a horizontal measurement
               (like “11ii”).

     DDTT        stores  the  date  or  other identifier set by NNDD, if called, and
               otherwise one constructed using the formatter’s  date  registers;
               see _g_r_o_f_f(1).  The _g_r_o_f_f locale determines its format, but regis‐
               ter IIssooddaattee may override it.

     EEMM        interpolates an em dash, \\[[eemm]].

     FF         interpolates  an automatically numbered footnote mark; the number
               is used by the next FFSS call without an argument.  In _t_r_o_f_f  mode,
               the  mark  is  superscripted;  in _n_r_o_f_f mode, it is surrounded by
               square brackets.

     HH11ttxxtt     stores the text of the current first‐level heading; HH and HHUU  up‐
               date it, as does TTCC when processing table of contents entries and
               captions of displayed figures, tables, equations, and exhibits.

     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’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.  _g_r_o_f_f _m_m interprets each size in  ty‐
               pographical  points, translating zero values to 1100.  Omitted val‐
               ues 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 nota‐
               tion is included between parentheses, prefixed  with  LLeettnnss!!ccooppyy,
               and  suffixed with LLeettnnss!!ttoo.  Observe the spaces after “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  selects the notation format when NNSS is given  no  argument.   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”

     LLtt        “LIST OF TABLES”

     LLxx        “LIST OF EXHIBITS”

     MMOO11
     ...
     MMOO1122      “January” through “December”

     QQrrff       “See  chapter  \E*[Qrfh], page \En[Qrfp].”  If your document uses
               multiple heading levels, you might redefine this  string  to  use
               the word “section” instead of “chapter”.

     QQrrffhh      stores  the  heading  mark  corresponding to the most recent GGEETTRR
               call.

     QQrrffpp      stores the page number corresponding  to  the  most  recent  GGEETTRR
               call.

     RRff        interpolates an automatically numbered reference mark; the number
               is used by the next RRSS call.

     RRpp        “REFERENCES”

     RRppffmmtt     specifies the LLBB arguments that _g_r_o_f_f _m_m uses to format the items
               in an RRPP reference list.  The default is “\\\\nn[[LLii]] 00 11 00 \\&& 00”.

     RRgg        interpolates the registered (trade) mark sign.

     SSmm        interpolates the service mark sign.

     TTccssttaattuuss  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 11.

RReeggiisstteerrss
     Default register values, where meaningful, are shown in parentheses.

     ..mmggmm     indicates that _g_r_o_f_f _m_m is in use (Boolean‐valued; 11).

     AApphh      formats an appendix heading (and  title,  if  supplied);  see  AAPPPP
              (Boolean‐valued; 11).

     AAuu       includes supplemental author information (the third and subsequent
              arguments  to  AAUU) in memorandum “from” information; see CCOOVVEERR and
              MMTT, and the AAuummtt string (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.  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 un‐
              likely to get the result you want (22).

     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  standard
              error  stream.  A value of 0 outputs nothing; 1 reports formatting
              progress.  Higher values communicate internal state information 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  col‐
                      umn.
              3       Flush  a  pending display on the current page or column if
                      there is enough space, otherwise at the top of the next.
              4       Flush as many pending displays as possible in a  new  page
                      or column.
              5       Fill columns or pages with flushed displays until none re‐
                      main.

     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.

     EE        determines the font style used by MMTT memoranda,  LLTT  letters,  and
              the _m_s_._c_o_v cover page style to set the date and certain other doc‐
              ument data; 00 selects roman, and 11 bold (Boolean‐valued; 11).

     EEjj       sets  the threshold for page breaks (ejection) prior to the format
              of headings.  Headings at levels above this value are set  on  the
              same page and column as any preceding text if possible; see 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).

     FFttnnuumm    is an auto‐incrementing footnote counter; see FFSS.  _g_r_o_f_f _m_m recog‐
              nizes ::pp as an alias of FFttnnuumm for DWB compatibility.

     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 register HH11, but it is incremented just before a page
              break.  This can be useful in hook macros; see HH and HHXX.

     HHbb       sets  the threshold for breaking the line after formatting a head‐
              ing.  Text after headings at levels above this value is set on the
              same output line if possible.  Paragraphs numbered via nnPP  or  the
              NNpp register cause a break regardless; 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       selects  an  indentation policy for text formatted 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 ver‐
              tical  space; see HH.  Headings at levels above the value in regis‐
              ter 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 devices: 11vv).

     HHppss22     configures the amount of vertical space preceding a heading within
              the HHppss threshold; see HH (_t_r_o_f_f devices: 11vv; _n_r_o_f_f devices: 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 deepest when
              a heading mark 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).

     IIssooddaattee  configures the use of ISO 8601 date format;  that  is,  _Y_Y_Y_Y‐_M_M‐_D_D
              instead of the format specified by the localization file.  Call NNDD
              without arguments after updating its value (Boolean‐valued; 00).

     LL        defines the page length for the document, and must be set from the
              command  line.  A scaling unit should be appended.  The default is
              that of the selected _g_r_o_f_f output device.

     LLee
     LLff
     LLtt
     LLxx       configure the report of lists of equation, figure, table, and  ex‐
              hibit  captions,  respectively,  after a table of contents; see TTCC
              (all: Boolean‐valued; 11).

     LLeettwwaamm   sets the maximum number of input lines permitted in a writer’s ad‐
              dress; see WWAA and WWEE (1144).

     LLii       configures the text indentation (in  ens)  applied  to  enumerated
              list  types; that is, to items in AALL and RRLL lists, and in LLBB lists
              whose _t_y_p_e argument is greater than zero (55).

     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 (\\nn[[..RR]]).

     LLsspp      configures the base amount of vertical space used  for  separation
              in  the document.  _m_m applies this spacing to many contexts, some‐
              times with multipliers; see DDSS, FFSS, HH, LLII, and PP  (_t_r_o_f_f  devices:
              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 current
              first‐level heading) and _y the page  number  within  the  section.
              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 _g_r_o_f_f _m_m 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       numbers paragraphs with a leading mark in the  format  _s._p,  where
              _s  is is first‐level heading number and _p is the paragraph 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 default
              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 punctuation in the
              separator is either a dot or the EEMM string.  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 register %%
              except when “section‐page” numbering is enabled.

     PPii       configures  the  indentation (in ens) applied to the first line of
              an unnumbered paragraph that has such (see PP); and the text inden‐
              tation of non‐enumerated list items; that is, to items in BBLL, BBVVLL,
              DDLL, and VVLL lists (but not MMLL), and in LLBB lists whose _t_y_p_e argument
              is zero or less (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 EEFF 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, HHUU, DDEE, or LLEE

     RReeff      is used internally to control _m_m_r_o_f_f(1)’s two‐pass approach to in‐
              dex and reference management; see IINNDD, IINNDDPP, IINNIITTII, IINNIITTRR, and PPIICC
              (Boolean‐valued; 00).

     RRffnnuumm    is an auto‐incrementing reference counter; see RRSS.  _g_r_o_f_f _m_m  rec‐
              ognizes ::RR as an alias of RRffnnuumm for DWB compatibility.

     RRffssttyyllee  determines  the  format  of the reference number in the RRff string.
              _g_r_o_f_f _m_m maps 00 to 11 in _n_r_o_f_f mode and 22 in _t_r_o_f_f mode (00).

              VVaalluuee   MMeeaanniinngg
              0       automatic
              1       bracketed
              2       superscripted
              3       bracketed and superscripted

              Changes to RRffssttyyllee’s value may not  take  effect  until  the  next
              heading or paragraphing macro call.

     RRppeejj     configures  the  default page ejection policy for reference pages;
              see RRPP (00).

              VVaalluuee   EEffffeecctt
              0       Break the page before and after the reference list.
              1       Suppress page break after the list.
              2       Suppress page break before the list.
              3       Suppress page breaks before and after the list.

     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  un‐
              less register NN is set to 33 or 55 at the command line (Boolean‐val‐
              ued).

     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.
              This register is a _g_r_o_f_f _m_m extension.

     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  command
              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 argument (if any) to a CCOOVVEERR or MMTT call determines the file that  _g_r_o_f_f
     _m_m loads to configure the document’s layout; see section “Files” below.

     LLTT’s  behavior  depends  on the _s_t_y_l_e argument given to it; it calls macros
     with names suffixed accordingly.  It is therefore possible to define  addi‐
     tional letter types, either in the territory‐specific macro file, or as lo‐
     cal  additions.   LLTT sets the registers PPtt and PPii to 0 and 5, respectively.
     (DWB used a value of 3 for PPii.)  It then calls an initialization macro cor‐
     responding to the type.  Define the following macros to support a new  let‐
     ter type.

     lleett@@iinniitt___t_y_p_e
            initializes 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 un‐
            less 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 ...]
            is called by SSGG only for LLTT letters; MMTT  memoranda  implement  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 appended to
            the signature line.

     lleett@@ffcc___t_y_p_e _c_l_o_s_i_n_g
            is called by FFCC, and takes the formal closing as its 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 argu‐
     ment (_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_4_._1_/_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_4_._1_/_t_m_a_c_/_m_m_._t_m_a_c
            is a wrapper enabling the package to be loaded with the  option  “--mm
            mmmm”.

     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_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_4_._1_/_t_m_a_c_/_m_m_/_m_s_._c_o_v
            implements an _m_s‐like cover page.

     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_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_4_._1_/_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_4_._1_/_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_4_._1_/_t_m_a_c_/_m_m_/_l_o_c_a_l_e
            performs any (further) desired localization if present.

     _/_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_/_l_e_t_t_e_r_._m_m
            illustrates features of the LLTT letter formats.

     _/_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_e_m_o_r_a_n_d_u_m_._m_m
            illustrates features of the MMTT memorandum formats.

     _/_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_/_s_t_o_r_y_._m_m
            illustrates use of _m_m for literary purposes.

AAuutthhoorrss
     Jörgen Hägg of Lund, Sweden, wrote the version of the _m_m macro package dis‐
     tributed  with  _g_r_o_f_f based on an early version of _g_r_o_f_f _m_s by James Clark.
     Werner Lemberg and G. Branden Robinson revised and updated it.

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,  in‐
     troduces the package but does not document _g_r_o_f_f _m_m 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 Lem‐
     berg, 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.24.1                       2026‐04‐22                        _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ögerju‐
     sterad text.

     CCOOVVEERR  kan  använda _s_e___m_s som argument. Detta ger ett svenskt försättsblad.
     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änsterställt).

     ..LLTT SSVVHH
            Högerställd löptext med adressat i position  T4  (passar  fönsterku‐
            vert).

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

     ..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 lik‐
            nande).

     ..LLOO SSIIDDOORR _a_n_t_a_l
            Anger totala antalet sidor och skrivs ut efter sidnumret inom paren‐
            teser.

     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

FFiilleerr
     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_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_4_._1_/_t_m_a_c_/_m_m_/_s_e__*_._c_o_v

SSee oocckkssåå
     _g_r_o_f_f___m_m(7)

groff 1.24.1                       2026‐04‐22                      _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: typeset‐
     ting  and  document processing.  The former provide access to _g_r_o_f_f’s type‐
     setting capabilities in ways that are simpler to master  than  _g_r_o_f_f’s  re‐
     quests and escape sequences.  The latter provide highly customizable markup
     tags  that  allow  the user to design and output professional‐looking docu‐
     ments with a minimum of typesetting intervention.

     Files processed with _p_d_f_m_o_m(1) produce PDF documents.   The  documents  in‐
     clude  a  PDF outline that appears in the navigation pane panel of document
     viewers, and may contain clickable internal and external links.

     Normally, _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 PostScript  dri‐
     ver, _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 im‐
     ages.

     Files processed with ggrrooffff --mmoomm (or --mm mmoomm) format for the device specified
     with the --TT option.  (In this installation, ppss is the  default  output  de‐
     vice.)

     _m_o_m  comes with her own comprehensive documentation in HTML.  A PDF manual,
     “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_4_._1_/_t_m_a_c_/_m_o_m_._t_m_a_c
            is a wrapper enabling the package to be loaded with the  option  “--mm
            mmoomm”.

     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_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 num‐
            bered 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 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 \\**[[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 condense  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 num‐
            bered endnotes)

     \\**[[EEXXTT]]
     \\**[[EEXXTTXX]]
            Pseudo‐extending on/off

            \\**[[EEXXTT]] begins pseudo‐extending type.  \\**[[EEXXTTXX]]  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:
                   \\**[[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 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 \\**[[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 inlines to func‐
            tion properly.  Please see _I_M_P_O_R_T_A_N_T, below.

            String tabs need to be marked off with inline escape  sequences  be‐
            fore  being  set  up with the ..SSTT macro.  Any input line may contain
            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  horizontal
            movements, including padding) are taken into account when _m_o_m deter‐
            mines 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 cor‐
            rect  starting  position of string tabs marked off in lines that are
            centered or set flush right.

            Equally, she cannot guess the starting position if a line  is  fully
            justified and broken with ..SSPPRREEAADD.

            In  other  words,  in order to use string tabs, LLEEFFTT must be active,
            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 example, 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  beyond
            which  you  don’t  want  your type to go.  When the bottom margin is
            reached, _m_o_m starts a new page.  ..BB__MMAARRGGIINN rreeqquuiirreess aa uunniitt  ooff  mmeeaa‐‐
            ssuurree..   Decimal fractions are allowed.  To set a nominal bottom mar‐
            gin 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 document process‐
            ing macros are very hard‐nosed about aligning bottom margins.

            Note: The meaning of ..BB__MMAARRGGIINN is slightly different when you’re us‐
            ing 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 ex‐
            ist, either because you haven’t registered the style or because  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  prob‐
            lem.

            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  conjunc‐
            tion 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‐ex‐
                   istent  _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‐ex‐
                   istent _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; additionally, 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 key‐
            strokes, I recommend using ..FFAAMMIILLYY ffoorr _f_a_m_i_l_y, and ..FFTT ffoorr _f_o_n_t, ex‐
            cept 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.

            When running _g_r_o_f_f 1.19.2 or later, and you call the ..FFAAMMIILLYY  macro,
            _m_o_m  _r_e_m_e_m_b_e_r_s the font style (such as roman or italic) currently in
            use (if the font style exists in the new _f_a_m_i_l_y)  and  continues  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
            sets all subsequent type in the fallback font (by  default,  CCoouurriieerr
            MMeeddiiuumm  RRoommaann)  until she encounters a ..FFTT call 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  request
            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 information on
            adding  fonts and families to _g_r_o_f_f,_a_swell_a_sto see a list of the ex‐
            tensions _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  exam‐
            ple, 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 ..FFAAMMIILLYY.
            (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 arguments
            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  differing
            weights and shapes within the same family.

            Have  a  look  here for a list of the weight/style arguments _m_o_m al‐
            lows.  Be aware, though, that you must have the fonts, correctly in‐
            stalled 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 ver‐
            sion 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,  using  either  the
            fallback  font  or  the font that was in effect prior 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  ex‐
            cept 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 measure.

            A hanging indent looks like this:
                   The thousand injuries of Fortunato I had borne as best I
                     could, but when he ventured upon insult, I vowed
                     revenge.  You who so well know the nature of my soul
                     will not suppose, however, that I gave utterance to a
                     threat, at length I would be avenged...
            The first line of text _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 addi‐
            tive.   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 begin 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 indents;
            at  subsequent  invocations  when you wish to supply a measure, both
            must be given again.  As with ..IILL and ..IIRR, the measures are added to
            the values previously passed to the macro.  Hence, if  you  wish  to
            change  just one of the values, you must give an argument of zero to
            the other.

            _A _w_o_r_d _o_f _a_d_v_i_c_e_: If you need to manipulate left and  right  indents
            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  specify
            text‐dependent  measures,  in  which  case no unit of measure is re‐
            quired.  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  in‐
            dents by the width of _j_e_l_l_o.

            Like  ..IILL  and  ..IIRR, ..IIBB with no argument indents by its last active
            values.  See the brief explanation of how mom  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 ..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.  Subse‐
            quent invocations with a measure add to the previous measure.  A mi‐
            nus sign may be prepended to the argument to subtract from the  cur‐
            rent  measure.   The \\ww inline escape may be used to specify 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 indicat‐
            ing that you should update your documents.

            As a consequence of this change, ..IILLXX, ..IIRRXX and ..IIBBXX may now also be
            invoked as ..IILLQQ, ..IIRRQQ and ..IIBBQQ.  Both forms are acceptable.

            Without  an argument, the macros to quit indents merely restore your
            original margins and line length.  The measures stored in the indent
            macros themselves are saved so you can call them again without  hav‐
            ing to supply a measure.

            If  you pass these macros the optional argument 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 supply a measure
            again.

            ..IIQQ CCLLEEAARR, as you’d suspect, quits and clears the values for all in‐
            dent 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.  Subse‐
            quent 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 subtract  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 re‐
            quired.  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 value.

            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  start‐
            ing  any serious typesetting.  A unit of measure is required.  Deci‐
            mal fractions are allowed.  Therefore, to set the left margin  at  3
            picas (1/2 inch), you’d enter either
                   ..LL__MMAARRGGIINN 33PP
            or
                   ..LL__MMAARRGGIINN ..55ii

            If  you  use the macros ..PPAAGGEE, ..PPAAGGEEWWIIDDTTHH or ..PPAAPPEERR without invoking
            ..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 docu‐
            ment 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 ex‐
            planation of _m_u_l_t_i_‐_c_o_l_u_m_n_s and some sample input.

            _N_o_t_e_:  Do  not  confuse ..MMCCOO with the ..CCOOLLUUMMNNSS macro in the document
            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  moment
            ..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  measure;  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  baseline
            of the longest column, use ..MMCCXX with an argument of 00 (zero; 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 some‐
            thing 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 margin, 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 base‐
            line of the first line of text down by one  linespace.   To  compen‐
            sate, 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 en‐
            ter
                   ..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  al‐
            lowed.   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: LLEETT‐‐
            TTEERR, LLEEGGAALL, SSTTAATTEEMMEENNTT, TTAABBLLOOIIDD, LLEEDDGGEERR,  FFOOLLIIOO,  QQUUAARRTTOO,  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 example
                   ..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 requires 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  invoking
            ..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, overridden.

            Note: ..RR__MMAARRGGIINN behaves in a special way when you’re using the docu‐
            ment 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  direction
            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  linespace.
            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 con‐
            veniently, 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 zipping 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  in‐
            dent.

            _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 au‐
            tomatically 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 mea‐
            sure; _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 ad‐
            ditive.   In the following example, the second ""..TTII 22PP"" is exactly _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 argu‐
            ment 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 en‐
            tered
                   .TAB 1
                   Some text\c
                   .TN
                   Some more text\c
                   .TN
                   \&\c
                   .TN
                   Yet more text
            \&  is a zero‐width, non‐printing character that _g_r_o_f_f recognizes as
            valid input, hence meets the requirement for  input  text  following
            ..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 mea‐
            sure, 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 base‐
            line.  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 margins in docu‐
            ment 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  position  on  the
            current  page.   Therefore, ..TT__MMAARRGGIINN should only be used at the top
            of a file (prior to entering text) or after NEWPAGE, like this:
                   ..NNEEWWPPAAGGEE
                   ..TT__MMAARRGGIINN 66PP
                   _<_t_e_x_t_>

AAuutthhoorrss
     Peter Schaffter wrote _m_o_m.  Deri James added  PDF  support.   Bernd  Warken
     contributed this man page.

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
            _m_o_m manual (installed version)

     _m_o_m manual
            (latest version)

     _m_o_m 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 Lem‐
     berg, 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.24.1                       2026‐04‐22                       _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 docu‐
     ment formatting system.  The _m_s package is suitable for the composition  of
     letters, memoranda, reports, and books.

     These _g_r_o_f_f macros support cover page and table of contents generation, au‐
     tomatically  numbered headings, several paragraph styles, a variety of text
     styling options, footnotes, and multi‐column page layouts.  _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 inclusion of tables,
     mathematical equations, diagrams, and consistently formatted  bibliographic
     citations.

     _g_r_o_f_f _m_s is mostly compatible with the documented interface and behavior of
     AT&T  Unix  Version 7 _m_s.  It recreates most extensions from 4.2BSD (Berke‐
     ley) and Research Tenth Edition Unix.

DDooccuummeenntt ssttrruuccttuurree
     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 com‐
     pose  a  simple document from scratch, begin it by calling LLPP or PPPP.  Orga‐
     nize longer documents as follows.

     DDooccuummeenntt ttyyppee
            Calling the RRPP macro at the beginning of your document puts the doc‐
            ument 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  implementations  are
            specific to AT&T or Berkeley, and are not supported in _g_r_o_f_f _m_s.

     FFoorrmmaatt aanndd llaayyoouutt
            By  setting registers and strings, you can configure your document’s
            typeface,  margins,  spacing,  headers  and  footers,  and  footnote
            arrangement.  See subsection “Document control settings” below.

     DDooccuummeenntt ddeessccrriippttiioonn
            A  document description consists of any of: a title, one or more au‐
            thors’ names and affiliated institutions, an abstract, and a date or
            other identifier.  See subsection “Document description macros”  be‐
            low.

     BBooddyy tteexxtt
            The  main  matter of your document follows its description (if any).
            _m_s supports highly structured text consisting of  paragraphs  inter‐
            spersed  with multi‐level headings (chapters, sections, subsections,
            and so forth) and augmented by lists, footnotes,  tables,  diagrams,
            and similar material.  The preponderance of subsections below covers
            these matters.

     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.   A
            macro  call  at the end of the document emits the collected entries.
            This material necessarily follows the rest of  the  text  since  GNU
            _t_r_o_f_f  is a single‐pass formatter; it cannot determine the page num‐
            ber of a division of the text until it  has  been  set  and  output.
            Since  _m_s  output  was designed for the production of hard copy, the
            traditional procedure was to manually relocate the pages  containing
            the table of contents between the cover page and the body text.  To‐
            day, page resequencing is more often done in the digital domain.  An
            index  works  similarly, but because it typically needs to be sorted
            after collection, its preparation requires separate processing.

   DDooccuummeenntt ccoonnttrrooll sseettttiinnggss
     The following tables list the document control registers, strings, and spe‐
     cial characters.  For any parameter whose default is unsatisfactory, define
     it before calling any _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 (type) size                     next paragraph   10p
     \n[VS]      Vertical spacing (leading)            next paragraph   12p
     \n[HY]      Hyphenation mode                      next paragraph   6
     \*[FAM]     Font family                           next paragraph   T
     ───────────────────────────────────────────────────────────────────────────

                                 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 (type) size increment       next heading   1p
     \n[GROWPS]     Size increase depth limit         next heading   0
     \n[HORPHANS]   # of following lines kept         next heading   1
     \*[SN-STYLE]   Numbering style (alias)           next heading   \*[SN-DOT]
     ───────────────────────────────────────────────────────────────────────────

     \\**[[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 (type) size                   next footnote   \n[PS]-2p
     \n[FVS]     Vertical spacing (leading)          next footnote   \n[FPS]+2p
     \n[FPD]     Paragraph distance (spacing)        next footnote   \n[PD]/2
     \*[FR]      Line length ratio                   _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 discussion
     in the applicable section below.  The PPOO, LLLL, and LLTT register defaults vary
     by output device and paper format; the values shown are for typesetters us‐
     ing U.S. letter paper, and then terminals.  See section “Paper  format”  of
     _g_r_o_f_f(1).  The PPDD and DDDD registers use the larger value if the vertical mo‐
     tion  quantum  of the output device is too coarse for the smaller one; usu‐
     ally, this is the case only for output to terminals.  The “gutter” affected
     by \\nn[[MMIINNGGWW]] is the gap between columns in  multiple‐column  page  arrange‐
     ments.   The  TTCC--MMAARRGGIINN register and TTCC--LLEEAADDEERR special character affect the
     formatting 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 in‐
     formation is required in a header or footer.  Use of these  macros  is  op‐
     tional,  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  document,
            creating a separate cover page.  The default arrangement is to place
            most  of  the document description (title, author names and institu‐
            tions, and abstract, but not the date) at the top of the first page.
            If the optional nnoo--rreeppeeaatt--iinnffoo argument  is  given,  _m_s  produces  a
            cover  page  but does not repeat any of its information subsequently
            (but see the DDAA macro below regarding the date).  Normally, RRPP  sets
            the  page  number following the cover page to 1.  Specifying the op‐
            tional nnoo--rreennuummbbeerr argument suppresses  this  alteration.   Optional
            arguments  can occur in any order.  _m_s recognizes nnoo as a synonym of
            nnoo--rreeppeeaatt--iinnffoo to maintain AT&T compatibility.  Options  other  than
            nnoo are GNU extensions.

     ..TTLL    Specify the document title.  _m_s collects text on input lines follow‐
            ing  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 following
            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  institutional  affiliation.   An  AAUU
            call is usefully 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  default,  _m_s
            places the word “ABSTRACT” centered and in italics above the text of
            the abstract.  The optional argument “nnoo” suppresses 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  vertical
     spacing  (distance  between text baselines), respectively.  The font family
     and type size are ignored on terminals.  Set these  parameters  before  the
     first  call  of a heading, paragraphing, or (non‐date) document description
     macro to apply them to headers, footers, and (for FFAAMM) footnotes.

     The HHYY register defines the automatic hyphenation mode used with the hhyy re‐
     quest.  Setting \\nn[[HHYY]] to 00 disables automatic hyphenation.  This is a  Re‐
     search Tenth Edition Unix extension.

   TTyyppooggrraapphhiiccaall ssyymmbboollss
     _m_s  provides  a  few strings to obtain typographical symbols not easily en‐
     tered with the keyboard.  These and many others are  available  as  special
     character escape sequences——see _g_r_o_f_f___c_h_a_r(7).

     \\**[[--]]  Interpolate an em dash.

     \\**[[QQ]]
     \\**[[UU]]  Interpolate  typographer’s quotation marks where available, and neu‐
            tral 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.
     These calls insert 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 starts close to the bottom of a page, and
     there is insufficient space to accommodate \\nn[[PPOORRPPHHAANNSS]] lines before an au‐
     tomatic page break, _g_r_o_f_f _m_s forces a  page  break  before  formatting  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 [_w_i_d_t_h]]
            Set a paragraph with a left indentation.  The optional _m_a_r_k  is  not
            indented,  is  useful  in the construction of lists, and is empty by
            default.  _w_i_d_t_h overrides the indentation amount in \\nn[[PPII]]; its  de‐
            fault  unit  is  “nn”.   Once  specified, _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 indented
            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  default,
     type  size as the body text.  Headings are available with and without auto‐
     matic numbering.  Text on input lines following the macro call becomes  the
     heading’s  title.   Call  a  paragraphing macro to end the heading text and
     start the section’s content.

     ..NNHH [_d_e_p_t_h]
            Set an automatically numbered heading.  _m_s produces a numbered head‐
            ing 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 out‐
            put.   If  _d_e_p_t_h  is  omitted, _m_s assumes “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  indices  as  their
            predecessors.  This feature is a Berkeley extension.

     After  NNHH  is  called, the assigned number is made available in the strings
     SSNN--DDOOTT (as it appears in a printed heading with  default  formatting,  fol‐
     lowed  by  a terminating period) and SSNN--NNOO--DDOOTT (with the terminating period
     omitted).  These, and SSNN--SSTTYYLLEE, 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 docu‐
     mented by Berkeley); this string facilitates 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 ex‐
            tension indicating the heading depth corresponding to the _d_e_p_t_h  ar‐
            gument  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 mechanism 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 in‐
     crement 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 incremental  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 produced  by  these
     macros  increases by \\nn[[PPSSIINNCCRR]] units over \\nn[[PPSS]] multiplied by the differ‐
     ence of \\nn[[GGRROOWWPPSS]] and _d_e_p_t_h.  GGRROOWWPPSS and PPSSIINNCCRR are GNU extensions.

     In _g_r_o_f_f _m_s_, the NNHH and SSHH macros consult the HHOORRPPHHAANNSS register to  prevent
     the  output  of isolated headings at the bottom of a page; it specifies the
     minimum number of lines of the subsequent paragraph that must  be  kept  on
     the same page as the heading.  If insufficient space remains on the current
     page to accommodate the heading and this number of lines of paragraph text,
     _g_r_o_f_f _m_s forces a page break before setting the heading.  Any display macro
     call  or  _t_b_l,  _p_i_c,  or  _e_q_n region between the heading and the subsequent
     paragraph suppresses this grouping.  This is a GNU extension.

   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 intuitive.
     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.  Without
            arguments, _m_s styles subsequent text in bold until  the  next  para‐
            graphing, 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) in‐
            stead 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 Research Tenth Edition Unix extension.

     ..CCWW [_t_e_x_t [_p_o_s_t [_p_r_e]]]
            As BB, but use a constant‐width (monospaced) roman  typeface  instead
            of bold.  This is a Research Tenth Edition Unix extension.

     ..BBXX [_t_e_x_t]
            Typeset  _t_e_x_t and draw a box around it.  On terminals, reverse 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.  On  terminals,  _t_e_x_t  is  bracketed
            with underscores (“_”).  _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.
            Call the macro multiple times to enlarge the type size further.

     ..SSMM    Set  subsequent text in smaller type (2 points smaller than the cur‐
            rent size) until the next type size, paragraphing, or heading  macro
            call.   Call  the  macro multiple times to reduce the type size fur‐
            ther.

     ..NNLL    Set subsequent text at the normal type size (\\nn[[PPSS]]).

     When _p_r_e is used, a hyphenation control escape sequence \\%% that would ordi‐
     narily 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  can  indent  a  region of text while otherwise formatting it normally.
     Such indented regions can be nested.

     ..RRSS    Begin a region where headings, paragraphs, and displays are indented
            (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 it, allowing text following the keep (in the  source
     document)  to  fill  in  the  remainder of the current page.  When the page
     breaks by reaching its bottom or by 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 ar‐
     gument 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; to box words within a line,  recall  BBXX  in
     section  “Highlighting”  above.   _m_s draws box lines close to the text they
     enclose so that they are usable  within  paragraphs.   When  boxing  entire
     paragraphs  thus,  you may improve their appearance by calling BB11 after the
     first paragraphing macro, and invoking the sspp request before calling BB22.

     If you want a boxed keep to float, 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 allowed 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 cen‐
            tered.

     ..DDSS RR
     ..RRDD    Begin (DDSS: kept) right‐aligned display.  This is a GNU extension.

     ..DDEE    End any display.

     _g_r_o_f_f _m_s inserts the distance stored in \\nn[[DDDD]] before and after  each  pair
     of  display  macros;  this is a Berkeley extension.  This distance replaces
     any adjacent inter‐paragraph distance or subsequent spacing prior to a sec‐
     tion heading.  The DDII register is a GNU extension; its value is an indenta‐
     tion 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 effect at the next display boundary.

   TTaabblleess,, ffiigguurreess,, eeqquuaattiioonnss,, aanndd rreeffeerreenncceess
     _m_s  often  sees use with the _t_b_l, _p_i_c, _e_q_n, and _r_e_f_e_r preprocessors.  _g_r_o_f_f
     _m_s applies the \\nn[[DDDD]] distance to regions of the document preprocessed with
     _e_q_n, _p_i_c, and _t_b_l.  Mark text meant for preprocessors by  enclosing  it  in
     pairs  of  tokens  as  follows,  with nothing between the dot and the macro
     name.  Preprocessors match these tokens only at the start of an input line.
     The formatter interprets them as macro calls.

     ..TTSS [HH]
     ..TTEE    Demarcate a table to be processed by the _t_b_l preprocessor.  The  op‐
            tional  HH  argument  instructs _m_s to repeat table rows (often column
            headings) at the top of each new page the table spans,  if  applica‐
            ble;  calling  the TTHH macro marks the end of such rows.  _t_b_l(1) pro‐
            vides a comprehensive reference to the preprocessor and offers exam‐
            ples of its use.

     ..PPSS _h _v
     ..PPEE
     ..PPFF    PPSS marks the start of a _p_i_c(1) preprocessor diagram; either of PPEE or
            PPFF ends it, the latter with “flyback” to the  vertical  position  at
            its  top.  _h and _v are the horizontal and vertical dimensions of the
            picture; _p_i_c supplies them automatically.

     ..EEQQ [_a_l_i_g_n [_l_a_b_e_l]]
     ..EENN    Demarcate mathematics to be processed by the _e_q_n  preprocessor.   _m_s
            centers the equation by default; _a_l_i_g_n can be CC, LL, or II to (explic‐
            itly)  center, left‐align, or indent it by \\nn[[DDII]], respectively.  _m_s
            right‐aligns any _l_a_b_e_l.  See _e_q_n(1).

     ..[[
     ..]]     Demarcate a bibliographic citation to be processed by the _r_e_f_e_r pre‐
            processor.  _r_e_f_e_r(1) provides a comprehensive reference to the  pre‐
            processor 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  unnumbered  heading
     (..SSHH).

     Attempting to place a multi‐page table inside a keep can lead to unpleasant
     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_, 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  foot‐
            note  mark, in the text.  Each time this string is interpolated, the
            number it produces increments by one.  Automatic numbers start at 1.
            This is a Berkeley extension.

     Enclose the footnote text in 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]
            Begin a footnote.  The FFSS--MMAARRKK hook (see below) is called  with  any
            supplied  _m_a_r_k  argument, which is then also placed at the beginning
            of the footnote text.  If _m_a_r_k is omitted, the  next  pending  auto‐
            matic  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 arguments
     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 parameters.
     The registers FFII, FFPPDD, FFPPSS, and FFVVSS correspond to PPII, PPDD, PPSS, and  VVSS,  re‐
     spectively; FFPPDD, FFPPSS, and FFVVSS are GNU extensions.

     The  FFFF register controls the formatting of automatically numbered footnote
     paragraphs, and those for which FFSS is given a _m_a_r_k argument, at the  bottom
     of a column or page as follows.

            0      Set  an automatic number, or a specified FFSS _m_a_r_k argument, as
                   a superscript (on typesetters) or surrounded by square brack‐
                   ets (on terminals).  The footnote paragraph  is  indented  as
                   with  PPPP  if  there is an FFSS argument or an automatic number,
                   and as with LLPP otherwise.  This is the default.

            1      As 00, but set _m_a_r_k 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 _m_a_r_k hanging (like
                   IIPP).

   LLaanngguuaaggee aanndd llooccaalliizzaattiioonn
     _g_r_o_f_f _m_s provides several strings that you can customize for your own  pur‐
     poses,  or redefine to adapt the macro package to languages other than Eng‐
     lish.  It is already localized for Czech, German, Spanish, French, Italian,
     Polish, Russian, and Swedish.  Load the desired localization macro  package
     after _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  define
     the  strings LLHH, CCHH, and RRHH to set the left, center, and right headers, re‐
     spectively; and LLFF, CCFF, and RRFF to set the left, center, and right  footers.
     This approach suffices for documents that do not distinguish odd‐ and even‐
     numbered pages.

     Another  method  is  to call macros that set headers or footers for odd‐ or
     even‐numbered pages.  Each such macro takes a delimited argument separating
     the left, center, and right header or footer texts from  each  other.   You
     can  replace the neutral apostrophes (') shown below with any character not
     appearing in the header or footer text.  These macros are  Berkeley  exten‐
     sions.

     ..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‐num‐
            bered (verso) pages, respectively; the OOFF and EEFF macros define foot‐
            ers for them.

     With either method, a percent sign %% in header or footer text  is  replaced
     by the current page number.  By default, _m_s places no header on a page num‐
     bered “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 numbered “1”.
            This is a Berkeley extension.

     For  even greater flexibility, _m_s is designed to permit the redefinition of
     the macros that are called when formatter traps that ordinarily  cause  the
     headers and footers to be output are sprung.  PPTT (“page trap”) is called by
     _m_s when the header is to be written, and BBTT (“bottom 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  de‐
     fine HHDD if you need additional processing after setting the header.  The HHDD
     hook  is  a Berkeley extension.  Any such macros you (re)define must imple‐
     ment 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  set‐
     ting  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 fol‐
     lowing 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 instead 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 arguments,
            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 minimum distance be‐
            tween 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 because a  heading  is  too
     long  to  fit  or because style dictates that page numbers not be repeated.
     You may wish to indent the text thus wrapped to correspond to  its  heading
     depth; this can be done in the entry text by prefixing it with tabs or hor‐
     izontal  motion  escape sequences, or by providing a second argument to the
     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 resets 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 entry 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 supplemental entry is in‐
            dented  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, center
            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 ob‐
     viates the need to repeat heading text after XXSS calls.  Call XXNN and XXHH  af‐
     ter  NNHH and SSHH, respectively.  Text to be appended to the formatted section
     heading, but not to appear in the table of contents entry, 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 en‐
            try; the indentation is computed from the _d_e_p_t_h argument of the pre‐
            ceding 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  production.
     (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 arguments 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 con‐
     tents entry with its page number; define the TTCC--LLEEAADDEERR special character 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 described above
     as Berkeley and Research Tenth Edition Unix extensions, and adds several of
     its own.

     •  The  internals of _g_r_o_f_f _m_s differ from those 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 docu‐
        mented  in the AT&T _m_s manual (“Typing Documents on the UNIX System: Us‐
        ing the -ms Macros with Troff and Nroff”, M. E. Lesk, Bell Laboratories,
        1978).

     •  The error‐handling policy of _g_r_o_f_f _m_s is to detect  and  report  errors,
        rather than to ignore them silently.

     •  Research Tenth Edition Unix supported PP11/PP22 macros to bracket code exam‐
        ples; _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 diagnostic
        message.

     •  Multiple line spacing is not supported.  Use a larger  vertical  spacing
        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 dis‐
        plays, cause a reset of paragraph rendering parameters, and  may  change
        the  indentation; they do so not by incrementing or decrementing it, but
        by setting it absolutely.  This can cause problems  for  documents  that
        define  additional macros of their own that manipulate indentation.  Use
        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  “Mea‐
        surements”  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 document.

     •  AT&T _m_s’s AAUU macro supported arguments whose values were used with  some
        non‐RRPP document types; that of _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  ac‐
        cess  the page number via the usual %% register and invoke the aaff request
        to assign a different format to it if desired.  (If you redefine 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  default
        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 sec‐
        ond  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.

     •  _g_r_o_f_f _m_s sets the register GGSS to 1; the AT&T _m_s package does not use it.
        A document can test its value to determine whether it is being formatted
        with _g_r_o_f_f _m_s or another implementation.

   UUnniixx VVeerrssiioonn 77 mmaaccrrooss uunniimmpplleemmeenntteedd bbyy _gg_rr_oo_ff_ff _mm_ss
     Several  macros  described in the Unix Version 7 _m_s documentation are unim‐
     plemented by _g_r_o_f_f _m_s because they are specific to the requirements of doc‐
     uments produced internally by Bell Laboratories, some of which also require
     a glyph for the Bell System logo that _g_r_o_f_f does not support.  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 addresses of Bell Labs  sites  (HHOO,  IIHH,
     MMHH, PPYY, WWHH), or lacked a stable definition over time (UUXX).

LLeeggaaccyy ffeeaattuurreess
     _g_r_o_f_f  _m_s retains some legacy features solely to support formatting of his‐
     torical 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
     External  names available to documents that use the _g_r_o_f_f _m_s macros contain
     only uppercase letters and digits.  The package reserves for  internal  use
     the following identifiers:

     •  those containing the characters **, @@, and ::; and

     •  those containing only uppercase letters and digits.

     When  selecting  a name for your document’s own macros, strings, and regis‐
     ters, avoid those reserved by _g_r_o_f_f _m_s and those defined by GNU _t_r_o_f_f.  See
     _g_r_o_f_f(7) for complete lists thereof.

     _g_r_o_f_f _m_s organizes most of its internal names  into  modules.   The  naming
     convenion is 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.

     •  Names constructed to implement arrays are of the form _a_r_r_a_y!!_i_n_d_e_x.

FFiilleess
     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_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_4_._1_/_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_4_._1_/_t_m_a_c_/_m_s_._t_m_a_c
            is  a  wrapper enabling the package to be loaded with the option “--mm
            mmss”.

AAuutthhoorrss
     The GNU version of the _m_s macro package was written by James Clark and con‐
     tributors.  This document was written by Clark, Larry Kollar, and G.  Bran‐
     den 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 extension
            package, enabling colored, bordered boxes when the ppddff output 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  Lem‐
     berg,  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.24.1                       2026‐04‐22                        _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 digraph
     table of the text editor Vim.  Each escape sequence translates to a Unicode
     code  point,  and will render correctly if the underlying font is a Unicode
     font that covers the code point.

     For example, “\\[[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 se‐
     quence with a mnemonic glyph name, its second argument is a special charac‐
     ter escape sequence based on the code point, and the comment describes  the
     glyph defined.

     The RFC 1345 glyph names cover a wide range of Unicode code points, includ‐
     ing   supplemental   Latin,  Greek,  Cyrillic,  Hebrew,  Arabic,  Hiragana,
     Katakana, and Bopomofo letters, punctuation, math notation,  currency  sym‐
     bols, industrial and entertainment icons, and box‐drawing symbols.

     The  Vim  digraph  table  is largely a subset of RFC 1345 (being limited to
     two‐character mnemonics), but, as  a  newer  implementation,  adds  several
     mnemonics not specified in the RFC (Latin capital and small letters W and Y
     with  grave  accent,  bullet,  horizontal  ellipsis,  quadruple prime, “ap‐
     proaches the limit”, and two mappings each for the Euro and rouble  signs).
     These have also been added to _r_f_c_1_3_4_5_._t_m_a_c.

     _r_f_c_1_3_4_5_._t_m_a_c  contains about 1,700 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  con‐
     tains the glyphs that you actually use in your document.

     The  RFC 1345 mnemonics are not identical in every case to the mappings for
     special character glyph names that are built  in  to  _g_r_o_f_f;  for  example,
     “\\[[<<<<]]”  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 char‐
     acters defined in _r_f_c_1_3_4_5_._t_m_a_c are accented Latin letters, and will be  af‐
     fected by this deficiency, producing subpar typography.

FFiilleess
     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_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.24.1                       2026‐04‐22                   _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,  de‐
     signed  as  an aid for debugging documents written in its language.  It is‐
     sues a message to the standard error stream upon entry  to  and  exit  from
     each  macro  call.   This can ease the process of isolating errors in macro
     definitions.

     Activate the package by specifying the command‐line option  “--mm  ttrraaccee”  to
     the  formatter  program (often _g_r_o_f_f(1)).  You can achieve finer control 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 arguments
     are expanded one level more.  This causes problems if an argument uses four
     or more backslashes to delay interpretation of an escape sequence.  For ex‐
     ample, the macro call
            .foo \\\\n[bar]
     normally passes “\\n[bar]” to macro “foo”, but with 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  es‐
     cape character that is not interpreted in copy mode.
            .foo \En[bar]

FFiilleess
     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_t_m_a_c_/_t_r_a_c_e_._t_m_a_c
            implements the package.

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 standard  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 so when employing a macro package like _m_s or _m_o_m, to
     avoid distraction 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  defined
     (by _s_._t_m_a_c), their calls were not traced; contrast with the macro “Mymac”.

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  Lem‐
     berg,  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.24.1                       2026‐04‐22                     _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 automatically
     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 “--TT hhttmmll” or “--TT xxhhttmmll”.  The HTML output
     driver _g_r_o_h_t_m_l(1) is in a beta state; _g_r_o_f_f distributes these macros to en‐
     courage its testing.

     Macro       Meaning
     ────────────────────────────────────────────────────────────
     JJOOBBNNAAMMEE     split output into multiple files
     HHXX          automatic heading level cut‐off
     BBCCLL         specify colours on a web page
     BBGGIIMMGG       specify background image
     UURRLL         create a URL using two parameters
     MMTTOO         create an HTML email address
     TTAAGG         generate an HTML name
     IIMMGG         include an image file
     PPIIMMGG        include PNG image
     MMPPIIMMGG       place PNG on the margin and wrap text around it
     HHnnSS         begin heading
     HHnnEE         end heading
     LLKK          emit automatically collected links
     HHRR          produce a horizontal rule
     NNHHRR         suppress automatic generation of rules
     HHTTLL         record document title as HTML metadata only
     HHEEAADD        add data to <head> block
     UULLSS         unordered list begin
     UULLEE         unordered list end
     OOLLSS         ordered list begin
     OOLLEE         ordered list end
     DDLLSS         definition list begin
     DDLLEE         definition list end
     LLII          insert a list item
     DDCC          generate a drop capital
     HHTTMMLL        transmit raw HTML to output driver
     CCDDSS         code example begin
     CCDDEE         code example end
     AALLNN         place links on left of main text
     LLNNSS         start two‐column table with links on the left
     LLNNEE         end two‐column table started with ..LLNNSS
     LLIINNKKSSTTYYLLEE   initialize default URL attributes

MMaaccrrooss
     JJOOBBNNAAMMEE _f_i_l_e_‐_n_a_m_e_‐_s_t_e_m
              Split output into multiple HTML files.  In _m_s documents, a file is
              split whenever an ..SSHH or “..NNHH 11” call is encountered.   Its  argu‐
              ment  is the file name stem used for output files.  This option is
              equivalent to _g_r_o_h_t_m_l’s --jj option.

     HHXX _n     Set section heading level above which _g_r_o_h_t_m_l is not to  automati‐
              cally  generate  links  to  _n_.   For  example,  when used with the
              _g_r_o_f_f___m_s(7) package, “..HHXX 22” causes _g_r_o_h_t_m_l to generate a list  of
              links  for _m_s macro calls “..NNHH 11” and “..NNHH 22” but not for “..NNHH 33”,
              whereas “..HHXX 00” generates no hyperlinks to section headings.  Giv‐
              ing _g_r_o_f_f the option “--PP --ll” disables automatic heading linkage.

     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
              Configure colours used for page foreground, page  background,  ac‐
              tive  hypertext link, hypertext links not yet visited, and visited
              hypertext links.

     BBGGIIMMGG _f_i_l_e
              Set the background image to _f_i_l_e_.

     UURRLL _u_r_l [_l_i_n_k_‐_t_e_x_t [_p_o_s_t]]
              Generate a hyperlink to _u_r_l with optional _l_i_n_k_‐_t_e_x_t followed imme‐
              diately by non‐linked text _p_o_s_t_.

              If _l_i_n_k_‐_t_e_x_t is absent, _u_r_l is formatted as the  link  text.   Hy‐
              phenation  is  disabled  while  formatting  a URL; insert explicit
              break points with the \\:: escape sequence.

     MMTTOO _a_d_d_r_e_s_s [_l_i_n_k_‐_t_e_x_t [_p_o_s_t]]
              Generate an email hyperlink to  _a_d_d_r_e_s_s  with  optional  _l_i_n_k_‐_t_e_x_t
              followed immediately by non‐linked text _p_o_s_t_.

              If  _l_i_n_k_‐_t_e_x_t  is  absent,  _a_d_d_r_e_s_s is formatted as the link text.
              Hyphenation is disabled while formatting a  URL;  insert  explicit
              break points with the \\:: escape sequence.

     TTAAGG _n_a_m_e
              Generate  an anchor _n_a_m_e marking its location in the document as a
              target for hyperlinks.

     IIMMGG _f_i_l_e_‐_n_a_m_e [--CC|--LL|--RR] [_w_i_d_t_h [_h_e_i_g_h_t]]
              Insert graphical image _f_i_l_e_‐_n_a_m_e_.  The  optional  second  argument
              aligns  the image to the center (--CC; default), left (--LL), or right
              (--RR).  The optional _w_i_d_t_h defaults to 100 units (in the context of
              the HTML renderer) and the optional _h_e_i_g_h_t to the same measurement
              as _w_i_d_t_h _.

     PPIIMMGG [--CC|--LL|--RR] _f_i_l_e_‐_n_a_m_e [_w_i_d_t_h [_h_e_i_g_h_t]]
              Insert graphical image _f_i_l_e_‐_n_a_m_e_, assumed to  be  in  PNG  format.
              Compared to IIMMGG, this macro has the advantage of working with both
              PostScript  and  HTML devices since it converts _f_i_l_e_‐_n_a_m_e into EPS
              format using _p_n_g_t_o_p_n_m(1), _p_n_m_c_r_o_p(1), and _p_n_m_t_o_p_s(1).  _h_e_i_g_h_t  and
              _w_i_d_t_h  may  be given as percentages (of the line length \\nn[[..ll]] and
              page length \\nn[[..pp]], respectively).

              If the document isn’t processed with “--TT hhttmmll” or “--TT xxhhttmmll”,  you
              must use _g_r_o_f_f(1)’s --UU option.

     MMPPIIMMGG [--LL|--RR] [--GG _g_a_p] _f_i_l_e_‐_n_a_m_e [_w_i_d_t_h [_h_e_i_g_h_t]]
              As  PPIIMMGG, but place the image at a margin and wrap text around it.
              The image is aligned the to the left (--LL, default) or  right  (--RR)
              margin.  --GG _g_a_p imposes horizontal space of _g_a_p pixels between the
              picture  and  the  text  that wraps around it.  The default _g_a_p is
              zero.

     HHnnSS _n    Begin heading at level _n_.

     HHnnEE      End heading text.

     LLKK       Direct _g_r_o_h_t_m_l to emit the list of automatically generated  hyper‐
              links at this location.

     HHRR       Generate  a full‐width horizontal rule when used with “--TT hhttmmll” or
              “--TT xxhhttmmll”.

     NNHHRR      Suppress the horizontal rules at the  document’s  top  and  bottom
              that _g_r_o_h_t_m_l emits by default.

     HHTTLL      Generate  an  HTML title only.  This differs from _g_r_o_f_f___m_s(7)’s TTLL
              macro, which generates both an HTML title  and  an  <H1>  heading.
              Use  it  to  provide an HTML title as document metadata but not as
              formatted text.  The title ends when vertical  space  (..sspp)  or  a
              break (..bbrr) is seen.

     HHEEAADD     Add  arbitrary  data  to  the HTML <head> element.  Ignored if not
              processed with “--TT hhttmmll” or “--TT xxhhttmmll”.

     HHTTMMLL     All text after this macro is treated as raw HTML.  Ignored if  not
              processed with “--TT hhttmmll” or “--TT xxhhttmmll”.

     DDCC _L _t_e_x_t [_c_o_l_o_r]
              Format  a  “drop cap”——a large character _L (usually a capital let‐
              ter) at a larger size and with a lower text baseline than the fol‐
              lowing _t_e_x_t_, such that the cap‐heights of _L and _t_e_x_t align, in the
              specified _c_o_l_o_r (default: black).

     CCDDSS      Begin code display; a monospaced font is selected and  filling  is
              disabled.

     CCDDEE      End code display.

     AALLNN [_c_o_l_o_r [_w_i_d_t_h_‐_p_e_r_c_e_n_t_a_g_e]]
              Enable  a  “navigation pane” containing links to section headings,
              aligned to the left of running text, and configure  its  rendering
              parameters.   Columnation  is  achieved with an HTML table.  _c_o_l_o_r
              indicates an HTML background color to be used  in  the  navigation
              column;  the  default  is ##eeeeeeeeeeee.  _w_i_d_t_h_‐_p_e_r_c_e_n_t_a_g_e allocates the
              given percentage of the navigation pane’s table  column;  the  de‐
              fault  is  3300.   Call this macro at most once, at the beginning of
              the document.

     LLNNSS      Begin text indexed by the navigation pane configured by AALLNN.

     LLNNEE      End text indexed by navigation pane started by LLNNSS.

     LLIINNKKSSTTYYLLEE _c_o_l_o_r [_f_o_n_t_‐_s_t_y_l_e [_o_p_e_n_‐_g_l_y_p_h _c_l_o_s_e_‐_g_l_y_p_h]]
              Configure rendering of formatted  hyperlink  targets  for  devices
              other than hhttmmll and xxhhttmmll; render targets in _c_o_l_o_r (default: blue)
              using  the  typeface _f_o_n_t_‐_s_t_y_l_e (default: CCRR) bracketed with _o_p_e_n_‐
              _g_l_y_p_h and _c_l_o_s_e_‐_g_l_y_p_h (defaults: \\[[llaa]] and \\[[rraa]], respectively).

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.  Configure this behavior  with  HHXX  and/or
     LLKK.

LLiimmiittaattiioonnss ooff _gg_rr_oo_hh_tt_mm_ll
     _t_b_l(1) tables are rendered as PNG images.

     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  cir‐
     cumvent  this,  _w_w_w_._t_m_a_c  inserts a zero‐width character which expands to a
     harmless space (only if run with --TThhttmmll or --TTxxhhttmmll).

     Some of the macros, like AALLNN, LLNNSS, and LLNNEE, are integrated  only  with  the
     _g_r_o_f_f___m_s(7) package.

FFiilleess
     _/_u_s_r_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._2_4_._1_/_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.24.1                       2026‐04‐22                       _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  inter‐
     preter for an extensible text formatting language and a set of programs for
     preparing output for various devices and file formats.  Unix‐like operating
     systems  often  distribute a _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 wide‐
     spread _r_o_f_f implementation.

     Below we present typographical concepts foundational to  understanding  any
     _r_o_f_f  implementation, narrate the development history of some _r_o_f_f systems,
     detail the command pipeline managed by _g_r_o_f_f(1), survey the formatting lan‐
     guage, suggest tips for editing _r_o_f_f input, and recommend  further  reading
     materials.

CCoonncceeppttss
     AT&T  _t_r_o_f_f  was  designed to take input as it would be composed on a type‐
     writer, including the teletypewriters used as early computer terminals, and
     relieve the user drafting a document of  concern  with  details  like  line
     length maintenance, hyphenation breaking, and consistent paragraph indenta‐
     tion.   Early in its development, the program gained the ability to prepare
     output for a phototypesetter; a document could then be prepared for  output
     to  a teletypewriter, a phototypesetter, or both.  GNU _t_r_o_f_f continues this
     tradition of permitting an author to compose a single master version  of  a
     document which can then be rendered upon a variety of output formats or de‐
     vices, including PDF, HTML, laser printers, and terminal displays.

     _r_o_f_f input contains text interspersed with instructions to control the for‐
     matter.   Even  in the absence of such instructions, a _r_o_f_f formatter still
     processes its input in several ways, by filling, hyphenating, breaking, and
     adjusting it,  and  supplementing  it  with  inter‐sentence  space.   These
     processes are basic to typesetting, and can be controlled at the input doc‐
     ument’s discretion.

     Instructions to _r_o_f_f take two forms.  One is the _r_e_q_u_e_s_t, which occupies an
     input  line and starts with the _c_o_n_t_r_o_l _c_h_a_r_a_c_t_e_r, a dot “..”.  The other is
     the _e_s_c_a_p_e _s_e_q_u_e_n_c_e, which can occur almost anywhere and  starts  with  the
     _e_s_c_a_p_e _c_h_a_r_a_c_t_e_r, a backslash “\\”.  Both characters are configurable.

            .br \" break the output line

     When  a device‐independent _r_o_f_f formatter starts up, it obtains information
     about the device for which it is preparing output  from  the  latter’s  de‐
     scription 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‐ending
     convention.  It reads input a character at a time, collecting words  as  it
     goes,  and fits as many words together on an output line as it can——this is
     known as _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 exceptions separate words.

     A  _r_o_f_f formatter attempts to detect boundaries between sentences, and sup‐
     plies supplemental inter‐sentence space between  them.   It  flags  certain
     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 character to defeat end‐of‐sentence
     detection  on  a per‐instance basis.  Normally, the occurrence of a visible
     non‐end‐of‐sentence character (as opposed to a space  or  tab)  immediately
     after  an  end‐of‐sentence character cancels detection of the end of a sen‐
     tence.  However, the formatter treats several characters _t_r_a_n_s_p_a_r_e_n_t_l_y  af‐
     ter the occurrence of an end‐of‐sentence character——it does not cancel end‐
     of‐sentence  status upon encountering them.  Such characters are often used
     as footnote marks or to close quotations and parentheticals.   The  default
     set  is  "",  '', )), ]], **, \\[[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 sequences whose purpose is to obtain
     glyphs that are not easily typed at the keyboard,  or  which  have  special
     meaning to the formatter (like \\ itself).

     When  an  output line is nearly full, it is uncommon for the next word col‐
     lected from the input to exactly fill it——often, there is  room  left  over
     for  only part of the next word.  _H_y_p_h_e_n_a_t_i_o_n is the process of splitting a
     word so that it appears partially on one line, followed by a hyphen to  in‐
     dicate  to the reader that the word has been broken, and that its remainder
     lies on the next.  Hyphenation break points can be manually specified;  GNU
     _t_r_o_f_f also uses a hyphenation algorithm and language‐specific pattern files
     (based  on  TeX’s)  to decide which words can be hyphenated and where.  Hy‐
     phenation does not always occur even when the hyphenation rules for a  word
     allow it; it can be disabled, and when not disabled there are several para‐
     meters that can prevent it in certain circumstances.

     Once an output line is full, the formatter places the next word (or remain‐
     der  of  a  hyphenated  one)  on  a different output line; this is called a
     _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 au‐
     tomatic break, the 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 outputs  a  one‐
     line  vertical space (effectively a blank output line).  Macro packages may
     discourage or disable this “blank line method” of paragraphing in favor  of
     their  own  macros.   A  line  that begins with one or more spaces causes a
     break.  The spaces are output at the beginning of the next line without be‐
     ing _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 be‐
     low) are discarded.  The formatter breaks the pending output  line  without
     adjustment upon encountering the end of input.

     After  performing  an  automatic  break,  the formatter may then _a_d_j_u_s_t the
     line, widening inter‐word spaces until the text reaches the  right  margin.
     Extra  spaces between words are preserved.  Leading and trailing spaces are
     handled as noted above.  You can align text to the  left  or  right  margin
     only, or center it, using _r_e_q_u_e_s_t_s_.

     A  _r_o_f_f  formatter translates horizontal tab characters, also called simply
     “tabs”, in the input into movements to the next tab stop.  Tab stops are by
     default located every half inch measured from the drawing  position  corre‐
     sponding to the beginning of the input line; see subsection “Page geometry”
     below.   With them, simple tables can be made.  However, this method can be
     deceptive, as the appearance (and width) of the text in an editor  and  the
     results from the formatter can vary greatly, particularly when proportional
     typefaces  are  used.  A tab character does not cause a break and therefore
     does not interrupt filling.  The formatter provides facilities for  sophis‐
     ticated  table  composition; there are many details to track when using the
     “tab” and “field” low‐level features, so most users turn to the _t_b_l(1) pre‐
     processor 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 reg‐
     ular 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
     expects 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 you expect the
     formatter to perform.  If a request is meaningless without arguments, it is
     typically ignored.  Requests and escape sequences comprise the control lan‐
     guage of the formatter.  Of key importance are  the  requests  that  define
     macros.   Macros are invoked like requests, enabling the request repertoire
     to be extended or overridden.  (Argument handling in macros is more  flexi‐
     ble but also more complex.)

     A  _m_a_c_r_o  can be thought of as an abbreviation you can define for a collec‐
     tion 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_.   Interpola‐
     tions  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 measure‐
     ments.  The device description file defines its resolution and page  dimen‐
     sions (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 its origin near the upper left  cor‐
     ner.   Coordinate  values  are  in basic units and increase down and to the
     right.  Useful ones are typically positive and within numeric ranges corre‐
     sponding to the page boundaries.

     Text is arranged on a one‐dimensional lattice of text  baselines  from  the
     top  to  the  bottom of the page.  A _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.  _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 quantity to 120% of the type size.  The initial vertical drawing posi‐
     tion is one unit of vertical spacing below the page top.  Typographers term
     this unit a _v_e_e_.

     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 measured, or
     where a geometric object will commence rendering.  Notionally,  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.)  A glyph therefore “starts” at its  bottom‐
     left  corner.  The formatter’s origin is one vee below the page top to pre‐
     vent a glyph from lying partially or wholly off the page.

     Further, it is conventional not to write or draw at the  extreme  edges  of
     the  page.  Typesetters configure a _p_a_g_e _o_f_f_s_e_t_, a rightward shift from the
     left edge that defines the zero point from which the formatter reckons  the
     line  indentation  and  length.  (_g_r_o_f_f’s terminal output devices have page
     offsets of zero.)

     Combining the foregoing facts results in an origin that lies  at  the  page
     offset  in the horizontal dimension and at the text baseline (using the de‐
     fault vertical spacing) in the vertical dimension.  A document  can  change
     these prior to its first written or drawn output.

     Vertical spacing has an impact on page‐breaking decisions.  Generally, when
     a  break  occurs, the formatter automatically moves the drawing position to
     the next text baseline.  If the formatter were already writing to the  last
     line  that fits on the page, advancing by one vee would place the next text
     baseline off the page.  To avoid that, _r_o_f_f formatters instruct the  output
     driver  to eject the page, start a new one, and again place the drawing po‐
     sition at the page offset one vee below the page top; this is a _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 also breaks the
     page, producing a useless blank one.  Macro packages keep users from having
     to confront this difficulty by setting “traps”; moreover, all but the  sim‐
     plest  page layouts tend to have headers and footers, or at least bear ver‐
     tical margins of at least one vee.

   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; further,
     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
     (given arguments) 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  expres‐
     sions  to clarify their meaning when stored or interpolated.  Each register
     can be assigned a _f_o_r_m_a_t_, causing its value to interpolate with leading ze‐
     roes, in Roman numerals, or alphabetically.  Some read‐only  registers  are
     string‐valued, meaning that they interpolate text and lack a format.

     _F_o_n_t_s are identified either by a name or by a _m_o_u_n_t_i_n_g _p_o_s_i_t_i_o_n (a non‐neg‐
     ative  number).   Four  styles are available on all devices.  RR is “roman”:
     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 output 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.  Typesetting 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  unstyled  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  geometric
     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 dis‐
     tinction between those two elements is not always obvious (and a full  dis‐
     cussion  is  beyond  our scope).  In brief, “A” is a character when we con‐
     sider it in the abstract: to make it a glyph, we  must  select  a  typeface
     with  which  to render it, and determine its type size and color.  The for‐
     matting process turns input characters into output glyphs.  A  few  charac‐
     ters  commonly seen on keyboards are treated specially by the _r_o_f_f language
     and may not look correct in output if used unthinkingly; they are the (dou‐
     ble) 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 rea‐
     sons this feature is disabled by default.

     A further few language elements arise as page layouts become more sophisti‐
     cated 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 automatically by the
     formatter, that is  associated  with  a  macro:  fulfilling  the  condition
     _s_p_r_i_n_g_s the trap——calls the macro.

     Footnote  support  often  exercises all three of the foregoing features.  A
     simple implementation might work as follows.  The author writes a  pair  of
     macros:  one  starts  a footnote and the other ends it.  They further set a
     trap a small distance above the page bottom,  reserving  a  footnote  area.
     The  author  calls  the  first macro where a footnote mark is desired.  The
     macro establishes a diversion so that the footnote text is collected at the
     place in the body text where its corresponding mark  appears.   It  further
     creates  an environment for the footnote so that it sets at a smaller type‐
     face.  The footnote text is formatted in the diversion using that  environ‐
     ment,  but it does not yet appear in the output.  The document author calls
     the footnote end macro, which returns to the previous environment and  ends
     the  diversion.   Later,  after  body  text nearly fills the page, the trap
     springs.  The macro called by the trap draws a line  across  the  page  and
     emits  the stored diversion by calling it like a macro.  Thus, the footnote
     is rendered.

HHiissttoorryy
     Computer‐driven document formatting dates back to the 1960s.  The _r_o_f_f sys‐
     tem 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 de‐
     scendants, and because bits were expensive in those days; five‐ and six‐bit
     character encodings were still in widespread usage, and  mixed‐case  alpha‐
     betics  in  file names seen as a luxury.  _R_U_N_O_F_F introduced a syntax of in‐
     lining formatting directives amid document text, by beginning a line with a
     period (an unlikely occurrence in human‐readable material)  followed  by  a
     “control  word”.   Control words with obvious meaning like “.line length _n”
     were supported as well as an abbreviation system; the latter came to  over‐
     whelm  the former in popular usage and later derivatives of the program.  A
     sample of control words from a _R_U_N_O_F_F manual of  December  1966  was  docu‐
     mented  as follows (with the parameter notation slightly altered).  The ab‐
     breviations 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 Gen‐
     eral 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, see‐
     ing many ports and derivations elsewhere.

     In 1969, Doug McIlroy wrote one such reimplementation,  adding  extensions,
     in  the  BCPL language for a GE 645 running GECOS at the Bell Labs location
     in Murray Hill, New Jersey.  In  its  manual,  the  control  commands  were
     termed  “requests”,  their two‐letter names were canonical, and the control
     character was configurable with a ..cccc  request.   Other  familiar  requests
     emerged  at  this time; no‐adjust (..nnaa), need (..nnee), page offset (..ppoo), tab
     configuration (..ttaa, though it worked differently), temporary indent  (..ttii),
     character  translation (..ttrr), and automatic 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 heuristic system for automatically placing  hyphen‐
     ation points, designed and implemented by Molly Wagner.  It furthermore in‐
     troduced  numeric  variables,  termed registers.  By 1971, this program had
     been ported to Multics and was known as _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 re‐
     quest, and what later _r_o_f_fs would call diversions were available via “foot‐
     note” 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 acquire 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 type‐
     writers) 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  practicalities
     of preparing standardized documents like patent applications (and Unix man‐
     ual pages), combined with McIlroy’s enthusiasm for macro languages, perhaps
     created  an  irresistible  pressure to make _r_o_f_f extensible.  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 lan‐
     guage——it sported a swath of features now considered essential to _r_o_f_f sys‐
     tems: definition of macros (..ddee), diversion of text thither (..ddii), and  re‐
     moval  thereof  (..rrmm);  trap  planting  (..wwhh;  “when”) and relocation (..cchh;
     “change”); conditional processing (..iiff); and environments (..eevv).  Incremen‐
     tal 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 leaders (..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 configura‐
     tion 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 Mur‐
     ray 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 implemented 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  fea‐
     ture  a  request  list, unlike _n_r_o_f_f(1).  Apart from typesetter‐driven fea‐
     tures, 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,  italics, and a symbol font specially commissioned by Bell Labs from
     Graphic Systems, Kernighan and Lorinda Cherry implemented _e_q_n for  typeset‐
     ting  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  fur‐
     ther revisions as late as 1992 by Kernighan.  (The original version was en‐
     titled  “Nroff/Troff  User’s  Manual”, which may partially explain why _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  Sys‐
     tem”, describing _m_s and basic _n_r_o_f_f/_t_r_o_f_f usage, updating it as the package
     accrued  features.   Sixth Edition (1975) 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 docu‐
     mented the _m_a_n macro package, introducing most of the macros  described  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  de‐
     vice.  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 Ben‐
     son‐Varian plotters.

     Ossanna had passed away unexpectedly in 1977, and after the release of Ver‐
     sion 7, with the C/A/T typesetter becoming supplanted  by  alternative  de‐
     vices  such  as  the  Autologic  APS‐5  and  the Mergenthaler Linotron 202,
     Kernighan undertook a revision and rewrite of _t_r_o_f_f to generalize  its  de‐
     sign.   To  implement  this revised architecture, he developed the font and
     device description file formats and the page description language that  re‐
     main in use today.  He described these novelties in the article “A Typeset‐
     ter‐independent TROFF”, last revised in 1982, and like the _t_r_o_f_f manual it‐
     self, 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  printers
     with built‐in interpreters for it.  An output driver for PostScript, _d_p_o_s_t,
     was  swiftly  developed.  However, AT&T’s software licensing 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 dis‐
     tributed under copyleft licenses,  ensuring  to  all  the  availability  of
     source  code  and the freedom to modify and redistribute it, properties un‐
     precedented in _r_o_f_f systems to that point.  _g_r_o_f_f  rapidly  attracted  con‐
     tributors,  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  fea‐
     tures; see _g_r_o_f_f___d_i_f_f(7).  Since its inception and for at least the follow‐
     ing  three  decades,  it has been used by practically all GNU/Linux and BSD
     operating systems.

     _g_r_o_f_f continues to be developed, is available for almost all operating sys‐
     tems in common use (along with several obscure ones), and is  free.   These
     factors make _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
     Unix System V _t_r_o_f_f, which was based on Documenter’s Workbench (“DWB”) 2.0,
     itself a descendant of Bell Labs device‐independent _t_r_o_f_f, released it  un‐
     der  a  free but GPL‐incompatible license.  Gunnar Ritter and later Carsten
     Kunze then enhanced it to produce Heirloom Doctools _t_r_o_f_f.  Sometime later,
     AT&T Software Technology made available  a  subsequent  revision  of  Docu‐
     menter’s Workbench _t_r_o_f_f, DWB 3.3, under yet another free but GPL‐incompat‐
     ible license.  Kunze again ported the software to modern POSIX systems.

     In  July 2013, Ali Gholami Rudi announced _n_e_a_t_r_o_f_f, a permissively licensed
     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 specific 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 argu‐
     ments 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 preprocessors in
     series, followed by a a formatter program and then  an  output  driver  (or
     “device  postprocessor”).   Commonly,  these programs are structured into a
     pipeline; that is, each is run in sequence such that the output of  one  is
     taken  as the input to the next, without passing through secondary storage.
     (Non‐Unix systems may simulate pipelines with temporary files.)

            $ _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 description
     language that is then interpreted by a postprocessor for viewing, printing,
     or further handling.

     Each program interprets input in a language that is independent of the oth‐
     ers; some are purely descriptive, as with _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 input.  Most _r_o_f_f
     input employs the macros of a document formatting package, intermixed  with
     instructions for one or more preprocessors, and is seasoned with escape se‐
     quences  and  requests  from the _r_o_f_f language.  Some documents are simpler
     still, since their formatting packages discourage direct use  of  _r_o_f_f  re‐
     quests;  man pages are a prominent example.  Many features of the _r_o_f_f lan‐
     guage are seldom needed by users; only authors of macro packages require  a
     substantial command of them.

   PPrreepprroocceessssoorrss
     A  _r_o_f_f  preprocessor  is a program that, directly or ultimately, generates
     output in the _r_o_f_f language.  Typically, each preprocessor defines  a  lan‐
     guage  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.   Pre‐
     processors  must consequently be run in an appropriate order; _g_r_o_f_f(1) han‐
     dles this automatically for all preprocessors supplied by the GNU _r_o_f_f sys‐
     tem.

     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 pro‐
     gram must process it before the input is seen by the formatter,  or  incor‐
     rect 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  preprocessors
     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 process‐
     ing by a selected device.  This page description language is specialized in
     its parameters, but not its syntax, for the selected device; the format  is
     device‐_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 typeset‐
     ters.  Often, the name _t_r_o_f_f is used loosely to refer to both.  When gener‐
     alizing 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  unrelated  soft‐
     ware  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 or markup specific to the device or file
     format it supports.  An output driver might support multiple devices,  par‐
     ticularly if they are similar.

     The  names  of  the devices and their driver programs are not standardized.
     Technological fashions evolve; the devices popular for document preparation
     when AT&T _t_r_o_f_f was first written in the 1970s are no longer used  in  pro‐
     duction environments.  Device capabilities have tended to increase, improv‐
     ing  resolution and font repertoire, and adding color output and hyperlink‐
     ing.  Further, to reduce file size and processing time, AT&T  _t_r_o_f_f’s  page
     description language placed low limits on the magnitudes of some quantities
     it  could represent.  Its PostScript output driver, _d_p_o_s_t(1), had a resolu‐
     tion 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 formatting
     elements.  The _r_o_f_f language is powerful enough to support arbitrary compu‐
     tation and it supplies facilities that encourage  extension.   The  primary
     such  facility  is macro definition; with this feature, macro packages have
     been developed that are tailored for particular applications.

   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 ac‐
     quire and master.  The implementation of a package _n_a_m_e is  typically  kept
     in  a file called “name_._t_m_a_c” (historically, “_t_m_a_c_.name”).  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 alterna‐
     tively 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 packages include _m_a_n for traditional man pages and _m_d_o_c for BSD‐
     style  manual pages.  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 Allman), _m_m (from “memorandum
     macros”), and _m_o_m, a punningly named package exercising many  _g_r_o_f_f  exten‐
     sions.  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 fa‐
     cilities, string variables, registers for storage of numbers or dimensions,
     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 expressions 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  material,
     or otherwise change the state of the parser.  The user can define their own
     request‐like  elements by composing together text, requests, and escape se‐
     quences _a_d _l_i_b_i_t_u_m_.  A document writer will not (usually) note any  differ‐
     ence  in  usage  for  requests  or macros; both are found on control lines.
     However, there is a distinction; requests take either a fixed number of ar‐
     guments (sometimes zero), silently ignoring any excess, or consume the rest
     of the input line, whereas macros can take a variable number of  arguments.
     Since  arguments  are separated by spaces, macros require a means of embed‐
     ding a space in an argument; in other words, of quoting it.  This then  de‐
     mands  a mechanism of embedding the quoting character itself, in case _i_t is
     needed literally in a macro argument.  AT&T _t_r_o_f_f had complex rules involv‐
     ing the placement and repetition 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 double 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 any‐
     where, 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  interpo‐
     lated 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 employing “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 a _r_o_f_f formatter fills text automatically, its experienced users tend
     to avoid visual composition of text in input files: the esthetic appeal  of
     the  formatted  output  is  what  matters.  Therefore, _r_o_f_f input should be
     arranged such that it is easy for authors and maintainers  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  recog‐
        nition.   It is frequently convenient to end text lines after colons and
        semicolons as well, as  these  typically  precede  independent  clauses.
        Consider  doing  so  after commas; they often occur in lists that become
        easy to scan when itemized by line, or  constitute  supplements  to  the
        sentence that are added, deleted, or updated to clarify it.  Parentheti‐
        cal  and  quoted  phrases are also good candidates for placement on text
        lines by themselves.

     •  Set your text editor’s line length to 72 characters or  fewer;  see  the
        subsections  below.   This limit, combined with the previous item of ad‐
        vice, makes it less common that an input line will wrap in your text ed‐
        itor, and thus will help you perceive excessively long constructions  in
        your text.  Recall that natural languages originate in speech, not writ‐
        ing,  and  that  punctuation is correlated with pauses for breathing and
        changes in prosody.

     •  Use \\&& after “!!”, “??”, and “..” if they are followed by space or  newline
        characters and don’t end a sentence.

     •  In  filled text lines, use \\&& before “..” and “''” if they are preceded by
        space, so that revisions to the  input  don’t  turn  them  into  control
        lines.

     •  Do  not  use  spaces to perform indentation or align columns of a table.
        Leading spaces are reliable when text is not being filled.   (Exception:
        when laying out a table with GNU _t_b_l, specifying the nnoossppaacceess region op‐
        tion  causes  the  program  to  ignore spaces at the boundaries of table
        cells.)

     •  Comment your document.  It is never too soon to apply comments to record
        information of use to future document maintainers (including your future
        self).  The \\"" escape sequence causes the formatter to  ignore  the  re‐
        mainder of the input line.

     •  Use  the  empty  request——a  control character followed immediately by a
        newline——to visually manage separation of material in the  input.   Many
        of  the  _g_r_o_f_f project’s own documents use an empty request between sen‐
        tences, after macro definitions, and where a break is expected, and  two
        empty  requests between paragraphs or other requests or macro calls that
        will introduce vertical space into the document.  You  can  combine  the
        empty  request  with  the  comment escape sequence to include whole‐line
        comments in your document, and even “comment out” sections of it.

     An example sufficiently long to illustrate most of the above suggestions in
     practice follows.  An arrow → indicates a tab character.

            .\"   nroff this_file.roff | less
            .\"   groff -T ps this_file.roff > this_file.ps
            →The theory of relativity is intimately connected with
            the theory of space and time.
            .
            I shall therefore begin with a brief investigation of
            the origin of our ideas of space and time,
            although in doing so I know that I introduce a
            controversial subject.  \" remainder of paragraph elided
            .
            .

            →The experiences of an individual appear to us arranged
            in a series of events;
            in this series the single events which we remember
            appear to be ordered according to the criterion of
            \[lq]earlier\[rq] and \[lq]later\[rq], \" punct swapped
            which cannot be analysed further.
            .
            There exists,
            therefore,
            for the individual,
            an I-time,
            or subjective time.
            .
            This itself is not measurable.
            .
            I can,
            indeed,
            associate numbers with the events,
            in such a way that the greater number is associated with
            the later event than with an earlier one;
            but the nature of this association may be quite
            arbitrary.
            .
            This association I can define by means of a clock by
            comparing the order of events furnished by the clock
            with the order of a given series of events.
            .
            We understand by a clock something which provides a
            series of events which can be counted,
            and which has other properties of which we shall speak
            later.
            .\" Albert Einstein, _The Meaning of Relativity_, 1922

   EEddiittiinngg wwiitthh EEmmaaccss
     Official GNU doctrine holds that the best program for editing a _r_o_f_f  docu‐
     ment is Emacs; see _e_m_a_c_s(1).  It provides an _n_r_o_f_f major mode that is suit‐
     able  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  approach includes file‐local variables at the end of
        the file; we can also configure the fill column this way.
               .\" Local Variables:
               .\" fill-column: 72
               .\" mode: nroff
               .\" End:

     •  Certain file name extensions, like those often used by man pages,  acti‐
        vate _n_r_o_f_f mode automatically.

     •  Loading a file with the sequence
               .\" -*- nroff -*-
        in  its  first  line into an Emacs buffer causes the editor to enter its
        _n_r_o_f_f major mode.  Unfortunately, some  implementations  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  recog‐
     nize _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 con‐
     figured to enable, several features; consult the editor’s online help  top‐
     ics  “auto-setting”,  “filetype”,  and “syntax”.  Then put the following at
     the end of your _r_o_f_f files, after any Emacs configuration.

                   .\" 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 knowl‐
     edge of Unix or text editing (if necessary) to sophisticated computer‐aided
     typesetting.   It  has been placed under a free software license by its au‐
     thors and updated by a team of _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  pointers
     to much historical _r_o_f_f information.

     Multicians, a site by Multics enthusiasts, contains a lot of information on
     the  MIT projects CTSS and Multics, including _R_U_N_O_F_F; it is especially use‐
     ful for its glossary and the many links to historical documents.

     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) contributed by their copy‐
     right 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 signifi‐
     cance are those describing the language and its  device‐independent  imple‐
     mentation.

     “Troff  User’s  Manual”  by  Joseph  F.  Ossanna, 1976 (revised by Brian W.
     Kernighan, 1992), AT&T Bell Laboratories Computing Science Technical Report
     No. 54.

     “A Typesetter‐independent TROFF” by Brian W.  Kernighan,  1982,  AT&T  Bell
     Laboratories Computing Science Technical Report No. 97.

     You  can  obtain  many relevant Bell Labs papers in PDF from Bernd Warken’s
     “roff classical” GitHub repository.

   MMaannuuaall ppaaggeess
     A componentized system like _r_o_f_f potentially has many man pages,  each  de‐
     scribing  an  aspect  of  it.  Unfortunately, there is no consistent naming
     scheme for these pages among the various implementations.

     In GNU _r_o_f_f, the _g_r_o_f_f(1) man page enumerates  all  man  pages  distributed
     with  the  system,  and  individual  pages frequently refer to external re‐
     sources as well as manuals on a variety of topics imbricated with _g_r_o_f_f.

     In 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.24.1                       2026‐04‐22                            _r_o_f_f(7)
