# groff - GNU roff language reference - man(7) - [phpMan] [_groff_(7)](https://www.chedong.com/phpMan.php/man/groff/7/markdown) Miscellaneous Information Manual [_groff_(7)](https://www.chedong.com/phpMan.php/man/groff/7/markdown) ## 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)](https://www.chedong.com/phpMan.php/man/roff/7/markdown) for a survey of and background on _roff_ systems. This document is intended as a reference. The primary _groff_ manual, _Groff:_ _The_ _GNU_ _Implemen‐_ _tation_ _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, DVI, and PDF, may be available in _/usr/share/doc/groff-base_. _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 sys‐ tem, the project that develops that system, and the command of that name. GNU _troff_, installed on this system as [_troff_(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown), is the _formatter:_ a program that reads de‐ vice and font descriptions ([_groff_font_(5)](https://www.chedong.com/phpMan.php/man/grofffont/5/markdown)), interprets the _groff_ language expressed in text input files, and translates that input into a device-independent output format ([_groff_out_(5)](https://www.chedong.com/phpMan.php/man/groffout/5/markdown)) that is usually then post-processed by an output driver to produce PostScript, PDF, HTML, DVI, or terminal output. ## Input format Input to GNU _troff_ is organized into lines separated by the Unix newline character (U+000A), and must be in one of two character encodings it can recognize: IBM code page 1047 on EBCDIC systems, and ISO Latin-1 (8859-1) otherwise. Use of ISO 646-1991:IRV (“US-ASCII”) or (equiv‐ alently) the “Basic Latin” subset of ISO 10646 (“Unicode”) is recommended; see [_groff_char_(7)](https://www.chedong.com/phpMan.php/man/groffchar/7/markdown). The [_preconv_(1)](https://www.chedong.com/phpMan.php/man/preconv/1/markdown) preprocessor transforms other encodings, including UTF-8, to satisfy _troff_'s requirements. ## Syntax characters Several input characters are syntactically significant to _groff_. . 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 con‐ trol 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**, **.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. In the **.ds**, **.ds1**, **.as**, and **.as1 **requests, an initial neutral double quote in the second argument is stripped off to allow embedding of leading spaces. 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 in‐ troduces 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 be‐ low). Horizontal white space characters are significant to _groff,_ but trailing spaces on text lines are ignored. _space_ Space characters separate arguments in request invocations, macro calls, and string interpolations. In text, 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 un‐ til 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 se‐ quences ‘**\ **’ (the escape character followed by a space), **\0**, **\|**, **\^**, or **\h**; see sec‐ tion “Escape sequences” below. _newline_ In text, a newline puts an inter-word space onto the output and, if filling is en‐ abled, triggers end-of-sentence recognition on the preceding text. See section “Line continuation” below. _tab_ A tab character in text 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)](https://www.chedong.com/phpMan.php/man/roff/7/markdown). 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 classifica‐ tion 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 in the middle of a request invocation, macro call, or escape sequence. Input line continuation is invisi‐ ble to the formatter, with two exceptions: the **| **operator recognizes the new input line, and the input line counter register **.c **is incremented. The **\c **escape sequence continues an _output_ line. Nothing on the input line after it is for‐ matted. In contrast to **\_**newline_, a line after **\c **is treated as a new input line, so a con‐ trol 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 **contains a positive value if the last output line was 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 de‐ fault 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)](https://www.chedong.com/phpMan.php/man/grotty/1/markdown) recognize the eight stan‐ dard ISO 6429/ECMA-48 color names (also known vulgarly as “ANSI colors”). ## Measurements Numeric parameters that specify measurements are expressed as integers or decimal fractions with an optional _scaling_ _unit_ suffixed. A scaling unit is a letter that immediately follows the last digit of a number. Digits after the decimal point are optional. Measurements are scaled by the scaling unit and stored internally (with any fractional part discarded) in basic units. The device resolution can therefore be obtained by storing a value of “**1i**” to a register. The only constraint on the basic unit is that it is at least as small as any other unit. **u **Basic 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. **s**, **z **Scaled points and multiplication by the output device's _sizescale_ parameter, respec‐ tively. **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; an en is one-half 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 “Regis‐ ters” below) is implicitly dimensionless, or reckoned in basic units if interpreted in a mea‐ surement 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 in‐ teger arithmetic should also be kept in mind; see below. ## Numeric expressions A _numeric_ _expression_ evaluates to an integer. The following operators are recognized. + addition - subtraction * multiplication / truncating division % modulus ──────────────────────────────────────────── unary + assertion, motion, incrementation unary - negation, motion, decrementation ──────────────────────────────────────────── ; scaling >? maximum greater than <= less than or equal >= greater than or equal = equal == equal ──────────────────────────────────────────── & logical conjunction (“and”) : logical disjunction (“or”) ! logical complementation (“not”) ──────────────────────────────────────────── ( ) precedence ──────────────────────────────────────────── | boundary-relative motion _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 is usually 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)](https://www.chedong.com/phpMan.php/man/grofftmac/5/markdown) for the _62bit.tmac_ macro pack‐ age.) 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. Overflow and division (or modulus) by zero are errors and abort evaluation of a numeric expression. Arithmetic unary operators operate on the numeric expression to their right; they are **-** (negation) and **+ **(assertion—for completeness; it does nothing). The unary minus must often be used with parentheses to avoid confusion with the decrementation operator, discussed be‐ low. 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 divi‐ sor _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 expres‐ sion _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 extrema of two operands: **>? **(maximum) and ** **(greater than), **<= **(less than or equal), **>=** (greater than or equal), and **= **(equal). **== **is a synonym for **=**. When evaluated, a comparison is replaced with “**0**” if it is false and “**1**” if true. In the _roff_ language, positive values are true, others false. We can operate on truth values with the logical operators **& **(logical conjunction or “and”) and **: **(logical disjunction or “or”). They evaluate as comparison operators do. A logical complementation (“not”) operator, **!, **works only within “**if**”, “**ie**”, and “**while**” requests. Furthermore, **! **is recognized only at the beginning of a numeric expression not contained by another numeric expression. In other words, it must be the “outermost” operator. Including it elsewhere in the expression produces a warning in the “**number**” category (see [_troff_(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown)), and its expression evaluates false. This unfortunate limitation maintains compatibility with AT&T _troff_. Test a numeric expression for falsity 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 prece‐ dence 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 rela‐ tive 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 bound‐ ary. For horizontal motions, the measurement specifies a distance relative to a drawing po‐ sition corresponding to the beginning of the _input_ line. By default, tab stops reckon move‐ ments in this way. Most escape sequences do not; **| **tells them to do so. For vertical mo‐ tions, 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 diver‐ sion), typeface, color, special character, character class, 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, or invalid as GNU _troff_ input. Invalid input characters are subset of control characters (from the sets “C0 Controls” and “C1 Controls” as Unicode describes them). When _troff_ encounters one in an identifier, it produces a warning in category “**input**” (see section “Warnings” in [_troff_(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown)). They are re‐ moved during interpretation: an identifier “foo”, followed by an invalid character and then “bar”, is processed as “foobar”. On a machine using the ISO 646, 8859, or 10646 character encodings, invalid input characters are **0x00**, **0x08**, **0x0B**, **0x0D**–**0x1F**, and **0x80**–**0x9F**. On an EBCDIC host, they are **0x00**–**0x01**, **0x08**, **0x09**, **0x0B**, **0x0D**–**0x14**, **0x17**–**0x1F**, and **0x30**–**0x3F**. Some of these code points are used by _troff_ internally, making it non-trivial to extend the program to accept UTF-8 or other encodings that use characters from these ranges. An identifier with a closing bracket (“]”) in its name can't be accessed with bracket-form escape sequences that expect an identifier as a parameter. Similarly, the identifier “(” can't be interpolated _except_ with bracket forms. If you begin a macro, string, or diversion name with either of the characters “[” or “]”, you foreclose use of the [_refer_(1)](https://www.chedong.com/phpMan.php/man/refer/1/markdown) preprocessor, which recognizes “.[” and “.]” as bibliographic reference delimiters. The escape sequence **\A **tests its argument for validity as an identifier. How GNU _troff_ handles the interpretation of an undefined identifier depends on the context. There is no way to invoke an undefined request; such syntax is interpreted as a macro call instead. If the identifier is interpreted as a string, macro, or diversion, _troff_ emits a warning in category “**mac**”, defines it as empty, and interpolates nothing. If the identifier is interpreted as a register, _troff_ emits a warning in category “**reg**”, initializes it to zero, and interpolates that value. See section “Warnings” in [_troff_(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown), and subsection “In‐ terpolating registers” and section “Strings” below. Attempting to use an undefined typeface, style, special character, color, character class, environment, or stream generally provokes an error diagnostic. Identifiers for requests, macros, strings, and diversions share one name space; special char‐ acters and character classes another. No other object types do. ## Control characters Control characters are recognized only at the beginning of an input line, or at the beginning of the branch of a control structure request; see section “Control structures” below. A few requests cause a break implicitly; use the no-break control 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 nam‐ ing 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 re‐ quest 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 be‐ tween arguments is necessary; any excess is ignored. GNU _troff_ does not allow tabs for argu‐ ment separation. 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**, inter‐ pret 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 struc‐ ture the source of documents or macro files with them. ## Calling macros If a macro of the desired name does not exist when called, it is created, assigned an empty definition, and a warning in category “**mac**” is emitted. 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 format‐ ted 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 de‐ scendants can be made to support them. See [_groff_font_(5)](https://www.chedong.com/phpMan.php/man/grofffont/5/markdown). If even that is not feasible, see the “Calling Macros” section of the _groff_ Texinfo manual for the complex macro argument quot‐ ing 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 se‐ quence 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-char‐ acter argument (no closing parenthesis is used), and an argument of arbitrary length is en‐ closed 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**). If an escape character is followed by a character that does not identify a defined operation, the escape character is ignored (producing a diagnostic of the “**escape**” warning category, which is not enabled by default) and the following character is processed normally. Escape sequence interpolation is of higher precedence than escape sequence argument interpre‐ tation. 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 defined as infix operators 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. A few escape sequences, **\A**, **\b**, **\o**, **\w**, **\X**, and **\Z**, accept a newline as a delimiter. New‐ lines that serve as delimiters continue to be recognized as input line terminators. Use of newlines as delimiters in escape sequences is also discouraged. Finally, the escape sequences **\D**, **\h**, **\H**, **\l**, **\L**, **\N**, **\R**, **\s**, **\S**, **\v**, and **\x **prohibit many delimiters. • 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 re‐ strictions 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 charac‐ ters 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 “Implementa‐ tion differences” in [_groff_diff_(7)](https://www.chedong.com/phpMan.php/man/groffdiff/7/markdown). ## Dummy characters As discussed in [_roff_(7)](https://www.chedong.com/phpMan.php/man/roff/7/markdown), the first character on an input line is treated specially. Further, formatting a glyph has many consequences on formatter state (see section “Environments” be‐ low). 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 ex‐ tra space after an end-of-sentence character, preventing interpretation of a control charac‐ ter 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 condi‐ tional 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 sep‐ arate 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 a combination of the foregoing. The opening and closing brace escape sequences **\{ **and **\} **perform such grouping. Brace escape sequences outside of control struc‐ tures 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 nec‐ essary 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 pre‐ ceding 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. _**cond-expr_**... **...is true if...** ────────────────────────────────────────────────────────────────────────────────────────────── **'_**s1_**'_**s2_**' _**s1_ produces the same formatted output as _s2_. **c _**g_ a glyph _g_ is available. **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 char‐ acter apart from **! **(see below); it performs an _output_ _comparison_ _test._ Shown first in the table above, the _output_ _comparison_ _operator_ interpolates a true value if formatting its com‐ parands _s1_ and _s2_ produces the same output commands. Other delimiters can be used in place of the neutral apostrophes. _troff_ formats _s1_ and _s2_ in separate environments; after the com‐ parison, the resulting data are discarded. The resulting glyph properties, including font family, style, size, and slant, must match, but not necessarily the requests and/or escape sequences used to obtain them. Motions must match in orientation and magnitude to within the applicable horizontal or 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 imme‐ diately by spaces or tabs, complements an expression. Spaces and tabs are optional immedi‐ ately 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_.) ## 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. _c_ denotes a single input character. _font_ a font either specified as a font name or a numeric mounting position. _anything_ all characters up to the end of the line, to the ending delimiter for the escape sequence, or within **\{ **and **\}**. Escape sequences may generally be used freely in _anything_, except when it is read in copy mode. _message_ is a character sequence to be emitted on the standard error stream. Special character escape sequences are _not_ interpreted. _n_ is a numeric expression that evaluates to a non-negative integer. _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 **or escape sequences like **\D**. Macro calls are not themselves productive, but their in‐ terpolated contents can be. _±N_ is a numeric expression with a meaning dependent on its sign. If a numeric expression presented as _±N_ starts with a ‘**+**’ sign, an 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 leading minus sign in _N_ is always interpreted as a decrementation opera‐ tor, not an algebraic sign. To assign a register a negative value or the negated value of another register, enclose it with its operand in parentheses or subtract it from zero. If a prior value does not exist (the register was undefined), an increment or decrement is applied as if to 0. ## Request short reference Not all details of request behavior are outlined here. See the _groff_ Texinfo manual or, for features new to GNU _troff_, [_groff_diff_(7)](https://www.chedong.com/phpMan.php/man/groffdiff/7/markdown). **.ab **Abort processing; exit with failure status. **.ab _**message_ Abort processing; write _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 _**register_ _c_ Assign format _c_ to _register_, where _c_ is “**i**”, “**I**”, “**a**”, “**A**”, or a sequence of deci‐ mal 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 al‐ phabetics, respectively, in the lettercase specified. The default is **0**. **.aln _**new_ _old_ Create alias (additional name) _new_ for existing register named _old_. **.als _**new_ _old_ Create alias (additional name) _new_ for existing request, string, macro, or diver‐ sion _old_. **.am _**macro_ Append to _macro_ until **.. **is encountered. **.am _**macro_ _end_ Append to _macro_ until **._**end_ is called. **.am1 _**macro_ Same as **.am **but with compatibility mode switched off during macro expansion. **.am1 _**macro_ _end_ Same as **.am **but with compatibility mode switched off during macro expansion. **.ami _**macro_ Append to a macro whose name is contained in the string _macro_ until **.. **is encoun‐ tered. **.ami _**macro_ _end_ Append to a macro indirectly. _macro_ and _end_ are strings whose contents are inter‐ polated for the macro name and the end macro, respectively. **.ami1 _**macro_ Same as **.ami **but with compatibility mode switched off during macro expansion. **.ami1 _**macro_ _end_ Same as **.ami **but with compatibility mode switched off during macro expansion. **.as _**name_ Create string _name_ with empty contents; no operation if _name_ already exists. **.as _**name_ _contents_ Append _contents_ to string _name_. **.as1 _**string_ **.as1 _**string_ _contents_ As **.as**, but with compatibility mode disabled when _contents_ interpolated. **.asciify _**diversion_ Unformat ASCII characters, spaces, and some escape sequences in _diversion_. ### .backtrace Write the state of the input stack to the standard error stream. See the **-b **option of [_groff_(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown). **.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. **.bd _**special-font_ _font_ _n_ Embolden _special-font,_ overstriking its glyphs offset by _n_-1 units when _font_ is se‐ lected. See register **.b**. **.blm **Unset blank line macro (trap). Restore default handling of blank lines. **.blm _**name_ Set blank line macro (trap) to _name_. **.box **Stop directing output to current diversion; any pending output line is discarded. **.box _**name_ Direct output to diversion _name_, omitting a partially collected line. **.boxa **Stop appending output to current diversion; any pending output line is discarded. **.boxa _**name_ Append output to diversion _name_, 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_ Copy contents of _file_ without formatting to the (top-level) diversion. **.cflags _**n_ _c1_ _c2_ ... Assign properties encoded by _n_ to characters _c1_, _c2_, and so on. **.ch _**name_ Unplant page location trap _name_. **.ch _**name_ _vpos_ Change page location trap _name_ planted by **.wh **by moving its location to _vpos_ (de‐ fault scaling unit **v**). **.char _**c_ _contents_ Define ordinary or special character _c_ as _contents_. **.chop _**object_ Remove the last character from the macro, string, or diversion named _object_. **.class _**name_ _c1_ _c2_ ... Define a (character) class _name_ comprising the characters or range expressions _c1_, _c2_, and so on. **.close _**stream_ Close the _stream_. **.color **Enable output of color-related device-independent output commands. **.color _**n_ If _n_ is zero, disable output of color-related device-independent output commands; otherwise, enable them. **.composite _**from_ _to_ Map glyph name _from_ to glyph name _to_ while constructing a composite glyph name. **.continue **Finish the current iteration of a while loop. **.cp **Enable compatibility mode. **.cp _**n_ If _n_ is zero, disable compatibility mode, otherwise enable it. **.cs _**font_ _n_ _m_ Set constant character width mode for _font_ to _n_/36 ems with em _m_. **.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 _**name_ Append output to diversion _name_. **.de _**macro_ Define or redefine _macro_ until “**..**” occurs at the start of a control line in the current conditional block. **.de _**macro_ _end_ Define or redefine _macro_ until _end_ is invoked or called at the start of a control line in the current conditional block. **.de1 _**macro_ As **.de**, but disable compatibility mode during macro expansion. **.de1 _**macro_ _end_ As “**.de _**macro_ _end_”, but disable compatibility mode during macro expansion. **.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 compo‐ nent 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). Each output device has a color named “**default**”, which cannot be rede‐ fined. A device's default stroke and fill colors are not necessarily the same. **.dei _**macro_ Define macro indirectly. As **.de**, but use interpolation of string _macro_ as the name of the defined macro. **.dei _**macro_ _end_ Define macro indirectly. As **.de**, but use interpolations of strings _macro_ and _end_ as the names of the defined and end macros. **.dei1 _**macro_ As **.dei**, but disable compatibility mode during macro expansion. **.dei1 _**macro_ _end_ As **.dei _**macro_ _end_, but disable compatibility mode during macro expansion. **.device _**anything_ Write _anything_, read in copy mode, to _troff_ output as a device control command. An initial neutral double quote is stripped to allow embedding of leading spaces. **.devicem _**name_ Write contents of macro or string _name_ to _troff_ output as a device control command. **.di **Stop directing output to current diversion. **.di _**name_ Direct output to diversion _name_. **.do _**name_ ... Interpret the string, request, diversion, or macro _name_ (along with any arguments) with compatibility mode disabled. Compatibility mode is restored (only if it was active) when the _expansion_ of _name_ is interpreted. **.ds _**name_ Create empty string _name_. **.ds _**name_ _contents_ Create a string _name_ containing _contents_. **.ds1 _**name_ **.ds1 _**name_ _contents_ As **.ds**, but with compatibility mode disabled when _contents_ interpolated. **.dt **Clear diversion trap. **.dt _**vertical-position_ _name_ Set the diversion trap to macro _name_ 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 _**anything_ Interpret _anything_ as if it were an input line if the conditional expression of the corresponding **.ie **request was false. **.em _**name_ Call macro _name_ 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_. **.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 _**a_ Set field delimiter to _a_ and pad glyph to space. **.fc _**a_ _b_ Set field delimiter to _a_ and pad glyph to _b_. **.fchar _**c_ _contents_ Define fallback character (or glyph) _c_ as _contents_. **.fcolor **Restore previous fill color. **.fcolor _**c_ Set fill color to _c_. **.fi **Enable filling of output lines; a pending output line is broken. Sets **\n[.u]**. **.fl **Flush output buffer. **.fp _**pos_ _id_ Mount font with font description file name _id_ at non-negative position _n_. **.fp _**pos_ _id_ _font-description-file-name_ Mount font with _font-description-file-name_ as name _id_ at non-negative position _n_. **.fschar _**f_ _c_ _anything_ Define fallback character (or glyph) _c_ for font _f_ as string _anything_. **.fspecial _**font_ Reset list of special fonts for _font_ to be empty. **.fspecial _**font_ _s1_ _s2_ ... When the current font is _font_, then the fonts _s1_, _s2_, ... are special. ### .ft **.ft P **Select previous font mounting position (abstract style or font); same as **\f[] **or **\fP**. **.ft _**font_ Select typeface _font,_ which can be a mounting position, abstract style, or font name; same as **\f[_**font_**] **escape sequence. _font_ cannot be **P**. **.ftr _**font1_ _font2_ Translate _font1_ to _font2_. **.fzoom _**font_ **.fzoom _**font_ **0** Stop magnifying _font_. **.fzoom _**font_ _z_ Set zoom factor for _font_ to _z_ (in thousandths; default: 1000). **.gcolor **Restore previous stroke color. **.gcolor _**c_ Set stroke color to _c_. **.hc **Reset the hyphenation character to **\% **(the default). **.hc _**char_ Change the hyphenation character to _char_. **.hcode _**c1_ _code1_ [_c2_ _code2_] ... Set the hyphenation code of character _c1_ to _code1_, that of _c2_ to _code2_, and so on. **.hla _**lang_ Set the hyphenation language to _lang_. **.hlm _**n_ Set the maximum quantity of consecutive hyphenated lines to _n_. **.hpf _**pattern-file_ Read hyphenation patterns from _pattern-file_. **.hpfa _**pattern-file_ Append hyphenation patterns from _pattern-file_. **.hpfcode _**a_ _b_ [_c_ _d_] ... Define mappings for character codes in hyphenation pattern files read with **.hpf **and **.hpfa**. **.hw _**word_ ... Define hyphenation overrides for each _word;_ a hyphen “**-**” indicates a hyphenation point. **.hy **Set automatic hyphenation mode to **1**. **.hy 0 **Disable automatic hyphenation; same as **.nh**. **.hy _**mode_ Set automatic hyphenation mode 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 the line can be justified with the addition of up to _hyphenation-space_ to each inter-word space (default scaling unit **m**). **.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_ _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_ Ignore input (except for side effects of **\R **on auto-incrementing registers) until **._**end_ is called at the start of a control line in the current conditional block. **.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_ _name_ Set (or replace) an input line trap in the environment, calling macro _name_, 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_ _name_ As **.it**, except that input lines interrupted with the **\c **escape sequence are not counted. **.kern **Enable pairwise kerning. **.kern _**n_ If _n_ is zero, disable pairwise kerning, otherwise enable it. **.lc **Unset leader repetition character. **.lc _**c_ Set leader repetition character to _c_ (default: “**.**”). **.length _**reg_ _anything_ Compute the number of characters of _anything_ and store the count in the register _reg_. **.linetabs **Enable line-tabs mode (calculate tab positions relative to beginning of output line). ### .linetabs 0 Disable line-tabs mode. **.lf _**n_ Set number of next input line to _n_. **.lf _**n_ _file_ Set number of next input line to _n_ and input file name to _file_. **.lg _**m_ Set ligature mode to _m_ (**0 **= disable, **1 **= enable, **2 **= enable for two-letter liga‐ tures 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 af‐ fect a pending output line. **.lsm **Unset the leading space macro (trap). Restore default handling of lines with lead‐ ing spaces. **.lsm _**name_ Set the leading space macro (trap) to _name_. **.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. **.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 _**register_ Mark vertical drawing position in _register_. **.mso _**file_ As **.so**, except that _file_ is sought in the _tmac_ directories. **.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, 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 to be numbered with **nm**. **.nn _**n_ Suppress numbering of the next _n_ output lines to be numbered with **nm**. If _n_=0, can‐ cel suppression. **.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_. **.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 out‐ put. See **.rs**. **.nx **Immediately jump to end of current file. **.nx _**file_ Stop formatting current file and begin reading _file._ **.open _**stream_ _file_ Open _file_ for writing and associate the stream named _stream_ with it. Unsafe re‐ quest; disabled by default. **.opena _**stream_ _file_ As **.open**, but append to _file._ Unsafe request; disabled by default. **.os **Output vertical distance that was saved by the **.sv **request. **.output _**contents_ Emit _contents_ directly to intermediate output, allowing leading whitespace if _string_ starts with **" **(which is stripped off). **.pc **Reset page number character to ‘**%**’. **.pc _**c_ Page number character. **.pev **Report the state of the current environment followed by that of all other environ‐ ments to the standard error stream. **.pi _**program_ Pipe output to _program_ (_nroff_ only). 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**). **.pm **Report, to the standard error stream, the names and sizes in bytes of defined macros, strings, and diversions. **.pn _**±N_ Next page number _N_. **.pnr **Write the names and contents of all defined registers to the standard error stream. **.po **Change to previous page offset. The current page offset is available in register **.o**. **.po _**±N_ Page offset _N_. **.ps **Return to 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 _**file_ Retrieve the bounding box of the PostScript image found in _file,_ which must conform to Adobe's Document Structuring Conventions (DSC). See registers **llx**, **lly**, **urx**, **ury**. **.pso _**command-line_ Execute _command-line_ with [_popen_(3)](https://www.chedong.com/phpMan.php/man/popen/3/markdown) and interpolate its output. Unsafe request; disabled by default. **.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 or special character _c1_, _c2_, ... defined by a **.char**, **.fchar**, or **.schar **request. **.rd _**prompt_ Read insertion. **.return **Return from a macro. **.return _**anything_ Return twice, namely from the macro at the current level and from the macro one level higher. **.rfschar _**f_ _c1_ _c2_ ... Remove the font-specific definitions of glyphs _c1_, _c2_, ... for font _f_. **.rj _**npl_ 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 fill‐ ing, then break again. If _npl_ ≤ 0, stop right-aligning. **.rm _**name_ Remove 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 _**ident_ Remove register _ident_. **.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_ _contents_ Define global fallback character (or glyph) _c_ as _contents_. **.shc **Reset the soft hyphen character to **\[hy]**. **.shc _**c_ Set the soft hyphen character to _c_. **.shift _**n_ In a macro definition, left-shift arguments by _n_ positions. **.sizes _**s1_ _s2_ ... _sn_ [**0**] Set available type sizes similarly to the **sizes **directive in a _DESC_ file. Each _s_i is interpreted in units of scaled points (**z**). **.so _**file_ Replace the request's control line with the contents of _file_, “sourcing” it. **.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 loca‐ tion 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 po‐ sition 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 diver‐ sion. **.special **Reset global list of special fonts to be empty. **.special _**s1_ _s2_ ... Fonts _s1_, _s2_, etc. are special and are searched for glyphs not in the current 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 minimal inter-word spacing to _n_ 12ths of current font's space width. **.ss _**n_ _m_ As “**.ss _**n_”, and set additional inter-sentence space to _m_ 12ths of current font's space width. **.stringdown _**stringvar_ Replace each byte in the string named _stringvar_ with its lowercase version. **.stringup _**stringvar_ Replace each byte in the string named _stringvar_ with its uppercase version. **.sty _**n_ _style_ Associate abstract _style_ with font position _n_. **.substring _**str_ _start_ [_end_] Replace the string named _str_ with its substring bounded by the indices _start_ and _end_, inclusive. Negative indices count backwards 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-line_ Execute _command-line_ with [_system_(3)](https://www.chedong.com/phpMan.php/man/system/3/markdown). Unsafe request; disabled by default. **.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 rela‐ tive 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 **.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 _**message_ Write _message,_ followed by a newline, to the standard error stream. **.tm1 _**message_ As **.tm**, but an initial neutral double quote in _message_ is removed, allowing it to contain leading spaces. **.tmc _**message_ As **.tm1**, without emitting a newline. **.tr _**abcd_... Translate ordinary or special characters _a_ to _b_, _c_ to _d_, and so on prior to output. **.trf _**file_ Transparently output the contents of _file._ Unlike **.cf**, invalid input characters in _file_ are rejected. **.trin _**abcd_... As **.tr**, except that **.asciify **ignores the translation when a diversion is interpo‐ lated. **.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 _**diversion_ Unformat space characters and tabs in _diversion_, preserving font information. **.vpt **Enable vertical position traps. **.vpt 0 **Disable vertical position traps. **.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)](https://www.chedong.com/phpMan.php/man/troff/1/markdown). **.warnscale _**su_ Set scaling unit used in certain warnings to _su_ (one of **u**, **i**, **c**, **p**, or **P**; default: **i**). **.wh _**vpos_ Remove visible page location trap at _vpos_ (default scaling unit **v**). **.wh _**vpos_ _name_ Plant macro _name_ as page location trap at _vpos_ (default scaling unit **v**), removing any visible trap already there. **.while _**cond-expr_ _anything_ Repeatedly execute _anything_ unless and until _cond-expr_ evaluates false. **.write _**stream_ _anything_ Write _anything_ to the stream named _stream_. **.writec _**stream_ _anything_ Similar to **.write **without emitting a final newline. **.writem _**stream_ _xx_ Write contents of macro or string _xx_ to the stream named _stream_. ## Escape sequence short reference The escape sequences **\"**, **\#**, **\$**, **\***, **\?**, **\a**, **\e**, **\n**, **\t**, **\g**, **\V**, and **\_**newline_ are interpreted even in copy mode. **\" **Comment. Everything up to the end of the line is ignored. **\# **Comment. Everything up to and including the next newline is ignored. **\*_**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 argu‐ ments. **\$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 concatenation of all macro or string parameters, separated by spaces. **\$@ **Interpolate concatenation of all macro or string parameters, with each surrounded by double quotes and separated by spaces. **\$^ **Interpolate concatenation of all macro or string parameters as if they were arguments to the **.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. **\% **Control hyphenation. **\! **Transparent line. The remainder of the input line is interpreted (1) when the current diversion is read; or (2) if in the top-level diversion, by the postprocessor (if any). **\?_**anything_**\?** Transparently embed _anything_, read in copy mode, in a diversion, or unformatted as an output comparand in a conditional expression. **\_**space_ Move right one 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. **\(_**gl_ Interpolate glyph with two-character name _gl_. **\[_**glyph_**]** Interpolate glyph with name _glyph_ (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 hexa‐ decimal. **\[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). **\k_**r_ Mark horizontal position in one-character register name _r_. **\k(_**rg_ Mark horizontal position in two-character register name _rg_. **\k[_**reg_**]** Mark horizontal position in register with arbitrarily long 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_ Set stroke color to that with one-character name _c_. **\m(_**cl_ Set stroke color to that with two-character name _cl_. **\m[_**color_**]** Set stroke color to that with arbitrarily long name _color_. **\m[] **Restore previous stroke color. **\M_**c_ Set fill color to that with one-character name _c_. **\M(_**cl_ Set fill color to that with two-character name _cl_. **\M[_**color_**]** Set fill color to that with arbitrarily long name _color_. **\M[] **Restore previous fill color. **\n_**r_ Interpolate contents of register with one-character name _r_. **\n(_**rg_ Interpolate contents of register with two-character name _rg_. **\n[_**reg_**]** Interpolate contents of register with arbitrarily long name _reg_. **\N'_**n_**' **Interpolate glyph with index _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 bound‐ ing 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 mo‐ tion 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; 0 restores the previous type 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. As **.ps **request. **\s[_**±N_**]** **\s_**±_**[_**N_**]** **\s'_**±N_**'** **\s_**±_**'_**N_**' **Set/increase/decrease the type size to/by _N_ scaled points. 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 contents of environment variable with one-character name _e_. **\V(_**ev_ Interpolate contents of environment variable with two-character name _ev_. **\V[_**env_**]** Interpolate contents of environment variable with arbitrarily long name _env_. **\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; nega‐ tive before, positive after). **\X'_**anything_**'** Write _anything_ to _troff_ output as a device control command. Within _anything_, the es‐ cape sequences **\&**, **\)**, **\%**, and **\: **are ignored; **\_**space_ and **\~ **are converted to single space characters; and **\\ **has its escape character stripped. So that the basic Latin subset of the Unicode character set can be reliably encoded in _anything,_ the special character escape sequences **\-**, **\[aq]**, **\[dq]**, **\[ga]**, **\[ha]**, **\[rs]**, and **\[ti] **are mapped to basic Latin characters; see [_groff_char_(7)](https://www.chedong.com/phpMan.php/man/groffchar/7/markdown). For this transformation, character translations and special character definitions are ignored. **\Y_**n_ Write contents of macro or string _n_ to _troff_ output as a device control command. **\Y(_**nm_ Write contents of macro or string _nm_ to _troff_ output as a device control command. **\Y[_**name_**]** Write contents of macro or string _name_ to _troff_ output as a device control command. **\z_**c_ Format character _c_ with zero width—without advancing the drawing position. **\Z'_**anything_**'** Save the drawing position, format _anything_, then restore it. ### 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. Terminal devices in particular implement almost none. Rendering starts at the drawing position; when finished, the drawing position is left at the rightmost point of the object, even for closed figures, except where noted. GNU _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 hori‐ zontal measurements (and diameters of circles) is **m**; for vertical ones, **v**. Circles, ellipses, and polygons can be drawn stroked or filled. These are independent prop‐ erties; 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 drawing position and each point in sequence. GNU _troff_ closes the polygon by drawing a line from (_hn_, _vn_) back to the initial drawing posi‐ tion. 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 minimal supported thickness. A negative _n_ selects a thickness proportional to the type size; this is the default. ### Device control commands The **.device **and **.devicem **requests, and **\X **and **\Y **escape sequences, enable documents to pass information directly to a postprocessor. These are useful for exercising device-specific ca‐ pabilities that the _groff_ language does not abstract or generalize; such functions include the embedding of hyperlinks and image files. Device-specific functions are documented in each output driver's man page. ## 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 called with only one argument, the named string becomes empty. Otherwise, _troff_ stores the remain‐ der of the control line in copy mode; see subsection “Copy mode” below. The **\* **escape sequence dereferences a string's name, interpolating its contents. If the name does not exist, it is defined as empty, nothing is interpolated, and a warning in category “**mac**” is emitted. See section “Warnings” in [_troff_(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown). The bracketed interpolation form ac‐ cepts arguments that are handled as macro arguments are; see section “Calling macros” above. In contrast to macro calls, however, if a closing bracket **] **occurs in a string argument, that argument must be enclosed in double quotes. **\* **is interpreted even in copy mode. When defining strings, argument interpolations must be escaped if they are to reference parameters from the calling context; see section “Parameters” below. An initial neutral double quote **" **in the string contents is stripped to allow embedding of leading spaces. Any other **" **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 in‐ put line of text. **\_**newline_ works just as it does elsewhere. The resulting string is stored _without_ the newlines. Care is therefore required when interpolating strings while filling is disabled. It is not possible to embed a newline in a string that will be interpreted as such when the string is interpolated. To achieve that effect, use **\* **to interpolate a macro in‐ stead. The **.as **request is similar to **.ds **but appends to a string instead of redefining it. If **.as** is called with only one argument, no operation is performed (beyond dereferencing the string). Because strings are similar to macros, they too can be defined to suppress AT&T _troff_ compat‐ ibility mode enablement when interpolated; see section “Compatibility mode” below. The **.ds1** request defines a string that suspends compatibility mode when the string is later interpo‐ lated. **.as1 **is likewise similar to **.as**, with compatibility mode suspended when the appended portion of the string is later interpolated. **Caution: **Unlike other requests, the second argument to these requests consumes the remainder of the input line, including trailing spaces. Ending string definitions (and appendments) with a comment, even an empty one, prevents unwanted space from creeping into them during source document maintenance. Several requests exist to perform rudimentary string operations. Strings can be queried (**.length**) and modified (**.chop**, **.substring**, **.stringup**, **.stringdown**), and their names can be manipulated through renaming, removal, and aliasing (**.rn**, **.rm**, **.als).** When a request, macro, string, or diversion is aliased, redefinitions and appendments “write through” alias names. To replace an alias with a separately defined object, you must use the **rm **request on its name first. ## Registers In the _roff_ language, numbers can be stored in _registers._ Many built-in registers exist, supplying anything from the date to details of formatting parameters. You can also define your own. See section “Identifiers” above for information on constructing a valid name for a register. Define registers and update their values with the **nr **request or the **\R **escape sequence. Registers can also be incremented or decremented by a configured amount at the time they are interpolated. The value of the increment is specified with a third argument to the **.nr **re‐ quest, and a special interpolation syntax, **\n_**±_ is used to alter and then retrieve the regis‐ ter's value. Together, these features are called _auto-increment_. (A negative auto-increment can be considered an “auto-decrement”.) Many predefined registers are available. In the following presentation, the register inter‐ polation syntax **\n[_**name_**] **is used to refer to a register _name_ to clearly distinguish it from a string or request _name_. The register name space is separate from that used for requests, macros, strings, and diversions. Bear in mind that the symbols **\n[] **are _not_ part of the reg‐ ister name. ### Read-only registers Predefined registers whose identifiers start with a dot are read-only. Many are Boolean-val‐ ued. Some are string-valued, meaning that they interpolate text. A register name (without the dot) is often associated with a request of the same name; exceptions are noted. \n[**.$**] Count of arguments passed to currently interpolated macro or string. \n[**.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 currently interpolated macro (Boolean-valued). \n[**.c**] Input line number; see **.lf **and register “**c.**”. \n[**.C**] 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 output lines remaining to be centered. \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; skew is how far to the right of the center of a glyph the center of an accent over that glyph should be placed. \n[**.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 default font family (string-valued). \n[**.fn**] Resolved name of selected font (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**] Font height; 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[**.hym**] Hyphenation margin in environment. \n[**.hys**] Hyphenation space adjustment threshold in environment. \n[**.i**] Indentation amount; see **.in**. \n[**.in**] Indentation amount applicable to the pending output line; see **.ti**. \n[**.int**] Previous output line was “interrupted” or continued with **\c **(Boolean-valued). \n[**.j**] Adjustment mode encoded as an integer; see **.ad **and **.na**. Do not interpret or perform arithmetic on its value. \n[**.k**] 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 (Boolean-valued). \n[**.ll**] Line length applicable to the pending output line. \n[**.lt**] Title length. \n[**.m**] Stroke color (string-valued); see **.gcolor **and **\m**. Empty if the stroke color is the default. \n[**.M**] Fill color (string-valued); see **.fcolor **and **\M**. Empty if the fill color is the 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 (Boolean-valued). \n[**.nn**] Count of output lines remaining to have numbering suppressed. \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**] Type size in scaled points. \n[**.psr**] Most recently requested type size in scaled points; see **.ps **and **\s**. \n[**.pvs**] Post-vertical line spacing. \n[**.R**] Count of available unused registers; always 10,000 in GNU _troff_. \n[**.rj**] Count of lines remaining to be right-aligned. \n[**.s**] Type size in points as a decimal fraction (string-valued); see **.ps **and **\s**. \n[**.slant**] Slant of font in degrees; see **\S**. \n[**.sr**] Most recently requested type size in points as a decimal fraction (string-val‐ ued); see **.ps **and **\s**. \n[**.ss**] Size of minimal inter-word space in twelfths of the space width of the se‐ lected font. \n[**.sss**] Size of additional inter-sentence space in twelfths of the space width of the selected font. \n[**.sty**] Selected abstract style (string-valued); see **.ft **and **\f**. \n[**.t**] Distance to next vertical position trap; see **.wh **and **.ch**. \n[**.T**] An output device was explicitly selected (Boolean-valued); see _troff_ **-T **op‐ tion. \n[**.tabs**] Representation of tab settings suitable for use as argument to **.ta **(string- valued). \n[**.trunc**] Amount of vertical space truncated by the most recently sprung vertical posi‐ tion 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 (Boolean-valued); see **.fi **and **.nf**. \n[**.U**] Unsafe mode is enabled (Boolean-valued); see _troff_ **-U **option. \n[**.v**] 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 previous 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**] Zoom multiplier of current 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)](https://www.chedong.com/phpMan.php/man/localtime/3/markdown) when the formatter launches. This initialization can be overridden by _SOURCE_DATE_EPOCH_ and _TZ_; see section “Environment” of [_groff_(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown). \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 start of 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 ren‐ dering 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 ren‐ dering into dummy environment by **\w**. \n[**systat**] Return value of _system()_ function; 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 de‐ vice can render as glyphs at a desired size. (Terminals and some output devices have fonts that render at only one or two sizes. As examples of the latter, take the _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 typesetting devices, at least one _special_ _font_ is available, comprising _unstyled_ glyphs for mathematical operators and other purposes. Like AT&T _troff,_ 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 as‐ sociates 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 out‐ put 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._ 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 ab‐ breviations 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 issu‐ ing appropriate formatter instructions, you can override these defaults before your document writes its first glyph. Terminal output devices cannot change font families and lack special fonts. They support style changes by overstriking, or by altering ISO 6429/ECMA-48 _graphic_ _renditions_ (character cell attributes). ## 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 indi‐ vidual 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 hy‐ phenation modes is available to the **.hy **request; these determine whether hyphenation will ap‐ ply to a word prior to breaking a line at the end of a page (more or less; see below for de‐ tails), and at which positions within that word automatically determined hyphenation points are permissible. The default is “**1**” for historical reasons, but this is not an appropriate value for the English hyphenation patterns used by _groff_; localization macro files loaded by _troffrc_ and macro packages often override it. **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. (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-spe‐ cific data (**.hla**, **.hpf**, and **.hpfa**) and lettercase relationships (**.hcode **and **.hpfcode**). Fur‐ thermore, 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 ad‐ justed 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)](https://www.chedong.com/phpMan.php/man/grofftmac/5/markdown). ## 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). Alter‐ natively, a second argument names a macro whose call syntax ends the definition; this “end macro” is then called normally. Spaces or tabs are permitted after the first control charac‐ ter 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, re‐ turning to the enclosing context. ### Parameters Macro call and string interpolation parameters can be accessed using escape sequences start‐ ing with “**\$**”. The **\n[.$] **read-only register stores the count of parameters available to a macro or string; its value can be changed by 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 When _troff_ processes certain requests, most importantly those which define or append to a macro or string, it does so in _copy_ _mode_: it copies the characters of the definition into a dedicated storage region, interpolating the escape sequences **\n**, **\g**, **\$**, **\***, **\V**, and **\? **nor‐ mally; interpreting **\_**newline_ immediately; discarding comments **\" **and **\#**; interpolating the current leader, escape, or tab character with **\a**, **\e**, and **\t**, respectively; and storing all other escape sequences in an encoded form. 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 recog‐ nition, 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 contain‐ ing 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 back‐ slash 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 char‐ acter, this would not be possible. _roff_ documents should not use the **\\ **or **\. **character se‐ quences 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 inter‐ preted 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 inter‐ preted 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 ful‐ filled, 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 foot‐ ers, 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-enabled (**.vpt**). A diversion is not formatted in the context of a page, so it lacks page location traps; in‐ stead 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 char‐ acters (**.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. Setting a trap is also called _planting_ one. It is said that a trap is _sprung_ if its condition is fulfilled. Registers associated with trap management include vertical position trap enablement status (**\n[.vpt]**), distance to the next trap (**\n[.t]**), 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 undi‐ verted 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 mov‐ ing 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 ab‐ solute 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; 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 im‐ mediately, 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 some‐ times said to be “stored in a macro”, but this coinage obscures the important distinction be‐ tween macros and strings on one hand and diversions on the other; the former store _unformat‐_ _ted_ input text, and the latter capture _formatted_ output. Diversions also do not interpret arguments. Applications of diversions include “keeps” (preventing a page break from occur‐ ring at an inconvenient place by forcing a set of output lines to be set as a group), foot‐ notes, 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 “di‐ verted” immediately to the output device. Dereferencing an undefined diversion will create an empty one of that name and cause a warn‐ ing in category **mac **to be emitted. (see section “Warnings” in [_troff_(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown)). A diversion does not exist for the purpose of testing with the **d **conditional operator until its initial defin‐ ition 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 **works similarly, but ignore partially collected lines. Call any of these macros again without an argument to end the diversion. Diversions can be nested. The registers **.d**, **.z**, **dn**, and **dl **report information about the cur‐ rent (or last closed) diversion. **.h **is meaningful in diversions, including the top level. 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_ _em‐_ _bedding_. The **asciify **and **unformat **requests reprocess diversions. ## Punning names Macros, strings, and diversions share a name space; see section “Identifiers” above. Inter‐ nally, the same mechanism is used to store them. You can thus call a macro with string in‐ terpolation syntax and vice versa. Interpolating a string does not hide existing macro argu‐ ments. 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 environ‐ ment 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 charac‐ ters • input line traps • stroke and fill colors The **ev **request pushes to and pops from the environment stack, while **evc **copies a named envi‐ ronment's contents to the current one. ## Underlining In _RUNOFF_ (see [_roff_(7)](https://www.chedong.com/phpMan.php/man/roff/7/markdown)), underlining, even of lengthy passages, was straightforward because only fixed-pitch printing devices were targeted. Typesetter output posed a greater chal‐ lenge. There exists a _groff_ request **.ul **(see above) that underlines subsequent source lines on terminal devices, but on typesetters, it selects an italic font style instead. The _ms_ macro package (see [_groff_ms_(7)](https://www.chedong.com/phpMan.php/man/groffms/7/markdown)) 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)](https://www.chedong.com/phpMan.php/man/doclifter/1/markdown) 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 fol‐ lowing. .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 _in_ after ### Underlining by overstriking with \(ul The **\z **escape sequence writes a glyph without advancing the drawing position, enabling over‐ striking. Thus, **\z_**c_**\(ul **formats _c_ with an underrule glyph on top of it. Video terminals im‐ plement 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_**__**_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 intermediate output formats described by CSTR #54 are documented in [_groff_diff_(7)](https://www.chedong.com/phpMan.php/man/groffdiff/7/markdown). _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 in‐ put 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)](https://www.chedong.com/phpMan.php/man/troff/1/markdown)). A trace of the formatter's input processing stack can be emit‐ ted when errors or warnings occur by means of [_troff_(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown)'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 de‐ fined names—macros, strings, and diversions—(**.pm**); environments (**.pev**), registers (**.pnr**), and page location traps (**.ptr**) to the standard error stream. ## Authors This document was written by by Trent A. Fisher, Werner Lemberg, and [G. Branden Robinson](mailto:). Section “Underlining” was primarily written by [Bernd Warken](mailto:). **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 out‐ put format referred to collectively in _groff_ documentation as “AT&T _troff_”. “A Typesetter-independent TROFF” by Brian W. Kernighan, 1982, AT&T Bell Laboratories Comput‐ ing Science Technical Report No. 97 (CSTR #97), provides additional insights into the device and font description file formats and device-independent output format. [_groff_(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown) 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)](https://www.chedong.com/phpMan.php/man/groffchar/7/markdown) discusses character encoding issues, escape sequences that produce glyphs, and enumer‐ ates _groff_'s predefined special character escape sequences. [_groff_diff_(7)](https://www.chedong.com/phpMan.php/man/groffdiff/7/markdown) covers differences between the GNU _troff_ formatter, its device and font description file formats, its device-independent output format, and those of AT&T _troff_, whose de‐ sign it reimplements. [_groff_font_(5)](https://www.chedong.com/phpMan.php/man/grofffont/5/markdown) describes the formats of the files that describe devices (_DESC_) and fonts. [_groff_tmac_(5)](https://www.chedong.com/phpMan.php/man/grofftmac/5/markdown) 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 on macro package naming conventions. [_roff_(7)](https://www.chedong.com/phpMan.php/man/roff/7/markdown) presents a detailed history of _roff_ systems and summarizes concepts common to them. groff 1.23.0 31 March 2024 [_groff_(7)](https://www.chedong.com/phpMan.php/man/groff/7/markdown)