# groff

## Name



           groff - GNU _roff_ language reference
    


## Description



           _groff_ is short for GNU _roff_ , a free reimplementation of the AT&T
           device-independent _troff_ typesetting system.  See _roff_(7) for a
           survey of and background on _roff_ systems.
    
           This document is intended as a reference.  The primary _groff_
           manual, _Groff: The GNU Implementation of troff_ , by Trent A. Fisher
           and Werner Lemberg, is a better resource for learners, containing
           many examples and much discussion.  It is written in Texinfo; you
           can browse it interactively with “info groff”.  Additional
           formats, including plain text, HTML, TeX DVI, and PDF, may be
           available in _/usr/local/share/doc/groff-1.23.0_.
    
           _groff_ is also a name for an extended dialect of the _roff_ language.
           We use “roff” to denote features that are universal, or nearly so,
           among implementations of this family.  We apply the term “groff”
           to the language documented here, the GNU implementation of the
           overall system, the project that develops that system, and the
           command of that name.
    
           GNU _troff_ , installed on this system as _troff_(1), is the _formatter:_
           a program that reads device and font descriptions (_groff_font_(5)),
           interprets the _groff_ language expressed in input text, and
           translates it into a device-independent page description language
           (_groff_out_(5)) that is usually then post-processed by an output
           driver to produce PostScript, PDF, HTML, DVI, or terminal output.
    


## Input format



           Organize input to GNU _troff_ into lines separated by the Unix
           newline character (U+000A), using the character encoding it
           recognizes: ISO Latin-1 (8859-1).  We recommend use of
           ISO 646:1991 IRV (US-ASCII) or (equivalently) the Basic Latin
           subset of ISO 10646 (Unicode); see _groff_char_(7).
    
           Some control characters (from the sets “C0 Controls” and “C1
           Controls” as Unicode describes them) are invalid as input
           characters.  GNU _troff_ discards them upon reading.  (It also emits
           a warning in category “input”; see section “Warnings” of
           _troff_(1).)  It processes a character sequence “foo”, followed by
           an invalid character and then “bar”, as “foobar”.
    
           Invalid input characters comprise **0x00** , **0x0B** , **0x0D** –**0x1F** , and
           **0x80** –**0x9F**.  (Historically, control characters like ASCII STX, ETX,
           and BEL (Control+B, Control+C, and Control+G) respectively) have
           been observed in _roff_ documents, 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 expressions”
           below).  We discourage this expedient; in GNU _troff_ it is
           unnecessary (outside of compatibility mode) because the program
           parses delimited arguments at a different input level than their
           surrounding context.  See section “Miscellaneous” of
           _groff_diff_(7).)  GNU _troff_ 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.
    


## Syntax characters



           Several input characters are syntactically significant to _groff_.
           The most important of these distinguish _control lines,_ which
           instruct the formatter, from _text lines_ 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 **el** and **nop** requests, and the
               condition in “**if** ”, **ie** , and “**while** ” requests.  The control
               character invokes requests and calls macros by the name that
               follows it.  The **cc** request can change the control character.
    
           '   The neutral apostrophe is the _no-break control character,_
               recognized where the control character is.  It suppresses the
               (first) break implied by the **bp** , **ce** , **cf** , **fi** , **fl** , “**in** ”, **nf** , **rj** ,
               **sp** , **ti** , and **trf** requests.  The requested operation takes
               effect at the next break.  It makes **br** nilpotent.  The no-
               break control character can be changed with the **c2** request.
               When formatted, “**'** ” may be typeset as a typographical
               quotation mark; use the **\[aq]** special character escape
               sequence to format a neutral apostrophe glyph.
    
           "   The neutral double quote can be used to enclose arguments to
               macros and strings, and is required if those arguments contain
               space or tab characters.  The requests “**as** ”, **as1** , **cf** , **char** ,
               **ds** , **ds1** , **fchar** , **fschar** , **mso** , **msoquiet** , **nx** , “**open** ”, **opena** , **pi** ,
               **schar** , “**so** ”, **soquiet** , **sy** , and **trf** strip a leading neutral
               double quote from their final arguments to allow 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 **\[dq]** special 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 **ec** request; **eo** disables
               escape sequence recognition.  Use the **\[rs]** special character
               escape sequence to format a backslash glyph, and **\e** 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.  _groff_ offers the more flexible square
               bracket syntax.
    
           [   An opening bracket is special only in certain escape
               sequences; when recognized, it introduces an argument (list)
               of any length, not including a closing bracket.
    
           ]   A closing bracket is special only when an escape sequence
               using an opening bracket as an argument delimiter is being
               interpreted.  It ends the argument (list).
    
           Additionally, the Control+A character (U+0001) in text is
           interpreted as a _leader_ (see below).
    
           Horizontal whitespace characters are significant to _groff,_ but
           trailing spaces on text lines are ignored.
    
           _space_  On control lines and within bracketed escape sequences,
                  spaces separate arguments.  On text lines, they separate
                  words.  Multiple adjacent space characters in text cause
                  _groff_ to attempt end-of-sentence detection on the preceding
                  word (and trailing punctuation).  The amount of space
                  between words and sentences is controlled by the **ss**
                  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), **\0** , **\|** , **\^** , or **\h** ;
                  see section “Escape sequences” below.
    
           _newline_
                  On text lines, a newline formats an inter-word space and,
                  if filling is enabled, triggers end-of-sentence recognition
                  on the preceding text.  See section “Line continuation”
                  below.
    
           _tab_    A tab character on a text line causes the drawing position
                  to advance to the next defined tab stop.
    


## Tabs and leaders



           The formatter interprets input horizontal tab characters (“tabs”)
           and Control+A characters (“leaders”) into movements to the next
           tab stop.  Tabs simply move to the next tab stop; leaders place
           enough periods to fill the space.  Tab stops are by default
           located every half inch measured from the drawing position
           corresponding to the beginning of the input line; see section
           “Page geometry” of _roff_(7).  Tabs and leaders do not cause breaks
           and therefore do not interrupt filling.  Tab stops can be
           configured with the **ta** request, and tab and leader glyphs with the
           **tc** and **lc** requests, respectively.
    


## Line continuation



           When filling is enabled, input and output line breaks generally do
           not correspond.  The _roff_ language therefore distinguishes input
           and output line continuation.
    
           A backslash **\** immediately followed by a newline, sometimes
           discussed as **\**_newline_ , 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.  **\**_newline_ 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 **.c** increments.
    
           The **\c** escape sequence continues an _output_ line.  Nothing on the
           input line after it is formatted.  In contrast to **\**_newline_ , a line
           after **\c** 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 **\c** , flushing out the pending output line in the
           usual way.  The register **.int** interpolates a positive value only
           if the pending output line has been continued with **\c** ; this datum
           is associated with the environment.
    


## Colors



           _groff_ supports color output with a variety of color spaces and up
           to 16 bits per channel.  Some devices, particularly terminals, may
           be more limited.  When color support is enabled, two colors are
           current at any given time: the _stroke color,_ with which glyphs,
           rules (lines), and geometric objects like circles and polygons are
           drawn, and the _fill color,_ which can be used to paint the interior
           of a closed geometric figure.  The **color** , **defcolor** , **gcolor** , and
           **fcolor** requests; **\m** and **\M** escape sequences; and **.color** , **.m** , and
           **.M** registers exercise color support.
    
           Each output device has a color named “**default** ”, which cannot be
           redefined.  A device's default stroke and fill colors are not
           necessarily the same.  For the **dvi** , **html** , **pdf** , **ps** , and **xhtml**
           output devices, _troff_ automatically loads a macro file defining
           many color names at startup.  By the same mechanism, the devices
           supported by _grotty_(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.)
    


## Measurements



           Express numeric parameters that specify measurements as integers
           or decimal fractions with an optional scaling unit suffixed.  A
           _scaling unit_ is a letter 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 “**1i** ” to a register, then reading the register.
    
           **u** Basic unit; it is at least as small as any other unit.
           **i** Inch; defined as 2.54 centimeters.
           **c** Centimeter.
           **p** Point; a typesetter's unit used for measuring type size.
                  There are 72 points to an inch.
           **P** Pica; another typesetter's unit.  There are 6 picas to an
                  inch and 12 points to a pica.
           **z** Typographical point; like **p** , but used only with type sizes,
                  to overcome a limitation of AT&T _troff_.
           **s** Scaled point.
           **f** 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 parameters in effect.
    
           **m** Em; an em is equal to the current type size in points.
           **n** En; on typesetters, an en is one-half em, but on terminals
                  an en equals an em.
           **v** Vee; distance between text baselines.
           **M** Hundredth of an em.
    
       **Motion quanta**
           An output device's basic unit **u** is not necessarily its smallest
           addressable length; **u** can be smaller to avoid problems with
           integer roundoff.  The minimum distances that a device can work
           with in the horizontal and vertical directions are termed its
           _motion quanta,_ stored in the **.H** and **.V** registers, respectively.
           Measurements are rounded to applicable motion quanta.  Half-
           quantum fractions round toward zero.
    
       **Default units**
           A general-purpose register (one created or updated with the **nr**
           request; see section “Registers” below) is implicitly
           dimensionless, or reckoned in basic units if interpreted in a
           measurement context.  But it is convenient for many requests and
           escape sequences to infer a scaling unit for an argument if none
           is specified.  An explicit scaling unit (not after a closing
           parenthesis) can override an undesirable default.  Effectively,
           the default unit is suffixed to the expression if a scaling unit
           is not already present.  GNU _troff_ 's use of integer arithmetic
           should also be kept in mind; see below.
    


## Numeric expressions



           When evaluated, a _numeric expression_ interpolates an integer.  GNU
           _troff_ 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
    
           _troff_ provides a set of mathematical and logical operators
           familiar to programmers—as well as some unusual ones—but supports
           only integer arithmetic.  (Provision is made for interpreting and
           reporting decimal fractions in certain cases.)  The internal data
           type used for computing results depends 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 _groff_tmac_(5) for the _62bit.tmac_ macro package.)  Arithmetic
           saturates.  (If overflow would occur, GNU _troff_ emits a warning in
           category “**range** ”.  See section “Warnings” of _troff_(1).)
    
           Arithmetic infix operators perform a function on the numeric
           expressions to their left and right; they are **+**(addition), **-**
           (subtraction), *****(multiplication), **/**(truncating division), and **%**
           (modulus).  _Truncating division_ 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 “**(a / b)** ” and a remainder _r_ by “**(a % b)** ”,
           then _qb_ + _r_ = _a_.
    
           GNU _troff_ '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 _troff_ 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 “**0** ” if it is false and “**1** ” if true.  In the _roff_
           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 “**if** ”, “**ie** ”, and “**while** ”
           requests.  Furthermore, the formatter recognizes **!** only at the
           beginning of a numeric expression not contained by another numeric
           expression.  In other words, **!** must be the “outermost” operator.
           Its presence elsewhere causes the expression to evaluate false.
           (GNU _troff_ emits a warning in category “**number** ”.  See section
           “Warnings” of _troff_(1).)  This unfortunate limitation maintains
           compatibility with AT&T _troff_.  Test a numeric expression for
           falsity within a complex expression by comparing it to a false
           value.
    
           The _roff_ 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: **bp** , **in** , **ll** , **pl** , **pn** , **po** , **ps** , **pvs** , **rt** , **ti** , **\H** , **\R** ,
           and **\s**.  Here, leading plus and minus signs serve as
           incrementation and decrementation operators, respectively.  To
           negate an expression, 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 position but to a boundary.  For horizontal motions, the
           measurement specifies a distance relative to a drawing position
           corresponding to the beginning of the _input_ 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 **\B** escape sequence tests its argument for validity as a
           numeric expression.
    
           A register interpolated as an operand in a numeric expression must
           have an Arabic format; luckily, this is the default.
    
           Due to the way arguments are parsed, spaces are not allowed in
           numeric expressions unless the (sub)expression containing them is
           surrounded by parentheses.
    


## Identifiers



           An _identifier_ labels a GNU _troff_ datum such as a register, name
           (macro, string, or diversion), typeface, color, special character
           or character class, hyphenation language code, environment, or
           stream.  Valid identifiers consist of one or more ordinary
           characters.  An _ordinary character_ is an input character that is
           not the escape character, a leader, tab, newline, space, or
           invalid as GNU _troff_ input.
    
           An identifier with a closing bracket (“]”) in its name can't be
           accessed with bracket-form escape sequences that expect an
           identifier as a parameter.  Similarly, the identifier “(” can't be
           interpolated _except_ with bracket forms.
    
           Beginning a macro, string, or diversion name with the character
           “[” or “]” forecloses use of the _refer_(1) preprocessor, which
           recognizes input lines starting with “.[” and “.]”  as
           bibliographic reference delimiters.
    
           The escape sequence **\A** 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 interpolates nothing.  (GNU
           _troff_ emits a warning in category “**mac** ”.  See section “Warnings”
           of _troff_(1).)  Similarly, if the identifier is interpreted as a
           register name, the formatter initializes it to zero and
           interpolates that value.  _troff_ emits a warning in category “**reg** ”,
           See section “Warnings” in _troff_(1), and subsection “Interpolating
           registers” and section “Strings” below.  Attempting to use an
           undefined typeface, special character or character class, color,
           environment, hyphenation language code, or stream generally
           provokes an error diagnostic.
    
           Identifiers for requests, macros, strings, and diversions share
           one name space; special characters and character classes another.
           No other object types do.
    


## Control characters



           The formatter recognizes a control character only at the beginning
           of an input line, or at the beginning of a branch of a control
           structure request; see section “Control structures” below.
    
           A few requests cause a break implicitly; use the no-break control
           character to prevent the break.  Break suppression is its sole
           behavioral distinction.  Employing the no-break control character
           to invoke requests that don't cause breaks is harmless but poor
           style.
    
           The control character “**.** ” and the no-break control character “**'** ”
           can be changed with the **cc** and **c2** requests, respectively.  Within
           a macro definition, register **.br** indicates the control character
           used to call it.
    


## Invoking requests



           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 **rm** request makes it
           unavailable.  The **als** request can alias requests, permitting them
           to be wrapped or non-destructively replaced.  See section
           “Strings” below.
    
           There is no inherent limit on argument length or quantity.  Most
           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 _troff_ does not allow tabs for argument separation.
           (Plan 9 _troff_ does.)
    
           Generally, a space _within_ a request argument is not relevant, not
           meaningful, or is supported by bespoke provisions, as with the **tl**
           request's delimiters.  Some requests, like **ds** , interpret the
           remainder of the control line as a single argument.  See section
           “Strings” below.
    
           Spaces and tabs immediately after a control character are ignored.
           Commonly, authors use them to indent the source of documents or
           macro files.
    


## Calling macros



           If a macro of the desired name does not exist when called, the
           formatter creates it and assigns it an empty definition.  (GNU
           _troff_ emits a warning in category “**mac** ”.  See section “Warnings”
           in _troff_(1).)  Calling an undefined macro _does_ end a macro
           definition naming it as its end macro (see section “Writing
           macros” below).
    
           To embed spaces _within_ a macro argument, enclose the argument in
           neutral double quotes ‘**"** ’.  Horizontal motion escape sequences are
           sometimes a better choice for arguments to be formatted as text.
    
           The foregoing raises the question of how to embed neutral double
           quotes or backslashes in macro arguments when _those_ characters are
           desired as literals.  In GNU _troff_ , the special character escape
           sequence **\[rs]** produces a backslash and **\[dq]** a neutral double
           quote.
    
           In GNU _troff_ 's AT&T compatibility mode, these characters remain
           available as **\(rs** and **\(dq** , respectively.  AT&T _troff_ did not
           consistently define these special characters, but its descendants
           can be made to support them.  See _groff_font_(5).  If even that is
           not feasible, see the “Calling Macros” section of the _groff_
           Texinfo manual for the complex macro argument quoting rules of
           AT&T _troff_.
    


## Using escape sequences



           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 function.
    
           Escape sequences vary in length.  Some take an argument, and of
           those, some have different syntactical forms for a one-character,
           two-character, or arbitrary-length argument.  Others accept _only_
           an arbitrary-length argument.  In the former scheme, a one-
           character argument follows the function character immediately, an
           opening parenthesis “**(** ” introduces a two-character argument (no
           closing parenthesis is used), and an argument of arbitrary length
           is enclosed in brackets “**[]** ”.  In the latter scheme, the user
           selects a delimiter character.  A few escape sequences are
           idiosyncratic, and support both of the foregoing conventions (**\s**),
           designate their own termination sequence (**\?**), consume input until
           the next newline (**\!** , **\"** , **\#**), or support an additional modifier
           character (**\s** again, and **\n**).  In no case can an escape sequence
           parameter contain an unescaped newline.
    
           If the character that follows the escape character does not
           identify a defined operation, the formatter ignores the escape
           character.  (GNU _troff_ emits a warning in category “**escape** ”.  See
           section “Warnings” in _troff_(1).)
    
           Escape sequence interpolation is of higher precedence than escape
           sequence argument interpretation.  This rule affords flexibility
           in using escape sequences to construct parameters to other escape
           sequences.
    
           The escape character can be interpolated (**\e**).  Requests permit
           the escape mechanism to be deactivated (**eo**) and restored, or the
           escape character changed (**ec**), and to save and restore it (**ecs** and
           **ecr**).
    


## Delimiters



           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.
           Letters, numerals, and leaders can be used.  Punctuation
           characters are likely better choices, except for those meaningful
           in numeric expressions; see below.
    
           The following escape sequences don't take arguments and thus are
           allowed as delimiters: **\**_space_ , **\%** , **\|** , **\^** , **\{** , **\}** , **\'** , **\`** , **\-** , **\_** ,
           **\!** , **\?** , **\)** , **\/** , **\,** , **\ &**, **\:** , **\~** , **\0** , **\a** , **\c** , **\d** , **\e** , **\E** , **\p** , **\r** ,
           **\t** , and **\u**.  However, using them this way is discouraged; they can
           make the input confusing to read.
    
           Conditional expressions prohibit delimiters that are meaningful in
           numeric expressions, because the latter are a subset of the
           former.  The escape sequences **\D** , **\h** , **\H** , **\l** , **\L** , **\N** , **\R** , **\s** , **\S** ,
           **\v** , and **\x** similarly prohibit them because they accept numeric
           expressions as (or within) their arguments.
    
                  •  the numerals 0–9 and the decimal point “**.** ”
    
                  •  the (single-character) operators **+-/*% <>=&:()|**
    
                  •  any escape sequences other than **\%** , **\:** , **\{** , **\}** , **\'** , **\`** ,
                     **\-** , **\_** , **\!** , **\/** , **\c** , **\e** , and **\p**
    
           Delimiter syntax is complex and flexible primarily for historical
           reasons; the foregoing restrictions need be kept in mind mainly
           when using _groff_ in AT&T compatibility mode.  GNU _troff_ 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 any that result
           from interpolation.  Typically, **'** works fine.  See section
           “Implementation differences” in _groff_diff_(7).
    


## Dummy characters



           As discussed in _roff_(7), the first character on an input line is
           treated specially.  Further, formatting a glyph has many
           consequences on formatter state (see section “Environments”
           below).  Occasionally, we want to escape this context or embrace
           some of those consequences without actually rendering a glyph to
           the output.  **\ & **interpolates a dummy character, which is
           constitutive of output but invisible.  Its presence alters the
           interpretation context of a subsequent input character, and enjoys
           several applications: preventing the insertion of extra space
           after an end-of-sentence character, preventing interpretation of a
           control character at the beginning of an input line, preventing
           kerning between two glyphs, and permitting the **tr** request to remap
           a character to “nothing”.  **\)** works as **\ & **does, except that it
           does not cancel a pending end-of-sentence state.
    


## Control structures



           _groff_ has “if” and “while” control structures like other
           languages.  However, the syntax for grouping multiple input lines
           in the branches or bodies of these structures is unusual.
    
           They have a common form: the request name is (except for **el**
           “else”) followed by a conditional expression _cond-expr_ ; the
           remainder of the line, _anything_ , 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 _anything_ are
           therefore not seen.  _anything_ effectively _cannot_ be omitted; if
           _cond-expr_ is true and _anything_ 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 quantity of **\}** sequences on the
           same line is processed only if all the preceding conditions to
           which they correspond are true.  Furthermore, a **\}** closing the
           body of a “**while** ” request must be the last such escape sequence on
           an input line.
    
       **Conditional expressions**
           The “**if** ”, **ie** , and “**while** ” requests test the truth values of
           numeric expressions.  They also support several additional Boolean
           operators; the members of this expanded class are termed
           _conditional expressions_ ; their truth values are as shown below.
    
           [1mcond-expr[24m...   ...is true if...
           ───────────────────────────────────────────────────────────────────
                **'**_s1_**'**_s2_**'**_s1_ produces the same formatted output as _s2_.
                    **c** _g_   a character _g_ is defined.
                    **d** _m_   a string, macro, diversion, or request _m_ is
                          defined.
                      **e** the current page number is even.
                    **F** _f_   a font named _f_ is available.
                    **m** _c_   a color named _c_ is defined.
                      **n** the formatter is in _nroff_ mode.
                      **o** the current page number is odd.
                    **r** _n_   a register named _n_ is defined.
                    **S** _s_   a font style named _s_ is available.
                      **t** the formatter is in _troff_ mode.
                      **v** n/a (historical artifact; always false).
    
           If the first argument to an “**if** ”, **ie** , or “**while** ” request begins
           with a non-alphanumeric character apart from “**!** ” (see below) and
           is not a numeric expression, it performs an _output comparison_
           _test._  Shown first in the table above, the _output comparison_
           _operator_ interpolates a true value if formatting its comparands _s1_
           and _s2_ produces the same output commands.  Other delimiters can be
           used in place of the neutral apostrophes; see section “Delimiters”
           above.  _troff_ formats _s1_ and _s2_ 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 obtain 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 comparands
           protected with **\?** are read in copy mode, they need not even be
           valid _groff_ syntax.  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 “**c** ”, “**d** ”, “**F** ”, “**m** ”, “**r** ”, and “**S** ” operators,
           but right after “**!** ”, they end the predicate and the conditional
           evaluates true.  (This bizarre behavior maintains compatibility
           with AT&T _troff_.)
    
           Conditional operators do not create _roff_ language objects as
           interpolations with **\n** and **\*** escape sequences do.
    


## Syntax reference conventions



           In the following request and escape sequence specifications, most
           argument names were chosen to be descriptive.  A few denotations
           may require introduction.
    
                  _anything_   includes all characters up to the end of the
                             input line (which may be continued with
                             **\**_newline_), to the closing delimiter for the
                             escape sequence, or within **\{** and **\}**.  Escape
                             sequences in _anything_ are interpreted normally
                             except where otherwise stated, as when read in
                             copy mode.  Comments are ignored; trailing
                             whitespace generally is not.
                  _b_          is a numerical expression evaluated as a
                             Boolean; positive values are true, others false.
                  _c_          denotes a single input character, ordinary or
                             special.
                  _command_    is an instance of _contents_ (see below) to be
                             passed to the system as a command (potentially
                             with arguments).  A leading neutral double quote
                             is stripped, allowing embedded leading spaces.
                  _contents_   is arbitrary input, excluding an unescaped
                             newline, read in copy mode.  GNU _troff_ strips a
                             leading neutral double quote, allowing embedded
                             leading spaces.
                  _div_        is a diversion identifier.
                  _env_        is an environment identifier.
                  _file_       is an instance of _contents_ naming a file on the
                             system.  A leading neutral double quote is
                             stripped, allowing embedded leading spaces.  GNU
                             _troff_ does not accept newlines (line feeds) in
                             file names supplied as arguments to requests.
                  _font_       is a typeface specified as a font identifier, an
                             abstract style, or a mounting position.
                  _ident_      is a valid _groff_ identifier; its use often
                             indicates that the operation creates an object
                             of a type subsequently referred to as _mac, reg,_
                             _str,_ and so forth.
                  _mac_        is a macro identifier.
                  _message_    is an instance of _contents_ to emit on the
                             standard error stream.  A leading neutral double
                             quote is stripped, 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.
                  _name_       is a macro, string, or diversion identifier, or
                             the name of a request.
                  _npl_        is a numeric expression constituting a count of
                             subsequent _productive_ input lines; that is,
                             those that directly produce formatted output.
                             Text lines produce output, as do control lines
                             containing requests like “**.tl //Page %//** ” or
                             escape sequences like “**\l'1i'** ”.  Macro calls are
                             not themselves productive, but their
                             interpolations can be.
                  _reg_        is a register identifier.
                  _str_        is a string identifier.
                  _stream_     is an output stream identifier.
    
           If a numeric expression presented as _±N_ starts with a ‘**+** ’ sign, an
           increment in the amount of of _N_ is applied to the value applicable
           to the request or escape sequence.  If it starts with a ‘**-** ’ sign,
           a decrement of magnitude _N_ is applied instead.  Without a sign, _N_
           replaces any existing value.  A _roff_ 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.
    


## Request short reference



           GNU _troff_ reads arguments named _character-sequence, command,_
           _contents, file,_ and _message_ in copy mode (see section “Copy Mode”
           below) until the end of the input line.  A _character-sequence_
           comprises one or more ordinary, special, or indexed characters;
           spaces; or escape sequences that interpolate only these.  We name
           the remaining arguments for clarity; they are also _character-_
           _sequences._  A neutral double quote ‘**"** ’ can optionally prefix a
           _character-sequence;_ the formatter discards one if present,
           permitting initial embedded spaces in the argument.
    
           Not all details of request behavior are outlined here.  See the
           _groff_ Texinfo manual or, for features new to GNU _troff_ ,
           _groff_diff_(7).
    
           **.ab** Abort processing; exit with failure status.
           **.ab** _terminal-message_
                      Abort processing; write _terminal-message_ to the
                      standard error stream and exit with failure status.
           **.ad** Enable output line alignment and adjustment using the
                      mode stored in **\n[.j]**.
           **.ad** _c_      Enable output line alignment and adjustment in mode _c_
                      (_c_ =**b** ,**c** ,**l** ,**n** ,**r**).  Sets **\n[.j]**.
           **.af** _reg c_  Assign format _c_ to register _reg,_ where _c_ is “**i** ”, “**I** ”,
                      “**a** ”, “**A** ”, or a sequence of decimal digits whose
                      quantity denotes the minimum width in digits to be used
                      when the register is interpolated.  “**i** ” and “**a** ”
                      indicate Roman numerals and basic Latin alphabetics,
                      respectively, in the lettercase specified.  The default
                      is **0**.
           **.aln** _new-register existing-register_
                      Create alias (additional name) _new-register_ of
                      _existing-register_.
           **.als** _new-name existing-name_
                      Create alias (additional name) _new-name_ of request,
                      string, macro, or diversion _existing-name_.  If
                      _existing-name_ is undefined, GNU _troff_ produces a
                      warning in category “**mac** ” and ignores the request.  If
                      _new-name_ already exists, its definition is lost unless
                      already aliased.
           **.am** _mac_    Append to macro _mac_ until encountering “**..** ” at the
                      start of a control line in the current conditional
                      block.
           **.am** _mac end-mac_
                      Append to macro _mac_ until _end-mac_ is called at the
                      start of a control line in the current conditional
                      block.  _end-mac_ can be a request.
           **.am1** _mac_   As ”**am** ”, with compatibility mode disabled when the
                      appendment to macro _mac_ is interpreted.
           **.am1** _mac end-mac_
                      As “**.am** _mac_ ”, with compatibility mode disabled when the
                      appendment to macro _mac_ is interpreted.
           **.ami** _str_   Append to a macro indirectly—its name is in string _str_ —
                      until encountering “**..** ”.
           **.ami** _str end-mac-str_
                      Append to a macro indirectly.  As ”**am** ”, but _str_ and
                      _end-mac-str_ contain the names of the macro to be
                      appended to, and that whose call ends the appendment,
                      respectively.
           **.ami1** _str_  As **ami** , with compatibility mode disabled when the
                      appendment is interpreted.
           **.ami1** _str end-mac-str_
                      As **ami** , with compatibility mode disabled when the
                      appendment is interpreted.
           **.as** _ident_  Create string _ident_ with empty contents; no operation
                      if _ident_ already exists.
           **.as** _str contents_
                      Append _contents_ to string _str_.
           **.as1** _ident_ As “**.as** _ident_ ”.
           **.as1** _str contents_
                      As ”**as** ”, with compatibility mode disabled when the
                      appendment to string _str_ is interpreted.
           **.asciify** _div_
                      Unformat ordinary characters, spaces, and some escape
                      sequences in diversion _div_.
           **.backtrace** Write the state of the input stack to the standard
                      error stream.  See the **-b** option of _groff_(1).
           **.bd** _font_   Stop emboldening font _font._
           **.bd** _font n_ Embolden _font_ by overstriking its glyphs offset by _n_ -1
                      units.  See register **.b**.
           **.bd** _special-font font_
                      Stop emboldening _special-font_ when _font_ is selected.
                      _special-font_ must be a font name, not a mounting
                      position.
           **.bd** _special-font font n_
                      Embolden _special-font,_ overstriking its glyphs offset
                      by _n_ -1 units when _font_ is selected.  See register **.b**.
           **.blm** Unset blank line macro (trap).  Restore default
                      handling of blank lines.
           **.blm** _mac_   Set blank line macro (trap) to _mac_.
           **.box** Stop directing output to current diversion; any pending
                      output line is discarded.
           **.box** _ident_ Direct output to diversion _ident_ , omitting a partially
                      collected line.
           **.boxa** Stop appending output to current diversion; any pending
                      output line is discarded.
           **.boxa** _div_  Append output to diversion _div_ , omitting a partially
                      collected line.
           **.bp** Break page and start a new one.
           **.bp** _±N_     Break page, starting a new one numbered _±N_.
           **.br** Break output line.
           **.brp** Break output line; adjust if applicable.
           **.break** Break out of a ”**while** ” loop.
           **.c2** Reset no-break control character to “**'** ”.
           **.c2** _o_      Recognize ordinary character _o_ as no-break control
                      character.
           **.cc** Reset control character to ‘**.** ’.
           **.cc** _o_      Recognize ordinary character _o_ as the control
                      character.
           **.ce** Break, center the output of the next productive input
                      line without filling, and break again.
           **.ce** _npl_    Break, center the output of the next _npl_ productive
                      input lines without filling, then break again.  If _npl_
                      ≤ 0, stop centering.
           **.cf** _file_   Break and copy contents of _file_ as “throughput” to GNU
                      _troff_ output (see _groff_out_(5)).  Each line of _file_ is
                      output as if preceded by **\!** , but is not interpreted by
                      the formatter.  Unsafe request; disabled by default.
           **.cflags** _n c1 c2_ ...
                      Assign properties encoded by _n_ to characters _c1_ , _c2_ ,
                      and so on.
           **.ch** _mac_    Unplant page location trap _mac_.
           **.ch** _mac vertical-position_
                      Change page location trap _mac_ planted by **wh** by moving
                      its location to _vertical-position_ (default scaling
                      unit **v**).
           **.char** _c_    Define an ordinary, special, or indexed character _c_ as
                      empty.
           **.char** _c contents_
                      Define an ordinary, special, or indexed character _c_ as
                      _contents._
           **.chop** _name_ Remove the last character from the macro, string, or
                      diversion _name._
           **.class** _ident c1 c2_ ...
                      Define a (character) class _ident_ comprising the
                      characters or range expressions _c1_ , _c2_ , and so on.
           **.close** _stream_
                      Close _stream_ , making it unavailable for ”**write** ”
                      requests.
           **.color** Enable output of color-related device-independent
                      output commands.  It is enabled by default.
           **.color** _b_   Enable or disable output of color-related device-
                      independent output commands per Boolean expression _b_.
           **.composite** _c_
                      Remove composite character mapping for character _c._
           **.composite** _c1 c2_
                      Map character _c1_ to _c2_ when _c1_ is a combining component
                      in a composite character.
           **.continue** Skip the remainder of a “**while** ” loop's body,
                      immediately retesting its conditional expression.
           **.cp** Enable AT&T _troff_ compatibility mode.  It is disabled
                      by default.
           **.cp** _b_      Enable or disable AT&T _troff_ compatibility mode per
                      Boolean expression _b_.
           **.cs** _f_      Disable constant-width glyph spacing mode for font _f._
           **.cs** _f n_    Enable constant-width glyph spacing mode for font _f_ at
                      _n_ /36 ems.
           **.cs** _f n p_  Enable constant-width glyph spacing mode for _font_ at
                      _n_ /36 ems, as if one em equals _p_ scaled points.
           **.cu** Continuously underline the output of the next
                      productive input line.
           **.cu** _npl_    Continuously underline the output of the next _npl_
                      productive input lines.  If _npl_ =0, stop continuously
                      underlining.
           **.da** Stop appending output to current diversion.
           **.da** _div_    Append output to diversion _div_.
           **.de** _ident_  Define macro _ident_ until “**..** ” occurs at the start of a
                      control line in the current conditional block.
           **.de** _ident end-mac_
                      Define macro _ident_ until _end-mac_ is called at the start
                      of a control line in the current conditional block.
                      _end-mac_ can be a request.
           **.de1** _ident_ As **de** , with compatibility mode disabled when _mac_ is
                      interpreted.
           **.de1** _ident end-mac_
                      As “**.de** _ident end-mac_ ”, with compatibility mode
                      disabled when _mac_ is interpreted.
           **.defcolor** _ident scheme color-component_ ...
                      Define a color named _ident._  _scheme_ identifies a color
                      space and determines the number of required _color-_
                      _component_ s; it must be one of “**rgb** ” (three components),
                      “**cmy** ” (three), “**cmyk** ” (four), or “**gray** ” (one).  “**grey** ”
                      is accepted as a synonym of “**gray** ”.  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 “**f** ”, which multiplies its value by 65,536 (but
                      clamps it at 65,535).
           **.dei** _str_   Define macro indirectly.  As **de** , but interpolate string
                      _str_ to obtain the macro's name.
           **.dei** _str end-mac-str_
                      Define macro indirectly.  As **de** , but _str_ and _end-mac-_
                      _str_ contain the names of the macro to be defined, and
                      that whose call ends the definition, respectively.
           **.dei1** _str_  As **dei** , with compatibility mode disabled when the macro
                      is interpreted.
           **.dei1** _str end-mac-str_
                      As **dei** , with compatibility mode disabled when the macro
                      is interpreted.
           **.device** _character-sequence_
                      Write _character-sequence_ , a sequence of ordinary or
                      special characters and spaces, to _troff_ output as the
                      argument to a device extension command.
           **.devicem** _name_
                      Write contents of macro or string _name_ to _troff_ output
                      as the argument to a device extension command.
           **.di** Stop directing output to current diversion.
           **.di** _ident_  Direct output to diversion _ident_.
           **.do** _name argument_ ...
                      Interpret the string, request, diversion, or macro _name_
                      (along with any further arguments) with compatibility
                      mode disabled.  Compatibility mode is restored (only if
                      it was active) when the interpolation of _name_ is
                      interpreted.
           **.ds** _ident_  Create empty string named _ident_.
           **.ds** _ident contents_
                      Create a string named _ident_ containing _contents._
           **.ds1** _ident_
           **.ds1** _ident contents_
                      As **ds** , with compatibility mode disabled when the string
                      is interpreted.
           **.dt** Clear diversion trap.
           **.dt** _vertical-position mac_
                      Set the diversion trap to macro _mac_ at _vertical-_
                      _position_ (default scaling unit **v**).
           **.ec** Recognize **\** as the escape character.
           **.ec** _o_      Recognize ordinary character _o_ as the escape character.
           **.ecr** Restore escape character saved with **ecs**.
           **.ecs** Save the escape character.
           **.el** Interpolate a newline if the conditional expression of
                      the corresponding **ie** request was false.
           **.el** _anything_
                      Interpret _anything_ as if it were an input line if the
                      conditional expression of the corresponding **ie** request
                      was false.
           **.em** Unset end-of-input macro.
           **.em** _mac_    Call macro _mac_ after the end of input.
           **.eo** Disable the escape mechanism in interpretation mode.
           **.ev** Pop environment stack, returning to previous one.
           **.ev** _env_    Push current environment onto stack and switch to _env_ ,
                      creating it if necessary.
           **.evc** _env_   Copy environment _env_ to the current one.
           **.ex** Exit with successful status.
           **.fam** Set default font family to previous value.
           **.fam** _name_  Set default font family to _name_.
           **.fc** Disable field mechanism.
           **.fc** _c_      Set field delimiter to _c_ and pad glyph to space.
           **.fc** _c1 c2_  Set field delimiter to _c1_ and pad glyph to _c2_.
           **.fchar** _c_   Define fallback character _c_ as empty.
           **.fchar** _c contents_
                      Define fallback character _c_ as _contents_.  As **char** , but
                      while that request hides a glyph with the same name in
                      the selected font, **fchar** definitions are used only if
                      the font lacks a glyph for _c_.  GNU _troff_ performs this
                      test before searching special fonts.
           **.fcolor** Restore previous fill color, or the default if there is
                      none.
           **.fcolor** _col_
                      Select _col_ as the fill color.
           **.fi** Enable filling of output lines; a pending output line
                      is broken.  Sets **\n[.u]**.
           **.fl** Flush any pending output line.
           **.fp** _pos id_ Mount font with font description file name _id_ at non-
                      negative position _pos_.
           **.fp** _pos id font-description-file-name_
                      Mount font with _font-description-file-name_ as name _id_
                      at non-negative position _pos_.
           **.fschar** _f c_
                      Define fallback character _c_ specific to font _f_ as
                      empty.
           **.fschar** _f c contents_
                      Define fallback character _c_ specific to font _f_ as
                      _contents_.  As **char** , but GNU _troff_ locates a character
                      defined by **fschar** after any fonts named as arguments to
                      the **fspecial** are searched and before those named as
                      arguments to the “**special** ” request.
           **.fspecial** _font_
                      Empty the list of fonts treated as special when _font_ is
                      selected.
           **.fspecial** _fnt sfnt_ ...
                      When font _fnt_ is selected, treat each font _sfnt_ as
                      _special;_ that is, search it for any glyph not found in
                      _f_.  GNU _troff_ searches fonts specified as arguments to
                      the “**special** ” request after those given as arguments to
                      the **fspecial** request.
           **.ft**
           **.ft P** Select the typeface _font._  If _font_ 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 _troff_ combines it with
                      the default family (see **fam** above and **\F** below) to make
                      a resolved font name.  If _font_ is “**DESC** ”, if the
                      mounting position is not an abstract style and no font
                      is mounted there, or the mounting position is negative,
                      GNU _troff_ ignores the request.  (It also emits a
                      warning in category “**font** ”, or “**range** ”, as appropriate.
                      See section “Warnings” in _troff_(1).)  Also see **\f .**
           **.ftr** _f_     Remove translation of font named _f_.
           **.ftr** _f1 f2_ Translate font name _f1_ to _f2_.
           **.fzoom** _font_ **0**
                      Stop magnifying _font_.
           **.fzoom** _font zoom_
                      Set magnification of mounted _font_ to _zoom_ , a multiplier
                      of the current type size in thousandths (default:
                      1000).
           **.gcolor** Restore previous stroke color, or the default if there
                      is none.
           **.gcolor** _col_
                      Select _col_ as the stroke color.
           **.hc** Reset the hyphenation character to **\%**(the default).
           **.hc** _c_      Change the hyphenation character to _c_.
           **.hcode** _dst1 src1_ [_dst2 src2_] ...
                      Set the hyphenation code of character _dst1_ to that of
                      _src1_ , and so on.
           **.hla** Clear the environment's hyphenation language (disabling
                      automatic hyphenation).
           **.hla** _ident_ Set the environment's hyphenation language to _ident_.
           **.hlm** Set the consecutive automatically hyphenated line limit
                      to **-1**(the default), meaning “no limit”.
           **.hlm** _n_     Set the consecutive automatically hyphenated line limit
                      to to _n._  A negative value means “no limit”.
           **.hpf** _file_  Read hyphenation patterns from _file_.
           **.hpfa** _file_ Append hyphenation patterns from _file_.
           **.hpfcode** _a b_ [_c d_] ...
                      _Caution:_ This request will be withdrawn in a future
                      _groff_ release.  Use **hcode** instead.
                      Define mappings for character codes in hyphenation
                      pattern files.
           **.hw** _word_ ...
                      Define each _hyphenation exception word_ comprising
                      ordinary or special characters with each hyphen-minus
                      “**-** ” in _word_ indicating a hyphenation point.
           **.hy** Set automatic hyphenation mode to the value of the
                      **.hydefault** register.
           **.hy 0** Disable automatic hyphenation; same as **.nh**.
           **.hy** _mode_   Set automatic hyphenation mode to _mode_ ; see section
                      “Hyphenation” below.
           **.hydefault** _mode_
                      Set hyphenation mode default to _mode_ ; see section
                      “Hyphenation” below.
           **.hym** Set the (right) hyphenation margin to **0**(the default).
           **.hym** _length_
                      Set the (right) hyphenation margin to _length_ (default
                      scaling unit **m**).
           **.hys** Set the hyphenation space to **0**(the default).
           **.hys** _hyphenation-space_
                      Suppress automatic hyphenation in adjustment modes “**b** ”
                      or “**n** ” if that adjustment can be achieved by adding no
                      more than _hyphenation-space_ to each inter-word space
                      (default scaling unit **m**).
           **.ie** _cond-expr_
                      Interpolate a newline if _cond-expr_ is true, otherwise
                      skip to a corresponding **el** request.
           **.ie** _cond-expr anything_
                      If _cond-expr_ is true, interpret _anything_ as if it were
                      an input line, otherwise skip to a corresponding **el**
                      request.
           **.if** _cond-expr_
                      Interpolate a newline if _cond-expr_ is true.
           **.if** _cond-expr anything_
                      If _cond-expr_ is true, then interpret _anything_ as if it
                      were an input line.
           **.ig** Ignore input (except for side effects of **\R** on auto-
                      incrementing registers) until “**..** ” occurs at the start
                      of a control line in the current conditional block.
           **.ig** _end-mac_
                      Ignore input (except for side effects of **\R** on auto-
                      incrementing registers) until _end-mac_ is called at the
                      start of a control line in the current conditional
                      block.  _end-mac_ can be a request.
           **.in** Set indentation amount to previous value.
           **.in** _±N_     Set indentation to _±N_ (default scaling unit **m**).
           **.it** Cancel any pending input line trap.
           **.it** _npl mac_
                      Set (or replace) an input line trap in the environment,
                      calling _mac_ after the next _npl_ productive input lines
                      have been read.  Lines interrupted with the **\c** escape
                      sequence are counted separately.
           **.itc** Cancel any pending input line trap.
           **.itc** _npl mac_
                      As ”**it** ”, except that input lines interrupted with the
                      **\c** escape sequence are not counted.
           **.kern** Enable pairwise kerning.
           **.kern** _b_    Enable or disable pairwise kerning per Boolean
                      expression _b_.
           **.lc** Unset leader repetition character.
           **.lc** _c_      Set leader repetition character to _c_ (default: “**.** ”).
           **.length** _reg contents_
                      Compute the number of characters in _contents_ and store
                      the count in the register _reg_.
           **.linetabs** Activate line-tabs in the environment.  It is disabled
                      by default.
           **.linetabs** _b_
                      Activate or deactivate line-tabs in the environment per
                      Boolean expression _b_.
           **.lf** _input-line-number_
                      Set the input line number GNU _troff_ uses when reporting
                      diagnostics.  The argument becomes the input line
                      number of the _next_ line the formatter reads.
           **.lf** _input-line-number character-sequence_
                      As **lf** with one argument, but also update the reported
                      file name to _character-sequence_.
           **.lg** Enable ligature mode **1**.
           **.lg** _m_      Set ligature mode to _m_ (**0** = disable, **1** = enable, **2** =
                      enable for two-letter ligatures only).
           **.ll** Set line length to previous value.  Does not affect a
                      pending output line.
           **.ll** _±N_     Set line length to _±N_ (default length 6.5**i** , default
                      scaling unit **m**).  Does not affect a pending output
                      line.
           **.lsm** Unset the leading space macro (trap).  Restore default
                      handling of lines with leading spaces.
           **.lsm** _mac_   Set the leading space macro (trap) to _mac_.
           **.ls** Change to the previous value of additional intra-line
                      skip.
           **.ls** _n_      Set additional intra-line skip value to _n_ , i.e., _n_ -1
                      blank lines are inserted after each text output line.
           **.lt** Set length of title lines to previous value.
           **.lt** _±N_     Set length of title lines (default length 6.5**i** , default
                      scaling unit **m**).
           **.mc** Cease writing margin character.
           **.mc** _c_      Begin writing margin character _c_ to the right of each
                      output line at a distance of 10**p**.
           **.mc** _c d_    Begin writing margin character _c_ on each output line at
                      distance _d_ to the right of the right margin (default
                      distance 10**p** , default scaling unit **m**).
           **.mk** Mark vertical drawing position in an internal register;
                      see **.rt**.
           **.mk** _reg_    Mark vertical drawing position in register _reg_.
           **.mso** _file_  As ”**so** ”, except that GNU _troff_ searches for the
                      specified _file_ in the same directories as macro files;
                      see _GROFF_TMAC_PATH_ in section “Environment” of
                      _groff_(1) and **-m** in section “Options” of the same page.
           **.msoquiet** _file_
                      As **mso** , but no warning is emitted if _file_ does not
                      exist.
           **.na** Disable output line adjustment.
           **.ne** Break page if distance to next page location trap is
                      less than one vee.
           **.ne** _d_      Break page if distance to next page location trap is
                      less than distance _d_ (default scaling unit **v**).
           **.nf** Disable filling of output lines; a pending output line
                      is broken.  Clears **\n[.u]**.
           **.nh** Disable automatic hyphenation; same as “**.hy 0** ”.
           **.nm** Deactivate output line numbering.
           **.nm** _±N_
           **.nm** _±N m_
           **.nm** _±N m s_
           **.nm** _±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 (**\0**) between the line number and
                      the output (default 1), and indenting the line number
                      by _i_ numeral widths (default 0).
           **.nn** Suppress numbering of the next output line counted by
                      **nm**.
           **.nn** _n_      Suppress numbering of the next _n_ output lines counted
                      by **nm**.  If _n_ =0, cancel suppression.
           **.nop** Interpolate a newline.
           **.nop** _anything_
                      Interpret _anything_ as if it were an input line.
           **.nr** _reg ±N_ Define or update register _reg_ with value _N_.
           **.nr** _reg ±N I_
                      Define or update register _reg_ with value _N_ and auto-
                      increment _I_ , which may be any integer.
           **.nroff** Make the conditional expressions **n** true and **t** false.
           **.ns** Enable _no-space mode_ , ignoring **.sp** requests until a
                      glyph or **\D** primitive is output.  See **.rs**.
           **.nx** Stop processing the input file and read the next, if
                      any.
           **.nx** _file_   Stop processing the input file and read _file_.
           **.open** _ident file_
                      Open _file_ for writing and associate a stream named
                      _ident_ with it, making it available for ”**write** ”
                      requests.  Unsafe request; disabled by default.
           **.opena** _ident file_
                      As “**open** ”, but if _file_ already exists, appends to it
                      instead of overwriting it.  Unsafe request; disabled by
                      default.
           **.os** Output vertical space that was saved by the **sv** request.
           **.output** _character-sequence_
                      Emit _character-sequence_ “transparently” (directly) to
                      _troff_ 's output.
           **.pc** Reset page number character to ‘**%** ’.
           **.pc** _c_      Change the page number character used in titles to _c_.
           **.pchar** _c_ ...
                      Report, to the standard error stream, information about
                      each ordinary, special, or indexed character _c_.  A
                      character defined by a request (**char** , **fchar** , **fschar** , or
                      **schar**) reports its contents as a JSON-encoded string,
                      but the output is not otherwise in JSON format.
           **.pcolor** 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.
           **.pcolor** _col_ ...
                      Report, to the standard error stream, the name, color
                      space identifier, and channel value assignments of each
                      color _col_.
           **.pcomposite**
                      Report, to the standard error stream, the list of
                      configured composite character mappings.  See the
                      “**composite** ” request.  The “from” code point is listed
                      first, followed by its “to” mapping.
           **.pev** Report the state of the current environment followed by
                      that of all other environments to the standard error
                      stream.
           **.pfp** 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 device, follow.
           **.pftr** Report, to the standard error stream, the list of font
                      translations.
           **.phw** Report, to the standard error stream, the list of
                      hyphenation exceptions associated with the current
                      hyphenation language.  Each hyphenation point is marked
                      with “**-** ”.  Words that will not be hyphenated at all are
                      prefixed with “**-** ”.  Those to which the automatic
                      hyphenation mode applies (meaning those defined in a
                      hyphenation pattern file rather than with the **hw**
                      request) are suffixed with a tab and asterisk (*****).
           **.pi** _command_
                      Pipe GNU _troff_ output through _command_ (which is read in
                      copy mode) by passing it to _popen_(3).  Multiple **pi**
                      requests construct a multi-stage pipeline in the same
                      order as the formatter encounters the requests.  Unsafe
                      request; disabled by default.
           **.pl** Set page length to default 11**i**.  The current page
                      length is stored in register **.p**.
           **.pl** _±N_     Change page length to _±N_ (default scaling unit **v**).
           **.pline** 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 _pending_ output line has
                      not yet undergone adjustment, and lacks a line number
                      and margin character (all as applicable).
           **.pm** Report, to the standard error stream, the names of all
                      defined macros, strings, and diversions and their
                      lengths in characters or nodes.
           **.pm** _name_ ...
                      Report, to the standard error stream, the JSON-encoded
                      name and contents of each macro, string, or diversion
                      _name_.
           **.pn** _±N_     Set next page number.
           **.pnr** Report the names, values, and (as applicable)
                      autoincrement amounts and assigned formats of all
                      defined registers to the standard error stream.
           **.pnr** _reg_ ...
                      Report the name and value and, if its type is numeric,
                      the autoincrement amount and assigned format, of each
                      register _reg_ to the standard error stream.
           **.po** Change to previous page offset.  The current page
                      offset is available in register **.o**.
           **.po** _±N_     Alter page offset (default scaling unit **m**).
           **.ps** Restore previous type size.
           **.ps** _±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 **\s[**_±N_**]**.
           **.psbb** _postscript-file_
                      Retrieve the bounding box of the PostScript image found
                      in _postscript-file,_ which must conform to Adobe's
                      Document Structuring Conventions (DSC).  See registers
                      **llx** , **lly** , **urx** , **ury**.
           **.pso** _command_
                      As “**so** ”, except that input comes from the standard
                      output stream of _command_ , which is passed to _popen_(3).
                      Unsafe request; disabled by default.
           **.pstream** 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).
           **.ptr** Report names and positions of all page location traps
                      to the standard error stream.
           **.pvs** Change to previous post-vertical line spacing.
           **.pvs** _±N_    Change post-vertical line spacing according to _±N_
                      (default scaling unit **p**).
           **.rchar** _c1 c2_ ...
                      Remove definition of each ordinary, special, or indexed
                      character _c_ , undoing the effect of a **char** , **fchar** , or
                      **schar** request.  The character definition removed (if
                      any) is the first encountered in the resolution process
                      documented in section “Using Symbols” of _Groff: The GNU_
                      _Implementation of troff_.  Glyphs, which are defined by
                      font description files, cannot be removed.  Spaces need
                      not separate the arguments.
           **.rd** Read insertion from standard input stream, ringing
                      terminal bell as prompt.
           **.rd** _terminal-message_
                      Read insertion from standard input stream, writing
                      _terminal-message_ to standard error stream as prompt.
           **.return** Stop interpreting an interpolated macro, skipping the
                      remainder of its definition.
           **.return** _anything_
                      As **return** , but perform the skip twice—once within the
                      macro being interpreted and once in an enclosing macro.
           **.rfschar** _f c1 c2_ ...
                      Remove font-specific character definitions _c1_ , _c2_ , ...
                      for created by **fschar** for font _f_.
           **.rj** Break, right-align the output of the next productive
                      input line without filling, then break again.
           **.rj** _npl_    Break, right-align the output of the next _npl_
                      productive input lines without filling, then break
                      again.  If _npl_ ≤ 0, stop right-aligning.
           **.rm** _name_ ...
                      Remove each request, macro, diversion, or string _name_.
           **.rn** _old new_
                      Rename request, macro, diversion, or string _old_ to _new_.
           **.rnn** _reg1 reg2_
                      Rename register _reg1_ to _reg2_.
           **.rr** _reg_ ...
                      Remove each register _reg_.
           **.rs** Restore spacing; disable no-space mode.  See **.ns**.
           **.rt** Return _(upward only)_ to vertical position marked by **.mk**
                      on the current page.
           **.rt** _N_      Return _(upward only)_ to vertical position _N_ (default
                      scaling unit **v**).
           **.schar** _c_   Define global fallback character _c_ as empty.
           **.schar** _c contents_
                      Define global fallback character _c_ as _contents_.  As
                      **char** , but GNU _troff_ locates a character defined with
                      **schar** after any fonts named as arguments to the
                      “**special** ” request and before any mounted special fonts.
           **.shc** Reset the soft hyphen character to **\[hy]**.
           **.shc** _c_     Set the soft hyphen character to _c_.
           **.shift** In a macro definition, left-shift arguments by one
                      position.
           **.shift** _n_   In a macro definition, left-shift arguments by
                      _n_ positions.
           **.sizes** _s1 s2_ ... _sn_ [**0**]
                      Set available type sizes to the list of values or
                      ranges; each _s_ i is interpreted in units of scaled
                      points (**s**).  GNU _troff_ strips a leading neutral double
                      quote from _s1_ ; it reads each _s_ i in copy mode.
           **.so** _file_   Replace the request's control line with the contents of
                      _file_ , “sourcing” it.  GNU _troff_ searches for _file_ in
                      any directories specified by **-I** command-line options,
                      followed by the current working directory.  If _file_
                      does not exist, the formatter ignores the request.
                      (GNU _troff_ emits a warning in category “**file** ”.)
           **.soquiet** _file_
                      As ”**so** ”, but no warning is emitted if _file_ does not
                      exist.
           **.sp** Break and move the next text baseline down by one vee,
                      or until springing a page location trap.
           **.sp** _dist_   Break and move the next text baseline down by _dist_ , or
                      until springing a page location trap (default scaling
                      unit **v**).  A negative _dist_ will not reduce the position
                      of the text baseline below zero.  Prefixing _dist_ with
                      the **|** operator moves to a position relative to the page
                      top for positive _N_ , and the bottom if _N_ is negative; in
                      all cases, one line height (vee) is added to _dist_.
                      _dist_ is ignored inside a diversion.
           **.special** Empty the list of special fonts designated by this
                      request when given arguments.
           **.special** _s_ ...
                      Declare each font _s_ as _special,_ searching it for glyphs
                      not found in the selected font.
           **.spreadwarn**
                      Toggle the spread warning on and off (the default)
                      without changing its value.
           **.spreadwarn** _N_
                      Emit a **break** warning if the additional space inserted
                      for each space between words in an adjusted output line
                      is greater than or equal to _N_.  A negative _N_ is treated
                      as 0.  The default scaling unit is **m**.  At startup,
                      **spreadwarn** is inactive and _N_ is 3 m**.**
           **.ss** _n_      Set minimum inter-word space and additional inter-
                      sentence space sizes to _n_ 12ths of the selected font's
                      **spacewidth** parameter (default: 12).
           **.ss** _n m_    As “**.ss** _n_ ”, but set additional inter-sentence space
                      size to _m_ 12ths of the selected font's **spacewidth**
                      parameter.
           **.stringdown** _str_
                      Replace each byte in the string named _str_ with its
                      lowercase version.
           **.stringup** _str_
                      Replace each byte in the string named _str_ with its
                      uppercase version.
           **.sty** _pos style_
                      Associate abstract _style_ with non-negative font
                      position _pos_.
           **.substring** _str start_ [_end_]
                      Replace the string named _str_ with its substring bounded
                      by the indices _start_ and _end_ , inclusive.  Negative
                      indices count backward from the end of the string.
           **.sv** As **ne** , but save 1 v for output with **os** request.
           **.sv** _d_      As **ne** , but save distance _d_ for later output with **os**
                      request (default scaling unit **v**).
           **.sy** _command_
                      Execute _command_ (which is read in copy mode) in the
                      operating environment by passing it to _system_(3).  See
                      register **systat**.  Unsafe request; disabled by default.
           **.ta** Clear tab stops.
           **.ta** _n1 n2_ ... _n_ n **T** _r1 r2_ ... _r_ n
                      Set tabs at positions _n1_ , _n2_ , ..., _n_ n, then set tabs at
                      _n_ n+_m_ × _r_ n+_r1_ through _n_ n+_m_ × _r_ n+_r_ n, 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 _ni_ at a distance relative to the previous, _n_(_i_ -1).
                      Each argument _ni_ or _ri_ can be suffixed with a letter to
                      align text within the tab column bounded by tab stops
                      _i_ and _i_ +1; “**L** ” for left-aligned (the default), “**C** ” for
                      centered, and “**R** ” for right-aligned.
           **.tag** Reserved for internal use.
           **.taga** Reserved for internal use.
           **.tc** Unset tab repetition character.
           **.tc** _c_      Set tab repetition character to _c_ (default: none).
           **.ti** _±N_     Temporarily indent next output line (default scaling
                      unit **m**).
           **.tkf** _font s1 n1 s2 n2_
                      Enable track kerning for _font_.
           **.tl '**_left_**'**_center_**'**_right_**'**
                      Format three-part title.
           **.tm** Write a newline to the standard error stream.
           **.tm** _terminal-message_
                      Send _terminal-message_ , 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 _not_ remove a leading double quote; contrast **.tm1**.
           **.tm1** As **tm**.
           **.tm1** _message_
                      As **tm** , but removes a leading neutral double quote ‘**"** ’
                      from _message_ , permitting initial embedded spaces in it,
                      and reads it to the end of the input line in copy mode.
           **.tmc** No operation.
           **.tmc** _message_
                      As **tm1** , but does not append a newline.
           **.tr** _abcd_...
                      Translate ordinary or special characters _a_ to _b_ , _c_ to
                      _d_ , and so on prior to output.
           **.trf** _file_  Break and copy contents of _file_ as “throughput” to GNU
                      _troff_ output (see _groff_out_(5)).  Unlike **cf** , characters
                      invalid as input to GNU _troff_ are discarded.  If _file_ 's
                      contents do not end with a newline, **trf** appends one.
           **.trin** _abcd_...
                      As **tr** , except that **asciify** ignores the translation when
                      a diversion is interpolated.
           **.trnt** _abcd_...
                      As **tr** , except that translations are suppressed in the
                      argument to **\!**.
           **.troff** Make the conditional expressions **t** true and **n** false.
           **.uf** _font_   Set underline font used by **ul** to _font._
           **.ul** Underline (italicize in _troff_ mode) the output of the
                      next productive input line.
           **.ul** _npl_    Underline (italicize in _troff_ mode) the output of the
                      next _npl_ productive input line.  If _npl_ =0, stop
                      underlining.
           **.unformat** _div_
                      Unformat space characters and tabs in diversion _div_ ,
                      preserving font information.
           **.vpt** Enable vertical position traps.  They are enabled by
                      default.
           **.vpt** _b_     Enable or disable vertical position traps per Boolean
                      expression _b_.
           **.vs** Change to previous vertical spacing.
           **.vs** _±N_     Set vertical spacing to _±N_ (default scaling unit **p**).
           **.warn** Enable all warning categories.
           **.warn 0** Disable all warning categories.
           **.warn** _n_    Enable warnings in categories whose codes sum to _n_ ; see
                      _troff_(1).
           **.warnscale** _scaling-unit_
                      Select scaling unit used in certain warnings (one of **u** ,
                      **i** , **c** , **p** , or **P** ; default: **i**).  Ignored on _nroff_ -mode
                      output devices, for which these diagnostics report the
                      vertical page location in lines, and the horizontal
                      page location in ens.
           **.wh** _vertical-position_
                      Remove visible page location trap at _vertical-position_
                      (default scaling unit **v**).
           **.wh** _vertical-position mac_
                      Plant macro _mac_ as page location trap at _vertical-_
                      _position_ (default scaling unit **v**), removing any visible
                      trap already there.
           **.while** _cond-expr_
                      Interpolate newlines unless and until _cond-expr_
                      evaluates false.
           **.while** _cond-expr anything_
                      Repeatedly execute _anything_ unless and until _cond-expr_
                      evaluates false.
           **.write** _stream character-sequence_
                      Write _character-sequence_ , a sequence of ordinary
                      characters, spaces, or tabs, to _stream_ , which must
                      previously have been the subject of an “**open** ” (or
                      **opena**) request, followed by a newline.  GNU _troff_
                      flushes the stream after writing to it.
           **.writec** _stream character-sequence_
                      As ”**write** ”, but does not write a newline to the output.
           **.writem** _stream name_
                      Write the contents of the macro or string _name_ to
                      _stream_ , which must previously have been the subject of
                      an “**open** ” (or **opena**) request.  The contents of _name_ are
                      read in copy mode.
    


## Escape sequence short reference



           The escape sequences **\"** , **\#** , **\$** , **\*** , **\?** , **\a** , **\e** , **\n** , **\t** , **\g** , **\V** ,
           and **\**_newline_ are interpreted even in copy mode.
    
           The escape sequences **\f** , **\F** , **\H** , **\m** , **\M** , **\R** , **\s** , and **\S** are not
           tokenized when GNU _troff_ reads its input.  **\R** 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 “Gtroff Internals” section
           of the _groff_ 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_.
           **\*(**_st_  Interpolate string with two-character name _st_.
           **\*[**_string_**]**
                  Interpolate string with name _string_ (of arbitrary length).
           **\*[**_string arg_ ...**]**
                  Interpolate string with name _string_ (of arbitrary length),
                  taking _arg_ ... as arguments.
           **\$0** Interpolate name by which currently executing macro was
                  invoked.
           **\$**_n_    Interpolate macro or string parameter numbered _n_ (1≤ _n_ ≤9).
           **\$(**_nn_  Interpolate macro or string parameter numbered _nn_
                  (01≤ _nn_ ≤99).
           **\$[**_nnn_**]**
                  Interpolate macro or string parameter numbered _nnn_ (_nnn_ ≥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 **ds** request.
           **\'** is a synonym for **\[aa]** , the acute accent special character.
           **\`** is a synonym for **\[ga]** , the grave accent special character.
           **\-** is a synonym for **\[-]** , the minus sign special character.
           **\_** is a synonym for **\[ul]** , the underrule special character.
           **\%** Mark a hyphenation point within a word.  At the beginning
                  of a word, prevent it from being otherwise hyphenated.
           **\!** Transparent throughput.  Read everything up to the next
                  newline in copy mode and ignore it, but pass it through to
                  (1) an enclosing diversion, or (2) if appearing in the top-
                  level diversion, GNU _troff_ output.
           **\?**_anything_**\?**
                  Transparently embed _anything_ , read in copy mode, in a
                  diversion, or unformatted as an output comparand in a
                  conditional expression.  Ignored in the top-level
                  diversion.
           **\**_space_ Move right one inter-word space.
           **\~** Insert an unbreakable, adjustable space.
           **\0** 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-sentence 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 hyphen glyph).
           **\**_newline_
                  Continue current input line on the next.
           **\{** Begin conditional input.
           **\}** End conditional input.
           **\(**_sc_   Interpolate glyph of special character with two-character
                  identifier _sc_.
           **\[**_spchar_**]**
                  Interpolate glyph of special character with identifier
                  _spchar_ (of arbitrary length).
           **\[**_base-char comp_ ...**]**
                  Interpolate composite glyph constructed from _base-char_ and
                  each component _comp_.
           **\[char** _nnn_**]**
                  Interpolate glyph of eight-bit encoded character _nnn_ , where
                  0≤ _nnn_ ≤255.
           **\[u** _nnnn_[_n_[_n_]]**]**
                  Interpolate glyph of Unicode character with code point
                  _nnnn_[_n_[_n_]] in uppercase hexadecimal.
           **\[u** _base-char_[**_**_combining-component_]...**]**
                  Interpolate composite glyph from Unicode character _base-_
                  _char_ and _combining-components_.
           **\a** Interpolate a leader in copy mode.
           **\A'**_anything_**'**
                  Interpolate 1 if _anything_ is a valid identifier, and 0
                  otherwise.
           **\b'**_string_**'**
                  Build bracket: pile a sequence of glyphs corresponding to
                  each character in _string_ vertically, and center it
                  vertically on the output line.
           **\B'**_anything_**'**
                  Interpolate 1 if _anything_ is a valid numeric expression,
                  and 0 otherwise.
           **\c** Continue output line at next input line.
           **\C'**_glyph_**'**
                  As **\[**_glyph_**]** , but compatible with other _troff_
                  implementations.
           **\d** Move downward ½ em on typesetters.
           **\D'**_drawing-command_**'**
                  See subsection “Drawing commands” below.
           **\e** Interpolate the escape character.
           **\E** As **\e** , but not interpreted in copy mode.
           **\fP** Select previous font mounting position (abstract style or
                  font); same as “**.ft** ” or “**.ft P** ”.
           **\f** _F_    Select font mounting position, abstract style, or font with
                  one-character name or one-digit position _F_.  _F_ cannot be **P**.
           **\f(**_ft_  Select font mounting position, abstract style, or font with
                  two-character name or two-digit position _ft_.
           **\f[**_font_**]**
                  Select font mounting position, abstract style, or font with
                  arbitrarily long name or position _font_.  _font_ cannot be **P**.
           **\f[]** Select previous font mounting position (abstract style or
                  font).
           **\F** _f_    Set default font family to that with one-character name _f_.
           **\F(**_fm_  Set default font family to that with two-character name _fm_.
           **\F[**_fam_**]**
                  Set default font family to that with arbitrarily long name
                  _fam_.
           **\F[]** Set default font family to previous value.
           **\g** _r_    Interpolate format of register with one-character name _r_.
           **\g(**_rg_  Interpolate format of register with two-character name _rg_.
           **\g[**_reg_**]**
                  Interpolate format of register with arbitrarily long name
                  _reg_.
           **\h'**_N_**'** Horizontally move the drawing position by _N_ ems (or
                  specified units); **|** may be used.  Positive motion is
                  rightward.
           **\H'**_N_**'** Set height of current font to _N_ scaled points (or specified
                  units).  If _N_ is zero, set the font height to the selected
                  type size.
           **\k** _r_    Store the horizontal drawing position, relative to that
                  corresponding to the start of the input line (ignoring page
                  offset and indentation), in register name _r_.
           **\k(**_rg_  Store the horizontal drawing position, relative to that
                  corresponding to the start of the input line (ignoring page
                  offset and indentation), in register name _rg_.
           **\k[**_reg_**]**
                  Store the horizontal drawing position, relative to that
                  corresponding to the start of the input line (ignoring page
                  offset and indentation), in register name _reg_.
           **\l'**_N_[_c_]**'**
                  Draw horizontal line of length _N_ with character _c_ (default:
                  **\[ru]** ; default scaling unit **m**).
           **\L'**_N_[_c_]**'**
                  Draw vertical line of length _N_ with character _c_ (default:
                  **\[br]** ; default scaling unit **v**).
           **\m** _c_    Select stroke color with one-character name _c_.
           **\m(**_cl_  Select stroke color with two-character name _cl_.
           **\m[**_color_**]**
                  Select stroke color with arbitrarily long name _color_.
           **\m[]** Restore previous stroke color.
           **\M** _c_    Select fill color with one-character name _c_.
           **\M(**_cl_  Select fill color with two-character name _cl_.
           **\M[**_color_**]**
                  Select fill color with arbitrarily long name _color_.
           **\M[]** Restore previous fill color.
           **\n** _r_    Interpolate value of register with one-character name _r_.
           **\n(**_rg_  Interpolate value of register with two-character name _rg_.
           **\n[**_reg_**]**
                  Interpolate value of register with arbitrarily long
                  name _reg_.
           **\N'**_n_**'** Format indexed character numbered _n_ in the current font.
           **\o'**_abc_...**'**
                  Overstrike centered glyphs of characters _a_ , _b_ , _c_ , and so
                  on.
           **\O0** At the outermost suppression level, disable emission of
                  glyphs and geometric objects to the output driver.
           **\O1** At the outermost suppression level, enable emission of
                  glyphs and geometric objects to the output driver.
           **\O2** 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
                  **\O** escape sequence, the page offset, line length, image
                  file name (if any), horizontal and vertical device motion
                  quanta, and input file name.
           **\O3** Begin a nested suppression level.
           **\O4** End a nested suppression level.
           **\O[5** _Pfile_**]**
                  At the outermost suppression level, write the name _file_ to
                  the standard error stream at position _P_ , which must be one
                  of **l** , **r** , **c** , or **i**.
           **\p** Break output line at next word boundary; adjust if
                  applicable.
           **\r** Move “in reverse” (upward) 1 em.
           **\R'**_name ±N_**'**
                  Set, increment, or decrement register _name_ by _N_.
           **\s** _±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 **ps** request.
           **\s(**_±N_
           **\s** _±_**(**_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 previous size.  Otherwise, as **ps** request.
           **\s[**_±N_**]**
           **\s** _±_**[**_N_**]**
           **\s'**_±N_**'**
           **\s** _±_**'**_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 **ps**
                  request.
           **\S'**_N_**'** Slant output glyphs by _N_ degrees; the direction of text
                  flow is positive.
           **\t** Interpolate a tab in copy mode.
           **\u** Move upward ½ em on typesetters.
           **\v'**_N_**'** Vertically move the drawing position by _N_ vees (or
                  specified units); **|** may be used.  Positive motion is
                  downward.
           **\V** _e_    Interpolate value of system environment variable with one-
                  character name _e_ as returned by _getenv_(3).
           **\V(**_ev_  Interpolate value of system environment variable with two-
                  character name _ev_ as returned by _getenv_(3).
           **\V[**_env_**]**
                  Interpolate value of system environment variable with
                  arbitrarily long name _env_ as returned by _getenv_(3).
           **\w'**_anything_**'**
                  Interpolate width of _anything_ , formatted in a dummy
                  environment.
           **\x'**_N_**'** Increase vertical spacing of pending output line by _N_ vees
                  (or specified units; negative before, positive after).
           **\X'**_character-sequence_**'**
                  Write _character-sequence_ to _troff_ output as a device
                  extension command.  The _groff_ 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 _groff_char_(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.  These are not representable
                  when interpolated directly into device-independent output,
                  as might be done when writing 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 _troff_ 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 characters 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 usefully named
                  bookmark or hyperlink anchor, GNU _troff_ maps other special
                  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 characters, produce warnings in category
                  “**char** ”.
           **\Y** _n_    Write contents of macro or string _n_ to _troff_ output as a
                  device extension command.
           **\Y(**_nm_  Write contents of macro or string _nm_ to _troff_ output as a
                  device extension command.
           **\Y[**_name_**]**
                  Write contents of macro or string _name_ to _troff_ output as a
                  device extension command.
           **\z** _c_    Format character _c_ with zero width—without advancing the
                  drawing position.
           **\Z'**_anything_**'**
                  Save the drawing position, format _anything_ , then restore
                  the saved drawing position.
    
       **Drawing commands**
           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 position is left at the rightmost point of the object,
           even for closed figures, except where noted.  GNU _troff_ 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
           default scaling unit for horizontal measurements (and diameters of
           circles) is **m** ; for vertical ones, **v**.
    
           Circles, ellipses, and polygons can be drawn stroked or filled.
           These are independent properties; if you want a filled, stroked
           figure, you must draw the same figure twice using each drawing
           command.  A filled figure is always smaller than an outlined one
           because the former is drawn only within its defined area, whereas
           strokes have a line thickness (set with **\D't'**).
    
           **\D'~**_h1 v1_ ... _hn vn_**'**
                  Draw B-spline to each point in sequence, leaving drawing
                  position at (_hn_ , _vn_).
           **\D'a** _hc vc h v_**'**
                  Draw circular arc centered at (_hc_ , _vc_) counterclockwise
                  from the drawing position to a point (_h_ , _v_) relative to the
                  center.  (_hc_ , _vc_) is adjusted to the point nearest the
                  perpendicular bisector of the arc's chord.
           **\D'c** _d_**'**
                  Draw circle of diameter _d_ with its leftmost point at the
                  drawing position.
           **\D'C** _d_**'**
                  As **\D'C'** , but the circle is filled.
           **\D'e** _h v_**'**
                  Draw ellipse of width _h_ and height _v_ with its leftmost
                  point at the drawing position.
           **\D'E** _h v_**'**
                  As **\D'e'** , but the ellipse is filled.
           **\D'l** _h v_**'**
                  Draw line from the drawing position to (_h_ , _v_).
           **\D'p** _h1 v1_ ... _hn vn_**'**
                  Draw polygon with vertices at the drawing position and each
                  point in sequence.  GNU _troff_ closes the polygon by drawing
                  a line from (_hn_ , _vn_) back to the initial drawing position.
                  Afterward, the drawing position is left at (_hn_ , _vn_).
           **\D'P** _h1 v1_ ... _hn vn_**'**
                  As **\D'p'** , but the polygon is filled.
           **\D't** _n_**'**
                  Set stroke thickness of geometric objects to to _n_ basic
                  units.  A zero _n_ selects the minimum supported thickness.
                  A negative _n_ selects a thickness proportional to the type
                  size; this is the default.
    


## Strings



           _groff_ supports strings primarily for user convenience.
           Conventionally, if one would define a macro only to interpolate a
           small amount of text, without invoking requests or calling any
           other macros, one defines a string instead.  Only one string is
           predefined by the language.
    
           \*[**.T**]     Contains the name of the output device (for example,
                      “**utf8** ” or “**pdf** ”**).**
    
           The **ds** request creates a string with a specified name and
           contents.  If the identifier named by **ds** already exists as an
           alias, the target of the alias is redefined.  If **ds** is invoked
           with only one argument, the named string becomes empty.  The
           formatter removes a leading neutral double quote ‘**"** ’ from _contents_
           to permit the embedding of leading spaces.  It interprets any
           other ‘**"** ’ literally, but the wise author uses the special
           character escape sequence **\[dq]** 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 contents.  If the name does not exist, the formatter defines
           it as empty, interpolates nothing, and emits a warning in category
           “**mac** ”.  See section “Warnings” in _troff_(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, argument
           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 **\[dq]**
           instead if the string might be interpolated as part of a macro
           argument; see section “Calling macros” above.  Strings are not
           limited to a single input line of text.  **\**_newline_ works just as it
           does elsewhere.  The resulting string is stored _without_ the
           newlines.  When filling is disabled, care is required to avoid
           overrunning the line length when interpolating strings.
           Conversely, when filling is enabled, it is not necessary to append
           **\c** to a string interpolation to prevent a break afterward, as
           might be required in a macro argument.  Nor does a string require
           use of the GNU _troff_ **chop** 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 interpolated.  To achieve that effect, use **\*** to
           interpolate a macro instead; see section “Punning names” below.
    
           The “**as** ” request is similar to **ds** but appends to a string instead
           of redefining it.  If “**as** ” 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 _troff_ compatibility mode enablement when
           interpolated; see section “Compatibility mode” below.  The **ds1**
           request defines a string that suspends compatibility mode when the
           string is later interpolated.  **as1** is likewise similar to “**as** ”,
           with compatibility mode suspended when the appended portion of the
           string is later interpolated.
    
           _Caution:_ These requests treat the remainder of the input line as
           their second argument, including any spaces, up to a newline or
           comment escape sequence.  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 “**length** ” request, to requests that define characters (**char** ,
           **fchar** , **fschar** , and **schar**), and to the file name or command
           arguments of the **cf** , **hpf** , **hpfa** , **mso** , **msoquiet** , **nx** , “**open** ”, **opena** ,
           **pi** , **pso** , “**so** ”, **soquiet** , and **trf** requests.
    
           Several requests exist to perform rudimentary string operations.
           Strings can be queried (**length**) and modified (**chop** , **substring** ,
           **stringup** , **stringdown**), and their names can be manipulated through
           renaming, removal, and aliasing (**rn** , **rm** , **als).**
    
           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 **rm** request on its name
           first.
    


## Registers



           In the _roff_ language, numbers and measurements can be stored in
           _registers._  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 for information on constructing a
           valid name for a register.
    
           Each register (except read-only ones) can be assigned a _format_ ,
           causing its value to interpolate with leading zeroes, in Roman
           numerals, or alphabetically.  Some read-only registers are string-
           valued, meaning that they interpolate text and lack a format.
    
           Define registers and update their values with the **nr** request or
           the **\R** escape sequence.
    
           User-defined registers can also be incremented or decremented by a
           configured amount at the time they are interpolated.  The value of
           the increment is specified with a third argument to the **nr**
           request, and a special interpolation syntax, **\n** _±_ , alters and then
           retrieves the register's value.  Together, these features are
           called _auto-increment_.  (A negative auto-increment can be
           considered an “auto-decrement”.)
    
           Many predefined registers are available.  The following
           presentation uses register interpolation syntax **\n[**_name_**]** to refer
           to a register _name_ to clearly distinguish it from a string or
           request _name_ ; the symbols **\n[]** are _not_ part of the register name.
           The register name space is separate from that used for requests,
           macros, strings, and diversions.
    
       **Read-only registers**
           Predefined registers whose identifiers start with a dot are read-
           only.  Many are Boolean-valued.
    
           _Caution:_ Built-in registers are subject to removal like others;
           once removed, 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 (without the dot); exceptions are noted.
    
           \n[**.$**] Count of arguments passed to currently interpolated macro
                  or string.
           \n[**.a**] Amount of extra post-vertical line space; see **\x**.
           \n[**.A**] Approximate output is being formatted (Boolean-valued); see
                  _troff_ **-a** option.
           \n[**.b**] Font emboldening offset; see **bd**.
           \n[**.br**]
                  The normal control character was used to call the macro
                  being interpreted (Boolean-valued).
           \n[**.c**] Input line number; see **lf** and register “**c.** ”.
           \n[**.C**] AT&T _troff_ compatibility mode is enabled (Boolean-valued);
                  see **cp**.  Always false when processing ”**do** ”; see register
                  **.cp**.
           \n[**.cdp**]
                  Depth of last glyph formatted in the environment; positive
                  if glyph extends below the baseline.
           \n[**.ce**]
                  Count of input lines remaining to be centered in the
                  environment.
           \n[**.cht**]
                  Height of last glyph formatted in the environment; positive
                  if glyph extends above the baseline.
           \n[**.color**]
                  Color output is enabled (Boolean-valued).
           \n[**.cp**]
                  Within ”**do** ”, the saved value of compatibility mode; see
                  register **.C**.
           \n[**.csk**]
                  Skew of the last glyph formatted in the environment; see
                  register **skw**.
           \n[**.d**] Vertical drawing position in diversion.
           \n[**.ev**]
                  Name of environment (string-valued).
           \n[**.f**] Mounting position of selected font; see **ft** and **\f**.
           \n[**.F**] Name of input file (string-valued); see **lf**.
           \n[**.fam**]
                  Name of the environment's default font family (string-
                  valued).
           \n[**.fn**]
                  Resolved name of font selected in the environment (string-
                  valued); see **ft** and **\f**.
           \n[**.fp**]
                  Next non-zero free font mounting position index.
           \n[**.g**] Always true in GNU _troff_ (Boolean-valued).
           \n[**.h**] Text baseline high-water mark on page or in diversion.
           \n[**.H**] Horizontal motion quantum of output device in basic units.
           \n[**.height**]
                  Height of the environment's selected font; see **\H**.
           \n[**.hla**]
                  Hyphenation language in environment (string-valued).
           \n[**.hlc**]
                  Count of immediately preceding consecutive hyphenated lines
                  in environment.
           \n[**.hlm**]
                  Maximum quantity of consecutive hyphenated lines allowed in
                  environment.
           \n[**.hy**]
                  Automatic hyphenation mode in environment.
           \n[**.hydefault**]
                  Hyphenation mode default in environment.
           \n[**.hym**]
                  Hyphenation margin in environment.
           \n[**.hys**]
                  Hyphenation space adjustment threshold in environment.
           \n[**.i**] Environment's indentation amount; see ”**in** ”.
           \n[**.in**]
                  Indentation amount applicable to the output line pending in
                  the environment; see **ti**.
           \n[**.int**]
                  The text most recently formatted in the environment was
                  “interrupted” or continued with **\c**(Boolean-valued).
           \n[**.it**]
                  Count of input lines remaining in the environment's pending
                  input trap.
           \n[**.itc**]
                  The environment's pending input trap honors output line
                  continuation with **\c**(Boolean-valued).
           \n[**.itm**]
                  Name of the macro associated with the pending input trap
                  (string-valued).
           \n[**.j**] The environment's adjustment mode encoded as an integer;
                  see **ad** and **na**.  Do not interpret or perform arithmetic on
                  its value.
           \n[**.k**] The environment's horizontal drawing position relative to
                  indentation.
           \n[**.kern**]
                  Pairwise kerning is enabled (Boolean-valued).
           \n[**.l**] Line length; see **ll**.
           \n[**.L**] Line spacing; see **ls**.
           \n[**.lg**]
                  Ligature mode.
           \n[**.linetabs**]
                  Line-tabs mode is enabled in the environment (Boolean-
                  valued).
           \n[**.ll**]
                  Line length applicable to the environment's pending output
                  line.
           \n[**.lt**]
                  Environment's title line length.
           \n[**.m**] Stroke color (string-valued); see **gcolor** and **\m**.  The
                  default stroke color is named “**default** ”.
           \n[**.M**] Fill color (string-valued); see **fcolor** and **\M**.  The default
                  fill color is named “**default** ”.
           \n[**.n**] Length of formatted output on previous output line.
           \n[**.ne**]
                  Amount of vertical space required by last **ne** that caused a
                  trap to be sprung; also see register **.trunc**.
           \n[**.nm**]
                  Output line numbering is enabled in the environment
                  (Boolean-valued).
           \n[**.nn**]
                  Count of lines remaining in the environment for which
                  numbering is suppressed while output line numbering is
                  enabled.
           \n[**.ns**]
                  No-space mode is enabled (Boolean-valued).
           \n[**.o**] Page offset; see **po**.
           \n[**.O**] Output suppression nesting level; see **\O**.
           \n[**.p**] Page length; see **pl**.
           \n[**.P**] The page is selected for output (Boolean-valued); see _troff_
                  **-o** option.
           \n[**.pe**]
                  Page ejection is in progress (Boolean-valued).
           \n[**.pn**]
                  Number of the next page.
           \n[**.ps**]
                  The environment's type size in scaled points.
           \n[**.psr**]
                  The environment's most recently requested type size in
                  scaled points; see **ps** and **\s**.
           \n[**.pvs**]
                  The environment's post-vertical line spacing.
           \n[**.R**] Maximum representable integer in GNU _troff_.
           \n[**.rj**]
                  Count of input lines remaining to be right-aligned in the
                  environment.
           \n[**.s**] The environment's type size in points as a decimal fraction
                  (string-valued); see **ps** and **\s**.
           \n[**.slant**]
                  Slant in degrees of the environment's selected font; see
                  **\S**.
           \n[**.sr**]
                  The environment's most recently requested type size in
                  points as a decimal fraction (string-valued); see **ps** and
                  **\s**.
           \n[**.ss**]
                  Size of the environment's minimum inter-word space in
                  twelfths of the space width of the selected font.
           \n[**.sss**]
                  Size of the environment's additional inter-sentence space
                  in twelfths of the space width of the selected font.
           \n[**.sty**]
                  The environment's selected abstract style (string-valued);
                  see **ft** and **\f**.
           \n[**.t**] Distance to next vertical position trap; see **wh** and **ch**.  If
                  no such traps exist between the drawing position and the
                  bottom of the page, _troff_ interpolates the distance to the
                  page bottom.  Within a diversion, in the absence of a
                  diversion trap, this distance is the maximum possible
                  vertical position supported by the output device.
           \n[**.T**] An output device was explicitly selected (Boolean-valued);
                  see _troff_ **-T** option.
           \n[**.tabs**]
                  The environment's tab stop settings (if any) suitable for
                  use as argument to **ta**(string-valued).
           \n[**.trap**]
                  Name of the next vertical position trap after the vertical
                  drawing position.  (string-valued); see **wh** , **ch** , and **dt**.
           \n[**.trunc**]
                  Amount of vertical space truncated by the most recently
                  sprung vertical position trap, or, if the trap was sprung
                  by an **ne** , minus the amount of vertical motion produced by
                  **ne** ; also see register **.ne**.
           \n[**.u**] Filling is enabled in the environment (Boolean-valued); see
                  **fi** and **nf**.
           \n[**.U**] Unsafe mode is enabled (Boolean-valued); see _troff_ **-U**
                  option.
           \n[**.v**] The environment's vertical line spacing; see **vs**.
           \n[**.V**] Vertical motion quantum of the output device in basic
                  units.
           \n[**.vpt**]
                  Vertical position traps are enabled (Boolean-valued).
           \n[**.w**] Width of last glyph formatted in the environment.
           \n[**.warn**]
                  Sum of the numeric codes of enabled warning categories.
           \n[**.x**] Major version number of the running _troff_ formatter.
           \n[**.y**] Minor version number of the running _troff_ formatter.
           \n[**.Y**] Revision number of the running _troff_ formatter.
           \n[**.z**] Name of diversion (string-valued).  Empty if output is
                  directed to the top-level diversion.
           \n[**.zoom**]
                  Magnification of the environment's selected font (in
                  thousandths; zero if no magnification); see **fzoom**.
    
       **Writable predefined registers**
           Several registers are predefined but also modifiable; some are
           updated upon interpretation of certain requests or escape
           sequences.  Date- and time-related registers are set to the local
           time as determined by _localtime_(3) when the formatter launches.
           This initialization can be overridden by _SOURCE_DATE_EPOCH_ and _TZ_ ;
           see section “Environment” of _groff_(1).
    
           \n[**$$**] Process ID of _troff_.
           \n[**%**]  Page number.
           \n[**c.**] Input line number.
           \n[**ct**] Union of character types of each glyph rendered into dummy
                  environment by **\w**.
           \n[**dl**] Width of last closed diversion.
           \n[**dn**] Height of last closed diversion.
           \n[**dw**] Day of the week (1–7; 1 is Sunday).
           \n[**dy**] Day of the month (1–31).
           \n[**hours**]
                  Count of hours elapsed since midnight (0–23).
           \n[**hp**] Horizontal drawing position relative to that at the start
                  of the input line.
           \n[**llx**]
                  Lower-left _x_ coordinate (in PostScript units) of PostScript
                  image; see **psbb**.
           \n[**lly**]
                  Lower-left _y_ coordinate (in PostScript units) of PostScript
                  image; see **psbb**.
           \n[**ln**] Output line number; see **nm**.
           \n[**lsn**]
                  Count of leading spaces on input line.
           \n[**lss**]
                  Amount of horizontal space corresponding to leading spaces
                  on input line.
           \n[**minutes**]
                  Count of minutes elapsed in the hour (0–59).
           \n[**mo**] Month of the year (1–12).
           \n[**nl**] Vertical drawing position.
           \n[**opmaxx**]
           \n[**opmaxy**]
           \n[**opminx**]
           \n[**opminy**]
                  These four registers mark the top left- and bottom right-
                  hand corners of a rectangle encompassing all formatted
                  output on the page.  They are reset to -1 by **\O0** or **\O1**.
           \n[**rsb**]
                  As register **sb** , adding maximum glyph height to measurement.
           \n[**rst**]
                  As register **st** , adding maximum glyph depth to measurement.
           \n[**sb**] Maximum displacement of text baseline below its original
                  position after rendering into dummy environment by **\w**.
           \n[**seconds**]
                  Count of seconds elapsed in the minute (0–60).
           \n[**skw**]
                  Skew of last glyph rendered into dummy environment by **\w**.
           \n[**slimit**]
                  The maximum depth of _troff_ 's internal input stack.  If ≤0,
                  there is no limit: recursion can continue until available
                  memory is exhausted.  The default is 1,000.
           \n[**ssc**]
                  Subscript correction of last glyph rendered into dummy
                  environment by **\w**.
           \n[**st**] Maximum displacement of text baseline above its original
                  position after rendering into dummy environment by **\w**.
           \n[**systat**]
                  Return value of _system_(3); see **sy**.
           \n[**urx**]
                  Upper-right _x_ coordinate (in PostScript units) of
                  PostScript image; see **psbb**.
           \n[**ury**]
                  Upper-right _y_ coordinate (in PostScript units) of
                  PostScript image; see **psbb**.
           \n[**year**]
                  Gregorian year.
           \n[**yr**] Gregorian year minus 1900.
    


## Using fonts



           In digital typography, a _font_ 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 _groff_ **lj4** device's
           Lineprinter, and **lbp** 's Courier and Elite faces.)  A _roff_ formatter
           can change typefaces at any point in the text.  The basic faces
           are a set of _styles_ combining upright and slanted shapes with
           normal and heavy stroke weights: “**R** ”, “**I** ”, “**B** ”, and “**BI** ”—these
           stand for _roman, bold, italic,_ and _bold-italic._  For linguistic
           text, GNU _troff_ groups typefaces into _families_ containing each of
           these styles.  (Font designers prepare families such that the
           styles share esthetic properties.)  A _text font_ is thus often a
           family combined with a style, but it need not be: consider the **ps**
           and **pdf** devices' **ZCMI**(Zapf Chancery Medium italic)—often, no
           other style of Zapf Chancery Medium is provided.  On typesetters,
           at least one _special font_ is available, comprising _unstyled_ glyphs
           for mathematical operators and other purposes.
    
           Like the AT&T _troff_ formatter, GNU _troff_ does not itself load or
           manipulate a digital font file; instead it works with a _font_
           _description file_ that characterizes it, including its glyph
           repertoire and the _metrics_ (dimensions) 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 _mounting position,_ a place in an
           ordered list of available typefaces.  So that a document need not
           be strongly coupled to a specific font family, in GNU _troff_ 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 _resolved font name._  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 require renaming upon modification.  _groff_ maintains a
           convention that a device's serif font family is given the name **T**
           (“Times”), its sans-serif family **H**(“Helvetica”), and its
           monospaced family **C**(“Courier”).  Historical inertia has driven
           _groff_ 's font identifiers to short uppercase abbreviations of font
           names, as with **TR** , **TB** , **TI** , **TBI** , and a special font **S**.
    
           The default family used with abstract styles can be changed at any
           time; initially, it is **T**.  Typically, abstract styles are arranged
           in the first four mounting positions in the order shown above.
           The default mounting position, and therefore style, is always **1**
           (**R**).  By issuing appropriate formatter 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 _graphic renditions_ (character cell attributes).
    
           The **ft** request and **\f** escape sequence select a typeface by name,
           abstract style, or mounting position.  The **fam** request and **\F**
           escape sequence set the default font family.  The **ftr** request
           translates one font name to another; **fzoom** magnifies or reduces
           the typeface corresponding to a resolved one.  **sty** and **fp**
           associate abstract styles and font names with mounting positions.
    


## Hyphenation



           When filling, _groff_ hyphenates words as needed at user-specified
           and automatically determined hyphenation points.  Explicitly
           hyphenated words such as “mother-in-law” are always eligible for
           breaking after each of their hyphens.  The hyphenation
           character **\%** and non-printing break point **\:** escape sequences may
           be used to control the hyphenation and breaking of individual
           words.  The **.hw** request sets user-defined hyphenation points for
           specified words at any subsequent occurrence.  Otherwise, _groff_
           determines hyphenation points automatically by default.
    
           Several requests influence automatic hyphenation.  Because
           conventions vary, a variety of hyphenation modes is available to
           the **.hy** 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 _troffrc_ configure a default
           hyphenation mode appropriate to the language.
    
           **0** disables hyphenation.
    
           **1** enables hyphenation except after the first and before the
                  last character of a word.
    
           The remaining values “imply” **1** ; that is, they enable hyphenation
           under the same conditions as “**.hy 1** ”, and then apply or lift
           restrictions relative to that basis.
    
           **2** 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.)
    
           **4** disables hyphenation before the last two characters of a
                  word.
    
           **8** disables hyphenation after the first two characters of a
                  word.
    
           **16** enables hyphenation before the last character of a word.
    
           **32** enables hyphenation after the first character of a word.
    
           Apart from value 2, restrictions imposed by the hyphenation mode
           are _not_ respected for words whose hyphenations have been specified
           with the hyphenation character (“**\%** ” by default) or the **.hw**
           request.
    
           Nonzero values are additive.  For example, mode 12 causes _groff_ to
           hyphenate neither the last two nor the first two characters of a
           word.  Some values 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 (**.hla** , **.hpf** , and **.hpfa**) and
           lettercase relationships (**.hcode** and **.hpfcode**).  Furthermore,
           hyphenation of a word might be suppressed due to a limit on
           consecutive hyphenated lines (**.hlm**), a minimum line length
           threshold (**.hym**), or because the line can instead be adjusted with
           additional inter-word space (**.hys**).
    


## Localization



           The set of hyphenation patterns is associated with the hyphenation
           language set by the **.hla** request.  The **.hpf** request is usually
           invoked by a localization file loaded by the _troffrc_ file.  _groff_
           provides localization files for several languages; see
           _groff_tmac_(5).  These also set the default automatic hyphenation
           mode with **.hydefault**.
    


## Writing macros



           The **.de** request defines a macro named for its argument.  If that
           name already exists as an alias, the target of the alias is
           redefined; see section “Strings” above.  _troff_ 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 argument to
           **.de** names a macro whose call (or request whose invocation) syntax
           ends the definition; this _end macro_ is then interpreted normally.
           Spaces or tabs are permitted after the first control character in
           the line containing this ending token, but a tab immediately after
           the token prevents its recognition as the end of a macro
           definition.  Macro definitions can be nested if they use distinct
           end macros or if their ending tokens are sufficiently escaped.  An
           end macro need not be defined until it is called.  This fact
           enables a nested macro definition to begin inside one macro and
           end inside another.
    
           Variants of **.de** disable compatibility mode and/or indirect the
           names of the macros specified for definition or termination: these
           are **.de1** , **.dei** , and **.dei1**.  Append to macro definitions with **.am** ,
           **.am1** , **.ami** , and **.ami1**.  The **.als** , **.rm** , and **.rn** requests create an
           alias of, remove, and rename a macro, respectively.  **.return** stops
           the execution of a macro immediately, returning to the enclosing
           context.
    
       **Parameters**
           Macro call and string interpolation parameters can be accessed
           using escape sequences starting with “**\$** ”.  The **\n[.$]** read-only
           register stores the count of parameters available to a macro or
           string; change its value with the **.shift** request, which dequeues
           parameters from the current list.  The **\$0** escape sequence
           interpolates the name by which a macro was called.  Applying
           string interpolation to a macro does not change this name.
    
       **Copy mode**
           GNU _troff_ processes certain requests in _copy mode:_ it copies
           ordinary, special, and indexed characters as-is; interpolates the
           escape sequences **\n** , **\g** , **\$** , **\*** , **\V** , and **\?** normally; discards
           comments **\"** and **\#** ; interpolates **\a** , **\e** , and **\t** , as the current
           leader, escape, or tab character with respectively; represents
           **\**_newline_ , **\ &**, **\_** , **\|** , **\^** , **\{** , **\}** , **\`** , **\'** , **\-** , **\!** , **\c** , **\%** , **\**_space_ ,
           **\E** , **\)** , **\~** , and **\:** in an encoded form, and copies other escape
           sequences as-is.  The term “copy mode” reflects its most visible
           application 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 (**hpf**) or a diagnostic message written to the
           terminal (**tm**).  The complement of copy mode—a _roff_ formatter's
           behavior when not defining or appending to a macro, string, or
           diversion—where all macros are interpolated, requests invoked, and
           valid escape sequences processed immediately upon recognition, can
           be termed _interpretation mode_.
    
           The escape character, **\** by default, can escape itself.  This
           enables you to control whether a given **\n** , **\g** , **\$** , **\*** , **\V** , or **\?**
           escape sequence is interpreted at the time the macro containing it
           is defined, or later when the macro is called.
    
           You can think of **\\** as a “delayed” backslash; it is the escape
           character followed by a backslash from which the escape character
           has removed its special meaning.  Consequently, **\\** is not an
           escape sequence in the usual sense.  In any escape sequence **\**_X_
           that _troff_ does not recognize, the escape character is ignored and
           _X_ is output.  An unrecognized escape sequence causes a warning in
           category “**escape** ”, with two exceptions, **\\** being one.  The other
           is **\.** , which escapes 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 escaping the control
           character, this would not be possible.  _roff_ documents should not
           use the **\\** or **\.** character sequences outside of copy mode; they
           serve only to obfuscate the input.  Use **\e** to represent the escape
           character, **\[rs]** to obtain a backslash glyph, and **\ & **before **.** and
           **'** where _troff_ expects them as control characters if you mean to
           use them literally.
    
           Macro definitions can be nested to arbitrary depth.  In “**\\** ”, each
           escape character is interpreted twice—once in copy mode, when the
           macro is defined, and once in interpretation mode, when the macro
           is called.  This fact leads to exponential growth in the quantity
           of escape characters required to delay interpolation of **\n** , **\g** ,
           **\$** , **\*** , **\V** , and **\?** at each nesting level.  An alternative is to
           use **\E** , which represents an escape character that is not
           interpreted in copy mode.  Because **\.** is not a true escape
           sequence, we can't use **\E** to keep “**..** ” from ending a macro
           definition prematurely.  If the multiplicity of backslashes
           complicates maintenance, use end macros.
    


## Traps



           _Traps_ are locations in the output, or conditions on the input
           that, when reached or fulfilled, call a specified macro.  A
           _vertical position trap_ calls a macro when the formatter's vertical
           drawing position reaches or passes, in the downward direction, a
           certain location on the output page or in a diversion.  Its
           applications include setting page headers and footers, body text
           in multiple columns, and footnotes.  These traps can occur at a
           given location on the page (**.wh** , **.ch**); at a given location in the
           current diversion (**.dt**)—together, these are known as vertical
           position traps, which can be disabled and reënabled (**.vpt**).
           Setting a trap is also called _planting_ one.  It is said that a
           trap is _sprung_ if its condition is fulfilled.
    
           A diversion is not formatted in the context of a page, so it lacks
           page location traps; instead it can have a _diversion trap._  There
           can exist at most one such vertical position trap per diversion.
    
           Other kinds of trap can be planted at a blank line (**.blm**); at a
           line with leading space characters (**.lsm**); after a certain number
           of productive input lines (**.it** , **.itc**); or at the end of input
           (**.em**).  Macros called by traps are passed no arguments.
    
           Registers associated with trap management include vertical
           position trap enablement status (**\n[.vpt]**), distance to the next
           trap (**\n[.t]**), and the name of that trap (**\n[.trap]**); the count of
           lines remaining in the pending input trap (**\n[.it]**), the name of
           the macro associated with it (**\n[.itm]**), and whether that input
           trap honors the **\c** output line continuation escape sequence
           (**\n[.itc]**); amount of needed (**.ne** -requested) space that caused the
           most recent vertical position trap to be sprung (**\n[.ne]**), amount
           of needed space truncated from the amount requested (**\n[.trunc]**);
           page ejection status (**\n[.pe]**); and leading space count (**\n[lsn]**)
           with its corresponding amount of motion (**\n[lss]**).
    
       **Page location traps**
           A _page location trap_ is a vertical position trap that applies to
           the page; that is, to undiverted output.  Many can be present;
           manage them with the **wh** and **ch** requests.  Non-negative page
           locations given to these requests set the trap relative to the top
           of the page; negative values set the trap relative to the bottom
           of the page.  It is not 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 _visible_ trap (see below)
           at the same location is removed; this is **.wh** 's sole function if
           its second argument is missing.
    
           A trap is sprung only if it is _visible,_ meaning that its location
           is reachable on the page and it is not hidden by another trap at
           the same location already planted there.  (A trap planted at “20i”
           or “-30i” will not be sprung on a page of length “11i”.)
    
           A trap above the top or at or below the bottom of the page can be
           made visible by either moving it into the page area or increasing
           the page length so that the trap is on the page.  Negative trap
           values always use the _current_ page length; they are not converted
           to an absolute vertical position.  Use **.ptr** to dump page location
           traps to the standard error stream; their positions are reported
           in basic units.
    
       **The implicit page trap**
           An _implicit page trap_ always exists in the top-level diversion
           (see below); it works like a trap in some ways but not others.
           Its purpose is to eject the current page and start the next one.
           It has no name, so it cannot be moved or deleted with **wh** or **ch**
           requests.  You cannot hide it by placing another trap at its
           location, and can move it only by redefining the page length with
           **.pl**.  Its operation is suppressed when vertical page traps are
           disabled with the **vpt** request.
    


## Diversions



           In _roff_ systems it is possible to format text as if for output,
           but instead of writing it immediately, one can _divert_ the
           formatted text into a named storage area.  It is retrieved later
           by specifying its name after a control character.  The same name
           space is used for such _diversions_ 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 important
           distinction between macros and strings on one hand and diversions
           on the other; the former store _unformatted_ input text, and the
           latter capture _formatted_ output.  Diversions also do not interpret
           arguments.  Applications of diversions include “keeps” (preventing
           a page break from occurring at an inconvenient place by forcing a
           set of output lines to be set as a group), footnotes, tables of
           contents, and indices.  For orthogonality it is said that GNU
           _troff_ is in the _top-level diversion_ if no diversion is active
           (that is, formatted output is being “diverted” immediately to the
           output device).  The top-level diversion has no name.
    
           Dereferencing an undefined diversion creates an empty one of that
           name and emits a warning in category **mac**.  See section “Warnings”
           in _troff_(1) regarding the enablement and suppression of warnings.
           A diversion does not exist for the purpose of testing with the **d**
           conditional operator until its initial definition ends (see
           subsection “Conditional expressions” above).
    
           The **di** request creates a diversion, including any partially
           collected line.  **da** 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.  **box** and **boxa** 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 **.d** and **.z** report
           information about the current diversion, and **dn** and **dl** about the
           most recently closed one.  **.h** is meaningful in diversions,
           including the top-level one.
    
           After completing a diversion, the writable registers **dn** and **dl**
           contain its vertical and horizontal sizes, respectively.  Only the
           lines just processed are counted: for the computation of **dn** and
           **dl** , the requests **da** and **boxa** are handled as if **di** and **box** had been
           used, respectively—lines that have been already stored in the
           diversion (box) are not taken into account.
    
           The **\!** and **\?** escape sequences and **output** request escape from a
           diversion, the first two to the enclosing level and the last to
           the top level.  This facility is termed _transparent embedding_.
    
           The **asciify** and “**unformat** ” requests reprocess diversions.
    


## Punning names



           Macros, strings, and diversions share a name space; see section
           “Identifiers” above.  Internally, the same mechanism is used to
           store them.  You can thus call a macro with string interpolation
           syntax and vice versa.  Interpolating a string does not hide
           existing macro arguments.  The sequence **\\** can be placed at the
           end of a line in a macro definition or, within a macro definition,
           immediately after the interpolation of a macro as a string to
           suppress the effect of a newline.
    


## Environments



           Environments store most of the parameters that control text
           processing.  A default environment named “**0** ” exists when _troff_
           starts up; it is modified by formatting-related requests and
           escape sequences.
    
           You can create new environments and switch among them.  Only one
           is current at any given time.  Active environments are managed
           using a _stack,_ 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
           accessible by name and can be made current again by pushing it at
           any time.  Environments cannot be renamed or deleted, and can only
           be modified when current.  To inspect the environment stack, use
           the **pev** request; see section “Debugging” below.
    
           Environments store the following information.
    
           •  a partially collected line, if any
    
           •  data about the most recently output glyph and line (registers
              **.cdp** , **.cht** , **.csk** , **.n** , **.w**)
    
           •  typeface parameters (size, family, style, height and slant,
              inter-word and inter-sentence space sizes)
    
           •  page parameters (line length, title length, vertical spacing,
              line spacing, indentation, line numbering, centering, right-
              alignment, underlining, 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 **ev** request pushes to and pops from the environment stack,
           while **evc** copies a named environment's parameters to the current
           one.
    


## Postprocessor access



           Beyond the **cf** and **trf** requests, two escape sequences and two
           requests enable documents to pass information directly to a
           postprocessor.  These are useful for exercising device-specific
           capabilities that the _groff_ language does not abstract or
           generalize; examples include the embedding of hyperlinks and image
           files.  Device-specific functions are documented in each output
           driver's man page, such as _gropdf_(1), _grops_(1), or _grotty_(1).
    
           The “**device** ” request and **\X** escape sequence embed their arguments
           into GNU _troff_ output as parameters to an “**x X** ” device extension
           command (see _groff_out_(5)).  The interpretation of such parameters
           is determined by the output driver or other postprocessor.
    
           GNU _troff_ also permits the interpolation of macro or string
           contents as a device extension command.  The **devicem** request and
           **\Y** escape sequence correspond to “**.device \*[**_name_**]** ” and
           “**\X'\*[**_name_**]** ”, respectively.  They differ from their counterparts
           in that GNU _troff_ does not interpret the contents of the string or
           macro _name_ ; further, _name_ may be a macro and thus contain
           newlines.  (There is no way to embed a newline in the arguments to
           “**device** ” or **\X**.)  The inclusion of newlines requires an extension
           to the AT&T _troff_ device-independent page description language,
           and their presence confuses drivers that do not know about it (see
           subsection “Device control commands” of _groff_out_(5)).
    
           The **tag** and **taga** requests are reserved for internal use.
    


## Underlining



           In _RUNOFF_ (see _roff_(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 _groff_ request **.ul**(see above) that underlines subsequent
           source lines on terminals, but on typesetters, it selects an
           italic font style instead.  The _ms_ macro package (see _groff_ms_(7))
           offers a macro **.UL** , but it too produces the desired effect only on
           typesetters, and has other limitations.
    
           One could adapt _ms_ '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 _doclifter_(1) makes trouble, change the macro name **UNDERLINE**
           into some 2-letter word, like **Ul**.  Moreover, change the form of
           the font selection escape sequence from **\f[P]** to **\fP**.
    
       **Underlining without macro definitions**
           If one does not want to use macro definitions, e.g., when
           _doclifter_ 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 _doclifter_ , it might be necessary to change syntax forms
           such as **\[xy]** and **\*[xy]** to those supported by AT&T _troff_ : **\*(xy**
           and **\(xy** , 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
    
       **Underlining by overstriking with \(ul**
           The **\z** escape sequence writes a glyph without advancing the
           drawing position, enabling overstriking.  Thus, **\z** _c_**\(ul** 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 _nroff_ and _troff_ modes.
    
           Long words may then look intimidating in the input; a clarifying
           approach might be to use the input line continuation escape
           sequence **\**_newline_ 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
                  **: ${**_var_ o_p__value_**}**
           as output.
    


## Compatibility mode



           The differences between the _roff_ language recognized by GNU _troff_
           and that of AT&T _troff_ , as well as the device, font, and device-
           independent page description formats described by CSTR #54 are
           documented in _groff_diff_(7).  _groff_ provides an AT&T compatibility
           mode.  The **cp** request and registers **.C** and **.cp** set and test the
           enablement of this mode.
    


## Debugging



           Preprocessors use the **.lf** request to preserve the identities of
           line numbers and names of input files.  _groff_ emits a variety of
           error diagnostics and supports several categories of warning; the
           output of these can be selectively suppressed with **.warn**(and see
           the **-E** , **-w** , and **-W** options of _troff_(1)).  A trace of the
           formatter's input processing stack can be emitted when errors or
           warnings occur by means of _troff_(1)'s **-b** option, or produced on
           demand with the **backtrace** request.  **tm** , **tmc** , and **tm1** can be used
           to emit customized diagnostic messages or for instrumentation
           while troubleshooting.  **ex** and **ab** 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—(**pm**); characters (**pchar** ;
           experimental); colors (**pcolor**); composite character mappings
           (**pcomposite**); environments (**pev**); occupied font mounting positions
           (**pfp**); font translations (**pftr**); automatic hyphenation codes
           (**pchar**) and exceptions (**phw**); registers (**pnr**); open streams
           (**pstream**); and page location traps (**ptr**).  Requests can also
           disclose to the standard error stream the internal properties and
           representations of characters (**pchar**), macros (and strings and
           diversions) (**pm**), and the list of output nodes corresponding to
           the pending input line (**pline**).
    


## Authors



           This document was written by Trent A. Fisher, Werner Lemberg ⟨wl@
           gnu.org⟩, and G. Branden Robinson ⟨g.branden.robinson@gmail.com⟩.
           Section “Underlining” was primarily written by Bernd Warken
           ⟨groff-bernd.warken-72@web.de⟩.
    


## See also



           _Groff: The GNU Implementation of troff_ , by Trent A. Fisher and
           Werner Lemberg, is the primary _groff_ 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 language referred to
           collectively in _groff_ documentation as “AT&T _troff_ ”.
    
           “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.
    
           _groff_(1)
                  is the preferred interface to the _groff_ system; it manages
                  the pipeline that carries a source document through
                  preprocessors, the _troff_ formatter, and an output driver to
                  viewable or printable form.  It also exhaustively lists the
                  man pages provided with the GNU _roff_ system.
    
           _groff_char_(7)
                  discusses character encoding issues and escape sequences
                  that produce glyphs.
    
           _groff_diff_(7)
                  covers differences between the GNU _troff_ formatter, its
                  device and font description file formats, its device-
                  independent page description language, and those of AT&T
                  _troff_.
    
           _groff_font_(5)
                  describes the formats of the files that describe devices
                  (_DESC_) and fonts.
    
           _groff_tmac_(5)
                  surveys macro packages provided with _groff_ , describes how
                  documents can take advantage of them, offers guidance on
                  writing macro packages and using diversions, and includes
                  historical information.
    
           _roff_(7)
                  presents a detailed history of _roff_ systems and summarizes
                  concepts common to them.
    


* * *